55// model saw one undifferentiated list of every installed skill — built-in, project and workspace
66// alike — and answered a workspace question by listing all of them, differently each time.
77//
8- // Skills come from the synced snapshot on disk (no network); integrations and the memory setting
9- // from the workspace summary, cached and never awaited for long, since this renders every step.
8+ // Skills come from the synced snapshot on disk (no network); integrations, the memory setting and
9+ // knowledge from the workspace summary. Both are cached and waited on only briefly, since this
10+ // renders every step. Anything the CLI could not establish is left out or called unknown, never
11+ // reported as "none".
1012import fs from "fs/promises"
1113import path from "path"
14+ import { createHash } from "crypto"
1215import { ConfigMarkdown } from "@/config/markdown"
1316import { AltimateApi } from "@/altimate/api/client"
1417import * as SkillSync from "./skill-sync"
@@ -19,22 +22,28 @@ export interface WorkspaceSkill {
1922}
2023
2124/**
22- * What the knowledge engine gives this workspace. With the engine on and no documents
23- * selected , the workspace reads every document in the knowledge hub, so a count would be wrong.
25+ * What the knowledge engine gives this workspace. With the engine on and an explicitly empty
26+ * selection , the workspace reads every document in the knowledge hub, so a count would be wrong.
2427 */
2528export type WorkspaceKnowledge =
2629 | { kind : "off" }
2730 | { kind : "all" }
28- /** `names` is null when the document list could not be read; `count` is the selection size then. */
31+ /**
32+ * `count` is the number of selected documents that exist, or are not yet checked beyond the
33+ * listing cap. `names` holds the ones resolved, sorted; null when they could not be read.
34+ */
2935 | { kind : "selected" ; count : number ; names : string [ ] | null }
3036
3137export interface WorkspaceContents {
32- /** null when the snapshot is missing, another account's, or a previous link's. */
33- skills : WorkspaceSkill [ ] | null
34- /** Integration ids attached to the workspace; null when not known yet. */
38+ /**
39+ * The workspace's skills. null: not synced to this project for this account and link.
40+ * "unknown": the snapshot could not be read in time this step.
41+ */
42+ skills : WorkspaceSkill [ ] | null | "unknown"
43+ /** Integration ids attached to the workspace; null when not known. */
3544 integrations : string [ ] | null
3645 memoryEnabled : boolean | null
37- /** null when not known yet . */
46+ /** null when not known. */
3847 knowledge : WorkspaceKnowledge | null
3948}
4049
@@ -45,6 +54,8 @@ const MAX_LISTED_DOCUMENTS = 20
4554const MAX_DESCRIPTION_CHARS = 100
4655const SUMMARY_TTL_MS = 5 * 60_000
4756const SUMMARY_WAIT_MS = 300
57+ /** How long one step waits for the snapshot read; a slow filesystem never holds prompt assembly. */
58+ const SKILLS_WAIT_MS = 300
4859
4960/** Single-line, bounded text from a workspace owner's frontmatter. Not an instruction. */
5061function clean ( text : unknown , max : number ) : string {
@@ -55,12 +66,22 @@ function clean(text: unknown, max: number): string {
5566 return s . length > max ? `${ s . slice ( 0 , max - 1 ) } …` : s
5667}
5768
58- /** The workspace's own skills, read from the managed snapshot, sorted so every ask sees the same list. */
59- export async function workspaceSkills ( directory : string , datamateId : number ) : Promise < WorkspaceSkill [ ] | null > {
60- if ( ( await SkillSync . snapshotWorkspaceId ( directory ) ) !== datamateId ) return null
61- const root = SkillSync . snapshotRoot ( directory )
69+ // ---------------------------------------------------------------------------
70+ // Skills (snapshot on disk)
71+ // ---------------------------------------------------------------------------
72+
73+ /** Parsed snapshot per root, keyed on the root's identity: a sync publishes by swapping the
74+ * whole directory in, so a changed snapshot always has a new inode or mtime. */
75+ const parsedSnapshots = new Map < string , { stamp : string ; skills : WorkspaceSkill [ ] } > ( )
76+
77+ async function readSnapshot ( root : string ) : Promise < WorkspaceSkill [ ] | null > {
78+ let stamp : string
6279 let entries : string [ ]
6380 try {
81+ const st = await fs . stat ( root )
82+ stamp = `${ st . ino } :${ st . mtimeMs } `
83+ const hit = parsedSnapshots . get ( root )
84+ if ( hit ?. stamp === stamp ) return hit . skills
6485 entries = await fs . readdir ( root )
6586 } catch {
6687 return null
@@ -77,67 +98,120 @@ export async function workspaceSkills(directory: string, datamateId: number): Pr
7798 // not a skill folder, or unreadable — the sync reports those separately
7899 }
79100 }
80- return skills . sort ( ( a , b ) => a . name . localeCompare ( b . name ) )
101+ skills . sort ( ( a , b ) => a . name . localeCompare ( b . name ) )
102+ parsedSnapshots . set ( root , { stamp, skills } )
103+ return skills
104+ }
105+
106+ /** The snapshot questions this module asks; replaceable in tests (module exports cannot be spied). */
107+ const defaultSnapshot = {
108+ workspaceId : ( dir : string ) => SkillSync . snapshotWorkspaceId ( dir ) ,
109+ knownEmpty : ( dir : string , id : number ) => SkillSync . snapshotKnownEmpty ( dir , id ) ,
110+ root : ( dir : string ) => SkillSync . snapshotRoot ( dir ) ,
111+ }
112+ let snapshot = defaultSnapshot
113+
114+ export function setSnapshotForTests ( overrides : Partial < typeof defaultSnapshot > ) : void {
115+ snapshot = { ...defaultSnapshot , ...overrides }
116+ }
117+
118+ /** The workspace's own skills, sorted so every ask sees the same list. [] for a workspace the
119+ * last sync found empty (an empty workspace leaves no snapshot); null when not synced. */
120+ export async function workspaceSkills ( directory : string , datamateId : number ) : Promise < WorkspaceSkill [ ] | null > {
121+ if ( ( await snapshot . workspaceId ( directory ) ) !== datamateId ) {
122+ return ( await snapshot . knownEmpty ( directory , datamateId ) ) ? [ ] : null
123+ }
124+ return readSnapshot ( snapshot . root ( directory ) )
81125}
82126
127+ // ---------------------------------------------------------------------------
128+ // Summary (network)
129+ // ---------------------------------------------------------------------------
130+
83131type Summary = { integrations : string [ ] | null ; memoryEnabled : boolean | null ; knowledge : WorkspaceKnowledge | null }
84132const UNKNOWN : Summary = { integrations : null , memoryEnabled : null , knowledge : null }
85- const summaries = new Map < number , { at : number ; value ?: Summary ; pending ?: Promise < Summary > } > ( )
133+ /** `complete`: everything the response promised was read, so the entry may be reused. */
134+ type Fetched = { value : Summary ; complete : boolean }
135+ /** Keyed by account AND workspace id: ids are per tenant, so another account's workspace with the
136+ * same id must never be answered from this cache. */
137+ const summaries = new Map < string , { at : number ; value ?: Summary ; pending ?: Promise < Fetched > } > ( )
86138
87- /** Names of the selected documents that still exist, sorted ; null when the list could not be read . */
88- async function documentNames ( ids : number [ ] ) : Promise < string [ ] | null > {
139+ /** The account in use now, as a short digest ; null when there is no usable credential . */
140+ async function accountKey ( ) : Promise < string | null > {
89141 try {
90- const wanted = new Set ( ids )
91- const docs = await AltimateApi . listKnowledgeDocuments ( )
92- return docs
93- . filter ( ( d ) => wanted . has ( d . id ) && ! d . deleted )
142+ const c = await AltimateApi . getCredentials ( )
143+ if ( ! c . altimateApiKey ) return null
144+ return createHash ( "sha256" ) . update ( `${ c . altimateUrl } \u0000${ c . altimateInstanceName } \u0000${ c . altimateApiKey } ` ) . digest ( "hex" ) . slice ( 0 , 16 )
145+ } catch {
146+ return null
147+ }
148+ }
149+
150+ /** Selected documents that exist, resolved by id (at most MAX_LISTED_DOCUMENTS fetched). */
151+ async function selectedDocuments ( ids : number [ ] ) : Promise < WorkspaceKnowledge > {
152+ const head = ids . slice ( 0 , MAX_LISTED_DOCUMENTS )
153+ const unchecked = ids . length - head . length
154+ try {
155+ const docs = await Promise . all ( head . map ( ( id ) => AltimateApi . getKnowledgeDocument ( id ) ) )
156+ const names = docs
157+ . filter ( ( d ) : d is NonNullable < typeof d > => d !== null && ! d . deleted )
94158 . map ( ( d ) => clean ( d . name , 80 ) )
95159 . sort ( ( a , b ) => a . localeCompare ( b ) )
160+ return { kind : "selected" , count : names . length + unchecked , names }
96161 } catch {
97- return null
162+ return { kind : "selected" , count : ids . length , names : null }
98163 }
99164}
100165
101166async function knowledgeOf ( engineEnabled : boolean | undefined , ids : number [ ] | null | undefined ) : Promise < WorkspaceKnowledge | null > {
102167 if ( engineEnabled === undefined ) return null
103168 if ( ! engineEnabled ) return { kind : "off" }
104- const selected = ids ?? [ ]
105- if ( selected . length === 0 ) return { kind : "all" }
106- const names = await documentNames ( selected )
107- return { kind : "selected" , count : names ? names . length : selected . length , names }
169+ // Only an explicit empty selection means "every document"; a missing one is unknown.
170+ if ( ! Array . isArray ( ids ) ) return null
171+ if ( ids . length === 0 ) return { kind : "all" }
172+ return selectedDocuments ( ids )
108173}
109174
110- async function fetchSummary ( datamateId : number ) : Promise < Summary > {
175+ async function fetchSummary ( datamateId : number ) : Promise < Fetched > {
111176 try {
112177 const s = await AltimateApi . getDatamate ( String ( datamateId ) )
178+ const knowledge = await knowledgeOf ( s . knowledge_engine_enabled , s . knowledge_bases )
113179 return {
114- integrations : s . integrations ? s . integrations . map ( ( i ) => i . id ) . sort ( ) : [ ] ,
115- memoryEnabled : typeof s . memory_enabled === "boolean" ? s . memory_enabled : null ,
116- knowledge : await knowledgeOf ( s . knowledge_engine_enabled , s . knowledge_bases ) ,
180+ value : {
181+ integrations : Array . isArray ( s . integrations ) ? s . integrations . map ( ( i ) => i . id ) . sort ( ) : null ,
182+ memoryEnabled : typeof s . memory_enabled === "boolean" ? s . memory_enabled : null ,
183+ knowledge,
184+ } ,
185+ // A document list that could not be read is retried next step, not kept for five minutes.
186+ complete : ! ( knowledge ?. kind === "selected" && knowledge . names === null ) ,
117187 }
118188 } catch {
119- return UNKNOWN
189+ return { value : UNKNOWN , complete : false }
120190 }
121191}
122192
123- /** Integrations and memory setting, cached per workspace; a slow service yields "not known" this step. */
193+ /** Integrations, memory setting and knowledge, cached per account and workspace; a slow service
194+ * yields "not known" this step. */
124195export async function workspaceSummary ( datamateId : number , now = Date . now ( ) ) : Promise < Summary > {
125- const hit = summaries . get ( datamateId )
196+ const account = await accountKey ( )
197+ if ( account === null ) return UNKNOWN
198+ const key = `${ account } :${ datamateId } `
199+ const hit = summaries . get ( key )
126200 if ( hit ?. value && now - hit . at < SUMMARY_TTL_MS ) return hit . value
127201 let pending = hit ?. pending
128202 if ( ! pending ) {
129- pending = fetchSummary ( datamateId ) . then ( ( value ) => {
130- // A failed fetch (integrations unknown) is kept for this step only, so the next step retries.
131- summaries . set ( datamateId , { at : value . integrations === null ? 0 : Date . now ( ) , value } )
132- return value
203+ pending = fetchSummary ( datamateId ) . then ( ( fetched ) => {
204+ // An incomplete fetch is kept for this step only, so the next step retries.
205+ summaries . set ( key , { at : fetched . complete ? Date . now ( ) : 0 , value : fetched . value } )
206+ return fetched
133207 } )
134- summaries . set ( datamateId , { at : hit ?. at ?? 0 , value : hit ?. value , pending } )
208+ summaries . set ( key , { at : hit ?. at ?? 0 , value : hit ?. value , pending } )
135209 }
136210 const stale = hit ?. value ?? UNKNOWN
137211 let timer : ReturnType < typeof setTimeout > | undefined
138212 try {
139213 return await Promise . race ( [
140- pending ,
214+ pending . then ( ( f ) => f . value ) ,
141215 new Promise < Summary > ( ( done ) => {
142216 timer = setTimeout ( ( ) => done ( stale ) , SUMMARY_WAIT_MS )
143217 timer . unref ?.( )
@@ -150,21 +224,32 @@ export async function workspaceSummary(datamateId: number, now = Date.now()): Pr
150224
151225export function resetForTests ( ) : void {
152226 summaries . clear ( )
227+ parsedSnapshots . clear ( )
228+ snapshot = defaultSnapshot
153229}
154230
155- /** Pure formatter for the section. */
156- export function render ( contents : WorkspaceContents , cap = MAX_CONTENTS_CHARS ) : string {
231+ // ---------------------------------------------------------------------------
232+ // Rendering
233+ // ---------------------------------------------------------------------------
234+
235+ type SkillDetail = "full" | "names" | "count"
236+
237+ function renderWith ( contents : WorkspaceContents , detail : SkillDetail ) : string {
157238 const lines = [ "## What this Altimate Workspace provides" , "" ]
158- if ( contents . skills === null ) {
239+ const skills = contents . skills
240+ if ( skills === null ) {
159241 lines . push ( "Workspace skills: not synced to this project yet, so they cannot be listed." )
160- } else if ( contents . skills . length === 0 ) {
242+ } else if ( skills === "unknown" ) {
243+ lines . push ( "Workspace skills: could not be read just now; do not guess them." )
244+ } else if ( skills . length === 0 ) {
161245 lines . push ( "Workspace skills: none — this workspace has no custom skills." )
246+ } else if ( detail === "count" ) {
247+ lines . push ( `Workspace skills: ${ skills . length } (too many to list here; the skill list shows them by name).` )
162248 } else {
163- lines . push ( `Workspace skills (${ contents . skills . length } ):` )
164- for ( const s of contents . skills . slice ( 0 , MAX_LISTED_SKILLS ) )
165- lines . push ( s . description ? `- ${ s . name } — ${ s . description } ` : `- ${ s . name } ` )
166- if ( contents . skills . length > MAX_LISTED_SKILLS )
167- lines . push ( `- …and ${ contents . skills . length - MAX_LISTED_SKILLS } more` )
249+ lines . push ( `Workspace skills (${ skills . length } ):` )
250+ for ( const s of skills . slice ( 0 , MAX_LISTED_SKILLS ) )
251+ lines . push ( detail === "full" && s . description ? `- ${ s . name } — ${ s . description } ` : `- ${ s . name } ` )
252+ if ( skills . length > MAX_LISTED_SKILLS ) lines . push ( `- …and ${ skills . length - MAX_LISTED_SKILLS } more` )
168253 }
169254 if ( contents . integrations !== null )
170255 lines . push (
@@ -181,11 +266,10 @@ export function render(contents: WorkspaceContents, cap = MAX_CONTENTS_CHARS): s
181266 else if ( k ?. kind === "selected" && k . names === null )
182267 lines . push ( `Knowledge: ${ k . count } selected document${ k . count === 1 ? "" : "s" } (their names could not be loaded).` )
183268 else if ( k ?. kind === "selected" && k . names ) {
184- if ( k . names . length === 0 ) lines . push ( "Knowledge: none — the documents this workspace selected no longer exist." )
269+ if ( k . count === 0 ) lines . push ( "Knowledge: none — the documents this workspace selected no longer exist." )
185270 else {
186- const shown = k . names . slice ( 0 , MAX_LISTED_DOCUMENTS )
187- const more = k . names . length - shown . length
188- lines . push ( `Knowledge documents (${ k . names . length } ): ${ shown . join ( ", " ) } ${ more > 0 ? `, …and ${ more } more` : "" } .` )
271+ const more = k . count - k . names . length
272+ lines . push ( `Knowledge documents (${ k . count } ): ${ k . names . join ( ", " ) } ${ more > 0 ? `, …and ${ more } more` : "" } .` )
189273 }
190274 }
191275 lines . push (
@@ -195,22 +279,32 @@ export function render(contents: WorkspaceContents, cap = MAX_CONTENTS_CHARS): s
195279 "CLI and are available in every project; they are not part of the workspace — mention them only if " +
196280 "asked, under a separate \"built-in\" heading. Do not present every installed skill as the workspace's." ,
197281 )
198- let text = lines . join ( "\n" )
199- if ( text . length <= cap ) return text
200- // Drop descriptions before dropping skills; never cut an instruction mid-way.
201- const bare : WorkspaceContents = {
202- ...contents ,
203- skills : contents . skills ?. map ( ( s ) => ( { name : s . name , description : "" } ) ) ?? null ,
282+ return lines . join ( "\n" )
283+ }
284+
285+ /** Pure formatter for the section. Over the cap it drops skill descriptions, then lists only the
286+ * skill count; it never cuts an instruction mid-way and never drops the rest of the block. */
287+ export function render ( contents : WorkspaceContents , cap = MAX_CONTENTS_CHARS ) : string {
288+ for ( const detail of [ "full" , "names" , "count" ] as const ) {
289+ const text = renderWith ( contents , detail )
290+ if ( text . length <= cap ) return text
204291 }
205- text = render ( bare , Number . POSITIVE_INFINITY )
206- return text . length <= cap ? text : ""
292+ return ""
207293}
208294
209295/** The section for a bound workspace; "" on any failure, so prompt assembly never breaks. */
210296export async function section ( directory : string , datamateId : number ) : Promise < string > {
211297 try {
212- const [ skills , summary ] = await Promise . all ( [ workspaceSkills ( directory , datamateId ) , workspaceSummary ( datamateId ) ] )
213- return render ( { skills, ...summary } )
298+ let timer : ReturnType < typeof setTimeout > | undefined
299+ const skills = Promise . race ( [
300+ workspaceSkills ( directory , datamateId ) ,
301+ new Promise < "unknown" > ( ( done ) => {
302+ timer = setTimeout ( ( ) => done ( "unknown" ) , SKILLS_WAIT_MS )
303+ timer . unref ?.( )
304+ } ) ,
305+ ] ) . finally ( ( ) => timer && clearTimeout ( timer ) )
306+ const [ s , summary ] = await Promise . all ( [ skills , workspaceSummary ( datamateId ) ] )
307+ return render ( { skills : s , ...summary } )
214308 } catch {
215309 return ""
216310 }
0 commit comments