@smartmemory/compose 0.2.58-beta → 0.3.0

package/lib/stratum-mcp-client.js

@@ -1,23 +1,135 @@
 /**
- * stratum-mcp-client.js — MCP protocol client for stratum-mcp.
+ * stratum-mcp-client.js — MCP protocol client for the Stratum TS engine.
  *
- * Spawns `stratum-mcp` (no subcommand) as a child process and communicates
- * via the MCP SDK over stdio. This is for the build runner's plan/step_done
+ * Spawns the configured TS MCP entrypoint and communicates via the MCP SDK
+ * over stdio. This is for the build runner's plan/step_done
  * loop — distinct from server/stratum-client.js which uses CLI subcommands.
  *
  * Usage:
  *   const client = new StratumMcpClient();
  *   await client.connect();
  *   const dispatch = await client.plan(specPath, 'build', { featureCode: 'FEAT-1' });
- *   const next = await client.stepDone(dispatch.flow_id, 'step1', { phase: 'design' });
+ *   const ready = dispatch.ready[0];
+ *   const next = await client.stepDone(dispatch.runId, ready.id, { output: result }, ready.dispatchToken);
  *   await client.close();
  */
 
-import { execFileSync } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import YAML from 'yaml';
 import { validateBuildStreamEvent } from './build-stream-schema.js';
+import { resolveStratumMcpConnection } from './stratum-engine.js';
+
+const RUNTIME_INPUT_REF = /^\$\.input\.([A-Za-z_][A-Za-z0-9_]*)$/;
+
+/**
+ * Resolve producer-owned authoring values that TS v1 deliberately requires to
+ * be literals. Compose knows these values at plan time, so mutate a cloned spec
+ * object before it crosses the MCP boundary instead of templating raw YAML.
+ *
+ * Only schema fields with literal-only v1 types are resolved here. Prompt/data
+ * expressions remain engine-owned and are transmitted unchanged.
+ *
+ * @param {object} spec parsed Stratum specification
+ * @param {object} inputs plan input envelope
+ * @returns {object} a resolved clone; `spec` is never mutated
+ */
+export function resolvePlanSpecValues(spec, inputs = {}, runtimeProfiles = null) {
+  const resolved = structuredClone(spec);
+  const literalAgent = (value) => {
+    if (typeof value !== 'string') return null;
+    const provider = value.split(':', 1)[0];
+    return ['claude', 'codex'].includes(provider) ? provider : null;
+  };
+  const inputValue = (value) => {
+    if (typeof value !== 'string') return { matched: false, value };
+    const match = RUNTIME_INPUT_REF.exec(value);
+    return match ? { matched: true, value: inputs[match[1]] } : { matched: false, value };
+  };
+  // V4: the engine accepts only the bare provider literal, so a runtime agent
+  // that carried a tier/template (e.g. --implementer=claude::critical) loses it
+  // at resolution. Record the FULL stripped string, keyed by the enclosing step
+  // id, so the invocation can recover the tier/capability profile compose-side.
+  const recordProfile = (stepId, fullValue, literal) => {
+    if (runtimeProfiles && typeof fullValue === 'string' && fullValue !== literal) {
+      runtimeProfiles[stepId] = fullValue;
+    }
+  };
+
+  for (const [flowName, flow] of Object.entries(resolved?.flows ?? {})) {
+    if (flowName === 'entry' || !flow || typeof flow !== 'object') continue;
+    for (const step of flow.steps ?? []) {
+      const agent = inputValue(step.agent);
+      if (agent.matched) {
+        const literal = literalAgent(agent.value);
+        if (!literal) {
+          throw new TypeError(`runtime agent for step ${step.id} must resolve to claude or codex`);
+        }
+        recordProfile(step.id, agent.value, literal);
+        step.agent = literal;
+      }
+
+      const fanout = step.fanout;
+      if (!fanout || typeof fanout !== 'object') continue;
+      const preMerge = inputValue(fanout.pre_merge);
+      if (preMerge.matched) {
+        if (preMerge.value === undefined) delete fanout.pre_merge;
+        else if (!Array.isArray(preMerge.value) || preMerge.value.some((item) => typeof item !== 'string')) {
+          throw new TypeError(`runtime pre_merge for fanout ${step.id} must resolve to a string array`);
+        } else fanout.pre_merge = [...preMerge.value];
+      }
+      for (const stage of fanout.steps ?? []) {
+        const stageAgent = inputValue(stage.agent);
+        if (!stageAgent.matched) continue;
+        const literal = literalAgent(stageAgent.value);
+        if (!literal) {
+          throw new TypeError(`runtime agent for fanout ${step.id} must resolve to claude or codex`);
+        }
+        // Keyed by the FANOUT step id — the consumer invocation looks up by
+        // descriptor.step, not the inner stage.
+        recordProfile(step.id, stageAgent.value, literal);
+        stage.agent = literal;
+      }
+    }
+  }
+  return resolved;
+}
+
+/**
+ * V4: resolve a step's agent profile from the merged runtime + static maps,
+ * tolerating SCOPED ready ids. Ordinary subflow steps arrive with a scoped id
+ * (e.g. `coverage_check/run_tests`) while the sidecar keys are the bare step id
+ * (`run_tests`), so fall back to the last path segment. Returns undefined when
+ * no profile applies (bare provider literal).
+ */
+export function resolveStepProfile(profiles, stepId) {
+  if (!profiles || typeof profiles !== 'object' || !stepId) return undefined;
+  if (profiles[stepId]) return profiles[stepId];
+  const bare = String(stepId).split('/').pop();
+  if (bare && profiles[bare]) return profiles[bare];
+  return undefined;
+}
+
+/**
+ * Build the TS `stratum_agent_run` request from an agent string + compose-side
+ * options. The engine surface (contracts/mcp-surface.json) accepts only
+ * {agent, prompt, cwd, model?, sandboxMode?, background?} and rejects any other
+ * key, so the python-era knobs (allowed_tools/thinking/effort/correlation_id)
+ * are NOT sent — they are compose-side concerns applied at the invocation
+ * (resolveAgentConfig). `agent` is normalized to the bare provider literal the
+ * engine requires; `cwd` is required and defaults to the process cwd.
+ */
+export function buildAgentRunRequest(agentType, prompt, opts = {}) {
+  const provider = String(agentType ?? 'claude').split(':', 1)[0] || 'claude';
+  return {
+    agent: provider,
+    prompt,
+    cwd: opts.cwd ?? process.cwd(),
+    ...(opts.modelID ? { model: opts.modelID } : {}),
+    ...(opts.sandboxMode ? { sandboxMode: opts.sandboxMode } : {}),
+  };
+}
 
 export class StratumError extends Error {
   constructor(code, message, detail) {
@@ -39,10 +151,8 @@ export class StratumMcpClient {
    * Subscribe to BuildStreamEvent push notifications scoped to a (flowId, stepId).
    * Handler receives a parsed BuildStreamEvent envelope. Returns an unsubscribe fn.
    *
-   * Events arrive only while a tool call (parallelStart/parallelPoll/...) for that
-   * scope is in flight — the underlying transport is MCP progress notifications,
-   * which are tied to an active request. Subscribe BEFORE the poll loop, unsubscribe
-   * after `outcome` is observed.
+   * Events arrive only while an agent tool call for that scope is in flight —
+   * the underlying transport is MCP progress tied to an active request.
    *
    * @param {string} flowId
    * @param {string} stepId
@@ -88,7 +198,7 @@ export class StratumMcpClient {
    * BuildStreamEvent (schema_version + kind). Other progress payloads are
    * ignored.
    */
-  #makeProgressHandler() {
+  #makeProgressHandler(callCorrelationId) {
     return (progress) => {
       const msg = progress?.message;
       if (typeof msg !== 'string' || msg.length === 0) return;
@@ -97,6 +207,25 @@ export class StratumMcpClient {
       // Discriminator: BuildStreamEvent has schema_version + kind + flow_id + step_id
       if (!parsed || typeof parsed !== 'object') return;
       if (typeof parsed.kind !== 'string') return;
+      // The onprogress handler is bound to ONE tool call, so an envelope belongs
+      // to this call iff its flow_id is either (a) ABSENT (undefined) — the TS
+      // agent_run wire shape carries no correlation_id (see buildAgentRunRequest),
+      // so stamp this call's id — or (b) already EQUAL to this call's correlation
+      // id (python echo parity). V6/F7: any OTHER producer-set flow_id is a
+      // misroute (one call's stream must never leak into another's subscriber) —
+      // drop it. A present-but-falsy flow_id ('' / null / 0) is malformed, NOT
+      // absent: it is dropped+warned, never laundered into a stamped valid event.
+      if (callCorrelationId) {
+        if (parsed.flow_id === undefined) {
+          parsed.flow_id = callCorrelationId;
+        } else if (parsed.flow_id !== callCorrelationId) {
+          console.warn(
+            `[stratum-mcp-client] dropping misrouted BuildStreamEvent:` +
+            ` flow_id=${parsed.flow_id} does not match call ${callCorrelationId}`,
+          );
+          return;
+        }
+      }
       // STRAT-PAR-STREAM-CONSUMER-VALIDATE: validate envelope before forwarding.
       // On failure: warn and drop — never throw. Consumer must remain robust to
       // producer drift. Non-BuildStreamEvent payloads are silently ignored above.
@@ -114,7 +243,7 @@ export class StratumMcpClient {
   }
 
   /**
-   * Spawn stratum-mcp and establish MCP connection.
+   * Spawn the TS Stratum MCP server and establish a connection.
    * @param {object} [opts]
    * @param {string} [opts.command] - Override binary (for testing)
    * @param {string[]} [opts.args] - Override args
@@ -123,26 +252,16 @@ export class StratumMcpClient {
   async connect(opts = {}) {
     if (this.#connected) return;
 
-    const command = opts.command ?? 'stratum-mcp';
-    const args = opts.args ?? [];
-
-    // Pre-flight: verify binary exists on $PATH (skip for test overrides)
-    if (command === 'stratum-mcp') {
-      try {
-        execFileSync('which', [command], { stdio: 'pipe', timeout: 3000 });
-      } catch {
-        throw new Error(
-          'stratum-mcp not found on $PATH. Install with: pip install stratum-mcp'
-        );
-      }
-    }
+    const defaults = resolveStratumMcpConnection(opts.cwd);
+    const command = opts.command ?? defaults.command;
+    const args = opts.args ?? defaults.args;
 
     const transportOpts = { command, args, stderr: 'pipe' };
-    if (opts.cwd) transportOpts.cwd = opts.cwd;
+    if (opts.cwd ?? defaults.cwd) transportOpts.cwd = opts.cwd ?? defaults.cwd;
     // Inherit the parent environment. Given no `env`, StdioClientTransport
     // supplies only the MCP SDK's 6-var default allowlist
     // (HOME/LOGNAME/PATH/SHELL/TERM/USER), which strips the auth context the
-    // spawned stratum-mcp → claude agent needs. Once claude credentials moved
+    // spawned Stratum TS MCP → claude agent needs. Once credentials moved
     // to the macOS keychain, that stripped env stopped authenticating and every
     // agent step failed with `403 forbidden / "Request not allowed"`. Pass the
     // full env through; the stratum connector scrubs SENSITIVE_ENV_VARS
@@ -193,7 +312,7 @@ export class StratumMcpClient {
     if (opts.subscribeProgress) {
       // Long-running tool calls may stream events for many minutes.
       // Use generous timeouts and reset on each progress notification.
-      requestOpts.onprogress = this.#makeProgressHandler();
+      requestOpts.onprogress = this.#makeProgressHandler(opts.correlationId);
       requestOpts.resetTimeoutOnProgress = true;
       requestOpts.timeout = 600_000; // 10 min per heartbeat
       requestOpts.maxTotalTimeout = 24 * 60 * 60 * 1000; // 24h hard cap
@@ -201,31 +320,40 @@ export class StratumMcpClient {
 
     const result = await (client ?? this.#client).callTool(callArgs, undefined, requestOpts);
 
-    // MCP tool results come back as content array; extract text content
+    // TS stratum returns the payload as native MCP structured content and also
+    // mirrors it as JSON text. Prefer the native object, retaining text parsing
+    // for servers that only provide the baseline MCP content array.
+    const structuredContent = result.structuredContent;
+    const hasStructuredContent = structuredContent
+      && typeof structuredContent === 'object'
+      && !Array.isArray(structuredContent);
     const textContent = result.content?.find(c => c.type === 'text');
-    if (!textContent) {
+    if (!hasStructuredContent && !textContent) {
       throw new StratumError('EMPTY_RESPONSE', `Tool ${toolName} returned no text content`, '');
     }
 
     // MCP isError flag indicates tool-level failure
     if (result.isError) {
-      throw new StratumError('TOOL_ERROR', textContent.text, '');
+      const message = textContent?.text ?? JSON.stringify(structuredContent);
+      throw new StratumError('TOOL_ERROR', message, '');
     }
 
-    let parsed;
-    try {
-      parsed = JSON.parse(textContent.text);
-    } catch {
-      // Try to extract JSON from text that may have surrounding prose
-      const jsonMatch = textContent.text.match(/\{[\s\S]*\}/);
-      if (jsonMatch) {
-        try {
-          parsed = JSON.parse(jsonMatch[0]);
-        } catch {
+    let parsed = structuredContent;
+    if (!hasStructuredContent) {
+      try {
+        parsed = JSON.parse(textContent.text);
+      } catch {
+        // Try to extract JSON from text that may have surrounding prose
+        const jsonMatch = textContent.text.match(/\{[\s\S]*\}/);
+        if (jsonMatch) {
+          try {
+            parsed = JSON.parse(jsonMatch[0]);
+          } catch {
+            throw new StratumError('PARSE_ERROR', `Tool ${toolName} returned invalid JSON`, textContent.text);
+          }
+        } else {
           throw new StratumError('PARSE_ERROR', `Tool ${toolName} returned invalid JSON`, textContent.text);
         }
-      } else {
-        throw new StratumError('PARSE_ERROR', `Tool ${toolName} returned invalid JSON`, textContent.text);
       }
     }
 
@@ -244,13 +372,26 @@ export class StratumMcpClient {
 
   /**
    * Start a flow. Returns the first step dispatch.
-   * @param {string} spec - Inline YAML spec content (not a file path)
+   * @param {string|object} spec - Parsed spec or inline YAML content
    * @param {string} flow - Flow name within the spec
    * @param {object} inputs - Flow input values
    * @returns {Promise<object>} Step dispatch response
    */
-  async plan(spec, flow, inputs) {
-    return this.#callTool('stratum_plan', { spec, flow, inputs });
+  async plan(spec, flow, inputs, opts = {}) {
+    const parsedSpec = typeof spec === 'string' ? YAML.parse(spec) : spec;
+    const resolvedSpec = resolvePlanSpecValues(parsedSpec, inputs);
+    // D4: the engine jails file predicates (file_exists / file_contains in
+    // ensures) to a workspace root and fails closed ("file function requires a
+    // workspace root") without one. Pass the target repo so deterministic
+    // artifact ensures on ordinary steps evaluate. Persisted on the run, so
+    // resume needs no re-send.
+    return this.#callTool('stratum_plan', {
+      spec: resolvedSpec,
+      input: inputs,
+      ...(typeof opts.workspaceRoot === 'string' && opts.workspaceRoot.length > 0
+        ? { workspaceRoot: opts.workspaceRoot }
+        : {}),
+    });
   }
 
   /**
@@ -259,7 +400,7 @@ export class StratumMcpClient {
    * @returns {Promise<object>} Step dispatch response (same format as plan/stepDone)
    */
   async resume(flowId) {
-    return this.#callTool('stratum_resume', { flow_id: flowId });
+    return this.#callTool('stratum_resume', { runId: flowId });
   }
 
   /**
@@ -267,13 +408,17 @@ export class StratumMcpClient {
    * @param {string} flowId
    * @param {string} stepId
    * @param {object} result - Step result (must match output_contract)
+   * @param {string} [dispatchToken] - Engine-issued ready-entry issuance token to echo
    * @returns {Promise<object>}
    */
-  async stepDone(flowId, stepId, result) {
+  async stepDone(flowId, stepId, result, dispatchToken) {
     return this.#callTool('stratum_step_done', {
-      flow_id: flowId,
-      step_id: stepId,
+      runId: flowId,
+      stepId,
       result,
+      // Flag-day universal fencing: tokens are opaque and only non-empty strings
+      // are transmitted. The strict TS schema rejects the retired epoch field.
+      ...(typeof dispatchToken === 'string' && dispatchToken.length > 0 ? { dispatchToken } : {}),
     });
   }
 
@@ -284,30 +429,15 @@ export class StratumMcpClient {
    * @param {'approve'|'revise'|'kill'} outcome
    * @param {string} rationale
    * @param {'human'|'agent'|'system'} resolvedBy
+   * @param {string} [gateToken] - Audit-discovered waiting-gate issuance token to echo
    * @returns {Promise<object>}
    */
-  async gateResolve(flowId, stepId, outcome, rationale, resolvedBy = 'human') {
+  async gateResolve(flowId, stepId, outcome, rationale, resolvedBy = 'human', gateToken) {
     return this.#callTool('stratum_gate_resolve', {
-      flow_id: flowId,
-      step_id: stepId,
-      outcome,
-      rationale,
-      resolved_by: resolvedBy,
-    });
-  }
-
-  /**
-   * Skip the current step with a recorded reason.
-   * @param {string} flowId
-   * @param {string} stepId
-   * @param {string} reason
-   * @returns {Promise<object>}
-   */
-  async skipStep(flowId, stepId, reason) {
-    return this.#callTool('stratum_skip_step', {
-      flow_id: flowId,
-      step_id: stepId,
-      reason,
+      runId: flowId,
+      stepId,
+      decision: outcome,
+      ...(typeof gateToken === 'string' && gateToken.length > 0 ? { gateToken } : {}),
     });
   }
 
@@ -317,50 +447,7 @@ export class StratumMcpClient {
    * @returns {Promise<object>}
    */
   async audit(flowId) {
-    return this.#callTool('stratum_audit', { flow_id: flowId });
-  }
-
-  /**
-   * Start a counted iteration loop on a step.
-   * @param {string} flowId
-   * @param {string} stepId
-   * @returns {Promise<object>}
-   */
-  async iterationStart(flowId, stepId) {
-    return this.#callTool('stratum_iteration_start', {
-      flow_id: flowId,
-      step_id: stepId,
-    });
-  }
-
-  /**
-   * Report one iteration result.
-   * @param {string} flowId
-   * @param {string} stepId
-   * @param {object} result
-   * @returns {Promise<object>}
-   */
-  async iterationReport(flowId, stepId, result) {
-    return this.#callTool('stratum_iteration_report', {
-      flow_id: flowId,
-      step_id: stepId,
-      result,
-    });
-  }
-
-  /**
-   * Abort an iteration loop early.
-   * @param {string} flowId
-   * @param {string} stepId
-   * @param {string} reason
-   * @returns {Promise<object>}
-   */
-  async iterationAbort(flowId, stepId, reason) {
-    return this.#callTool('stratum_iteration_abort', {
-      flow_id: flowId,
-      step_id: stepId,
-      reason,
-    });
+    return this.#callTool('stratum_audit', { runId: flowId });
   }
 
   /**
@@ -399,77 +486,7 @@ export class StratumMcpClient {
   }
 
   /**
-   * Report batch task results for a parallel_dispatch step.
-   * @param {string} flowId
-   * @param {string} stepId
-   * @param {Array<{task_id: string, status: string, result?: object, error?: string}>} taskResults
-   * @param {'clean'|'conflict'|'fallback'|'manual_required'|{status:string,bounced_tasks?:object[]}} mergeStatus
-   *   COMP-PAR-MERGE-QUEUE-CONSUMER: either a bare status string (back-compat) or a
-   *   structured object carrying gate/conflict bounce records. Serializes as-is.
-   * @returns {Promise<object>} Next dispatch response
-   */
-  async parallelDone(flowId, stepId, taskResults, mergeStatus) {
-    return this.#callTool('stratum_parallel_done', {
-      flow_id:      flowId,
-      step_id:      stepId,
-      task_results: taskResults,
-      merge_status: mergeStatus,
-    });
-  }
-
-  /**
-   * Start server-side execution of a parallel_dispatch step (T2-F5-COMPOSE-MIGRATE).
-   * Returns {status: 'started', ...} on success or {error, message} on known error.
-   * @param {string} flowId
-   * @param {string} stepId
-   * @returns {Promise<object>}
-   */
-  async parallelStart(flowId, stepId) {
-    return this.#callTool('stratum_parallel_start', {
-      flow_id: flowId,
-      step_id: stepId,
-    }, { subscribeProgress: true });
-  }
-
-  /**
-   * Poll state of a server-dispatched parallel_dispatch step (T2-F5-COMPOSE-MIGRATE).
-   * Returns {summary, tasks, require_satisfied, can_advance, outcome}.
-   * Break on `outcome != null`, not `can_advance` — see design doc §3.
-   * @param {string} flowId
-   * @param {string} stepId
-   * @returns {Promise<object>}
-   */
-  async parallelPoll(flowId, stepId) {
-    return this.#callTool('stratum_parallel_poll', {
-      flow_id: flowId,
-      step_id: stepId,
-    }, { subscribeProgress: true });
-  }
-
-  /**
-   * Consumer-driven advance for parallel_dispatch steps with defer_advance:true.
-   * Call after observing outcome.status === 'awaiting_consumer_advance' from
-   * parallelPoll. Feeds merge_status back to Stratum which runs
-   * _evaluate_parallel_results + _advance_after_parallel and returns the real
-   * advance outcome.
-   *
-   * @param {string} flowId
-   * @param {string} stepId
-   * @param {'clean'|'conflict'|{status:'clean'|'conflict',bounced_tasks?:object[]}} mergeStatus
-   *   COMP-PAR-MERGE-QUEUE: either a bare status string (back-compat) or a
-   *   structured object carrying merge_conflict bounce records. Serializes as-is.
-   * @returns {Promise<object>}
-   */
-  async parallelAdvance(flowId, stepId, mergeStatus) {
-    return this.#callTool('stratum_parallel_advance', {
-      flow_id: flowId,
-      step_id: stepId,
-      merge_status: mergeStatus,
-    });
-  }
-
-  /**
-   * Run an agent (claude/codex) via the Python connector tier and stream
+   * Run an agent (claude/codex) via the Stratum connector tier and stream
    * BuildStreamEvent envelopes back via MCP progress notifications.
    * Subscribe via `onEvent(correlationId, '_agent_run', handler)` BEFORE calling.
    *
@@ -483,7 +500,7 @@ export class StratumMcpClient {
    * @param {object}   [opts.thinking]
    * @param {string}   [opts.effort]
    * @param {string}   [opts.cwd]
-   * @returns {Promise<{text: string, correlation_id: string}>}
+   * @returns {Promise<{text: string}>}
    *
    * NOTE: Schema injection is the caller's responsibility — `runAndNormalize`
    * runs `injectSchema(prompt, schema)` client-side. Forwarding `schema` to
@@ -492,21 +509,15 @@ export class StratumMcpClient {
    */
   async agentRun(agentType, prompt, opts = {}) {
     const correlationId = opts.correlationId ?? randomUUID();
-    const result = await this.#callTool('stratum_agent_run', {
-      type:              agentType,
-      prompt,
-      modelID:           opts.modelID ?? undefined,
-      allowed_tools:     opts.allowedTools ?? undefined,
-      disallowed_tools:  opts.disallowedTools ?? undefined,
-      thinking:          opts.thinking ?? undefined,
-      effort:            opts.effort ?? undefined,
-      cwd:               opts.cwd ?? undefined,
-      correlation_id:    correlationId,
-    }, { subscribeProgress: true });
-    if (result && typeof result === 'object' && !result.correlation_id) {
-      result.correlation_id = correlationId;
-    }
-    return result;
+    // TS surface (contracts/mcp-surface.json → stratum_agent_run): the request
+    // is {agent, prompt, cwd, model?, sandboxMode?, background?} and rejects any
+    // undeclared key. The python-era tier accepted {type, allowed_tools, ...};
+    // those knobs are resolved compose-side (resolveAgentConfig) and applied at
+    // this seam — the engine's connector honors model + sandboxMode. `cwd` is
+    // required, so default to the process cwd when the caller omits it.
+    return this.#callTool('stratum_agent_run',
+      buildAgentRunRequest(agentType, prompt, opts),
+      { subscribeProgress: true, correlationId });
   }
 
   /**
@@ -520,24 +531,24 @@ export class StratumMcpClient {
    * @returns {Promise<string>}
    */
   async runAgentText(agentType, prompt, opts = {}) {
-    const result = await this.#callTool('stratum_agent_run', {
-      type:   agentType,
-      prompt,
-      cwd:    opts.cwd ?? undefined,
-    }, { subscribeProgress: false });
+    const result = await this.#callTool('stratum_agent_run',
+      buildAgentRunRequest(agentType, prompt, opts),
+      { subscribeProgress: false });
     return result?.text ?? '';
   }
 
   /**
-   * Cancel an in-flight stratum_agent_run by correlation id. Returns
-   * `{status: 'cancelled' | 'not_found', correlation_id}` from the producer.
+   * Cancel an in-flight agent run. V2: the TS surface
+   * (contracts/mcp-surface.json → stratum_cancel_agent_run) takes {runId}, not
+   * the python-era {correlation_id} the engine now rejects. Only BACKGROUND runs
+   * carry a runId to cancel; a synchronous agent_run returns no handle, so this
+   * is a no-op (not_found) there — synchronous controlled executions are
+   * interrupted via the local connector's AbortController instead.
    *
-   * @param {string} correlationId
+   * @param {string} runId
    * @returns {Promise<object>}
    */
-  async cancelAgentRun(correlationId) {
-    return this.#callTool('stratum_cancel_agent_run', {
-      correlation_id: correlationId,
-    });
+  async cancelAgentRun(runId) {
+    return this.#callTool('stratum_cancel_agent_run', { runId });
   }
 }