Skip to content

Commit 9e8f8a3

Browse files
feat: read the engine's unfulfilled-keys report instead of diffing declared vs delivered (#1308)
* feat: read the engine's unfulfilled-keys report instead of diffing declared vs delivered The MCP catalog now keeps the `_meta` of a server's last tools/list page per client, exposed as `MCP.listMeta(name)`. On attach, the gaps come from the engine's `ai.altimate/unfulfilled` report, grouped by reason in the toast and headless line with the engine's detail (e.g. `spawn docker ENOENT`); `no-bridge` entries stay out of the missing set as before. The attached outcome carries the full report. `MIN_ENGINE_VERSION` moves to 0.7.2, the first engine that emits it; an engine that sends none claims no gaps rather than inventing them. Closes #1307 Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01GHBUvb843k1R7UAGi8Ya9b * test: end-to-end through the MCP service against a real engine Env-guarded (`ALTIMATE_ENGINE_E2E_ROOT`), skipped otherwise: spawns a built engine over stdio the way the overlay does, against a fake Altimate API and a real second MCP server, and reads the `ai.altimate/unfulfilled` report through `MCP.listMeta` into the attach toast text. The engine is a node shebang script, so the test spawns node rather than the bun test runner. Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01GHBUvb843k1R7UAGi8Ya9b * chore: wrap the catalog _meta hunks in altimate_change markers Marker Guard flagged the changed lines in the upstream-shared catalog; the single-line marker comments did not count as a wrapped block. Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01GHBUvb843k1R7UAGi8Ya9b * fix: accept numeric integration ids in the engine report Custom (tenant-created) integrations carry numeric ids; the parser treated the whole report as malformed over that one field and the attach announced no gaps at all. Take the id as a string. Found by the engine-to-CLI run against a local backend with a custom MCP integration. Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01GHBUvb843k1R7UAGi8Ya9b * fix(workspace): commit the tools and their report together, and say what a gap is with its own detail Answers the multi-model review of the unfulfilled report, client half. - the tools of a listing and its _meta are committed in one statement (State.meta beside State.defs) and read through one accessor, MCP.snapshot(name): a refresh that is pending or that failed leaves the last good pair standing, and the overlay can no longer pair one listing's tools with another's report - the catalog commits _meta when a listing completes — the last page that carries one wins, a listing with none clears it — instead of clearing at the start - served counts compare the declared keys in the catalog's sanitised key space, so the headline cannot undercount a served tool whose raw key the MCP layer renamed - the missing line groups by reason AND integration, so one integration's error is never printed as another's - spawn-failed reads 'server could not be started or reached', which is what the engine records under it Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01GHBUvb843k1R7UAGi8Ya9b * fix(workspace): a listing carries its own _meta, and the headline never counts a reported key Answers the Codex round on the report fixes: - McpCatalog.defsWithMeta returns the listing and its _meta as one value, and every commit of a listing stores that pair — not a per-client value another refresh may have overwritten while this one was awaiting - served counts exclude keys the engine reports unfulfilled, so two raw keys that sanitise to one catalog name cannot both count as served - parseUnfulfilled rejects an entry whose detail is present but not a string, failing closed like the other fields Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01GHBUvb843k1R7UAGi8Ya9b * fix(workspace): the headline counts catalog entries, not declarations Two raw keys that sanitise to one catalog name are one callable tool however many the engine lists; served and extension counts are the number of distinct sanitised entries that are present and unreported. Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01GHBUvb843k1R7UAGi8Ya9b * fix(workspace): a catalog entry is counted once across the ordinary and extension groups Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01GHBUvb843k1R7UAGi8Ya9b * chore(workspace): wrap the two remaining hunks in altimate_change markers Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01GHBUvb843k1R7UAGi8Ya9b * chore(workspace): markers around the listing hunks the guard still saw as bare Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01GHBUvb843k1R7UAGi8Ya9b * fix(workspace): require engine 0.7.3 for the unfulfilled-keys report Datamate 0.7.2 was released without the `ai.altimate/unfulfilled` report, which now ships in 0.7.3. `MIN_ENGINE_VERSION` moves to 0.7.3 so a 0.7.2 engine no longer clears the floor and announces no gaps. The tests that pin the floor and the overlay harness's default engine version follow. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_0172qrhMa5TQgETASi5hxMqD * fix(workspace): mask the engine's error text and match the notice to what is callable - Mask each gap's `detail` when the report is parsed (control characters collapsed, then `Telemetry.maskString`, the same treatment as subprocess stderr), so the attach toast and the attach log both carry the masked text. - Warn when fewer declared tools are callable than were declared, even with an empty report (two raw keys that sanitise to one catalog entry). With no report nothing is claimed, so that case stays `info`. - Re-announce when a gap's integration or error text changes under the same reason, so the toast never keeps stale remediation. - Log a warning when a report is present but malformed and is dropped. - The real-engine e2e test removes its temporary HOME. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_0172qrhMa5TQgETASi5hxMqD * test(mcp): list through a scripted client so leaked SDK mocks cannot empty it `bun test` runs the suite in one process and `mock.module` is process-wide. `mcp.test.ts` mocks `@modelcontextprotocol/sdk/client/index.js` with a client whose `listTools` returns no tools, so when it ran first the catalog `_meta` tests listed nothing. They now drive `McpCatalog` through a scripted client (the only method the catalog calls is `listTools`). The SDK's own `_meta` passthrough stays covered by the real-engine e2e test. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_0172qrhMa5TQgETASi5hxMqD * fix(workspace): log a malformed engine report before deduplicating the announcement A malformed report can share its announcement signature with an earlier empty or absent one, so the warning placed after the dedupe never fired for that transition. The session record now remembers whether the last report was malformed; the warning is checked before the dedupe and logged once per transition into that state, without a second toast. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_0172qrhMa5TQgETASi5hxMqD * fix(workspace): announce every changed verdict, and commit only the latest tool refresh From the review bots on the ready PR: - The attach signature carries whether a report arrived and the served declared count, so "no report" → "empty report" (a severity change) and an equal-total swap of which declared tools are served are both announced. - Only consecutive attached turns carry the malformed-report flag, so the next malformed report after a refusal is logged as a new transition. - A `tools/list_changed` refresh that a later one overtook drops its listing, so an out-of-order completion never writes older tools and report over newer. - The overlay test fixture defaults to no report; the tests about the report pass one explicitly. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_0172qrhMa5TQgETASi5hxMqD * fix(mcp): keep an older successful refresh when a newer one fails Refreshes commit unless a newer one already has, so an out-of-order completion never overwrites newer tools, and a failed newer refresh no longer discards an older one that succeeded. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_0172qrhMa5TQgETASi5hxMqD * fix(workspace): announce a swap of which declared tool is served at an equal count The attach verdict was keyed on the served count, so replacing one callable declared tool with another at the same total left the notice unannounced. Key it on the callable catalog entries themselves. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_0172qrhMa5TQgETASi5hxMqD * fix(mcp): drop a connect that a newer add, connect, disconnect or remove superseded createAndStore committed its result on resume without checking whether the server had changed while it connected, so a remove brought the server back and an older config overwrote a newer one. Each call now takes a per-server generation; a connect that resumes behind a newer one closes its own client instead of committing. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_0172qrhMa5TQgETASi5hxMqD * fix(mcp): take the server's token before the first suspension, and re-check it after each connect and disconnect took theirs after the config lookup, so a remove that landed during the lookup could be undone. Mutations that followed a client close could delete a newer call's state. A superseded connect still persisted enabled: true, undoing a newer disconnect on disk. Every add, connect, disconnect, remove and OAuth completion now takes its token first, writes only while it is current, and connect persists only while it is. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_0172qrhMa5TQgETASi5hxMqD * chore(mcp): mark the changed createAndStore signature Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_0172qrhMa5TQgETASi5hxMqD * chore(mcp): keep disconnect's upstream lines in place around the token Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_0172qrhMa5TQgETASi5hxMqD * fix(mcp): order lifecycle calls when they start, before the state lookup Two calls queued on the first state lookup could resume in either order and number themselves accordingly. Each call now takes a sequence number before anything suspends, and a later number always wins. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_0172qrhMa5TQgETASi5hxMqD * fix(mcp): re-check the call's token inside the queued enabled-flag write A disconnect's write could wait in the queue while a later add connected the server, then write enabled: false over it. The write now asks whether its call is still the latest, when it starts and again right before it touches the file. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_0172qrhMa5TQgETASi5hxMqD * test(release-validation): assert the enabled-flag writes with their current check Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_0172qrhMa5TQgETASi5hxMqD * fix(mcp): check a call's token before its first write, in add and remove A stale add wrote the runtime config, and a stale remove closed the newer client, before either found it had been superseded. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_0172qrhMa5TQgETASi5hxMqD * fix(mcp): `authenticate()` takes a token, so a remove during its listing wins The already-authorized path listed tools and committed the client with no check, so a server removed meanwhile came back connected. It now claims a token first, like `finishAuth`, and closes its client if a newer call owns the server. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_0172qrhMa5TQgETASi5hxMqD * fix(mcp): `authenticate()` clears only its own OAuth state A token check around the clear could not stop an older call, waiting on the auth file lock, from deleting a newer flow's state. `clearOAuthState` now takes the expected state and compares it inside the lock. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_0172qrhMa5TQgETASi5hxMqD * fix(mcp): keep `createAndStore`'s state lookup inside its marker block The previous change shifted the diff, so Marker Guard read the upstream lookup as unmarked. The race test now also asserts that a superseded `authenticate()` returns `disabled`. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_0172qrhMa5TQgETASi5hxMqD * fix(mcp): a superseded auth call reports the newer call's status `authenticate()` returned `failed` when its listing failed after a remove, and a superseded `finishAuth()` returned its own `connected`. Both now report the status of the call that won. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_0172qrhMa5TQgETASi5hxMqD * fix(mcp): finish an OAuth flow as the call that began it `finishAuth` claimed a new token, so a late callback could reconnect a server removed or disconnected after the flow began. Each pending flow now records its lifecycle token and transport. The browser path clears only its own state, and remove and `removeAuth` drop pending flows. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_0172qrhMa5TQgETASi5hxMqD * fix(mcp): `disconnect` drops a pending OAuth transport, like `remove` A transport a connect left behind has no recorded flow, so finishing it after a disconnect was a new call that reconnected the disabled server. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_0172qrhMa5TQgETASi5hxMqD * fix: only a flow begun by `startAuth` or `authenticate` can be finished - A `startAuth` superseded during setup publishes no flow and clears its own OAuth state. - `finishAuth` refuses a transport a connect left behind. - `removeAuth` removes credentials and pending flows only while its claim holds. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_0172qrhMa5TQgETASi5hxMqD * fix: a superseded sign-in start never overwrites a newer flow's OAuth state `beginAuth` stores its state only while it still owns the server, checked inside the auth file lock (`McpAuth.updateOAuthState(name, state, current)`), and stops before connecting when a later call has claimed the server. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_0172qrhMa5TQgETASi5hxMqD --------- Co-authored-by: ralphstodomingo <[email protected]> Co-authored-by: Claude Fable 5.1 <[email protected]>
1 parent 3ab191c commit 9e8f8a3

19 files changed

Lines changed: 2021 additions & 104 deletions

‎packages/opencode/src/altimate/workspace/engine-overlay.ts‎

Lines changed: 92 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@
2525
// that turn's start.
2626
import { DATAMATE_KEY } from "@/altimate/datamate-transport"
2727
import { MCP } from "@/mcp"
28+
import { sanitize } from "@/mcp/catalog"
2829
import { Config } from "@/config/config"
2930
import {
3031
currentDirectory,
@@ -45,6 +46,8 @@ import {
4546
clearsFloor,
4647
describeExtensionServed,
4748
describeMissing,
49+
parseUnfulfilled,
50+
reportedMissing,
4851
describeRefusal,
4952
engineEntry,
5053
engineToolKeys,
@@ -55,6 +58,7 @@ import {
5558
type McpStatus,
5659
type Outcome,
5760
type Toast,
61+
UNFULFILLED_META_KEY,
5862
} from "./engine-types"
5963

6064
export * from "./engine-types"
@@ -301,7 +305,14 @@ export async function managedWorkspaceLoaded(
301305

302306
/** `retried`: this session already spent its one re-add on a failed handshake.
303307
* Per session, so "start a new session to try again" is true. */
304-
type SessionRecord = { outcome: Outcome; announced?: string; announcedAt?: number; retried?: boolean }
308+
type SessionRecord = {
309+
outcome: Outcome
310+
announced?: string
311+
announcedAt?: number
312+
retried?: boolean
313+
/** The last attach saw a report it had to drop as malformed. */
314+
reportMalformed?: boolean
315+
}
305316
const sessions = new Map<string, SessionRecord>()
306317
const declaredCache = new Map<string, { value: Declared | null; at: number }>()
307318
/** Verdict signatures a headless process has already printed to stderr. */
@@ -315,6 +326,9 @@ function record(sessionID: string, outcome: Outcome): SessionRecord {
315326
announced: previous?.announced,
316327
announcedAt: previous?.announcedAt,
317328
retried: previous?.retried,
329+
// Only consecutive attached turns share it; anything in between resets it, so
330+
// the next malformed report is logged as a new transition. (bot review)
331+
reportMalformed: outcome.kind === "attached" ? previous?.reportMalformed : false,
318332
}
319333
sessions.set(sessionID, next)
320334
while (sessions.size > MAX_TRACKED_SESSIONS) {
@@ -338,6 +352,9 @@ function mcp() {
338352
add: (name: string, cfg: LocalMcpConfig | McpEntry) => MCP.add(name, cfg as Parameters<typeof MCP.add>[1]),
339353
remove: (name: string) => MCP.remove(name),
340354
tools: () => MCP.tools() as Promise<Record<string, unknown>>,
355+
listMeta: (name: string) => MCP.listMeta(name),
356+
snapshot: (name: string) =>
357+
MCP.snapshot(name) as Promise<{ tools: Record<string, unknown>; meta: Record<string, unknown> | undefined }>,
341358
}
342359
)
343360
}
@@ -656,20 +673,54 @@ async function reconcile(sessionID: string, directory: string, state: DirectoryS
656673
return
657674
}
658675

659-
const present = engineToolKeys(await mcp().tools())
660-
const missing = declared ? declared.keys.filter((k) => !present.has(k)) : undefined
676+
// One read for both: a tools/list refresh that completes between two separate
677+
// reads would pair one listing's tools with another's report. (multi-model review)
678+
const { tools, meta } = await mcp().snapshot(DATAMATE_KEY)
679+
const present = engineToolKeys(tools)
680+
// The gaps come from the engine's own report, with reasons; this client no
681+
// longer diffs the allowlist against what arrived. No report (nothing at or
682+
// above the floor omits it) means no gap is claimed, not that there is none.
683+
const unfulfilled = parseUnfulfilled(meta)
684+
const missingReport = unfulfilled === undefined ? undefined : reportedMissing(unfulfilled)
685+
const missing = missingReport?.map((u) => u.key)
661686
// `available` is everything the engine serves under the key. The engine adds
662687
// tools beyond the allowlist (knowledge, memory) when the workspace enables
663688
// them, so the "N of M declared" line counts only the declared ones present.
664-
const served = declared ? declared.keys.length - (missing?.length ?? 0) : present.size
689+
// Compared in the catalog's key space: `present` holds tool names as the MCP
690+
// layer sanitised them (`[a-zA-Z0-9_-]`), while the declaration carries the
691+
// raw keys, so a raw key with any other character would never count as served
692+
// and the headline would disagree with a report that names no gap. (multi-model review)
693+
// And never a key the engine itself reports as unfulfilled: two raw keys can
694+
// sanitise to one catalog name, and the report is the authority on which of
695+
// them the served tool stands for. (codex)
696+
// And counted per catalog entry, not per declaration: two raw keys that both
697+
// sanitise to `foo_bar` are one callable tool however many the engine lists.
698+
// Consumed across both groups: an ordinary key and an extension key that
699+
// collide are still one entry, counted where it is met first — with the
700+
// ordinary keys, which are counted first.
701+
const reported = new Set((unfulfilled ?? []).map((u) => u.key))
702+
const consumed = new Set<string>()
703+
const servedEntries = (keys: string[]) => {
704+
let n = 0
705+
for (const k of keys) {
706+
const entry = sanitize(k)
707+
if (!present.has(entry) || reported.has(k) || consumed.has(entry)) continue
708+
consumed.add(entry)
709+
n += 1
710+
}
711+
return n
712+
}
713+
const served = declared ? servedEntries(declared.keys) : present.size
665714
// Extension-declared tools appear in `present` only while the engine holds a
666715
// live IDE bridge; when they do they are real capability and the line names
667716
// them, but their absence is the normal no-IDE case, never `missing`.
668-
const extServed = declared ? declared.extensionKeys.filter((k) => present.has(k)).length : 0
717+
const extServed = declared ? servedEntries(declared.extensionKeys) : 0
669718
const outcome: Outcome = {
670719
kind: "attached",
671720
available: present.size,
672-
...(declared ? { declared: declared.keys.length, missing } : {}),
721+
...(declared ? { declared: declared.keys.length } : {}),
722+
...(missing === undefined ? {} : { missing }),
723+
...(unfulfilled === undefined ? {} : { unfulfilled }),
673724
...(declared?.extensions?.length ? { extensions: declared.extensions } : {}),
674725
}
675726
const rec = record(sessionID, outcome)
@@ -678,22 +729,51 @@ async function reconcile(sessionID: string, directory: string, state: DirectoryS
678729
// extServed is part of what the user hears, so it is part of the signature:
679730
// an equal-count tool swap that changes only the extension share must still
680731
// re-announce. (bot review)
681-
const signature = `attached:${workspace.key}:${outcome.available}:${outcome.declared ?? "?"}:${(missing ?? []).join(",")}:${extServed}`
732+
// A gap whose reason changed (a connection fixed, a binary still absent)
733+
// is a new verdict too, so the reasons are in the signature — and so are the
734+
// integration and the error text, which the toast's remediation is built
735+
// from. (multi-model review)
736+
// No report and an empty report are different verdicts (the severity rule
737+
// differs), and so is a change in which declared tools are callable at an equal
738+
// total, so both are in the signature too: the catalog entries themselves, not
739+
// their count, or a swap at an equal count goes unheard. (bot review, codex)
740+
const gaps =
741+
unfulfilled === undefined
742+
? "no-report"
743+
: JSON.stringify((missingReport ?? []).map((u) => [u.integrationId, u.key, u.reason, u.detail ?? ""]))
744+
const callable = JSON.stringify([...consumed].sort())
745+
const signature = `attached:${workspace.key}:${outcome.available}:${outcome.declared ?? "?"}:${served}:${callable}:${gaps}:${extServed}`
746+
// A report that is present but malformed is dropped whole (no gap is claimed);
747+
// say so in the log, or the missing reasons are a silent mystery. Checked before
748+
// the announcement is deduplicated, since a malformed report can share its
749+
// signature with an earlier empty or absent one, and logged once per transition
750+
// into that state rather than on every turn. (codex)
751+
const malformed = unfulfilled === undefined && meta?.[UNFULFILLED_META_KEY] !== undefined
752+
if (malformed && !rec.reportMalformed)
753+
log.warn("workspace engine report was malformed; showing no gaps", { workspaceId: workspace.id })
754+
rec.reportMalformed = malformed
682755
if (rec.announced === signature) return
683756
rec.announced = signature
684757
log.info("workspace engine attached", {
685758
workspaceId: workspace.id,
686759
available: outcome.available,
687760
declared: outcome.declared,
688-
missing,
761+
unfulfilled,
689762
})
690763
if (isHeadless()) return
764+
const headline = declared
765+
? `${served} of ${declared.keys.length} declared integration tools available.`
766+
: `${outcome.available} integration tools available.`
691767
await notify({
692768
title: `Workspace "${workspace.name}"`,
693-
message: declared
694-
? `${served} of ${declared.keys.length} declared integration tools available.${describeMissing(missing ?? [])}${describeExtensionServed(extServed)}`
695-
: `${outcome.available} integration tools available.`,
696-
variant: missing && missing.length > 0 ? "warning" : "info",
769+
message: `${headline}${describeMissing(missingReport ?? [])}${describeExtensionServed(extServed)}`,
770+
// Severity follows what is callable, not only what is reported: two raw
771+
// keys that sanitise to one catalog entry leave the headline short with an
772+
// empty report. With no report nothing is claimed, so that stays info.
773+
variant:
774+
(missingReport?.length ?? 0) > 0 || (unfulfilled !== undefined && !!declared && served < declared.keys.length)
775+
? "warning"
776+
: "info",
697777
})
698778
}
699779

‎packages/opencode/src/altimate/workspace/engine-seams.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,8 @@ export const syncInternals: {
5050
add: (name: string, cfg: LocalMcpConfig | McpEntry) => Promise<unknown>
5151
remove: (name: string) => Promise<unknown>
5252
tools: () => Promise<Record<string, unknown>>
53+
listMeta: (name: string) => Promise<Record<string, unknown> | undefined>
54+
snapshot: (name: string) => Promise<{ tools: Record<string, unknown>; meta: Record<string, unknown> | undefined }>
5355
}
5456
config?: {
5557
invalidate: () => Promise<void>

‎packages/opencode/src/altimate/workspace/engine-types.ts‎

Lines changed: 115 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
// derived MCP entry, and the pure predicates over them. Nothing here performs
55
// I/O or reads ambient state.
66
import { DATAMATE_KEY } from "@/altimate/datamate-transport"
7+
import { Telemetry } from "@/telemetry"
78

89
/** Oldest engine this client works against.
910
*
@@ -14,9 +15,12 @@ import { DATAMATE_KEY } from "@/altimate/datamate-transport"
1415
* workspace promise rests on: integrations configured purely in the workspace
1516
* UI must produce working tools with no local files. It also passes the
1617
* resolved connection to MCP-type handlers, so their credential placeholders
17-
* resolve. A 0.7.0 engine holds the pin but serves none of those tools, which
18-
* is why the floor is 0.7.1. */
19-
export const MIN_ENGINE_VERSION = "0.7.1"
18+
* resolve. A 0.7.0 engine holds the pin but serves none of those tools. 0.7.3
19+
* is the first that reports, on every tools/list, the allowlist keys it could
20+
* not serve and why (`UNFULFILLED_META_KEY`; 0.7.2 shipped without it); this
21+
* client no longer diffs the allowlist itself, so below 0.7.3 it would announce
22+
* no gaps at all. */
23+
export const MIN_ENGINE_VERSION = "0.7.3"
2024
export const ENGINE_PACKAGE = "@altimateai/datamate"
2125
export const ENGINE_BINARY = "datamate"
2226
export const INSTALL_COMMAND = `npm i -g ${ENGINE_PACKAGE}@${MIN_ENGINE_VERSION}`
@@ -33,7 +37,11 @@ export type Outcome =
3337
kind: "attached"
3438
available: number
3539
declared?: number
40+
/** Keys of `unfulfilled` that count as gaps (see `reportedMissing`). */
3641
missing?: string[]
42+
/** The engine's full report, `no-bridge` entries included; absent when
43+
* the engine sent none. */
44+
unfulfilled?: Unfulfilled[]
3745
/** The allowlist's extension-type integrations, when it names any: what a
3846
* live IDE bridge could serve. Whether they are present is decided per turn
3947
* against the catalog, never recorded here. */
@@ -225,11 +233,111 @@ export function describeRefusal(
225233
)
226234
}
227235

228-
export function describeMissing(missing: string[]): string {
236+
/** Where the engine (0.7.3+) reports the allowlist keys it could not serve,
237+
* on every tools/list response, so the client never diffs the allowlist
238+
* against what arrived: a diff can name the keys, never the reason. */
239+
export const UNFULFILLED_META_KEY = "ai.altimate/unfulfilled"
240+
241+
export type UnfulfilledReason =
242+
| "catalog-missing"
243+
| "invalid-connection"
244+
| "spawn-failed"
245+
| "no-bridge"
246+
| "unknown-key"
247+
| "exception"
248+
249+
/** One declared key the engine did not serve, in the engine's own words. A
250+
* reason outside the known set is kept verbatim: a newer engine may add one. */
251+
export type Unfulfilled = {
252+
key: string
253+
integrationId: string
254+
reason: UnfulfilledReason | (string & {})
255+
detail?: string
256+
}
257+
258+
/** The engine's error text as the toast and the log may carry it: control
259+
* characters collapsed and masked the way subprocess stderr is (`mcp/index.ts`).
260+
* The engine allowlists what it sends at the version floor; this is the
261+
* client's own guard, not a second allowlist. (multi-model review) */
262+
function cleanDetail(detail: string): string {
263+
return Telemetry.maskString(detail.replace(/[\u0000-\u001f\u007f]+/g, " ").trim())
264+
}
265+
266+
/** The engine's report out of a tools/list `_meta`. Undefined when there is
267+
* none, or it is malformed: the caller then knows nothing about gaps, which
268+
* is not the same as knowing there are none. */
269+
export function parseUnfulfilled(meta: Record<string, unknown> | undefined): Unfulfilled[] | undefined {
270+
const raw = meta?.[UNFULFILLED_META_KEY]
271+
if (!Array.isArray(raw)) return undefined
272+
const out: Unfulfilled[] = []
273+
for (const item of raw) {
274+
if (typeof item !== "object" || item === null) return undefined
275+
const { key, integrationId, reason, detail } = item as Record<string, unknown>
276+
// Custom (tenant-created) integrations carry numeric ids; take them as strings.
277+
const id = typeof integrationId === "number" ? String(integrationId) : integrationId
278+
if (typeof key !== "string" || typeof id !== "string" || typeof reason !== "string") return undefined
279+
// A present `detail` must be a string: an entry with a malformed one is a
280+
// malformed report, not a report with one field dropped. Fails closed like
281+
// the fields above. (codex)
282+
if (detail !== undefined && typeof detail !== "string") return undefined
283+
const shown = detail ? cleanDetail(detail) : ""
284+
out.push({ key, integrationId: id, reason, ...(shown ? { detail: shown } : {}) })
285+
}
286+
return out
287+
}
288+
289+
/** Absent extension tools without an IDE window are expected, not missing:
290+
* `no-bridge` entries never join the "declared but not available" line.
291+
* Everything else the engine reports is a real gap. */
292+
export function reportedMissing(unfulfilled: Unfulfilled[]): Unfulfilled[] {
293+
return unfulfilled.filter((u) => u.reason !== "no-bridge")
294+
}
295+
296+
const REASON_PHRASE: Record<UnfulfilledReason, string> = {
297+
"invalid-connection": "no usable connection",
298+
// The engine records transport construction, connect AND list failures under
299+
// this one reason, so the phrase must not claim more than "could not be reached".
300+
"spawn-failed": "server could not be started or reached",
301+
"catalog-missing": "no longer in the catalog",
302+
"unknown-key": "not offered by the integration",
303+
exception: "failed to load",
304+
"no-bridge": "needs a VS Code window",
305+
}
306+
307+
const MISSING_SHOWN = 5
308+
const DETAIL_CHARS = 60
309+
310+
/** The gaps, grouped by reason AND integration in report order, at most
311+
* `MISSING_SHOWN` keys across the groups; a group's first detail (the engine's
312+
* error text, e.g. `spawn docker ENOENT`) stands for the group. Grouped per
313+
* integration so one integration's error is never printed as another's — two
314+
* servers that both failed to start failed for their own reasons. (multi-model review) */
315+
export function describeMissing(missing: Unfulfilled[]): string {
229316
if (missing.length === 0) return ""
230-
const shown = missing.slice(0, 5).join(", ")
231-
const more = missing.length > 5 ? ` (+${missing.length - 5} more)` : ""
232-
return ` Declared but not available: ${shown}${more}.`
317+
const groups = new Map<string, { reason: string; keys: string[]; detail?: string }>()
318+
for (const u of missing) {
319+
const id = `${u.reason}${u.integrationId}`
320+
const group = groups.get(id) ?? { reason: u.reason, keys: [] }
321+
group.keys.push(u.key)
322+
if (group.detail === undefined && u.detail) group.detail = u.detail
323+
groups.set(id, group)
324+
}
325+
let budget = MISSING_SHOWN
326+
const parts: string[] = []
327+
for (const { reason, ...group } of groups.values()) {
328+
if (budget <= 0) break
329+
const shown = group.keys.slice(0, budget)
330+
budget -= shown.length
331+
const phrase = (REASON_PHRASE as Record<string, string>)[reason] ?? reason
332+
const detail = group.detail === undefined ? "" : ` (${truncate(group.detail, DETAIL_CHARS)})`
333+
parts.push(`${phrase}${detail}: ${shown.join(", ")}`)
334+
}
335+
const more = missing.length > MISSING_SHOWN ? ` (+${missing.length - MISSING_SHOWN} more)` : ""
336+
return ` Declared but not available — ${parts.join("; ")}${more}.`
337+
}
338+
339+
function truncate(text: string, max: number): string {
340+
return text.length <= max ? text : `${text.slice(0, max - 1)}…`
233341
}
234342

235343
/** Extension-declared tools a connected IDE bridge is actually serving. Zero

0 commit comments

Comments
 (0)