feat: runtime overrides — model, temperature, baseUrl on ComputerAgent

Three first-class fields callers can pass to override what the GAP repo
specifies, without forking the agent definition:

  new ComputerAgent({
    source: "...", harness: "...", runtime: ...,
    model: "claude-haiku-4-5-20251001",      // overrides agent.yaml model.preferred
    temperature: 0.2,                        // overrides constraints.temperature
    baseUrl: "https://my-proxy.example.com", // routes LLM calls through a proxy
  });

## Cost source — no price table

Same principle as #5: we don't compute or hardcode anything. `baseUrl`
becomes the `ANTHROPIC_BASE_URL` env var, which the Anthropic SDK reads
natively. `model` flows through the existing `mergeEngineOptions` chain.
`temperature` is an engine-dependent passthrough — gitagent honors it
(folds into gitclaw's `constraints` object), claude-agent-sdk warns once
per process (Claude SDK v0.2.x doesn't expose temperature on its public
Options type yet — fix lands when upstream adds it).

## What changed (additive — no breaking changes)

packages/sdk/src/types.ts:
  + ComputerAgentOptions.model?: string
  + ComputerAgentOptions.temperature?: number
  + ComputerAgentOptions.baseUrl?: string

packages/sdk/src/computer-agent.ts:
  Constructor computes `effectiveEnvs` (baseUrl injected as
  ANTHROPIC_BASE_URL when caller hasn't set that key explicitly) and
  `effectiveOptions` (model + temperature merged in). Both are memoized
  and used by both substrate boot and createSession so they stay
  consistent across multiple chats. Bad baseUrl throws at construction
  via `new URL(...)` parse — fail fast.

packages/identity-gitagentprotocol/src/manifest.ts:
  + Typed `model.constraints.temperature` (was passthrough-only).

packages/identity-gitagentprotocol/src/adapters/{claude-agent-sdk,gitagent}.ts:
  Map manifest.model.constraints.temperature → flat opts.temperature.
  Caller-supplied overrides still win via mergeEngineOptions on the
  harness side.

packages/engine-gitagent/src/engine.ts:
  Fold flat ctx.options.temperature into gitclaw's nested
  `constraints.temperature` (gitclaw's actual interface). Strip the
  flat field before spread so it doesn't leak as an unknown top-level
  option.

packages/engine-claude-agent-sdk/src/engine.ts:
  Strip flat temperature before spread (SDK doesn't accept it). Warn
  once per process via console.warn when temperature is set —
  explicitly tells the user to switch to gitagent if it matters,
  doesn't silently swallow.

## Tests added

10 new (314 → 324 total, all green):

  - sdk: 6 — model fold, model vs options precedence, temperature
    fold, baseUrl injection, baseUrl doesn't clobber explicit
    ANTHROPIC_BASE_URL, invalid baseUrl throws at construction
  - identity-gitagentprotocol/adapters: 4 — temperature mapped from
    constraints on both adapters, absent when not declared
  - engine-gitagent: 1 — flat temperature folds into constraints,
    pre-existing constraints field preserved, flat field stripped
    from the QueryOptions root

## Live-validated

  bun run examples/hello.ts                              # baseline still works
  bun run examples/_override-smoke.ts (now removed)      # all 3 overrides applied
    → Response: "Hello there friend." (model=haiku honored)
    → 428 tokens • $0.0115

  bad-url test (now removed):
    → ComputerAgent: invalid baseUrl "not a real url" — must be a
      valid URL (e.g. "https://api.anthropic.com").

## Wire schema unchanged

`CreateSessionBody.options` is already `Record<string, unknown>` —
opaque passthrough. No zod schema change needed. Engine and adapter
type augments are purely TS-side.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: kapaleshreyas

examples/hello.ts

@@ -32,6 +32,11 @@ await using agent = new ComputerAgent({
   runtime: new LocalSubstrate(),
   envs: { ANTHROPIC_API_KEY },
   options: { permissionMode: "bypassPermissions" },
+
+  // Optional runtime overrides — all three win over agent.yaml:
+  // model: "claude-haiku-4-5-20251001",       // force a specific model
+  // temperature: 0.2,                         // override sampling temperature
+  // baseUrl: "https://my-proxy.example.com",  // route through a proxy / self-hosted endpoint
 });
 
 const result = await agent.chat('Write a 3-line haiku about TypeScript to "haiku.txt".');

packages/engine-claude-agent-sdk/src/engine.ts

@@ -74,8 +74,16 @@ export class ClaudeAgentEngine implements EngineDriver<ClaudeAgentOptions> {
       }
     }
 
+    // `temperature` is part of our cross-engine options surface (Wedge 1.7)
+    // but `@anthropic-ai/claude-agent-sdk` v0.2.x's public `Options` type
+    // doesn't expose it. Warn once per process so callers know it's a no-op
+    // here — they can switch to harness="gitagent" if temperature matters,
+    // or wait for the upstream SDK to expose the field.
+    const flatTemperature = (ctx.options as { temperature?: number }).temperature;
+    if (flatTemperature !== undefined) warnTemperatureUnsupported();
+
     const options: ClaudeAgentOptions = {
-      ...ctx.options,
+      ...stripFlatTemperature(ctx.options),
       cwd: ctx.workdir,
       env: { ...ctx.envs },
       includePartialMessages: true,
@@ -175,3 +183,29 @@ function signalToController(signal: AbortSignal): AbortController {
   else signal.addEventListener("abort", () => ctrl.abort(), { once: true });
   return ctrl;
 }
+
+/**
+ * Drop the flat `temperature` shortcut before spreading into ClaudeAgentOptions.
+ * The Claude Agent SDK v0.2.x doesn't accept `temperature` on `Options`, so
+ * leaving it in would land as an unknown property (mostly harmless but noisy).
+ * See Wedge 1.7.
+ */
+function stripFlatTemperature<T extends Record<string, unknown>>(
+  opts: T,
+): Omit<T, "temperature"> {
+  const { temperature: _t, ...rest } = opts as T & { temperature?: number };
+  return rest as Omit<T, "temperature">;
+}
+
+let temperatureWarned = false;
+function warnTemperatureUnsupported(): void {
+  if (temperatureWarned) return;
+  temperatureWarned = true;
+  // eslint-disable-next-line no-console
+  console.warn(
+    "[computeragent] `temperature` is set but the claude-agent-sdk engine (v0.2.x) " +
+      "doesn't expose temperature on its public Options type — it has no effect. " +
+      "Use `harness: \"gitagent\"` if temperature control matters, or wait for the " +
+      "Anthropic SDK to add the field. (warned once per process)",
+  );
+}

packages/engine-gitagent/src/engine.test.ts

@@ -30,6 +30,55 @@ describe("GitAgentEngine", () => {
     expect(typeof (stream as AsyncIterable<unknown>)[Symbol.asyncIterator]).toBe("function");
   });
 
+  it("flat opts.temperature is folded into gitclaw's constraints.temperature (Wedge 1.7)", async () => {
+    let capturedOptions: Record<string, unknown> | undefined;
+    vi.doMock("gitclaw", async () => ({
+      query: async function* mockQuery(options: Record<string, unknown>) {
+        capturedOptions = options;
+        yield {
+          type: "assistant",
+          content: "ok",
+          model: "anthropic/claude-sonnet",
+          provider: "anthropic",
+          stopReason: "stop",
+        };
+      },
+    }));
+
+    vi.resetModules();
+    const { GitAgentEngine: PatchedEngine } = await import("./engine.js");
+
+    const ctrl = new AbortController();
+    const e = new PatchedEngine();
+    const events: unknown[] = [];
+    for await (const ev of e.startSession({
+      sessionId: "sess_t",
+      // GAP loader / SDK shortcut puts temperature flat on options.
+      options: { temperature: 0.42, constraints: { stop_sequences: ["X"] } } as never,
+      workdir: "/tmp",
+      envs: {},
+      userMessageQueue: (async function* () {
+        yield { role: "user" as const, content: "hi" };
+      })(),
+      onPermissionRequest: async () => ({ behavior: "deny", message: "n/a" }),
+      abortSignal: ctrl.signal,
+    })) {
+      events.push(ev);
+      if (events.length >= 2) break;
+    }
+
+    // gitclaw saw the temperature INSIDE constraints, not at the top level.
+    expect(capturedOptions).toBeDefined();
+    const constraints = (capturedOptions as { constraints?: Record<string, unknown> }).constraints;
+    expect(constraints?.temperature).toBe(0.42);
+    // Pre-existing constraints field is preserved.
+    expect(constraints?.stop_sequences).toEqual(["X"]);
+    // The flat shortcut was stripped (didn't leak into the QueryOptions root).
+    expect((capturedOptions as { temperature?: number }).temperature).toBeUndefined();
+
+    vi.doUnmock("gitclaw");
+  });
+
   it("emits ca_usage_snapshot after each GCAssistantMessage with usage, delta semantic (issue #5)", async () => {
     // Mock gitclaw to yield an assistant message with usage attached.
     vi.doMock("gitclaw", async () => ({

packages/engine-gitagent/src/engine.ts

@@ -114,13 +114,28 @@ export class GitAgentEngine implements EngineDriver<GitclawForwardOptions & { di
         ? (baseSuffix ? `${baseSuffix}\n\n${priorSuffix}` : priorSuffix)
         : (baseSuffix || undefined);
 
+      // Fold the flat `temperature` shortcut (set by `new ComputerAgent({...})`
+      // or by the GAP loader from `agent.yaml`'s `model.constraints.temperature`)
+      // into gitclaw's nested `constraints` object — that's where gitclaw
+      // actually looks. See Wedge 1.7.
+      const flatTemperature = (ctx.options as { temperature?: number }).temperature;
+      const inheritedConstraints =
+        (ctx.options as { constraints?: Record<string, unknown> }).constraints ?? {};
+      const constraints: Record<string, unknown> =
+        flatTemperature !== undefined
+          ? { ...inheritedConstraints, temperature: flatTemperature }
+          : inheritedConstraints;
+
       const options: QueryOptions = {
         prompt: singleMessageIterable(userText),
         dir: ctx.options.dir ?? ctx.workdir,
         sessionId: ctx.sessionId,
         abortController,
         hooks: { preToolUse: buildPreToolUse(ctx.onPermissionRequest) },
-        ...stripDir(ctx.options),
+        ...stripDirAndFlatTemperature(ctx.options),
+        ...(Object.keys(constraints).length > 0
+          ? { constraints: constraints as QueryOptions["constraints"] }
+          : {}),
         ...(systemPromptSuffix ? { systemPromptSuffix } : {}),
       };
 
@@ -220,6 +235,19 @@ function stripDir<T extends { dir?: string }>(opts: T): Omit<T, "dir"> {
   return rest;
 }
 
+/**
+ * Strip both `dir` and the flat `temperature` shortcut before spreading
+ * into gitclaw's QueryOptions. `temperature` is folded into `constraints`
+ * by the engine; if it leaks through as a flat field gitclaw ignores it
+ * but it's noisy in the typed options. See Wedge 1.7.
+ */
+function stripDirAndFlatTemperature<T extends { dir?: string; temperature?: number }>(
+  opts: T,
+): Omit<T, "dir" | "temperature"> {
+  const { dir: _dir, temperature: _temp, ...rest } = opts;
+  return rest;
+}
+
 /**
  * One-shot prompt iterable: yields a single user message then terminates.
  * Used by the per-turn `query()` loop so gitclaw consumes exactly one turn's

packages/identity-gitagentprotocol/src/adapters/claude-agent-sdk.ts

@@ -39,6 +39,15 @@ export async function gapToClaudeAgentOptions(
   if (manifest.model?.preferred) opts.model = manifest.model.preferred;
   if (manifest.runtime?.max_turns) opts.maxTurns = manifest.runtime.max_turns;
   if (manifest.runtime?.budget_usd !== undefined) opts.maxBudgetUsd = manifest.runtime.budget_usd;
+  // Carry the GAP-declared temperature through as a flat opt. The engine
+  // decides what to do with it — gitclaw folds it into `constraints`,
+  // claude-agent-sdk currently can't (no `temperature` on its public
+  // `Options` type) and warns. Caller-supplied `temperature` overrides this
+  // via the standard mergeEngineOptions chain. See Wedge 1.7.
+  if (manifest.model?.constraints?.temperature !== undefined) {
+    (opts as ClaudeAgentOptions & { temperature?: number }).temperature =
+      manifest.model.constraints.temperature;
+  }
 
   const tools = await loadGapTools(workdir);
   if (tools.allowedTools.length > 0 || tools.mcpToolNames.length > 0) {

packages/identity-gitagentprotocol/src/adapters/compliance.test.ts

@@ -16,6 +16,24 @@ async function runHarden(
   return harden({ ...options, ...callerOpts });
 }
 
+describe("manifest.model.constraints.temperature → opts.temperature (Wedge 1.7)", () => {
+  it("maps a declared temperature to a flat opts.temperature field", async () => {
+    const { options } = await gapToClaudeAgentOptions(
+      { ...base, model: { preferred: "claude-sonnet-4-5-20250929", constraints: { temperature: 0.3 } } },
+      "/tmp/no-such",
+    );
+    expect((options as ClaudeAgentOptions & { temperature?: number }).temperature).toBe(0.3);
+  });
+
+  it("omits temperature when not declared", async () => {
+    const { options } = await gapToClaudeAgentOptions(
+      { ...base, model: { preferred: "claude-sonnet-4-5-20250929" } },
+      "/tmp/no-such",
+    );
+    expect((options as ClaudeAgentOptions & { temperature?: number }).temperature).toBeUndefined();
+  });
+});
+
 describe("compliance.supervision.human_in_the_loop → permissionMode hardening", () => {
   it("'always' rewrites caller's bypassPermissions to default", async () => {
     const merged = await runHarden(

packages/identity-gitagentprotocol/src/adapters/gitagent.test.ts

@@ -28,4 +28,24 @@ describe("gapToGitagentOptions", () => {
       maxTurns: 12,
     });
   });
+
+  it("maps manifest.model.constraints.temperature to a flat temperature field (Wedge 1.7)", async () => {
+    const { options } = await gapToGitagentOptions(
+      {
+        name: "x",
+        version: "1.0.0",
+        model: { preferred: "anthropic:claude-sonnet-4-5", constraints: { temperature: 0.2 } },
+      } as never,
+      "/tmp/agent",
+    );
+    expect((options as { temperature?: number }).temperature).toBe(0.2);
+  });
+
+  it("omits temperature when not declared", async () => {
+    const { options } = await gapToGitagentOptions(
+      { name: "x", version: "1.0.0", model: { preferred: "anthropic:claude-sonnet-4-5" } } as never,
+      "/tmp/agent",
+    );
+    expect((options as { temperature?: number }).temperature).toBeUndefined();
+  });
 });

packages/identity-gitagentprotocol/src/adapters/gitagent.ts

@@ -28,6 +28,13 @@ export async function gapToGitagentOptions(
   const opts: GitagentOptions = { dir: workdir };
   if (manifest.model?.preferred) opts.model = manifest.model.preferred;
   if (manifest.runtime?.max_turns) opts.maxTurns = manifest.runtime.max_turns;
+  // Pass GAP's declared temperature as a flat field; the engine folds it
+  // into gitclaw's `constraints.temperature`. Caller-supplied `temperature`
+  // overrides via the standard mergeEngineOptions chain. See Wedge 1.7.
+  if (manifest.model?.constraints?.temperature !== undefined) {
+    (opts as GitagentOptions & { temperature?: number }).temperature =
+      manifest.model.constraints.temperature;
+  }
   // gitclaw does not yet expose a permission-mode knob through its options
   // surface; HITL enforcement on this engine is a future-PR concern.
   return { options: opts, harden: (m) => m };

packages/identity-gitagentprotocol/src/manifest.ts

@@ -18,6 +18,18 @@ export const GapManifest = z
       .object({
         preferred: z.string().optional(),
         fallback: z.array(z.string()).optional(),
+        /**
+         * Sampling constraints — engine-dependent how much of this gets honored.
+         * `temperature` is typed because every shipped engine considers it (some
+         * apply it, others ignore with a warning — see Wedge 1.7). Other fields
+         * pass through unchanged.
+         */
+        constraints: z
+          .object({
+            temperature: z.number().optional(),
+          })
+          .passthrough()
+          .optional(),
       })
       .passthrough()
       .optional(),