@smartmemory/compose 0.3.6-beta → 0.3.8

package/lib/local-claude-connector.js

@@ -1,3 +1,5 @@
+import { spawn } from 'node:child_process';
+import { processTermination } from './process-termination.js';
 /**
  * local-claude-connector.js — V2/V3 (STRAT-TS-FANOUT-CONSUMER).
  *
@@ -17,8 +19,11 @@
  * and reports usage. The SDK `query` is injectable for tests.
  */
 
+import { randomUUID } from 'node:crypto';
 import { query as sdkQuery } from '@anthropic-ai/claude-agent-sdk';
 
+import { appendEvent, resolveDispatchLedgerCwd } from './dispatch-ledger.js';
+
 const SENSITIVE_ENV_VARS = ['ANTHROPIC_API_KEY', 'OPENAI_API_KEY', 'CLAUDE_API_KEY', 'CLAUDECODE'];
 
 function isRecord(value) {
@@ -29,6 +34,77 @@ function nonneg(value) {
   return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : 0;
 }
 
+function reportedNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null;
+}
+
+function reportedString(value) {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+function isBlockedDispatch(value) {
+  const candidates = [value?.status, value?.outcome, value?.code, value?.subtype];
+  return candidates.some((candidate) => {
+    const normalized = typeof candidate === 'string' ? candidate.toLowerCase() : '';
+    return normalized === 'blocked'
+      || normalized === 'budget_exhausted'
+      || normalized === 'budget-exhausted';
+  });
+}
+
+function attachDispatchId(value, dispatchId) {
+  if ((typeof value !== 'object' && typeof value !== 'function') || value === null) return;
+  try {
+    Object.defineProperty(value, 'dispatchId', {
+      configurable: true,
+      enumerable: false,
+      value: dispatchId,
+    });
+  } catch {
+    // Capture metadata must never replace the SDK's original behavior.
+  }
+}
+
+function recordDispatch(dispatchId, context, capture, outcome, elapsedMs, effortExecuted) {
+  try {
+    const event = {
+      kind: 'dispatch',
+      dispatch_id: dispatchId,
+      site: reportedString(context.site) ?? 'unattributed',
+      agent: 'claude',
+      outcome,
+      model: reportedString(capture.model),
+      effort_intended: reportedString(context.effort_intended),
+      // Executed effort is only recorded once a model run is confirmed — the SDK
+      // emitted a model identity (init or result). A transport/startup failure
+      // before any model spoke leaves effort_executed null, so the executed-effort
+      // curve is not polluted by tiers that were requested but never actually ran
+      // (mirrors the codex route, whose effort_executed comes from run telemetry).
+      effort_executed: capture.model ? reportedString(effortExecuted) : null,
+      tokens_in: reportedNumber(capture.inputTokens),
+      tokens_out: reportedNumber(capture.outputTokens),
+      tokens_total: capture.inputTokens !== null || capture.outputTokens !== null
+        ? (reportedNumber(capture.inputTokens) ?? 0) + (reportedNumber(capture.outputTokens) ?? 0)
+        : null,
+      usd: reportedNumber(capture.costUsd),
+      duration_ms: reportedNumber(capture.durationMs) ?? reportedNumber(elapsedMs),
+    };
+    for (const [field, value] of [
+      ['build_id', context.build_id],
+      ['feature_code', context.feature_code],
+      ['step_id', context.step_id],
+    ]) {
+      if (reportedString(value) !== null) event[field] = value;
+    }
+    if (typeof context.attempt === 'number' && Number.isFinite(context.attempt)) {
+      event.attempt = context.attempt;
+    }
+    appendEvent(resolveDispatchLedgerCwd(context.project_cwd), event);
+  } catch {
+    // Dispatch capture is fail-open by contract.
+  }
+}
+
 /**
  * Run a controlled claude agent locally.
  *
@@ -39,24 +115,66 @@ function nonneg(value) {
  * @param {string[]} [opts.allowedTools]     enforced tool allowlist (read-only review)
  * @param {string[]} [opts.disallowedTools]
  * @param {object}   [opts.thinking]
+ * @param {string}   [opts.effort]           reasoning-effort tier (low|medium|high|xhigh|max)
  * @param {AbortController} [opts.abortController]  abort → interrupt the run
  * @param {(ev:{tool:string,input:object})=>void} [opts.onToolUse]  per tool_use block
  * @param {NodeJS.ProcessEnv} [opts.env]
  * @param {Function} [opts.query]            SDK `query` seam for tests
+ * @param {object} [opts.telemetry]           Compose-only dispatch context
  * @returns {Promise<{text:string, usage:object, telemetry:object}>}
  */
 export async function runLocalClaudeAgent(prompt, opts = {}) {
   const query = opts.query ?? sdkQuery;
+  const controller = opts.abortController;
+  controller?.signal.throwIfAborted();
+  // C2: group cancellation needs POSIX process groups. Windows has none, so
+  // instead of refusing the run (which killed EVERY local dispatch there,
+  // cancellable or not) we skip the custom spawn hook and let the SDK's own
+  // abortController tear the run down. That is weaker — the SDK kills only the
+  // CLI leader, so grandchildren can outlive a cancel — but a non-cancel run
+  // must never fail before spawn.
+  const platform = opts.platform ?? process.platform;
+  const ownProcessGroup = Boolean(controller) && platform !== 'win32';
+  const children = [];
+  let stderr = '';
+  const terminate = () => { for (const child of children) void child.terminate(); };
+  controller?.signal.addEventListener('abort', terminate, { once: true });
+  const { telemetry } = opts;
+  const telemetryContext = telemetry && typeof telemetry === 'object'
+    ? telemetry
+    : {};
   const env = { ...(opts.env ?? process.env) };
   for (const key of SENSITIVE_ENV_VARS) delete env[key];
 
+  // Only forward a non-empty effort so routes without a configured tier keep the
+  // SDK's default behavior; the applied value is what we record as effort_executed.
+  const appliedEffort = reportedString(opts.effort);
   const sdkOptions = {
     cwd: opts.cwd ?? process.cwd(),
     model: opts.model ?? process.env.CLAUDE_MODEL ?? 'claude-sonnet-4-6',
     permissionMode: 'acceptEdits',
     env,
+    ...(ownProcessGroup ? { spawnClaudeCodeProcess: (options) => {
+      controller.signal.throwIfAborted();
+      const child = spawn(options.command, options.args, {
+        cwd: options.cwd, env: options.env, detached: true, stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      const termination = processTermination(child, true, opts.cancellationGraceMs);
+      children.push(termination);
+      child.stderr.setEncoding('utf8');
+      child.stderr.on('data', chunk => { stderr = (stderr + chunk).slice(-16384); });
+      const sdkAbort = () => { void termination.terminate(); };
+      options.signal.addEventListener('abort', sdkAbort, { once: true });
+      void termination.close.then(() => options.signal.removeEventListener('abort', sdkAbort));
+      if (options.signal.aborted) sdkAbort();
+      return { stdin: child.stdin, stdout: child.stdout, pid: child.pid,
+        get killed() { return child.killed; }, get exitCode() { return child.exitCode; },
+        kill: () => { void termination.terminate(); return true; },
+        on: child.on.bind(child), once: child.once.bind(child), off: child.off.bind(child) };
+    } } : {}),
     ...(opts.abortController ? { abortController: opts.abortController } : {}),
     ...(opts.thinking !== undefined ? { thinking: opts.thinking } : {}),
+    ...(appliedEffort !== null ? { effort: appliedEffort } : {}),
   };
   // A read-only profile passes an explicit allowlist; without one, the agent
   // gets the full claude_code preset (unrestricted).
@@ -83,67 +201,145 @@ export async function runLocalClaudeAgent(prompt, opts = {}) {
   let inputTokens = 0;
   let outputTokens = 0;
   let costUsd = 0;
+  const capture = {
+    model: null,
+    inputTokens: null,
+    outputTokens: null,
+    costUsd: null,
+    durationMs: null,
+  };
+  let resultError = null;
+  let resultFailureOutcome = null;
+  const dispatchId = randomUUID();
+  const dispatchStartedAt = Date.now();
 
-  for await (const raw of query({ prompt, options: sdkOptions })) {
-    if (!isRecord(raw)) continue;
-    if (raw.type === 'system' && raw.subtype === 'init' && typeof raw.model === 'string') {
-      resolvedModel = raw.model;
-    }
-    if (raw.type === 'assistant' && isRecord(raw.message) && Array.isArray(raw.message.content)) {
-      for (const block of raw.message.content) {
-        if (!isRecord(block)) continue;
-        if (block.type === 'text' && typeof block.text === 'string') assistantText += block.text;
-        if (block.type === 'tool_use' && typeof block.name === 'string' && typeof opts.onToolUse === 'function') {
-          opts.onToolUse({ tool: block.name, input: isRecord(block.input) ? block.input : {} });
+  try {
+    for await (const raw of query({ prompt, options: sdkOptions })) {
+      if (!isRecord(raw)) continue;
+      if (raw.type === 'system' && raw.subtype === 'init' && typeof raw.model === 'string') {
+        resolvedModel = raw.model;
+        capture.model = raw.model;
+      }
+      if (raw.type === 'assistant' && isRecord(raw.message) && Array.isArray(raw.message.content)) {
+        for (const block of raw.message.content) {
+          if (!isRecord(block)) continue;
+          if (block.type === 'text' && typeof block.text === 'string') {
+            assistantText += block.text;
+            // COMP-AGENT-LANES: optional live-relay seam, mirroring onToolUse.
+            // Without a subscriber the text only accumulates (historical shape).
+            if (typeof opts.onAssistantText === 'function') opts.onAssistantText(block.text);
+          }
+          if (block.type === 'tool_use' && typeof block.name === 'string' && typeof opts.onToolUse === 'function') {
+            opts.onToolUse({ tool: block.name, input: isRecord(block.input) ? block.input : {} });
+          }
         }
       }
+      if (raw.type !== 'result') continue;
+      durationMs = nonneg(raw.duration_ms);
+      capture.durationMs = reportedNumber(raw.duration_ms);
+      capture.costUsd = reportedNumber(raw.total_cost_usd);
+      if (reportedString(raw.model) !== null) capture.model = raw.model;
+      if (isRecord(raw.usage)) {
+        capture.inputTokens = reportedNumber(raw.usage.input_tokens);
+        capture.outputTokens = reportedNumber(raw.usage.output_tokens);
+        capture.model = reportedString(raw.usage.model) ?? capture.model;
+      }
+      if (raw.subtype !== 'success') {
+        // F3: a failed run still consumed billable tokens/cost. Capture them from
+        // the error result (SDKResultError carries usage + total_cost_usd) and
+        // attach to the thrown Error — same usage shape as the success return — so
+        // the consumer failure path can debit the engine/GSD ledgers. Without this,
+        // repeated failures evade budget exhaustion.
+        const failCost = nonneg(raw.total_cost_usd);
+        const failIn = isRecord(raw.usage) ? nonneg(raw.usage.input_tokens) : 0;
+        const failOut = isRecord(raw.usage) ? nonneg(raw.usage.output_tokens) : 0;
+        const errors = Array.isArray(raw.errors) ? raw.errors.filter((v) => typeof v === 'string') : [];
+        const err = new Error(errors.join('; ') || `claude query failed: ${String(raw.subtype)}`);
+        err.usage = {
+          input_tokens: failIn,
+          output_tokens: failOut,
+          tokens: failIn + failOut,
+          cost_usd: failCost,
+          usd: failCost,
+          duration_ms: durationMs,
+          ms: durationMs,
+          model: resolvedModel,
+        };
+        err.costUsd = failCost;
+        resultError = err;
+        resultFailureOutcome = isBlockedDispatch(raw) ? 'blocked' : 'error';
+        throw err;
+      }
+      if (typeof raw.result === 'string') finalText = raw.result;
+      costUsd = nonneg(raw.total_cost_usd);
+      if (isRecord(raw.usage)) {
+        inputTokens = nonneg(raw.usage.input_tokens);
+        outputTokens = nonneg(raw.usage.output_tokens);
+      }
     }
-    if (raw.type !== 'result') continue;
-    durationMs = nonneg(raw.duration_ms);
-    if (raw.subtype !== 'success') {
-      // F3: a failed run still consumed billable tokens/cost. Capture them from
-      // the error result (SDKResultError carries usage + total_cost_usd) and
-      // attach to the thrown Error — same usage shape as the success return — so
-      // the consumer failure path can debit the engine/GSD ledgers. Without this,
-      // repeated failures evade budget exhaustion.
-      const failCost = nonneg(raw.total_cost_usd);
-      const failIn = isRecord(raw.usage) ? nonneg(raw.usage.input_tokens) : 0;
-      const failOut = isRecord(raw.usage) ? nonneg(raw.usage.output_tokens) : 0;
-      const errors = Array.isArray(raw.errors) ? raw.errors.filter((v) => typeof v === 'string') : [];
-      const err = new Error(errors.join('; ') || `claude query failed: ${String(raw.subtype)}`);
-      err.usage = {
-        input_tokens: failIn,
-        output_tokens: failOut,
-        tokens: failIn + failOut,
-        cost_usd: failCost,
-        usd: failCost,
+
+    // H2: do NOT throwIfAborted() here. A run that RESOLVES after its
+    // timeout/abort fired still reported billable usage, and the caller
+    // (result-normalizer's late-resolve branch) is the single place that turns
+    // that into AgentTimeoutError/AgentAbortedError/UserInterruptError with the
+    // usage attached. Throwing a bare AbortError here loses the usage and the
+    // attempt is never billed.
+    const result = {
+      text: finalText ?? assistantText,
+      usage: {
+        input_tokens: inputTokens,
+        output_tokens: outputTokens,
+        tokens: inputTokens + outputTokens,
+        cost_usd: costUsd,
+        usd: costUsd,
         duration_ms: durationMs,
         ms: durationMs,
         model: resolvedModel,
-      };
-      err.costUsd = failCost;
-      throw err;
-    }
-    if (typeof raw.result === 'string') finalText = raw.result;
-    costUsd = nonneg(raw.total_cost_usd);
-    if (isRecord(raw.usage)) {
-      inputTokens = nonneg(raw.usage.input_tokens);
-      outputTokens = nonneg(raw.usage.output_tokens);
+      },
+      telemetry: { durationMs, model: resolvedModel },
+    };
+    recordDispatch(
+      dispatchId,
+      telemetryContext,
+      capture,
+      'ok',
+      Date.now() - dispatchStartedAt,
+      appliedEffort,
+    );
+    attachDispatchId(result, dispatchId);
+    return result;
+  } catch (error) {
+    if (error !== resultError && error && typeof error === 'object') {
+      const errorUsage = isRecord(error.usage) ? error.usage : {};
+      const errorTelemetry = isRecord(error.telemetry) ? error.telemetry : {};
+      capture.model = reportedString(errorTelemetry.model)
+        ?? reportedString(errorUsage.model)
+        ?? capture.model;
+      capture.inputTokens = reportedNumber(errorUsage.input_tokens) ?? capture.inputTokens;
+      capture.outputTokens = reportedNumber(errorUsage.output_tokens) ?? capture.outputTokens;
+      capture.costUsd = reportedNumber(errorUsage.cost_usd)
+        ?? reportedNumber(errorUsage.usd)
+        ?? capture.costUsd;
+      capture.durationMs = reportedNumber(errorUsage.duration_ms)
+        ?? reportedNumber(errorUsage.ms)
+        ?? reportedNumber(errorTelemetry.durationMs)
+        ?? capture.durationMs;
     }
+    recordDispatch(
+      dispatchId,
+      telemetryContext,
+      capture,
+      resultFailureOutcome ?? (isBlockedDispatch(error) ? 'blocked' : 'error'),
+      Date.now() - dispatchStartedAt,
+      appliedEffort,
+    );
+    attachDispatchId(error, dispatchId);
+    if (controller?.signal.aborted) { terminate(); await Promise.all(children.map(child => child.finish())); }
+    if (stderr) { error.stderr = stderr; error.cause ??= new Error(stderr.trim()); }
+    throw error;
+  } finally {
+    controller?.signal.removeEventListener('abort', terminate);
+    if (controller?.signal.aborted) terminate();
+    await Promise.all(children.map(child => child.finish()));
   }
-
-  return {
-    text: finalText ?? assistantText,
-    usage: {
-      input_tokens: inputTokens,
-      output_tokens: outputTokens,
-      tokens: inputTokens + outputTokens,
-      cost_usd: costUsd,
-      usd: costUsd,
-      duration_ms: durationMs,
-      ms: durationMs,
-      model: resolvedModel,
-    },
-    telemetry: { durationMs, model: resolvedModel },
-  };
 }

package/lib/maya-client.js

@@ -0,0 +1,302 @@
+/**
+ * maya-client.js — COMP-FOH FOH-6 S1
+ *
+ * HTTP client for Maya's chat surface (`/Users/ruze/reg/my/SmartMemory/maya/`,
+ * read-only upstream — POST /api/chat, routes.py:5354; GET /health,
+ * maya_server.py:46). Speaks HTTP and nothing else; context composition and
+ * write-back belong to the relay.
+ *
+ * Failure conventions, per design-foh-6.md §2 and the smartmemory-client
+ * doctrine:
+ *   - 401 → ONE retry with the SAME token (transient), then MayaAuthError.
+ *     Never re-provision here: the identity owns the standing conversation,
+ *     and a 401 does not prove expiry.
+ *   - a 2xx we cannot trust (non-JSON body, success !== true, missing
+ *     message_id) is a failure with kind 'malformed-response', not a success —
+ *     message_id is the write-back idempotency key, so a reply without one
+ *     cannot be treated as a completed turn.
+ *   - network failure / deadline → status 0.
+ *   - health() never throws.
+ *
+ * The chat deadline defaults generously (her turn does LLM work upstream);
+ * the live VERIFY used 120s.
+ */
+
+/** Non-auth failure of a Maya call. */
+export class MayaHttpError extends Error {
+  constructor(message, status, kind) {
+    super(message);
+    this.name = 'MayaHttpError';
+    this.status = status;
+    this.kind = kind;
+  }
+}
+
+/** 401 after the single same-token retry. The relay maps this to the auth
+ *  funnel with its explicit continuity-costing actions. */
+export class MayaAuthError extends MayaHttpError {
+  constructor(message) {
+    super(message, 401);
+    this.name = 'MayaAuthError';
+  }
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.baseUrl
+ * @param {() => (string|Promise<string>)} opts.getToken  read at CALL time
+ * @param {number} [opts.timeoutMs]      health deadline (default 3000)
+ * @param {number} [opts.chatTimeoutMs]  chat deadline (default 120000)
+ */
+export function createMayaClient({ baseUrl, getToken, timeoutMs = 3000, chatTimeoutMs = 120000 }) {
+  async function fetchJson(path, { init, deadline }) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), deadline);
+    let res;
+    let text;
+    try {
+      res = await fetch(`${baseUrl}${path}`, { ...init, signal: controller.signal });
+      text = await res.text();
+    } catch (err) {
+      throw new MayaHttpError(
+        `maya: ${path} request failed: ${err?.message ?? 'unknown error'}`, 0,
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+    let parsed = null;
+    let parseFailed = false;
+    try { parsed = JSON.parse(text); } catch { parseFailed = true; }
+    return { status: res.status, ok: res.ok, body: parsed, parseFailed };
+  }
+
+  /** Liveness only. Unauthenticated, never throws. */
+  async function health() {
+    try {
+      const res = await fetchJson('/health', { deadline: timeoutMs });
+      return { ok: res.ok, status: res.status };
+    } catch {
+      return { ok: false };
+    }
+  }
+
+  /**
+   * One conversational turn. `channelContext` travels verbatim as the wire's
+   * `channel_context: [{author, text}]` and is OMITTED (not sent empty) when
+   * absent — an empty array still exercises Maya's context-injection path.
+   *
+   * @param {{message: string, channelContext?: Array<{author: string, text: string}>,
+   *          surface?: string, timezone?: string}} args
+   * @returns {Promise<{success: true, response: string, message_id: string,
+   *                    memory_available?: boolean}>}
+   */
+  async function chat({ message, channelContext, surface, timezone = 'UTC' }) {
+    const body = { message, timezone };
+    if (Array.isArray(channelContext) && channelContext.length) {
+      body.channel_context = channelContext;
+    }
+    if (surface !== undefined) body.surface = surface;
+
+    // Captured ONCE per chat() call: "one same-token retry" is a literal
+    // contract — reading the token again for the retry could pick up a
+    // concurrent paste/re-provision and silently move the retry onto a
+    // different identity and conversation (Codex r1 P2).
+    const token = await getToken();
+    const send = () => fetchJson('/api/chat', {
+      deadline: chatTimeoutMs,
+      init: {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+        body: JSON.stringify(body),
+      },
+    });
+
+    let res = await send();
+    if (res.status === 401) res = await send(); // one same-token retry
+    if (res.status === 401) {
+      throw new MayaAuthError('maya: authentication rejected after one same-token retry');
+    }
+    if (!res.ok) {
+      throw new MayaHttpError(`maya: chat failed (HTTP ${res.status})`, res.status);
+    }
+    if (res.parseFailed) {
+      throw new MayaHttpError(
+        `maya: chat returned a 2xx (HTTP ${res.status}) with a non-JSON body`,
+        res.status, 'malformed-response',
+      );
+    }
+    const reply = res.body;
+    if (reply?.success !== true || typeof reply?.response !== 'string'
+        || typeof reply?.message_id !== 'string' || !reply.message_id) {
+      throw new MayaHttpError(
+        'maya: chat returned a 2xx body this relay cannot trust '
+        + '(needs success:true, a response string, and a message_id)',
+        res.status, 'malformed-response',
+      );
+    }
+    return reply;
+  }
+
+  /** Streaming conversational turn. Token chunks are display-only; only a
+   *  validated final envelope completes the turn. */
+  async function chatStream({ message, channelContext, surface, timezone = 'UTC', onToken }) {
+    const body = { message, timezone };
+    if (Array.isArray(channelContext) && channelContext.length) {
+      body.channel_context = channelContext;
+    }
+    if (surface !== undefined) body.surface = surface;
+
+    // One deadline and one captured token cover both the HTTP-status retry and
+    // the complete response stream. A mid-stream 401 is never retried.
+    const token = await getToken();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), chatTimeoutMs);
+    let streamOpened = false;
+    let detached = false;
+
+    const send = () => fetch(`${baseUrl}/api/chat/stream`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'text/event-stream',
+        Authorization: `Bearer ${token}`,
+      },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+
+    try {
+      let res = await send();
+      if (res.status === 401) {
+        await res.body?.cancel();
+        res = await send();
+      }
+      if (res.status === 401) {
+        throw new MayaAuthError('maya: authentication rejected after one same-token retry');
+      }
+      if (!res.ok) {
+        throw new MayaHttpError(`maya: chat failed (HTTP ${res.status})`, res.status);
+      }
+      const contentType = res.headers.get('content-type')?.split(';', 1)[0].trim().toLowerCase();
+      if (contentType !== 'text/event-stream' || !res.body) {
+        throw new MayaHttpError(
+          `maya: chat stream returned a 2xx (HTTP ${res.status}) without text/event-stream`,
+          res.status, 'malformed-response',
+        );
+      }
+      streamOpened = true;
+
+      const handleFrame = (frame) => {
+        let event = '';
+        const data = [];
+        for (const line of frame.split('\n')) {
+          if (line.startsWith(':')) continue;
+          const colon = line.indexOf(':');
+          const field = colon === -1 ? line : line.slice(0, colon);
+          let value = colon === -1 ? '' : line.slice(colon + 1);
+          if (value.startsWith(' ')) value = value.slice(1);
+          if (field === 'event') event = value;
+          if (field === 'data') data.push(value);
+        }
+        if (!['token', 'final', 'error'].includes(event)) return null;
+
+        let envelope;
+        try { envelope = JSON.parse(data.join('\n')); } catch {
+          throw new MayaHttpError(
+            'maya: chat stream contained a malformed event payload',
+            res.status, 'malformed-response',
+          );
+        }
+        const payload = envelope?.payload;
+        if (event === 'token') {
+          if (typeof payload?.text === 'string' && typeof onToken === 'function') {
+            onToken(payload.text);
+          }
+          return null;
+        }
+        if (event === 'error') {
+          const detail = typeof payload?.detail === 'string' ? payload.detail : 'maya: stream failed';
+          if (payload?.status_code === 401) throw new MayaAuthError(detail);
+          throw new MayaHttpError(detail, payload?.status_code);
+        }
+        if (payload?.success !== true || typeof payload?.response !== 'string'
+            || typeof payload?.message_id !== 'string' || !payload.message_id) {
+          throw new MayaHttpError(
+            'maya: chat stream final payload cannot be trusted '
+            + '(needs success:true, a response string, and a message_id)',
+            res.status, 'malformed-response',
+          );
+        }
+        return payload;
+      };
+
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder('utf-8');
+      let buffer = '';
+
+      // Maya persists the turn AFTER emitting `final` (routes.py:5106-5310:
+      // conversation history, engagement, storage enqueue) — her own web
+      // client drains to EOF. Aborting on receipt of `final` would race that
+      // post-final work, so the validated reply returns immediately while a
+      // detached drain consumes the stream to EOF. The overall deadline still
+      // bounds the socket: on expiry the drain is aborted, never the reply.
+      const finishAfterFinal = (reply) => {
+        detached = true;
+        (async () => {
+          try {
+            while (!(await reader.read()).done) { /* contents ignored */ }
+          } catch { /* deadline abort or teardown — the reply already landed */ }
+          finally {
+            clearTimeout(timer);
+            controller.abort();
+          }
+        })();
+        return reply;
+      };
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+          buffer += decoder.decode();
+        } else {
+          buffer += decoder.decode(value, { stream: true });
+        }
+
+        let boundary;
+        while ((boundary = buffer.indexOf('\n\n')) !== -1) {
+          const frame = buffer.slice(0, boundary);
+          buffer = buffer.slice(boundary + 2);
+          const reply = handleFrame(frame);
+          if (reply) return done ? reply : finishAfterFinal(reply);
+        }
+        if (done) break;
+      }
+
+      if (buffer) {
+        const reply = handleFrame(buffer);
+        if (reply) return reply;
+      }
+      throw new MayaHttpError(
+        'maya: chat stream ended without a valid final event',
+        res.status, 'malformed-response',
+      );
+    } catch (err) {
+      const failure = err instanceof MayaHttpError
+        ? err
+        : new MayaHttpError(
+            `maya: /api/chat/stream request failed: ${err?.message ?? 'unknown error'}`, 0,
+          );
+      // The relay uses this to preserve the JSON-before-open / SSE-after-open
+      // boundary even when an error event arrives before the first token.
+      if (streamOpened) failure.streamStarted = true;
+      throw failure;
+    } finally {
+      if (!detached) {
+        clearTimeout(timer);
+        controller.abort();
+      }
+    }
+  }
+
+  return { health, chat, chatStream };
+}