Skip to content

Commit 62eff06

Browse files
sahrizviclaude
andcommitted
fix(workspace): scope, verify and bound the workspace contents block (review)
From the bot reviews on this PR: - Summaries are cached per account AND workspace id (workspace ids are per tenant), and nothing is fetched without a usable credential. - `snapshotWorkspaceId` validates and reads one manifest object, so a sync that swaps the tree between two reads cannot pair one account's check with another's workspace id. - Unknown stays unknown: an omitted integrations list is not "none", and an omitted or null knowledge selection is not "every document" — only an explicit empty selection is. - Knowledge documents are resolved by id (`GET /knowledge_bases/{id}`, at most 20) instead of listing the hub, whose list returns every document's full text. A 404 or deleted document is left out; a response that is not a document is an error, shown as "names could not be loaded" and retried next step rather than cached for five minutes. - A workspace the last sync found empty is reported as having no custom skills, not as "not synced" (an empty workspace leaves no snapshot to read). - The snapshot is parsed once per published tree (keyed on the root's inode and mtime) and each step waits at most 300 ms for it; past that, skills are "could not be read just now". - A link that could not be re-verified ("last known") gets no contents block. - Over the size cap the block drops skill descriptions, then lists only the skill count; it no longer disappears with the integrations, memory and knowledge lines. - Tests restore every spy in `afterEach`, and the slow-service test asserts the 300 ms bound with scheduling tolerance. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_018fJ3X7pcGT4R9yzjsJnqsV
1 parent 40c6cf6 commit 62eff06

7 files changed

Lines changed: 374 additions & 171 deletions

File tree

‎packages/opencode/src/altimate/api/client.ts‎

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -292,17 +292,23 @@ export namespace AltimateApi {
292292
}
293293
}
294294

295-
/** The tenant's knowledge hub documents, as id, name and whether deleted. */
296-
export async function listKnowledgeDocuments(): Promise<Array<{ id: number; name: string; deleted: boolean }>> {
295+
/**
296+
* One knowledge hub document as id, name and whether deleted; null when it does not exist
297+
* (404). Fetched by id rather than listing the hub, whose list returns every document's full
298+
* text. A response that is not a document is an error, never "no document".
299+
*/
300+
export async function getKnowledgeDocument(id: number): Promise<{ id: number; name: string; deleted: boolean } | null> {
297301
const creds = await getCredentials()
298-
const data = await request(creds, "GET", "/knowledge_bases/")
299-
const list: unknown[] = Array.isArray(data) ? data : (data?.knowledge_bases ?? data?.data ?? [])
300-
const out: Array<{ id: number; name: string; deleted: boolean }> = []
301-
for (const item of list) {
302-
const parsed = KnowledgeDocument.safeParse(item)
303-
if (parsed.success) out.push({ id: parsed.data.id, name: parsed.data.name, deleted: parsed.data.is_deleted === true })
302+
let data: unknown
303+
try {
304+
data = await request(creds, "GET", `/knowledge_bases/${id}`)
305+
} catch (e) {
306+
if (e instanceof Error && e.message.includes("status 404")) return null
307+
throw e
304308
}
305-
return out
309+
const parsed = KnowledgeDocument.safeParse(data)
310+
if (!parsed.success) throw new Error(`Unrecognised knowledge document response for id ${id}`)
311+
return { id: parsed.data.id, name: parsed.data.name, deleted: parsed.data.is_deleted === true }
306312
}
307313

308314
export async function createDatamate(payload: {

‎packages/opencode/src/altimate/workspace/contents.ts‎

Lines changed: 156 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,13 @@
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".
1012
import fs from "fs/promises"
1113
import path from "path"
14+
import { createHash } from "crypto"
1215
import { ConfigMarkdown } from "@/config/markdown"
1316
import { AltimateApi } from "@/altimate/api/client"
1417
import * 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
*/
2528
export 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

3137
export 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
4554
const MAX_DESCRIPTION_CHARS = 100
4655
const SUMMARY_TTL_MS = 5 * 60_000
4756
const 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. */
5061
function 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+
83131
type Summary = { integrations: string[] | null; memoryEnabled: boolean | null; knowledge: WorkspaceKnowledge | null }
84132
const 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

101166
async 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. */
124195
export 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

151225
export 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. */
210296
export 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
}

‎packages/opencode/src/altimate/workspace/identity.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -408,7 +408,9 @@ async function lastKnown(key: string, directory: string): Promise<BindingOutcome
408408
* as a separate block under its own cap: `render` drops the identity section entirely when it
409409
* overflows, and a long skill list must not take the link statement down with it. */
410410
async function withContents(outcome: BindingOutcome, directory: string, identity: string): Promise<string> {
411-
if (!identity || outcome.status !== "bound") return identity
411+
// A stale outcome is a link that could not be confirmed and may have changed; the identity text
412+
// says "last known". Listing that workspace's contents would present it as current, so skip them.
413+
if (!identity || outcome.status !== "bound" || outcome.stale) return identity
412414
const contents = await Contents.section(directory, outcome.binding.datamateId).catch(() => "")
413415
return contents ? `${identity}\n\n${contents}` : identity
414416
}

0 commit comments

Comments
 (0)