diff --git a/AGENTS.md b/AGENTS.md index 233981fe..96edf03e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -428,3 +428,5 @@ Three tools for launching, monitoring, and cancelling detached background jobs. - **`goop_write_wave` accepts `verifications[]` and `traceability[]` in two forms, and the distinction matters.** With `task_updates[]` (the common case), supply them as top-level fields — they are processed atomically alongside task updates. With `items[]`, supply them **per-item** — each `items[]` entry can carry its own `verifications[]` and `traceability[]`. A traceability row omitting `wave_number` inherits the enclosing item's wave; an explicit value overrides. A verification omitting `wave_id` defaults to the enclosing item's resolved wave row; an explicit id wins. Everything is written in one transaction — any failure rolls back rows *and* events, so no orphan events survive. Supplying top-level `verifications`/`traceability` **alongside** `items[]` is rejected deliberately, because those payloads would otherwise be silently dropped. - **Compaction hook replaces `output.prompt`, does not append to `output.context`.** The `experimental.session.compacting` hook (V1-only) overwrites `output.prompt` with a bounded continuation prompt from the shared formatter (`src/shared/continuation-prompt.ts`). `output.prompt` is last-writer-wins — earlier prompt content is not preserved or merged. `output.context` is never touched by the hook; if the host does not read `output.context` after compaction, context entries from other hooks are silently discarded. The hook stands down without mutating either field when no valid workflow can be resolved. + +- **Live V2 catalogs can publish `reasoning_options` instead of `variants`.** Real OpenCode host catalogs (e.g. `openai/gpt-5.6-sol`) publish `reasoning: true` plus `reasoning_options: [{type:"effort", values:[...]}]` with **no** `variants` array — only supported ids, no request encoding. `resolveCapabilities` (`src/features/thinking/capability.ts`) extracts these into an id-only supported set; `resolveThinkingValue` returns the honest string id (no fabricated headers/body); and the V2 adapter applies it through `agent.model.variant` alone (`src/core/hooks-v2.ts`). The same shape is classified as `raw.source === "v2"` on the V1 path, where `getVerifiedV1RequestOption` returns `undefined` and the provider default is preserved with a diagnostic — V1 never fabricates a request option. diff --git a/packages/opencode-plugin/src/core/dual-contract.test.ts b/packages/opencode-plugin/src/core/dual-contract.test.ts index 9136c07a..c9796282 100644 --- a/packages/opencode-plugin/src/core/dual-contract.test.ts +++ b/packages/opencode-plugin/src/core/dual-contract.test.ts @@ -366,6 +366,42 @@ describe("dual-contract parity", () => { expect(v1Resolution.warning).toBeUndefined(); }); + it("produces the same supported thinking-level set for equivalent V1 and real-shape V2 host payloads", () => { + // Redacted from the observed live OpenCode host catalog shape: the host + // publishes `reasoning:true` + `reasoning_options:[{type:"effort",...}]` + // with no `variants`. The V1 SDK contract publishes the same conceptual + // effort ladder under `capabilities.reasoning:true` + `options.:[...]`. + // Both shapes flow through the shared `resolveCapabilities` extractor; this + // parity assertion guarantees V1 and V2 agents on the same provider see + // the same supported set, regardless of which contract surfaced the data. + const REAL_LEVELS = ["none", "low", "medium", "high", "xhigh", "max"] as const; + + const realShapeV2HostPayload = { + reasoning: true, + reasoning_options: [{ type: "effort", values: [...REAL_LEVELS] }], + }; + + const equivalentV1HostPayload = { + capabilities: { reasoning: true }, + options: { reasoningEffort: [...REAL_LEVELS] }, + }; + + const v2Capabilities = resolveCapabilities(realShapeV2HostPayload); + const v1Capabilities = resolveCapabilities(equivalentV1HostPayload); + + expect(v2Capabilities.supported).toEqual([...REAL_LEVELS]); + expect(v1Capabilities.supported).toEqual([...REAL_LEVELS]); + // Set equality is the parity contract: order may differ between sources, + // but the supported set must not. + expect(new Set(v2Capabilities.supported)).toEqual(new Set(v1Capabilities.supported)); + + // Every canonical GoopSpec label resolves on both contracts. + for (const label of ["none", "low", "medium", "high", "xhigh"] as const) { + expect(resolveThinkingValue(label, v2Capabilities).apply).not.toBeNull(); + expect(resolveThinkingValue(label, v1Capabilities).apply).not.toBeNull(); + } + }); + it("produces equivalent applied values for the same thinking config and compatible model", async () => { const env = setupTestEnvironment("dual-thinking-parity"); const globalConfigPath = process.env.GOOPSPEC_GLOBAL_CONFIG_PATH; diff --git a/packages/opencode-plugin/src/core/hooks-v2.test.ts b/packages/opencode-plugin/src/core/hooks-v2.test.ts index 55333e29..85bf325d 100644 --- a/packages/opencode-plugin/src/core/hooks-v2.test.ts +++ b/packages/opencode-plugin/src/core/hooks-v2.test.ts @@ -14,6 +14,7 @@ import type { V2AgentDraft, V2AgentInfo, V2CatalogDraft, + V2CatalogModel, V2RuntimeContext, V2SessionRequestEvent, V2ToolExecuteAfterEvent, @@ -32,6 +33,17 @@ interface Registrations { catalogReloads: number; } +/** + * Casts host catalog test data through a single, explicit boundary. Real V2 + * hosts publish fields (`reasoning`, `reasoning_options`) that the minimal + * `V2CatalogModel` type does not declare (see fn_20260803_pia9pfxi); this + * keeps that documented gap from forcing excess-property errors on realistic + * fixtures while still routing every fixture through the real type. + */ +function catalogModel(fields: Record): V2CatalogModel { + return fields as V2CatalogModel; +} + function createRuntimeContext( registrations: Registrations, drafts: { agent?: V2AgentDraft; catalog?: V2CatalogDraft } = {}, @@ -444,4 +456,290 @@ describe("registerHooksV2()", () => { else process.env.GOOPSPEC_DEBUG = originalDebug; } }); + + it("sets agent.model.variant from an id-only reasoning_options catalog model without fabricating headers or body", async () => { + const env = setupTestEnvironment("v2-thinking-id-only-apply"); + const ctx = createMockPluginContext({ testDir: env.testDir, db: env.db }); + contexts.push(ctx); + writeFileSync( + join(ctx.sdk.directory, "goopspec.json"), + JSON.stringify({ agentThinkingLevels: { "executor-high": "medium" } }), + ); + const agent: V2AgentInfo = { + id: "goop-executor-high", + model: { providerID: "openai", id: "gpt-5.6-sol" }, + request: { headers: { "x-existing": "keep" }, body: { existing: true } }, + }; + // Real host shape (fn_20260803_pia9pfxi): reasoning:true + reasoning_options, + // no `variants` field at all — the host publishes no request encoding. + const catalog: V2CatalogDraft = { + provider: { + list: () => [ + { + provider: { id: "openai" }, + models: new Map([ + [ + "gpt-5.6-sol", + catalogModel({ + reasoning: true, + reasoning_options: [ + { type: "effort", values: ["none", "low", "medium", "high", "xhigh", "max"] }, + ], + }), + ], + ]), + }, + ], + }, + }; + const agents: V2AgentDraft = { + list: () => [agent], + update: (_id, update) => update(agent), + }; + const registrations: Registrations = { + agentTransforms: 0, + catalogTransforms: 0, + agentReloads: 0, + catalogReloads: 0, + }; + + await registerHooksV2(createRuntimeContext(registrations, { agent: agents, catalog }), ctx); + + expect(agent.model?.variant).toBe("medium"); + expect(agent.request.headers).toEqual({ "x-existing": "keep" }); + expect(agent.request.body).toEqual({ existing: true }); + env.cleanup(); + }); + + it("applies a configured goop-* thinking level end-to-end via a real-shape reasoning_options catalog and changes the variant when the config changes (wiring Pattern 4)", async () => { + // End-to-end wiring proof for the live host capability shape that caused + // the original defect (fn_20260803_pia9pfxi): the catalog publishes + // `reasoning:true` + `reasoning_options:[{type:"effort",values:[...]}]` + // with no `variants` field. A configured `agentThinkingLevels` value for a + // `goop-*` role must reach the V2 consumer and set `agent.model.variant` + // WITHOUT a preserve-default warning, and changing the configured level + // must change the applied variant. No headers/body are fabricated. + const env = setupTestEnvironment("v2-thinking-wiring-real-shape"); + const ctx = createMockPluginContext({ testDir: env.testDir, db: env.db }); + contexts.push(ctx); + writeFileSync( + join(ctx.sdk.directory, "goopspec.json"), + JSON.stringify({ agentThinkingLevels: { "executor-medium": "medium" } }), + ); + const agent: V2AgentInfo = { + id: "goop-executor-medium", + model: { providerID: "openai", id: "gpt-5.6-sol" }, + request: { headers: { "x-existing": "keep" }, body: { existing: true } }, + }; + const catalog: V2CatalogDraft = { + provider: { + list: () => [ + { + provider: { id: "openai" }, + models: new Map([ + [ + "gpt-5.6-sol", + catalogModel({ + reasoning: true, + reasoning_options: [ + { type: "effort", values: ["none", "low", "medium", "high", "xhigh", "max"] }, + ], + }), + ], + ]), + }, + ], + }, + }; + const agents: V2AgentDraft = { + list: () => [agent], + update: (_id, update) => update(agent), + }; + const registrations: Registrations = { + agentTransforms: 0, + catalogTransforms: 0, + agentReloads: 0, + catalogReloads: 0, + }; + const errorSpy = spyOn(console, "error").mockImplementation(() => {}); + + const hooks = await registerHooksV2( + createRuntimeContext(registrations, { agent: agents, catalog }), + ctx, + ); + + // (a) The configured "medium" reaches the consumer and sets the variant, + // with no preserve-default warning and no fabricated headers/body. + expect(agent.model?.variant).toBe("medium"); + expect(agent.request.headers).toEqual({ "x-existing": "keep" }); + expect(agent.request.body).toEqual({ existing: true }); + expect( + errorSpy.mock.calls + .map((c) => String(c[0] ?? "")) + .some((m) => m.includes("preserving the provider default")), + ).toBe(false); + + // (b) Changing the configured level to "high" changes the applied variant + // (both levels are in the supported set), still with no warning and no + // fabricated headers/body. + writeFileSync( + join(ctx.sdk.directory, "goopspec.json"), + JSON.stringify({ agentThinkingLevels: { "executor-medium": "high" } }), + ); + await hooks.reloadThinkingLevels(); + + expect(agent.model?.variant).toBe("high"); + expect(registrations.catalogTransforms).toBe(2); + expect(registrations.agentTransforms).toBe(2); + expect(agent.request.headers).toEqual({ "x-existing": "keep" }); + expect(agent.request.body).toEqual({ existing: true }); + expect( + errorSpy.mock.calls + .map((c) => String(c[0] ?? "")) + .some((m) => m.includes("preserving the provider default")), + ).toBe(false); + + errorSpy.mockRestore(); + env.cleanup(); + }); + + it("emits the preserve-default warning and leaves the agent unchanged for an unsupported level", async () => { + const env = setupTestEnvironment("v2-thinking-unsupported"); + const ctx = createMockPluginContext({ testDir: env.testDir, db: env.db }); + contexts.push(ctx); + writeFileSync( + join(ctx.sdk.directory, "goopspec.json"), + JSON.stringify({ agentThinkingLevels: { "executor-high": "xhigh" } }), + ); + const agent: V2AgentInfo = { + id: "goop-executor-high", + model: { providerID: "openai", id: "gpt-test" }, + request: { headers: { "x-existing": "keep" }, body: { existing: true } }, + }; + const catalog: V2CatalogDraft = { + provider: { + list: () => [ + { + provider: { id: "openai" }, + models: new Map([ + [ + "gpt-test", + catalogModel({ + variants: [{ id: "medium", headers: {}, body: { reasoning_effort: "medium" } }], + }), + ], + ]), + }, + ], + }, + }; + const agents: V2AgentDraft = { + list: () => [agent], + update: (_id, update) => update(agent), + }; + const registrations: Registrations = { + agentTransforms: 0, + catalogTransforms: 0, + agentReloads: 0, + catalogReloads: 0, + }; + const errorSpy = spyOn(console, "error").mockImplementation(() => {}); + + await registerHooksV2(createRuntimeContext(registrations, { agent: agents, catalog }), ctx); + + expect(agent.model?.variant).toBeUndefined(); + expect(agent.request.headers).toEqual({ "x-existing": "keep" }); + expect(agent.request.body).toEqual({ existing: true }); + const logged = errorSpy.mock.calls.map((c) => String(c[0] ?? "")); + expect( + logged.some( + (m) => m.includes("goop-executor-high") && m.includes("preserving the provider default"), + ), + ).toBe(true); + + errorSpy.mockRestore(); + env.cleanup(); + }); + + it("does not expose a transiently emptied capabilities map to a reentrant agent transform racing catalog capture", async () => { + const env = setupTestEnvironment("v2-thinking-reentrancy"); + const ctx = createMockPluginContext({ testDir: env.testDir, db: env.db }); + contexts.push(ctx); + writeFileSync( + join(ctx.sdk.directory, "goopspec.json"), + JSON.stringify({ agentThinkingLevels: { "executor-high": "medium" } }), + ); + + const agent: V2AgentInfo = { + id: "goop-executor-high", + model: { providerID: "openai", id: "gpt-test" }, + request: { headers: {}, body: {} }, + }; + const reentrantAgent: V2AgentInfo = { + id: "goop-executor-high", + model: { providerID: "openai", id: "gpt-test" }, + request: { headers: {}, body: {} }, + }; + const catalogRecords = [ + { + provider: { id: "openai" }, + models: new Map([ + [ + "gpt-test", + catalogModel({ + variants: [{ id: "medium", headers: {}, body: { reasoning_effort: "medium" } }], + }), + ], + ]), + }, + ]; + const registrations: Registrations = { + agentTransforms: 0, + catalogTransforms: 0, + agentReloads: 0, + catalogReloads: 0, + }; + + // A host that reenters the already-registered agent transform WHILE this + // catalog capture is still enumerating providers — before this refresh's + // new capability snapshot has been captured. Guards against firing on the + // very first registration, when no agent transform is registered yet. + let reentered = false; + const catalog: V2CatalogDraft = { + provider: { + list: () => { + if (!reentered && registrations.agentTransform) { + reentered = true; + void registrations.agentTransform({ + list: () => [reentrantAgent], + update: (_id, update) => update(reentrantAgent), + }); + } + return catalogRecords; + }, + }, + }; + const agents: V2AgentDraft = { + list: () => [agent], + update: (_id, update) => update(agent), + }; + + const hooks = await registerHooksV2( + createRuntimeContext(registrations, { agent: agents, catalog }), + ctx, + ); + expect(agent.model?.variant).toBe("medium"); + + // The second refresh is where the reentrant call fires: by now + // `registrations.agentTransform` is already set from the first pass. + await hooks.reloadThinkingLevels(); + + expect(reentered).toBe(true); + // The reentrant call must resolve against the last-known-good, fully + // populated snapshot — never a transiently emptied map from an in-place + // clear() that runs before the new snapshot is captured. + expect(reentrantAgent.model?.variant).toBe("medium"); + expect(reentrantAgent.request.body.reasoning_effort).toBe("medium"); + env.cleanup(); + }); }); diff --git a/packages/opencode-plugin/src/core/hooks-v2.ts b/packages/opencode-plugin/src/core/hooks-v2.ts index 19efa5a0..977a9d94 100644 --- a/packages/opencode-plugin/src/core/hooks-v2.ts +++ b/packages/opencode-plugin/src/core/hooks-v2.ts @@ -150,16 +150,21 @@ function catalogKey(providerID: string, modelID: string): string { return `${providerID}\u0000${modelID}`; } -function captureCatalogCapabilities( - draft: V2CatalogDraft, - capabilitiesByModel: Map, -): void { - capabilitiesByModel.clear(); +/** + * Builds a fresh capability snapshot from the catalog draft. Returns a new + * Map instead of mutating a shared one in place: the caller swaps the shared + * reference only after this returns, so a reentrant reader (an agent + * transform racing a catalog refresh) always sees a complete snapshot — + * the previous one or the new one, never a transiently emptied map. + */ +function captureCatalogCapabilities(draft: V2CatalogDraft): Map { + const next = new Map(); for (const record of draft.provider.list()) { for (const [modelID, model] of record.models) { - capabilitiesByModel.set(catalogKey(record.provider.id, modelID), resolveCapabilities(model)); + next.set(catalogKey(record.provider.id, modelID), resolveCapabilities(model)); } } + return next; } function applyThinkingLevelsToAgents( @@ -186,8 +191,18 @@ function applyThinkingLevelsToAgents( continue; } - if (typeof resolution.apply === "string") continue; - const variant = resolution.apply; + const apply = resolution.apply; + if (typeof apply === "string") { + // Id-only V2 match: the host published no request encoding for this + // level. Set only the variant id and let the host build the request — + // never fabricate headers/body for a string resolution. + draft.update(candidate.id, (agent) => { + if (agent.model) agent.model.variant = apply; + }); + continue; + } + + const variant = apply; draft.update(candidate.id, (agent) => { agent.request.headers = { ...agent.request.headers, ...variant.headers }; agent.request.body = { ...agent.request.body, ...variant.body }; @@ -212,26 +227,31 @@ async function registerThinkingLevelAgentTransform( return async () => {}; } - const capabilitiesByModel = new Map(); - try { + // Holds the current capability snapshot by reference. `refresh` replaces + // the reference wholesale rather than clearing-then-repopulating the same + // Map in place, so a reentrant reader always observes a complete snapshot. + const capabilities: { current: ReadonlyMap } = { + current: new Map(), + }; + + const refresh = async (): Promise => { await catalogCapability.transform((draft) => { - captureCatalogCapabilities(draft, capabilitiesByModel); + capabilities.current = captureCatalogCapabilities(draft); }); await agentCapability.transform((draft) => { - applyThinkingLevelsToAgents(draft, ctx, capabilitiesByModel); + applyThinkingLevelsToAgents(draft, ctx, capabilities.current); }); + }; + + try { + await refresh(); } catch (error) { logError("V2 thinking-level agent transform registration failed", error); } return async (): Promise => { try { - await catalogCapability.transform((draft) => { - captureCatalogCapabilities(draft, capabilitiesByModel); - }); - await agentCapability.transform((draft) => { - applyThinkingLevelsToAgents(draft, ctx, capabilitiesByModel); - }); + await refresh(); if (typeof catalogCapability.reload === "function") await catalogCapability.reload(); if (typeof agentCapability.reload === "function") await agentCapability.reload(); } catch (error) { diff --git a/packages/opencode-plugin/src/hooks/agent-registration.test.ts b/packages/opencode-plugin/src/hooks/agent-registration.test.ts index 9de71f1b..3b667a12 100644 --- a/packages/opencode-plugin/src/hooks/agent-registration.test.ts +++ b/packages/opencode-plugin/src/hooks/agent-registration.test.ts @@ -441,4 +441,79 @@ describe("createAgentRegistrationHook", () => { cleanup(); } }); + + it("preserves the provider default when V1 catalog exposes only the real-shape effort options", async () => { + // Redacted from the observed live OpenCode host catalog shape: the model + // publishes `reasoning:true` + `reasoning_options:[{type:"effort",...}]` + // and no `capabilities.reasoning` + `options` structure. The shared + // `resolveCapabilities` classifies this as a V2 id-only match + // (`raw.source === "v2"`, `variants: []`), so the supported set IS + // populated, but `getVerifiedV1RequestOption` only resolves when + // `raw.source === "v1"` — it returns undefined here. The V1 `chat.params` + // hook therefore cannot apply the level and emits the "no unambiguous V1 + // request option" diagnostic, preserving the provider default. The agent + // still runs; only the thinking level is not applied on the V1 contract. + // The V2 adapter handles the same shape via the string apply path + // (see hooks-v2.ts and dual-contract.test.ts parity coverage). + const { testDir, cleanup } = setupTestEnvironment("agent-reg-v1-real-shape"); + const errors: string[] = []; + const originalError = console.error; + const origGlobalPath = process.env.GOOPSPEC_GLOBAL_CONFIG_PATH; + try { + process.env.GOOPSPEC_GLOBAL_CONFIG_PATH = join(testDir, "no-global-config.json"); + writeFileSync( + join(testDir, "goopspec.json"), + JSON.stringify({ agentThinkingLevels: { orchestrator: "high" } }), + "utf-8", + ); + console.error = (...args: unknown[]) => errors.push(args.map(String).join(" ")); + + const ctx = createMockPluginContext({ testDir }); + const hooks = createAgentRegistrationHook(ctx); + const output = { temperature: 0, topP: 0, topK: 0, maxOutputTokens: undefined, options: {} }; + + await withProviderCatalog( + ctx, + { + providers: [ + { + id: "anthropic", + models: { + "claude-opus-4-6": { + reasoning: true, + reasoning_options: [ + { type: "effort", values: ["none", "low", "medium", "high", "xhigh", "max"] }, + ], + }, + }, + }, + ], + }, + async () => { + await hooks["chat.params"]?.( + { + sessionID: "session", + agent: "goop-orchestrator", + model: { providerID: "anthropic", id: "claude-opus-4-6" } as never, + provider: {} as never, + message: {} as never, + }, + output, + ); + }, + ); + + // The level is supported but not V1-applicable: options stay empty. + expect(output.options).toEqual({}); + expect(errors.some((entry) => entry.includes("no unambiguous V1 request option"))).toBe(true); + } finally { + console.error = originalError; + if (origGlobalPath === undefined) { + Reflect.deleteProperty(process.env, "GOOPSPEC_GLOBAL_CONFIG_PATH"); + } else { + process.env.GOOPSPEC_GLOBAL_CONFIG_PATH = origGlobalPath; + } + cleanup(); + } + }); });