Skip to content

Commit 2bd6632

Browse files
feat(workspace): tell the model about extension tools a live IDE bridge serves (#1291)
* feat(workspace): tell the model about extension tools a live IDE bridge serves The `## Workspace integrations` section projected only the three warehouse capabilities per connection type, so extension-type tools the engine serves through a live VS Code bridge (the dbt project tools, sql-tools) never reached the model even when they sat in its catalog. The presentation surfaces learned about them in #1236; this is the model-facing half. - `declared()` groups the extension keys under their catalog integration (`Declared.extensions`, optional so the flat lists stay the contract), and the attach outcome carries the groups so precedence never makes a second lookup. - `derive` names an extension tool only when two signals agree: its key materialised in the live catalog AND a bridge for this project is live now. Either missing is silence, not a warning. The tools ride on the `nothing-materialised` snapshot too, since a workspace can serve extension tools and no warehouse capability at all. - `servedExtensions` applies the same reachability filter as the warehouse inventory, at projection time, so an `analyst` is never told about tools it may not call. - The section appends the groups under a fixed intro naming the condition they depend on; a workspace with extension tools and nothing routed gets an extension-only shape that keeps the local-tools sentence. Extension lines are dropped before any warehouse type when the cap is hit. Every snapshot without extension tools renders byte-for-byte what it did before, including all silent disabled states. Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01GHBUvb843k1R7UAGi8Ya9b * fix(workspace): a claim about this project's bridge needs a verified pid, not a pidless sidecar liveBridge's option is now { claim }: for the prompt's sentence about the window open on this project, a recorded folder match on a sidecar whose pid is verified alive, or nothing. The sole-bridge fallback and the pidless-sidecar tolerance stay for the attach path, which mirrors the engine's own discovery. Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01GHBUvb843k1R7UAGi8Ya9b * fix(workspace): the live-bridge seam carries the claim option through So a test that stands in for the sidecar read sees whether the caller asked for a claim. Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01GHBUvb843k1R7UAGi8Ya9b * test(workspace): pin that the bridge probe is asked as a claim through the seam Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01GHBUvb843k1R7UAGi8Ya9b --------- Co-authored-by: ralphstodomingo <[email protected]> Co-authored-by: Claude Fable 5.1 <[email protected]>
1 parent c483691 commit 2bd6632

10 files changed

Lines changed: 588 additions & 36 deletions

File tree

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

Lines changed: 110 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -30,10 +30,25 @@
3030
// still be in the catalog while routing refuses them, and silence would leave the
3131
// model free to call what it can see. `DISABLED_COPY` below is the decision table.
3232
//
33+
// Extension-type tools (served through a live VS Code bridge) are the section's other
34+
// list. They shadow nothing, so they are awareness only; they are named only when
35+
// precedence has them as really served (in the catalog AND behind a live bridge —
36+
// see `extensionsServed` in precedence.ts), and a dormant bridge is silence, not a
37+
// warning. One consequence for the table: `nothing-materialised` speaks when it
38+
// carries extension tools — a workspace can serve those and no warehouse capability
39+
// at all — and stays silent otherwise, which keeps the byte-identical claim intact.
40+
//
3341
// SERVER-SIDE ONLY, for the same reason `precedence.ts` is: the TUI plugin runtime
3442
// loads plugins in a separate module realm, so an import from there would read a
3543
// different, always-empty `Precedence` map. Import this only from the session layer.
36-
import { type Capability, type Precedence, inertWorkspaceName, servedInventory } from "./precedence"
44+
import {
45+
type Capability,
46+
type Precedence,
47+
type ServedExtension,
48+
inertWorkspaceName,
49+
servedExtensions,
50+
servedInventory,
51+
} from "./precedence"
3752

3853
/** Hard ceiling on the rendered section. Deliberately independent of
3954
* `UNIFIED_INJECTION_BUDGET`: this is a routing directive, not knowledge, and must
@@ -190,12 +205,31 @@ export function systemSection(precedence: Precedence | undefined): string {
190205
const SEPARATOR = "\n\n"
191206

192207
/** The routing directive. Unchanged contract: silent unless the workspace is really
193-
* routing, so the model is never steered toward tools it should not use. */
208+
* routing, so the model is never steered toward tools it should not use. The one
209+
* addition is the extension tools a live IDE bridge serves, which ride along in
210+
* both shapes and are the only thing said in the extension-only shape. */
194211
function routingSection(precedence: Precedence, reserved = 0): string {
195-
if (!precedence.enabled) return precedence.disabledReason ? DISABLED_COPY[precedence.disabledReason] : ""
212+
const extLines = servedExtensions(precedence).map(extensionLine)
213+
if (!precedence.enabled) {
214+
// The one disabled state that can carry served extension tools (see `derive`):
215+
// no warehouse capability is routed, but the bridge is serving, and silence
216+
// would leave the model unaware of tools it can see. Without them the table's
217+
// entry renders exactly as before.
218+
if (precedence.disabledReason === "nothing-materialised" && extLines.length > 0) {
219+
return assembleExtensionsOnly(precedence.workspaceName, precedence.workspaceId, extLines, reserved)
220+
}
221+
return precedence.disabledReason ? DISABLED_COPY[precedence.disabledReason] : ""
222+
}
196223

197224
const served = servedInventory(precedence)
198-
if (served.length === 0) return ""
225+
// Enabled but no warehouse capability reachable (the analyst shape). The same
226+
// ruleset filters the extension tools, so normally none survive either; any that
227+
// do are still real and still callable, so they are said.
228+
if (served.length === 0) {
229+
return extLines.length > 0
230+
? assembleExtensionsOnly(precedence.workspaceName, precedence.workspaceId, extLines, reserved)
231+
: ""
232+
}
199233

200234
// `type` is the canonical local driver type (`postgres`), not the user-facing
201235
// connection name nor the engine's integration id (`postgresql`) — it is what the
@@ -209,7 +243,60 @@ function routingSection(precedence: Precedence, reserved = 0): string {
209243
return `- ${type} — ${servedPart}${localPart}`
210244
})
211245

212-
return assemble(precedence.workspaceName, precedence.workspaceId, typeLines, reserved)
246+
return assemble(precedence.workspaceName, precedence.workspaceId, typeLines, extLines, reserved)
247+
}
248+
249+
/** One extension-type integration and every tool of it the caller can call. The
250+
* integration name is catalog-authored and precedence already made it inert; the
251+
* keys are engine tool names, quoted the way the warehouse lines quote theirs. */
252+
function extensionLine(group: ServedExtension): string {
253+
return `- ${group.integration} — ${group.tools.map((t) => `\`${t.modelKey}\``).join(", ")}`
254+
}
255+
256+
/** Above the extension lines in both shapes of the section. It names the condition
257+
* the tools depend on, so a failure after the window closes can be explained
258+
* rather than retried blindly. */
259+
const EXTENSION_INTRO =
260+
"The VS Code window open on this project serves these extension tools through the workspace. Call them " +
261+
"like any other tool; they are unavailable while that window is closed:"
262+
263+
const extensionOmission = (n: number) =>
264+
`- …and ${n} further extension integration${n === 1 ? "" : "s"} served through the connected VS Code window.`
265+
266+
/** The section when extension tools are served and no warehouse capability is
267+
* routed. The local-tools sentence is kept: with nothing shadowed, every
268+
* connection really does stay local, and the model should not infer otherwise
269+
* from seeing `datamate_*` keys listed. Same cap, same drop rule as `assemble`;
270+
* and once the cap has taken every extension line there is nothing left to say,
271+
* so the shape is silent rather than an intro over an empty list. */
272+
function assembleExtensionsOnly(
273+
workspaceName: string,
274+
workspaceId: string | undefined,
275+
extLines: string[],
276+
reserved = 0,
277+
): string {
278+
const label = workspaceLabel(workspaceName, workspaceId)
279+
const render = (ext: string[]) => {
280+
const omitted = extLines.length - ext.length
281+
return [
282+
HEADING,
283+
"",
284+
`This project is bound to Altimate workspace ${label}. No warehouse capability is routed through it in ` +
285+
`this session: every connection uses the local tools (${ALL_LOCAL_TOOLS}).`,
286+
"",
287+
EXTENSION_INTRO,
288+
"",
289+
...ext,
290+
...(omitted > 0 ? [extensionOmission(omitted)] : []),
291+
].join("\n")
292+
}
293+
let ext = extLines
294+
let out = render(ext)
295+
while (out.length + reserved > MAX_SECTION_CHARS && ext.length > 0) {
296+
ext = ext.slice(0, -1)
297+
out = render(ext)
298+
}
299+
return ext.length > 0 ? out : ""
213300
}
214301

215302
/** The workspace name is customer-authored and lands in the system prompt — the
@@ -237,11 +324,13 @@ function assemble(
237324
workspaceName: string,
238325
workspaceId: string | undefined,
239326
typeLines: string[],
327+
extLines: string[] = [],
240328
reserved = 0,
241329
): string {
242330
const label = workspaceLabel(workspaceName, workspaceId)
243-
const render = (lines: string[]) => {
331+
const render = (lines: string[], ext: string[]) => {
244332
const omitted = typeLines.length - lines.length
333+
const extOmitted = extLines.length - ext.length
245334
const converse =
246335
omitted > 0
247336
? "For the served types omitted above, prefer the `datamate_*` tool for that type when one is in the " +
@@ -260,16 +349,27 @@ function assemble(
260349
...(omitted > 0
261350
? [`- …and ${omitted} further connection type${omitted === 1 ? "" : "s"} served by this workspace.`]
262351
: []),
352+
// On the lines that survived the cap, not the ones asked for: with every
353+
// extension line dropped, an intro over an omission count told the model
354+
// to call tools it was never shown. (bot review)
355+
...(ext.length > 0
356+
? ["", EXTENSION_INTRO, "", ...ext, ...(extOmitted > 0 ? [extensionOmission(extOmitted)] : [])]
357+
: []),
263358
"",
264359
converse,
265360
].join("\n")
266361
}
267362

268363
let lines = typeLines
269-
let out = render(lines)
270-
while (out.length + reserved > MAX_SECTION_CHARS && lines.length > 0) {
271-
lines = lines.slice(0, -1)
272-
out = render(lines)
364+
let ext = extLines
365+
let out = render(lines, ext)
366+
// Extension lines are dropped first: they are awareness, while the type lines
367+
// are directives the guard will enforce, and a redirect the model was never
368+
// warned of is the worse failure. Type lines go only once none are left.
369+
while (out.length + reserved > MAX_SECTION_CHARS && (ext.length > 0 || lines.length > 0)) {
370+
if (ext.length > 0) ext = ext.slice(0, -1)
371+
else lines = lines.slice(0, -1)
372+
out = render(lines, ext)
273373
}
274374
return out
275375
}

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -659,6 +659,7 @@ async function reconcile(sessionID: string, directory: string, state: DirectoryS
659659
kind: "attached",
660660
available: present.size,
661661
...(declared ? { declared: declared.keys.length, missing } : {}),
662+
...(declared?.extensions?.length ? { extensions: declared.extensions } : {}),
662663
}
663664
const rec = record(sessionID, outcome)
664665
// Keyed on the workspace too: a re-link with an identical inventory is still

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

Lines changed: 38 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ import { EventV2Bridge } from "@/event-v2-bridge"
1313
import { TuiEvent } from "@/server/tui-event"
1414
import { readLocalBindingScopedStrict } from "./state"
1515
import { log, syncInternals, type BindingRead, type ScopedBinding } from "./engine-seams"
16-
import type { Declared, Toast } from "./engine-types"
16+
import type { Declared, DeclaredExtension, Toast } from "./engine-types"
1717

1818
/** How long the allowlist lookup may hold a turn. Once per workspace per process. */
1919
export const DECLARED_TIMEOUT_MS = 4_000
@@ -129,14 +129,23 @@ export async function declared(workspaceId: string): Promise<Declared | null> {
129129
AltimateApi.getDatamate(workspaceId),
130130
AltimateApi.listIntegrations(),
131131
])
132-
const extensionIds = new Set(catalog.filter((i) => i.type === "extension").map((i) => i.id))
132+
const extensionNames = new Map(
133+
catalog.filter((i) => i.type === "extension").map((i): [string, string] => [i.id, i.name ?? i.id]),
134+
)
133135
const keys: string[] = []
134136
const extensionKeys: string[] = []
137+
const extensions: DeclaredExtension[] = []
135138
for (const integration of workspace.integrations ?? []) {
136-
const target = extensionIds.has(integration.id) ? extensionKeys : keys
137-
for (const tool of integration.tools ?? []) target.push(tool.key)
139+
const toolKeys = (integration.tools ?? []).map((tool) => tool.key)
140+
const name = extensionNames.get(integration.id)
141+
if (name === undefined) {
142+
keys.push(...toolKeys)
143+
continue
144+
}
145+
extensionKeys.push(...toolKeys)
146+
if (toolKeys.length > 0) extensions.push({ id: integration.id, name, keys: toolKeys })
138147
}
139-
return { keys, extensionKeys }
148+
return { keys, extensionKeys, ...(extensions.length > 0 ? { extensions } : {}) }
140149
} catch (err) {
141150
log.warn("could not read the declared workspace integrations", { workspaceId, err: String(err) })
142151
return null
@@ -171,9 +180,21 @@ export async function declaredBounded(workspaceId: string): Promise<Declared | n
171180
* sidecar whose recorded workspaceFolders contain `cwd`, else the sole live
172181
* bridge. Read-only — a dead pid is skipped, never unlinked; GC of stale
173182
* sidecars belongs to the engine and the extension. Presentation only: the
174-
* engine remains the authority on what actually connects. */
175-
export function liveBridge(cwd: string, dir: string = join(homedir(), ".altimate", "extension-rpc")): boolean {
176-
if (syncInternals.liveBridge) return syncInternals.liveBridge(cwd)
183+
* engine remains the authority on what actually connects.
184+
*
185+
* `claim` is for a caller that will STATE the bridge is this project's (the
186+
* system prompt does, and the model may act on it). It drops the two rules
187+
* that mirror the engine's tolerant discovery: the sole-bridge fallback (one
188+
* live bridge counts whatever it has open) and the pidless sidecar (an older
189+
* bridge that recorded no pid counts as live because nothing can say
190+
* otherwise). Under `claim` it is a recorded folder match on a sidecar whose
191+
* pid is verified alive, or nothing. (multi-model review; codex) */
192+
export function liveBridge(
193+
cwd: string,
194+
dir: string = join(homedir(), ".altimate", "extension-rpc"),
195+
opts: { claim?: boolean } = {},
196+
): boolean {
197+
if (syncInternals.liveBridge) return syncInternals.liveBridge(cwd, opts)
177198
const bridges: string[][] = []
178199
try {
179200
for (const entry of readdirSync(dir)) {
@@ -194,6 +215,10 @@ export function liveBridge(cwd: string, dir: string = join(homedir(), ".altimate
194215
// would read garbage pids as alive. (codex r3, cubic)
195216
if ("pid" in data && !(typeof data.pid === "number" && Number.isInteger(data.pid) && data.pid > 0 && pidAlive(data.pid)))
196217
continue
218+
// A pidless sidecar cannot be told apart from one its bridge left
219+
// behind on exit; the engine gives it the benefit of the doubt, a
220+
// claim about this project does not.
221+
if (!("pid" in data) && opts.claim) continue
197222
// Validate the folders shape: this is an unvalidated JSON file, and a
198223
// non-array must degrade to "live bridge, no recorded folders", not
199224
// throw out of the probe. Only fully qualified strings survive —
@@ -219,7 +244,11 @@ export function liveBridge(cwd: string, dir: string = join(homedir(), ".altimate
219244
return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel))
220245
}
221246
if (bridges.some((folders) => folders.some(within))) return true
222-
return bridges.length === 1
247+
// The sole-bridge fallback mirrors the engine's own discovery, which connects
248+
// to the one live bridge whatever it has open; presentation of what the
249+
// engine did is right to follow it. A claim about this project gets a
250+
// folder match or nothing.
251+
return !opts.claim && bridges.length === 1
223252
}
224253

225254
/** A recorded folder must be fully qualified. On Windows, drive-relative

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ export const syncInternals: {
2727
versionOf?: (bin: string) => Promise<string | null>
2828
fingerprint?: (bin: string) => string | null
2929
declared?: (workspaceId: string) => Promise<Declared | null>
30-
liveBridge?: (cwd: string) => boolean
30+
liveBridge?: (cwd: string, opts?: { claim?: boolean }) => boolean
3131
notify?: (toast: Toast) => Promise<void>
3232
printLine?: (line: string) => void
3333
/** Install-offer seams (see engine-offer.ts). */

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

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,16 @@ export const TOOL_PREFIX = `${DATAMATE_KEY}_`
2929
export type Outcome =
3030
| { kind: "disabled" }
3131
| { kind: "unbound" }
32-
| { kind: "attached"; available: number; declared?: number; missing?: string[] }
32+
| {
33+
kind: "attached"
34+
available: number
35+
declared?: number
36+
missing?: string[]
37+
/** The allowlist's extension-type integrations, when it names any: what a
38+
* live IDE bridge could serve. Whether they are present is decided per turn
39+
* against the catalog, never recorded here. */
40+
extensions?: DeclaredExtension[]
41+
}
3342
| { kind: "engine-missing"; declared?: number }
3443
/** `found` is null when the binary ran but printed nothing usable — broken
3544
* rather than old; the message says so. */
@@ -57,7 +66,16 @@ export type McpStatus = Record<string, { status: string; error?: string } | unde
5766
/** Declared allowlist for a workspace, split by whether the CLI can serve it.
5867
* Extension-type integrations are RPC into a live VS Code host and have no
5968
* meaning on the CLI surface, so they are excluded from the reported gap. */
60-
export type Declared = { keys: string[]; extensionKeys: string[] }
69+
export type Declared = {
70+
keys: string[]
71+
extensionKeys: string[]
72+
/** The extension keys again, grouped under their catalog integration, for the
73+
* surfaces that name them rather than count them. Optional: the flat lists are
74+
* the contract every existing reader was written against. */
75+
extensions?: DeclaredExtension[]
76+
}
77+
78+
export type DeclaredExtension = { id: string; name: string; keys: string[] }
6179

6280
/** A configured MCP entry in either shape it can reach us: opencode's own
6381
* `command: string[]` argv, or the `{ command, args }` split an IDE writes. */

0 commit comments

Comments
 (0)