@athenaintel/react 0.43.0 → 0.48.0

package/dist/agent-runtime/src/decision-checks.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-checks.cjs","sources":["../../../../agent-runtime/src/decision-checks.ts"],"sourcesContent":["/**\n * \"Confirm with your passkey\" for surfaces that can't run the passkey prompt\n * themselves (identity row 0b.9, PR C): the phone, Midas, the Chrome\n * extension, the Office add-ins and SDK apps on another origin.\n *\n * A passkey belongs to the deployment's web host, so the check runs there, in\n * the system browser. The surface asks agora for a check over the decisions\n * on its screen (`POST /api/passkeys/decision-checks/requests`), opens the\n * verification URL it gets back, and collects the token once the person\n * confirmed on the web app's check page. It then sends its decision with that\n * token, as the web app does: `X-Athena-Decision-Check` on REST and GraphQL,\n * `decisionCheck` on statewire's `run/input` and `run/lane-input`.\n *\n * Framework-free: React hosts wrap {@link runBrowserDecisionCheck} in a\n * TanStack mutation; the CLI and the phone call it as they are.\n *\n * Every outcome is a value, never a rejection. While checks are report-only\n * (PR D enforces them) the decision goes ahead whatever this resolves, with\n * the token only when the person confirmed.\n */\n\n/** The header a REST or GraphQL decide call carries its check token in. */\nexport const DECISION_CHECK_HEADER = 'X-Athena-Decision-Check';\n\n/** The most decisions one check covers: a screen's worth. */\nexport const MAX_DECISIONS_PER_CHECK = 25;\n\n/** What kind of decision a descriptor describes (agora's `DecisionKind`). */\nexport const DecisionCheckKind = {\n  APPROVAL_DECIDE: 'approval_decide',\n  AUTOMATION_APPROVAL_DECIDE: 'automation_approval_decide',\n  CHAT_APPROVAL_ANSWER: 'chat_approval_answer',\n} as const;\n\nexport type DecisionCheckKind = (typeof DecisionCheckKind)[keyof typeof DecisionCheckKind];\n\n/**\n * One decision a check covers, exactly as its decide call sends it: agora\n * builds the same item from the decide call and asks whether the token covers\n * it. `editedPayload` is the JSON value itself, never a hash of it.\n */\nexport interface DecisionCheckDescriptor {\n  readonly kind: string;\n  readonly targetIds: readonly string[];\n  readonly option: string;\n  readonly editedPayload?: unknown;\n  readonly standingDuration?: string;\n}\n\n/** Which surface asks, as the check page shows it. */\nexport type DecisionCheckClientKind =\n  | 'cli'\n  | 'desktop'\n  | 'mobile'\n  | 'chrome_extension'\n  | 'office_addin'\n  | 'sdk';\n\nexport interface DecisionCheckClient {\n  readonly kind: DecisionCheckClientKind;\n  /** A short name for this device or app (\"Pat's MacBook\"), shown on the page. */\n  readonly label?: string;\n}\n\nconst CHECKPOINT_NAMESPACE = 'athena-deep-agent:';\n\n/** A thread id the way agora names chat answers: without the checkpoint namespace. */\nexport function bareDecisionThreadId(threadId: string): string {\n  return threadId.startsWith(CHECKPOINT_NAMESPACE)\n    ? threadId.slice(CHECKPOINT_NAMESPACE.length)\n    : threadId;\n}\n\n/**\n * A chat answer as statewire carries it: a `run/input` resume of one parked\n * request, or the lane decisions of a `run/lane-input`.\n */\nexport type StatewireAnswerForCheck =\n  | { readonly kind: 'input'; readonly requestId: string; readonly value: unknown }\n  | { readonly kind: 'lanes'; readonly laneDecisions: Readonly<Record<string, unknown>> };\n\n/**\n * The decisions one statewire answer makes: `chat_approval_answer` on\n * `<thread>:<requestId>` with the resume value as its payload, or one per lane\n * on `<thread>:<lane interrupt id>` with that lane's decision as its payload.\n */\nexport function statewireAnswerDescriptors({\n  threadId,\n  answer,\n}: {\n  threadId: string;\n  answer: StatewireAnswerForCheck;\n}): DecisionCheckDescriptor[] {\n  const thread = bareDecisionThreadId(threadId);\n  if (answer.kind === 'input') {\n    return [\n      {\n        kind: DecisionCheckKind.CHAT_APPROVAL_ANSWER,\n        targetIds: [`${thread}:${answer.requestId}`],\n        option: 'resume',\n        editedPayload: answer.value,\n      },\n    ];\n  }\n  return Object.entries(answer.laneDecisions).map(([interruptId, decision]) => ({\n    kind: DecisionCheckKind.CHAT_APPROVAL_ANSWER,\n    targetIds: [`${thread}:${interruptId}`],\n    option: 'resume',\n    editedPayload: decision,\n  }));\n}\n\n/**\n * The phone's respond route (`POST /mobile/approvals/{thread}/respond`, also\n * the comment thread's inline approval): a `decisions` map is option\n * `decisions` with the map as its payload; otherwise the option is the action\n * and the payload its edited `tool_args`.\n */\nexport function respondDecisionDescriptor({\n  threadId,\n  toolCallId,\n  action,\n  toolArgs,\n  decisions,\n}: {\n  threadId: string;\n  toolCallId: string;\n  action?: string;\n  toolArgs?: unknown;\n  decisions?: Readonly<Record<string, unknown>>;\n}): DecisionCheckDescriptor {\n  const target = `${bareDecisionThreadId(threadId)}:${toolCallId}`;\n  if (decisions !== undefined && Object.keys(decisions).length > 0) {\n    return {\n      kind: DecisionCheckKind.CHAT_APPROVAL_ANSWER,\n      targetIds: [target],\n      option: 'decisions',\n      editedPayload: decisions,\n    };\n  }\n  return {\n    kind: DecisionCheckKind.CHAT_APPROVAL_ANSWER,\n    targetIds: [target],\n    option: action ?? 'decisions',\n    ...(toolArgs !== undefined && toolArgs !== null ? { editedPayload: toolArgs } : {}),\n  };\n}\n\n/**\n * How a browser check went. Every outcome but `confirmed` sends the decision\n * without a token while checks are report-only; the surface decides what to\n * tell the person (a nudge to set up a passkey for `no_passkey`).\n */\nexport type BrowserDecisionCheckOutcome =\n  | { readonly status: 'confirmed'; readonly token: string }\n  | { readonly status: 'no_passkey' }\n  | { readonly status: 'cancelled' }\n  | { readonly status: 'unsupported' }\n  | { readonly status: 'unavailable' }\n  | { readonly status: 'expired' }\n  | { readonly status: 'failed'; readonly message: string };\n\n/** What the surface shows while the person finishes in the browser. */\nexport interface PendingBrowserDecisionCheck {\n  readonly userCode: string;\n  readonly verificationUrl: string;\n  readonly expiresAt: Date;\n}\n\n/**\n * The surface's authenticated request to agora: `path` is absolute from the\n * API root (`/api/passkeys/...`). The host adds its base URL and credential\n * (the person's sign-in, or the device key) and returns the raw response.\n */\nexport type AgoraFetch = (path: string, init: RequestInit) => Promise<Response>;\n\nexport interface RunBrowserDecisionCheckOptions {\n  readonly decisions: readonly DecisionCheckDescriptor[];\n  readonly client: DecisionCheckClient;\n  readonly agoraFetch: AgoraFetch;\n  /** Open the check page in the system browser or a new tab. */\n  readonly openUrl: (url: string) => void | Promise<void>;\n  /** An app link the page sends the person back to once they answered. */\n  readonly returnUrl?: string;\n  /** Told when the browser is open (with the code to show), and `null` once it settled. */\n  readonly onPending?: (pending: PendingBrowserDecisionCheck | null) => void;\n  /** Aborting gives up waiting: the decision goes without a token (`cancelled`). */\n  readonly signal?: AbortSignal;\n  /** Injectable for tests. */\n  readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;\n  readonly now?: () => number;\n}\n\nconst REQUESTS_PATH = '/api/passkeys/decision-checks/requests';\nconst DEFAULT_INTERVAL_MS = 2_000;\nconst MIN_INTERVAL_MS = 1_000;\n/** A transient collect failure is retried; this many in a row gives up. */\nconst MAX_COLLECT_FAILURES = 5;\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nasync function readJson(response: Response): Promise<Record<string, unknown> | null> {\n  try {\n    const body: unknown = await response.json();\n    return isRecord(body) ? body : null;\n  } catch {\n    return null;\n  }\n}\n\nfunction defaultSleep(ms: number, signal?: AbortSignal): Promise<void> {\n  return new Promise((resolve) => {\n    if (signal?.aborted) {\n      resolve();\n      return;\n    }\n    const timer = setTimeout(() => {\n      signal?.removeEventListener('abort', onAbort);\n      resolve();\n    }, ms);\n    const onAbort = () => {\n      clearTimeout(timer);\n      resolve();\n    };\n    signal?.addEventListener('abort', onAbort, { once: true });\n  });\n}\n\nfunction messageOf(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n\n/** Tell the host about the open check; a host callback that throws changes nothing here. */\nfunction notifyPending(\n  options: RunBrowserDecisionCheckOptions,\n  pending: PendingBrowserDecisionCheck | null,\n): void {\n  try {\n    options.onPending?.(pending);\n  } catch (error) {\n    console.warn('[decision-check] the pending notice failed:', messageOf(error));\n  }\n}\n\ninterface OpenedCheck {\n  readonly requestId: string;\n  readonly pollSecret: string;\n  readonly userCode: string;\n  readonly verificationUrl: string;\n  readonly expiresAt: Date;\n  readonly intervalMs: number;\n}\n\nfunction openedCheck(body: Record<string, unknown> | null): OpenedCheck | null {\n  if (body === null) return null;\n  const { request_id, poll_secret, user_code, verification_url, expires_at, interval_seconds } =\n    body;\n  if (\n    typeof request_id !== 'string' ||\n    typeof poll_secret !== 'string' ||\n    typeof user_code !== 'string' ||\n    typeof verification_url !== 'string' ||\n    typeof expires_at !== 'string'\n  ) {\n    return null;\n  }\n  const expiresAt = new Date(expires_at);\n  if (Number.isNaN(expiresAt.getTime())) return null;\n  const seconds = typeof interval_seconds === 'number' ? interval_seconds : 0;\n  return {\n    requestId: request_id,\n    pollSecret: poll_secret,\n    userCode: user_code,\n    verificationUrl: verification_url,\n    expiresAt,\n    intervalMs: seconds > 0 ? Math.max(MIN_INTERVAL_MS, seconds * 1_000) : DEFAULT_INTERVAL_MS,\n  };\n}\n\nasync function openRequest(\n  options: RunBrowserDecisionCheckOptions,\n): Promise<OpenedCheck | BrowserDecisionCheckOutcome> {\n  let response: Response;\n  try {\n    response = await options.agoraFetch(REQUESTS_PATH, {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({\n        decisions: options.decisions,\n        client: options.client,\n        ...(options.returnUrl ? { return_url: options.returnUrl } : {}),\n      }),\n      signal: options.signal,\n    });\n  } catch (error) {\n    if (options.signal?.aborted) return { status: 'cancelled' };\n    return { status: 'failed', message: messageOf(error) };\n  }\n  // 404: an agora before browser checks; 503: none can be minted here.\n  if (response.status === 404 || response.status === 503) return { status: 'unavailable' };\n  if (!response.ok) {\n    return { status: 'failed', message: `The check could not start (${response.status}).` };\n  }\n  return openedCheck(await readJson(response)) ?? {\n    status: 'failed',\n    message: 'The check could not start.',\n  };\n}\n\nfunction settledOutcome(body: Record<string, unknown> | null): BrowserDecisionCheckOutcome | null {\n  if (body === null) return null;\n  if (body.status === 'confirmed' && typeof body.check_token === 'string' && body.check_token) {\n    return { status: 'confirmed', token: body.check_token };\n  }\n  if (body.status === 'declined') {\n    switch (body.reason) {\n      case 'no_passkey':\n        return { status: 'no_passkey' };\n      case 'unsupported':\n        return { status: 'unsupported' };\n      case 'failed':\n        return { status: 'failed', message: 'The passkey check failed in the browser.' };\n      default:\n        return { status: 'cancelled' };\n    }\n  }\n  return null;\n}\n\n/**\n * Ask the person to confirm `decisions` with their passkey in the system\n * browser, and wait for the answer: the token when they confirmed, or why\n * there is none. Never rejects.\n */\nexport async function runBrowserDecisionCheck(\n  options: RunBrowserDecisionCheckOptions,\n): Promise<BrowserDecisionCheckOutcome> {\n  if (options.decisions.length === 0) return { status: 'failed', message: 'Nothing to confirm.' };\n  if (options.decisions.length > MAX_DECISIONS_PER_CHECK) {\n    return {\n      status: 'failed',\n      message: `One check confirms up to ${MAX_DECISIONS_PER_CHECK} decisions.`,\n    };\n  }\n  const sleep = options.sleep ?? defaultSleep;\n  const now = options.now ?? Date.now;\n  const opened = await openRequest(options);\n  if ('status' in opened) return opened;\n\n  notifyPending(options, {\n    userCode: opened.userCode,\n    verificationUrl: opened.verificationUrl,\n    expiresAt: opened.expiresAt,\n  });\n  try {\n    try {\n      await options.openUrl(opened.verificationUrl);\n    } catch (error) {\n      // The page can still be opened by hand from the link the surface shows.\n      console.warn('[decision-check] could not open the browser:', messageOf(error));\n    }\n    let failures = 0;\n    while (now() < opened.expiresAt.getTime()) {\n      await sleep(opened.intervalMs, options.signal);\n      if (options.signal?.aborted) return { status: 'cancelled' };\n      let response: Response;\n      try {\n        response = await options.agoraFetch(\n          `${REQUESTS_PATH}/${encodeURIComponent(opened.requestId)}/collect`,\n          {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ poll_secret: opened.pollSecret }),\n            signal: options.signal,\n          },\n        );\n      } catch (error) {\n        if (options.signal?.aborted) return { status: 'cancelled' };\n        failures += 1;\n        if (failures >= MAX_COLLECT_FAILURES) return { status: 'failed', message: messageOf(error) };\n        continue;\n      }\n      // Unknown, expired or already collected: nothing more will come.\n      if (response.status === 404) return { status: 'expired' };\n      if (!response.ok) {\n        failures += 1;\n        if (failures >= MAX_COLLECT_FAILURES) {\n          return { status: 'failed', message: `The check could not finish (${response.status}).` };\n        }\n        continue;\n      }\n      failures = 0;\n      const settled = settledOutcome(await readJson(response));\n      if (settled !== null) return settled;\n    }\n    return { status: 'expired' };\n  } finally {\n    notifyPending(options, null);\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/agent-runtime/src/decision-checks.d.ts

@@ -0,0 +1,142 @@
+/**
+ * "Confirm with your passkey" for surfaces that can't run the passkey prompt
+ * themselves (identity row 0b.9, PR C): the phone, Midas, the Chrome
+ * extension, the Office add-ins and SDK apps on another origin.
+ *
+ * A passkey belongs to the deployment's web host, so the check runs there, in
+ * the system browser. The surface asks agora for a check over the decisions
+ * on its screen (`POST /api/passkeys/decision-checks/requests`), opens the
+ * verification URL it gets back, and collects the token once the person
+ * confirmed on the web app's check page. It then sends its decision with that
+ * token, as the web app does: `X-Athena-Decision-Check` on REST and GraphQL,
+ * `decisionCheck` on statewire's `run/input` and `run/lane-input`.
+ *
+ * Framework-free: React hosts wrap {@link runBrowserDecisionCheck} in a
+ * TanStack mutation; the CLI and the phone call it as they are.
+ *
+ * Every outcome is a value, never a rejection. While checks are report-only
+ * (PR D enforces them) the decision goes ahead whatever this resolves, with
+ * the token only when the person confirmed.
+ */
+/** The header a REST or GraphQL decide call carries its check token in. */
+export declare const DECISION_CHECK_HEADER = "X-Athena-Decision-Check";
+/** The most decisions one check covers: a screen's worth. */
+export declare const MAX_DECISIONS_PER_CHECK = 25;
+/** What kind of decision a descriptor describes (agora's `DecisionKind`). */
+export declare const DecisionCheckKind: {
+    readonly APPROVAL_DECIDE: 'approval_decide';
+    readonly AUTOMATION_APPROVAL_DECIDE: 'automation_approval_decide';
+    readonly CHAT_APPROVAL_ANSWER: 'chat_approval_answer';
+};
+export type DecisionCheckKind = (typeof DecisionCheckKind)[keyof typeof DecisionCheckKind];
+/**
+ * One decision a check covers, exactly as its decide call sends it: agora
+ * builds the same item from the decide call and asks whether the token covers
+ * it. `editedPayload` is the JSON value itself, never a hash of it.
+ */
+export interface DecisionCheckDescriptor {
+    readonly kind: string;
+    readonly targetIds: readonly string[];
+    readonly option: string;
+    readonly editedPayload?: unknown;
+    readonly standingDuration?: string;
+}
+/** Which surface asks, as the check page shows it. */
+export type DecisionCheckClientKind = 'cli' | 'desktop' | 'mobile' | 'chrome_extension' | 'office_addin' | 'sdk';
+export interface DecisionCheckClient {
+    readonly kind: DecisionCheckClientKind;
+    /** A short name for this device or app ("Pat's MacBook"), shown on the page. */
+    readonly label?: string;
+}
+/** A thread id the way agora names chat answers: without the checkpoint namespace. */
+export declare function bareDecisionThreadId(threadId: string): string;
+/**
+ * A chat answer as statewire carries it: a `run/input` resume of one parked
+ * request, or the lane decisions of a `run/lane-input`.
+ */
+export type StatewireAnswerForCheck = {
+    readonly kind: 'input';
+    readonly requestId: string;
+    readonly value: unknown;
+} | {
+    readonly kind: 'lanes';
+    readonly laneDecisions: Readonly<Record<string, unknown>>;
+};
+/**
+ * The decisions one statewire answer makes: `chat_approval_answer` on
+ * `<thread>:<requestId>` with the resume value as its payload, or one per lane
+ * on `<thread>:<lane interrupt id>` with that lane's decision as its payload.
+ */
+export declare function statewireAnswerDescriptors({ threadId, answer, }: {
+    threadId: string;
+    answer: StatewireAnswerForCheck;
+}): DecisionCheckDescriptor[];
+/**
+ * The phone's respond route (`POST /mobile/approvals/{thread}/respond`, also
+ * the comment thread's inline approval): a `decisions` map is option
+ * `decisions` with the map as its payload; otherwise the option is the action
+ * and the payload its edited `tool_args`.
+ */
+export declare function respondDecisionDescriptor({ threadId, toolCallId, action, toolArgs, decisions, }: {
+    threadId: string;
+    toolCallId: string;
+    action?: string;
+    toolArgs?: unknown;
+    decisions?: Readonly<Record<string, unknown>>;
+}): DecisionCheckDescriptor;
+/**
+ * How a browser check went. Every outcome but `confirmed` sends the decision
+ * without a token while checks are report-only; the surface decides what to
+ * tell the person (a nudge to set up a passkey for `no_passkey`).
+ */
+export type BrowserDecisionCheckOutcome = {
+    readonly status: 'confirmed';
+    readonly token: string;
+} | {
+    readonly status: 'no_passkey';
+} | {
+    readonly status: 'cancelled';
+} | {
+    readonly status: 'unsupported';
+} | {
+    readonly status: 'unavailable';
+} | {
+    readonly status: 'expired';
+} | {
+    readonly status: 'failed';
+    readonly message: string;
+};
+/** What the surface shows while the person finishes in the browser. */
+export interface PendingBrowserDecisionCheck {
+    readonly userCode: string;
+    readonly verificationUrl: string;
+    readonly expiresAt: Date;
+}
+/**
+ * The surface's authenticated request to agora: `path` is absolute from the
+ * API root (`/api/passkeys/...`). The host adds its base URL and credential
+ * (the person's sign-in, or the device key) and returns the raw response.
+ */
+export type AgoraFetch = (path: string, init: RequestInit) => Promise<Response>;
+export interface RunBrowserDecisionCheckOptions {
+    readonly decisions: readonly DecisionCheckDescriptor[];
+    readonly client: DecisionCheckClient;
+    readonly agoraFetch: AgoraFetch;
+    /** Open the check page in the system browser or a new tab. */
+    readonly openUrl: (url: string) => void | Promise<void>;
+    /** An app link the page sends the person back to once they answered. */
+    readonly returnUrl?: string;
+    /** Told when the browser is open (with the code to show), and `null` once it settled. */
+    readonly onPending?: (pending: PendingBrowserDecisionCheck | null) => void;
+    /** Aborting gives up waiting: the decision goes without a token (`cancelled`). */
+    readonly signal?: AbortSignal;
+    /** Injectable for tests. */
+    readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    readonly now?: () => number;
+}
+/**
+ * Ask the person to confirm `decisions` with their passkey in the system
+ * browser, and wait for the answer: the token when they confirmed, or why
+ * there is none. Never rejects.
+ */
+export declare function runBrowserDecisionCheck(options: RunBrowserDecisionCheckOptions): Promise<BrowserDecisionCheckOutcome>;

package/dist/agent-runtime/src/decision-checks.js

@@ -0,0 +1,207 @@
+const MAX_DECISIONS_PER_CHECK = 25;
+const DecisionCheckKind = {
+  CHAT_APPROVAL_ANSWER: "chat_approval_answer"
+};
+const CHECKPOINT_NAMESPACE = "athena-deep-agent:";
+function bareDecisionThreadId(threadId) {
+  return threadId.startsWith(CHECKPOINT_NAMESPACE) ? threadId.slice(CHECKPOINT_NAMESPACE.length) : threadId;
+}
+function statewireAnswerDescriptors({
+  threadId,
+  answer
+}) {
+  const thread = bareDecisionThreadId(threadId);
+  if (answer.kind === "input") {
+    return [
+      {
+        kind: DecisionCheckKind.CHAT_APPROVAL_ANSWER,
+        targetIds: [`${thread}:${answer.requestId}`],
+        option: "resume",
+        editedPayload: answer.value
+      }
+    ];
+  }
+  return Object.entries(answer.laneDecisions).map(([interruptId, decision]) => ({
+    kind: DecisionCheckKind.CHAT_APPROVAL_ANSWER,
+    targetIds: [`${thread}:${interruptId}`],
+    option: "resume",
+    editedPayload: decision
+  }));
+}
+const REQUESTS_PATH = "/api/passkeys/decision-checks/requests";
+const DEFAULT_INTERVAL_MS = 2e3;
+const MIN_INTERVAL_MS = 1e3;
+const MAX_COLLECT_FAILURES = 5;
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function readJson(response) {
+  try {
+    const body = await response.json();
+    return isRecord(body) ? body : null;
+  } catch {
+    return null;
+  }
+}
+function defaultSleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (signal == null ? void 0 : signal.aborted) {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal == null ? void 0 : signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    signal == null ? void 0 : signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function notifyPending(options, pending) {
+  var _a;
+  try {
+    (_a = options.onPending) == null ? void 0 : _a.call(options, pending);
+  } catch (error) {
+    console.warn("[decision-check] the pending notice failed:", messageOf(error));
+  }
+}
+function openedCheck(body) {
+  if (body === null) return null;
+  const { request_id, poll_secret, user_code, verification_url, expires_at, interval_seconds } = body;
+  if (typeof request_id !== "string" || typeof poll_secret !== "string" || typeof user_code !== "string" || typeof verification_url !== "string" || typeof expires_at !== "string") {
+    return null;
+  }
+  const expiresAt = new Date(expires_at);
+  if (Number.isNaN(expiresAt.getTime())) return null;
+  const seconds = typeof interval_seconds === "number" ? interval_seconds : 0;
+  return {
+    requestId: request_id,
+    pollSecret: poll_secret,
+    userCode: user_code,
+    verificationUrl: verification_url,
+    expiresAt,
+    intervalMs: seconds > 0 ? Math.max(MIN_INTERVAL_MS, seconds * 1e3) : DEFAULT_INTERVAL_MS
+  };
+}
+async function openRequest(options) {
+  var _a;
+  let response;
+  try {
+    response = await options.agoraFetch(REQUESTS_PATH, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        decisions: options.decisions,
+        client: options.client,
+        ...options.returnUrl ? { return_url: options.returnUrl } : {}
+      }),
+      signal: options.signal
+    });
+  } catch (error) {
+    if ((_a = options.signal) == null ? void 0 : _a.aborted) return { status: "cancelled" };
+    return { status: "failed", message: messageOf(error) };
+  }
+  if (response.status === 404 || response.status === 503) return { status: "unavailable" };
+  if (!response.ok) {
+    return { status: "failed", message: `The check could not start (${response.status}).` };
+  }
+  return openedCheck(await readJson(response)) ?? {
+    status: "failed",
+    message: "The check could not start."
+  };
+}
+function settledOutcome(body) {
+  if (body === null) return null;
+  if (body.status === "confirmed" && typeof body.check_token === "string" && body.check_token) {
+    return { status: "confirmed", token: body.check_token };
+  }
+  if (body.status === "declined") {
+    switch (body.reason) {
+      case "no_passkey":
+        return { status: "no_passkey" };
+      case "unsupported":
+        return { status: "unsupported" };
+      case "failed":
+        return { status: "failed", message: "The passkey check failed in the browser." };
+      default:
+        return { status: "cancelled" };
+    }
+  }
+  return null;
+}
+async function runBrowserDecisionCheck(options) {
+  var _a, _b;
+  if (options.decisions.length === 0) return { status: "failed", message: "Nothing to confirm." };
+  if (options.decisions.length > MAX_DECISIONS_PER_CHECK) {
+    return {
+      status: "failed",
+      message: `One check confirms up to ${MAX_DECISIONS_PER_CHECK} decisions.`
+    };
+  }
+  const sleep = options.sleep ?? defaultSleep;
+  const now = options.now ?? Date.now;
+  const opened = await openRequest(options);
+  if ("status" in opened) return opened;
+  notifyPending(options, {
+    userCode: opened.userCode,
+    verificationUrl: opened.verificationUrl,
+    expiresAt: opened.expiresAt
+  });
+  try {
+    try {
+      await options.openUrl(opened.verificationUrl);
+    } catch (error) {
+      console.warn("[decision-check] could not open the browser:", messageOf(error));
+    }
+    let failures = 0;
+    while (now() < opened.expiresAt.getTime()) {
+      await sleep(opened.intervalMs, options.signal);
+      if ((_a = options.signal) == null ? void 0 : _a.aborted) return { status: "cancelled" };
+      let response;
+      try {
+        response = await options.agoraFetch(
+          `${REQUESTS_PATH}/${encodeURIComponent(opened.requestId)}/collect`,
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ poll_secret: opened.pollSecret }),
+            signal: options.signal
+          }
+        );
+      } catch (error) {
+        if ((_b = options.signal) == null ? void 0 : _b.aborted) return { status: "cancelled" };
+        failures += 1;
+        if (failures >= MAX_COLLECT_FAILURES) return { status: "failed", message: messageOf(error) };
+        continue;
+      }
+      if (response.status === 404) return { status: "expired" };
+      if (!response.ok) {
+        failures += 1;
+        if (failures >= MAX_COLLECT_FAILURES) {
+          return { status: "failed", message: `The check could not finish (${response.status}).` };
+        }
+        continue;
+      }
+      failures = 0;
+      const settled = settledOutcome(await readJson(response));
+      if (settled !== null) return settled;
+    }
+    return { status: "expired" };
+  } finally {
+    notifyPending(options, null);
+  }
+}
+export {
+  DecisionCheckKind,
+  MAX_DECISIONS_PER_CHECK,
+  bareDecisionThreadId,
+  runBrowserDecisionCheck,
+  statewireAnswerDescriptors
+};
+//# sourceMappingURL=decision-checks.js.map

package/dist/agent-runtime/src/decision-checks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-checks.js","sources":["../../../../agent-runtime/src/decision-checks.ts"],"sourcesContent":["/**\n * \"Confirm with your passkey\" for surfaces that can't run the passkey prompt\n * themselves (identity row 0b.9, PR C): the phone, Midas, the Chrome\n * extension, the Office add-ins and SDK apps on another origin.\n *\n * A passkey belongs to the deployment's web host, so the check runs there, in\n * the system browser. The surface asks agora for a check over the decisions\n * on its screen (`POST /api/passkeys/decision-checks/requests`), opens the\n * verification URL it gets back, and collects the token once the person\n * confirmed on the web app's check page. It then sends its decision with that\n * token, as the web app does: `X-Athena-Decision-Check` on REST and GraphQL,\n * `decisionCheck` on statewire's `run/input` and `run/lane-input`.\n *\n * Framework-free: React hosts wrap {@link runBrowserDecisionCheck} in a\n * TanStack mutation; the CLI and the phone call it as they are.\n *\n * Every outcome is a value, never a rejection. While checks are report-only\n * (PR D enforces them) the decision goes ahead whatever this resolves, with\n * the token only when the person confirmed.\n */\n\n/** The header a REST or GraphQL decide call carries its check token in. */\nexport const DECISION_CHECK_HEADER = 'X-Athena-Decision-Check';\n\n/** The most decisions one check covers: a screen's worth. */\nexport const MAX_DECISIONS_PER_CHECK = 25;\n\n/** What kind of decision a descriptor describes (agora's `DecisionKind`). */\nexport const DecisionCheckKind = {\n  APPROVAL_DECIDE: 'approval_decide',\n  AUTOMATION_APPROVAL_DECIDE: 'automation_approval_decide',\n  CHAT_APPROVAL_ANSWER: 'chat_approval_answer',\n} as const;\n\nexport type DecisionCheckKind = (typeof DecisionCheckKind)[keyof typeof DecisionCheckKind];\n\n/**\n * One decision a check covers, exactly as its decide call sends it: agora\n * builds the same item from the decide call and asks whether the token covers\n * it. `editedPayload` is the JSON value itself, never a hash of it.\n */\nexport interface DecisionCheckDescriptor {\n  readonly kind: string;\n  readonly targetIds: readonly string[];\n  readonly option: string;\n  readonly editedPayload?: unknown;\n  readonly standingDuration?: string;\n}\n\n/** Which surface asks, as the check page shows it. */\nexport type DecisionCheckClientKind =\n  | 'cli'\n  | 'desktop'\n  | 'mobile'\n  | 'chrome_extension'\n  | 'office_addin'\n  | 'sdk';\n\nexport interface DecisionCheckClient {\n  readonly kind: DecisionCheckClientKind;\n  /** A short name for this device or app (\"Pat's MacBook\"), shown on the page. */\n  readonly label?: string;\n}\n\nconst CHECKPOINT_NAMESPACE = 'athena-deep-agent:';\n\n/** A thread id the way agora names chat answers: without the checkpoint namespace. */\nexport function bareDecisionThreadId(threadId: string): string {\n  return threadId.startsWith(CHECKPOINT_NAMESPACE)\n    ? threadId.slice(CHECKPOINT_NAMESPACE.length)\n    : threadId;\n}\n\n/**\n * A chat answer as statewire carries it: a `run/input` resume of one parked\n * request, or the lane decisions of a `run/lane-input`.\n */\nexport type StatewireAnswerForCheck =\n  | { readonly kind: 'input'; readonly requestId: string; readonly value: unknown }\n  | { readonly kind: 'lanes'; readonly laneDecisions: Readonly<Record<string, unknown>> };\n\n/**\n * The decisions one statewire answer makes: `chat_approval_answer` on\n * `<thread>:<requestId>` with the resume value as its payload, or one per lane\n * on `<thread>:<lane interrupt id>` with that lane's decision as its payload.\n */\nexport function statewireAnswerDescriptors({\n  threadId,\n  answer,\n}: {\n  threadId: string;\n  answer: StatewireAnswerForCheck;\n}): DecisionCheckDescriptor[] {\n  const thread = bareDecisionThreadId(threadId);\n  if (answer.kind === 'input') {\n    return [\n      {\n        kind: DecisionCheckKind.CHAT_APPROVAL_ANSWER,\n        targetIds: [`${thread}:${answer.requestId}`],\n        option: 'resume',\n        editedPayload: answer.value,\n      },\n    ];\n  }\n  return Object.entries(answer.laneDecisions).map(([interruptId, decision]) => ({\n    kind: DecisionCheckKind.CHAT_APPROVAL_ANSWER,\n    targetIds: [`${thread}:${interruptId}`],\n    option: 'resume',\n    editedPayload: decision,\n  }));\n}\n\n/**\n * The phone's respond route (`POST /mobile/approvals/{thread}/respond`, also\n * the comment thread's inline approval): a `decisions` map is option\n * `decisions` with the map as its payload; otherwise the option is the action\n * and the payload its edited `tool_args`.\n */\nexport function respondDecisionDescriptor({\n  threadId,\n  toolCallId,\n  action,\n  toolArgs,\n  decisions,\n}: {\n  threadId: string;\n  toolCallId: string;\n  action?: string;\n  toolArgs?: unknown;\n  decisions?: Readonly<Record<string, unknown>>;\n}): DecisionCheckDescriptor {\n  const target = `${bareDecisionThreadId(threadId)}:${toolCallId}`;\n  if (decisions !== undefined && Object.keys(decisions).length > 0) {\n    return {\n      kind: DecisionCheckKind.CHAT_APPROVAL_ANSWER,\n      targetIds: [target],\n      option: 'decisions',\n      editedPayload: decisions,\n    };\n  }\n  return {\n    kind: DecisionCheckKind.CHAT_APPROVAL_ANSWER,\n    targetIds: [target],\n    option: action ?? 'decisions',\n    ...(toolArgs !== undefined && toolArgs !== null ? { editedPayload: toolArgs } : {}),\n  };\n}\n\n/**\n * How a browser check went. Every outcome but `confirmed` sends the decision\n * without a token while checks are report-only; the surface decides what to\n * tell the person (a nudge to set up a passkey for `no_passkey`).\n */\nexport type BrowserDecisionCheckOutcome =\n  | { readonly status: 'confirmed'; readonly token: string }\n  | { readonly status: 'no_passkey' }\n  | { readonly status: 'cancelled' }\n  | { readonly status: 'unsupported' }\n  | { readonly status: 'unavailable' }\n  | { readonly status: 'expired' }\n  | { readonly status: 'failed'; readonly message: string };\n\n/** What the surface shows while the person finishes in the browser. */\nexport interface PendingBrowserDecisionCheck {\n  readonly userCode: string;\n  readonly verificationUrl: string;\n  readonly expiresAt: Date;\n}\n\n/**\n * The surface's authenticated request to agora: `path` is absolute from the\n * API root (`/api/passkeys/...`). The host adds its base URL and credential\n * (the person's sign-in, or the device key) and returns the raw response.\n */\nexport type AgoraFetch = (path: string, init: RequestInit) => Promise<Response>;\n\nexport interface RunBrowserDecisionCheckOptions {\n  readonly decisions: readonly DecisionCheckDescriptor[];\n  readonly client: DecisionCheckClient;\n  readonly agoraFetch: AgoraFetch;\n  /** Open the check page in the system browser or a new tab. */\n  readonly openUrl: (url: string) => void | Promise<void>;\n  /** An app link the page sends the person back to once they answered. */\n  readonly returnUrl?: string;\n  /** Told when the browser is open (with the code to show), and `null` once it settled. */\n  readonly onPending?: (pending: PendingBrowserDecisionCheck | null) => void;\n  /** Aborting gives up waiting: the decision goes without a token (`cancelled`). */\n  readonly signal?: AbortSignal;\n  /** Injectable for tests. */\n  readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;\n  readonly now?: () => number;\n}\n\nconst REQUESTS_PATH = '/api/passkeys/decision-checks/requests';\nconst DEFAULT_INTERVAL_MS = 2_000;\nconst MIN_INTERVAL_MS = 1_000;\n/** A transient collect failure is retried; this many in a row gives up. */\nconst MAX_COLLECT_FAILURES = 5;\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nasync function readJson(response: Response): Promise<Record<string, unknown> | null> {\n  try {\n    const body: unknown = await response.json();\n    return isRecord(body) ? body : null;\n  } catch {\n    return null;\n  }\n}\n\nfunction defaultSleep(ms: number, signal?: AbortSignal): Promise<void> {\n  return new Promise((resolve) => {\n    if (signal?.aborted) {\n      resolve();\n      return;\n    }\n    const timer = setTimeout(() => {\n      signal?.removeEventListener('abort', onAbort);\n      resolve();\n    }, ms);\n    const onAbort = () => {\n      clearTimeout(timer);\n      resolve();\n    };\n    signal?.addEventListener('abort', onAbort, { once: true });\n  });\n}\n\nfunction messageOf(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n\n/** Tell the host about the open check; a host callback that throws changes nothing here. */\nfunction notifyPending(\n  options: RunBrowserDecisionCheckOptions,\n  pending: PendingBrowserDecisionCheck | null,\n): void {\n  try {\n    options.onPending?.(pending);\n  } catch (error) {\n    console.warn('[decision-check] the pending notice failed:', messageOf(error));\n  }\n}\n\ninterface OpenedCheck {\n  readonly requestId: string;\n  readonly pollSecret: string;\n  readonly userCode: string;\n  readonly verificationUrl: string;\n  readonly expiresAt: Date;\n  readonly intervalMs: number;\n}\n\nfunction openedCheck(body: Record<string, unknown> | null): OpenedCheck | null {\n  if (body === null) return null;\n  const { request_id, poll_secret, user_code, verification_url, expires_at, interval_seconds } =\n    body;\n  if (\n    typeof request_id !== 'string' ||\n    typeof poll_secret !== 'string' ||\n    typeof user_code !== 'string' ||\n    typeof verification_url !== 'string' ||\n    typeof expires_at !== 'string'\n  ) {\n    return null;\n  }\n  const expiresAt = new Date(expires_at);\n  if (Number.isNaN(expiresAt.getTime())) return null;\n  const seconds = typeof interval_seconds === 'number' ? interval_seconds : 0;\n  return {\n    requestId: request_id,\n    pollSecret: poll_secret,\n    userCode: user_code,\n    verificationUrl: verification_url,\n    expiresAt,\n    intervalMs: seconds > 0 ? Math.max(MIN_INTERVAL_MS, seconds * 1_000) : DEFAULT_INTERVAL_MS,\n  };\n}\n\nasync function openRequest(\n  options: RunBrowserDecisionCheckOptions,\n): Promise<OpenedCheck | BrowserDecisionCheckOutcome> {\n  let response: Response;\n  try {\n    response = await options.agoraFetch(REQUESTS_PATH, {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({\n        decisions: options.decisions,\n        client: options.client,\n        ...(options.returnUrl ? { return_url: options.returnUrl } : {}),\n      }),\n      signal: options.signal,\n    });\n  } catch (error) {\n    if (options.signal?.aborted) return { status: 'cancelled' };\n    return { status: 'failed', message: messageOf(error) };\n  }\n  // 404: an agora before browser checks; 503: none can be minted here.\n  if (response.status === 404 || response.status === 503) return { status: 'unavailable' };\n  if (!response.ok) {\n    return { status: 'failed', message: `The check could not start (${response.status}).` };\n  }\n  return openedCheck(await readJson(response)) ?? {\n    status: 'failed',\n    message: 'The check could not start.',\n  };\n}\n\nfunction settledOutcome(body: Record<string, unknown> | null): BrowserDecisionCheckOutcome | null {\n  if (body === null) return null;\n  if (body.status === 'confirmed' && typeof body.check_token === 'string' && body.check_token) {\n    return { status: 'confirmed', token: body.check_token };\n  }\n  if (body.status === 'declined') {\n    switch (body.reason) {\n      case 'no_passkey':\n        return { status: 'no_passkey' };\n      case 'unsupported':\n        return { status: 'unsupported' };\n      case 'failed':\n        return { status: 'failed', message: 'The passkey check failed in the browser.' };\n      default:\n        return { status: 'cancelled' };\n    }\n  }\n  return null;\n}\n\n/**\n * Ask the person to confirm `decisions` with their passkey in the system\n * browser, and wait for the answer: the token when they confirmed, or why\n * there is none. Never rejects.\n */\nexport async function runBrowserDecisionCheck(\n  options: RunBrowserDecisionCheckOptions,\n): Promise<BrowserDecisionCheckOutcome> {\n  if (options.decisions.length === 0) return { status: 'failed', message: 'Nothing to confirm.' };\n  if (options.decisions.length > MAX_DECISIONS_PER_CHECK) {\n    return {\n      status: 'failed',\n      message: `One check confirms up to ${MAX_DECISIONS_PER_CHECK} decisions.`,\n    };\n  }\n  const sleep = options.sleep ?? defaultSleep;\n  const now = options.now ?? Date.now;\n  const opened = await openRequest(options);\n  if ('status' in opened) return opened;\n\n  notifyPending(options, {\n    userCode: opened.userCode,\n    verificationUrl: opened.verificationUrl,\n    expiresAt: opened.expiresAt,\n  });\n  try {\n    try {\n      await options.openUrl(opened.verificationUrl);\n    } catch (error) {\n      // The page can still be opened by hand from the link the surface shows.\n      console.warn('[decision-check] could not open the browser:', messageOf(error));\n    }\n    let failures = 0;\n    while (now() < opened.expiresAt.getTime()) {\n      await sleep(opened.intervalMs, options.signal);\n      if (options.signal?.aborted) return { status: 'cancelled' };\n      let response: Response;\n      try {\n        response = await options.agoraFetch(\n          `${REQUESTS_PATH}/${encodeURIComponent(opened.requestId)}/collect`,\n          {\n            method: 'POST',\n            headers: { 'Content-Type': 'application/json' },\n            body: JSON.stringify({ poll_secret: opened.pollSecret }),\n            signal: options.signal,\n          },\n        );\n      } catch (error) {\n        if (options.signal?.aborted) return { status: 'cancelled' };\n        failures += 1;\n        if (failures >= MAX_COLLECT_FAILURES) return { status: 'failed', message: messageOf(error) };\n        continue;\n      }\n      // Unknown, expired or already collected: nothing more will come.\n      if (response.status === 404) return { status: 'expired' };\n      if (!response.ok) {\n        failures += 1;\n        if (failures >= MAX_COLLECT_FAILURES) {\n          return { status: 'failed', message: `The check could not finish (${response.status}).` };\n        }\n        continue;\n      }\n      failures = 0;\n      const settled = settledOutcome(await readJson(response));\n      if (settled !== null) return settled;\n    }\n    return { status: 'expired' };\n  } finally {\n    notifyPending(options, null);\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/agent-runtime/src/desktop-handoff.d.ts

@@ -64,6 +64,12 @@ export declare const desktopHandoffViewSchema: z.ZodObject<{
             reason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+    origin: z.ZodOptional<z.ZodString>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        text: "text";
+        voice: "voice";
+    }>>;
+    draft: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 export type DesktopHandoffView = z.infer<typeof desktopHandoffViewSchema>;
 export declare const desktopHandoffLaunchSchema: z.ZodObject<{
@@ -117,6 +123,12 @@ export declare const createDesktopHandoffResponseSchema: z.ZodObject<{
                 reason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
+        origin: z.ZodOptional<z.ZodString>;
+        mode: z.ZodOptional<z.ZodEnum<{
+            text: "text";
+            voice: "voice";
+        }>>;
+        draft: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>;
     launch: z.ZodObject<{
         kind: z.ZodLiteral<"desktop">;

package/dist/agent-runtime/src/errors.cjs

@@ -38,6 +38,23 @@ function readRunStartRefusal(error) {
     status: typeof status === "number" ? status : null
   };
 }
+const VOICE_REJECTION_REASONS = /* @__PURE__ */ new Set([
+  "no-voice",
+  "not-voice-owner",
+  "voice-active",
+  "voice-stale-session",
+  "voice-unavailable",
+  "voice-not-enabled",
+  "voice-model-transport",
+  "text-too-long"
+]);
+function isVoiceCommandRejection(error) {
+  var _a;
+  const failure = error == null ? void 0 : error.failure;
+  if ((failure == null ? void 0 : failure.fate) !== "rejected") return false;
+  const reason = (_a = failure.payload) == null ? void 0 : _a.reason;
+  return typeof reason === "string" && VOICE_REJECTION_REASONS.has(reason);
+}
 function statewireRejectionCode(error) {
   var _a;
   const detail = (_a = statewireRejectionPayload(error)) == null ? void 0 : _a.detail;
@@ -133,6 +150,7 @@ exports.isConversationArchivedRejection = isConversationArchivedRejection;
 exports.isLegacyThreadReadOnlyRejection = isLegacyThreadReadOnlyRejection;
 exports.isStatewireChannelTeardown = isStatewireChannelTeardown;
 exports.isStatewireExpiredVerdict = isStatewireExpiredVerdict;
+exports.isVoiceCommandRejection = isVoiceCommandRejection;
 exports.projectDeepAgentConnection = projectDeepAgentConnection;
 exports.readRetryableCommandRejection = readRetryableCommandRejection;
 exports.readRetryableRunRefusal = readRetryableRunRefusal;

package/dist/agent-runtime/src/errors.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"errors.cjs","sources":["../../../../agent-runtime/src/errors.ts"],"sourcesContent":["import type { StatewireClient } from 'statewire';\nimport type { DeepAgentConnectionState } from './types';\n\n/** Structured payload attached to a server-rejected Statewire command. */\nexport interface StatewireRejectionPayload {\n  status: number;\n  detail: unknown;\n}\n\n/** Return a rejected command's structured `{ status, detail }` payload. */\nexport function statewireRejectionPayload(error: unknown): StatewireRejectionPayload | null {\n  const failure = (error as { failure?: { fate?: unknown; payload?: unknown } } | null)?.failure;\n  if (failure?.fate !== 'rejected') return null;\n\n  const payload = failure.payload as { status?: unknown; detail?: unknown } | undefined;\n  if (typeof payload?.status !== 'number') return null;\n  return { status: payload.status, detail: payload.detail };\n}\n\n/**\n * The server's human-readable reason for a rejected command — `detail.message`\n * (or a plain-string `detail`) — else `null`. Hosts surface it as send\n * feedback so the user sees the actionable cause instead of the generic\n * client-side `command rejected (<status>)`.\n */\nexport function statewireRejectionDetailMessage(error: unknown): string | null {\n  const detail = statewireRejectionPayload(error)?.detail;\n  if (typeof detail === 'string') return detail.length > 0 ? detail : null;\n  if (detail === null || typeof detail !== 'object' || Array.isArray(detail)) return null;\n  const message = (detail as { message?: unknown }).message;\n  return typeof message === 'string' && message.length > 0 ? message : null;\n}\n\n/**\n * A structured, retryable refusal the host recorded as the run error\n * (`runs.error`): the dispatch never started — the pod or instance was\n * closing (`pod_draining`) — and the entries stayed in their lanes for the\n * thread's next placement. Distinct from a rejected COMMAND\n * ({@link statewireRejectionPayload}): this is the shape harness-sdk writes\n * when the run executor raises the rejection, so it lives on the replicated\n * run entry, not on a command settle.\n */\nexport interface RetryableRunRefusal {\n  /** The structured `detail.code` (`pod_draining`). */\n  code: string;\n  /** The server's human-readable reason, when it sent one. */\n  message: string | null;\n}\n\n/** The `{ code, message, retryable: true }` detail of a structured refusal, or `null`. */\nfunction readRetryableDetail(detail: unknown): { code: string; message: string | null } | null {\n  if (detail === null || typeof detail !== 'object' || Array.isArray(detail)) return null;\n  const { code, message, retryable } = detail as {\n    code?: unknown;\n    message?: unknown;\n    retryable?: unknown;\n  };\n  if (retryable !== true || typeof code !== 'string' || code.length === 0) return null;\n  return { code, message: typeof message === 'string' && message.length > 0 ? message : null };\n}\n\nexport function readRetryableRunRefusal(error: unknown): RetryableRunRefusal | null {\n  if (error === null || typeof error !== 'object' || Array.isArray(error)) return null;\n  return readRetryableDetail((error as { detail?: unknown }).detail);\n}\n\n/**\n * The `detail.code` agora answers when a send names another channel of the\n * collab agent a session started on (`collab_agent_bridge.py`): a session\n * keeps its channel — the SDK app's Agent / Ask mode — for its lifetime, and\n * the way to the other mode is a new session. Wire-frozen.\n */\nexport const COLLAB_AGENT_CHANNEL_SESSION_MISMATCH = 'collab_agent_channel_session_mismatch';\n\n/**\n * A structured refusal the host recorded as the run error when the run could\n * not START: the run executor raised the gate's `{status, detail: {code,\n * message}}` envelope (agora's `_status_reject`) before it accepted the\n * dispatched input, so the message went back to its lane and the thread rests\n * `error` with it still queued. Unlike a retryable refusal\n * ({@link readRetryableRunRefusal}) nothing will dispatch it later: resending\n * the same input is refused the same way, so the server's message is the only\n * explanation the person gets.\n */\nexport interface RunStartRefusal {\n  /** The structured `detail.code` (`collab_agent_channel_session_mismatch`, …). */\n  code: string;\n  /** The server's human-readable reason, when it sent one. */\n  message: string | null;\n  /** The HTTP-style status the gate raised with, when recorded. */\n  status: number | null;\n}\n\n/**\n * The non-retryable structured refusal off a replicated run error\n * (`runs.error`), or `null` — for a run that failed while it was running (a\n * plain `{message}`), a retryable refusal, or no error at all.\n */\nexport function readRunStartRefusal(error: unknown): RunStartRefusal | null {\n  if (error === null || typeof error !== 'object' || Array.isArray(error)) return null;\n  const { detail, status } = error as { detail?: unknown; status?: unknown };\n  if (detail === null || typeof detail !== 'object' || Array.isArray(detail)) return null;\n  const { code, message, retryable } = detail as {\n    code?: unknown;\n    message?: unknown;\n    retryable?: unknown;\n  };\n  if (retryable === true || typeof code !== 'string' || code.length === 0) return null;\n  return {\n    code,\n    message: typeof message === 'string' && message.length > 0 ? message : null,\n    status: typeof status === 'number' ? status : null,\n  };\n}\n\n/** The structured `detail.code` of a rejected command, or `null`. */\nexport function statewireRejectionCode(error: unknown): string | null {\n  const detail = statewireRejectionPayload(error)?.detail;\n  if (detail === null || typeof detail !== 'object' || Array.isArray(detail)) return null;\n  const code = (detail as { code?: unknown }).code;\n  return typeof code === 'string' && code.length > 0 ? code : null;\n}\n\n/**\n * A structured, retryable refusal of a COMMAND, read off its rejection\n * ({@link statewireRejectionPayload}): the host's `_structured_reject(...,\n * retryable=True)` envelope — `command_auth_context_expired` when a pod\n * replacement dropped the socket-scoped auth a replayed command needed,\n * `pod_draining` when the host was closing. The command never ran, and the\n * host itself says a resend after the reconnect will; `detail.code` is the\n * wire-frozen contract clients classify on. Same shape as\n * {@link readRetryableRunRefusal}, which reads it off a replicated run entry.\n */\nexport interface RetryableCommandRejection {\n  /** The structured `detail.code`. */\n  code: string;\n  /** The server's human-readable reason, when it sent one. */\n  message: string | null;\n}\n\nexport function readRetryableCommandRejection(error: unknown): RetryableCommandRejection | null {\n  const payload = statewireRejectionPayload(error);\n  return payload === null ? null : readRetryableDetail(payload.detail);\n}\n\n/** The host's `detail.code` for a command replayed onto a pod that could not restore its auth context. */\nexport const STATEWIRE_COMMAND_AUTH_CONTEXT_EXPIRED = 'command_auth_context_expired';\n\n/**\n * Whether a rejected command hit the host's fail-closed auth recovery: the\n * command was replayed onto a replacement pod that could not restore the\n * attach's auth context, so it was refused unrun (503, retryable). The\n * reconnect already under way restores the context; a single resend after it\n * is the recovery, not a failure to report.\n */\nexport function isStatewireCommandAuthContextExpired(error: unknown): boolean {\n  const payload = statewireRejectionPayload(error);\n  return (\n    payload?.status === 503 &&\n    readRetryableDetail(payload.detail)?.code === STATEWIRE_COMMAND_AUTH_CONTEXT_EXPIRED\n  );\n}\n\n/**\n * The `detail.code` agora answers for a write to an archived (trashed)\n * conversation (`host_rejects._conversation_archived_reject`, a 409): it\n * takes no new turns, config writes or approval answers until it is\n * restored, and stopping still works. Wire-frozen.\n */\nexport const CONVERSATION_ARCHIVED = 'conversation_archived';\n\n/** What a person is told when that refusal comes back (the server says the same). */\nexport const CONVERSATION_ARCHIVED_MESSAGE =\n  'This conversation is archived. Restore it to continue.';\n\n/**\n * Whether a rejected command was refused because the conversation is archived\n * ({@link CONVERSATION_ARCHIVED}). Not retriable: nothing changes until a\n * restore, so callers show {@link CONVERSATION_ARCHIVED_MESSAGE} rather than a\n * \"try again\".\n */\nexport function isConversationArchivedRejection(error: unknown): boolean {\n  return statewireRejectionCode(error) === CONVERSATION_ARCHIVED;\n}\n\n/**\n * Whether a rejected command hit the legacy-thread dispatch fence: the\n * structured 409 the server answers when an out-of-band run is writing a\n * pre-cutover thread (or its adoption failed). A per-send failure — the\n * snapshot never carries a standing read-only flag.\n */\nexport function isLegacyThreadReadOnlyRejection(error: unknown): boolean {\n  const payload = statewireRejectionPayload(error);\n  if (payload?.status !== 409) return false;\n\n  const detail = payload.detail as { code?: unknown } | undefined;\n  return detail?.code === 'legacy_thread_read_only';\n}\n\n/**\n * Whether a rejected command was refused because its rewind anchor no longer\n * matches the host's parent for the edited message (`wrong-anchor`).\n *\n * A retry/edit resubmit is dispatched optimistically, so this rejection lands\n * after the UI already cleared its edit affordances: the turn simply never\n * re-runs. Callers use this to tell the user the resubmit was dropped instead\n * of leaving a console-only failure.\n */\nexport function isStatewireRewindAnchorRejection(error: unknown): boolean {\n  const failure = (error as { failure?: { fate?: unknown; payload?: unknown } } | null | undefined)\n    ?.failure;\n  if (failure?.fate !== 'rejected') return false;\n  return (failure.payload as { reason?: unknown } | undefined)?.reason === 'wrong-anchor';\n}\n\n/**\n * Whether a statewire send failure is the host's `expired` verdict\n * (`result-unavailable`): the command's seq was at or below the host's\n * admitted watermark and no retained result was left for it. Either the\n * command ran and settled but the client re-asked for the answer (a resend\n * after the stream came back) only after the host had let the retained result\n * go, or the seq was already admitted and the command was absorbed as a\n * duplicate without ever running — a client whose shared session record fell\n * behind the watermark stays there until a reconnect re-syncs it. The library\n * never reruns the command on replay, so for an idempotent read the answer is\n * simply gone — asking again is the correct reaction, not reporting a failure;\n * a write cannot assume it was applied.\n */\nexport function isStatewireExpiredVerdict(error: unknown): boolean {\n  const failure = (error as { failure?: { fate?: unknown; cause?: unknown } | null | undefined })\n    ?.failure;\n  return failure?.fate === 'expired' && failure.cause === 'server';\n}\n\n/**\n * Whether a statewire send failure is a local channel death rather than a\n * command error.\n *\n * The library's contract for `SendFailure.cause`: `\"server\"` is the server's\n * own answer; every other cause is \"a channel death the client settled\n * locally\" — `unmount`, `stream-gone`, and `session-lost`. A thread switch\n * settles every in-flight command that way, so logging these at error level\n * reports two failures for an ordinary switch and buries the ones that mean\n * something.\n *\n * Channel health is already surfaced where it belongs: the connection\n * indicator renders the connection state. This\n * predicate only decides the log level.\n */\nexport function isStatewireChannelTeardown(error: unknown): boolean {\n  const cause = (error as { failure?: { cause?: unknown } } | null | undefined)?.failure?.cause;\n  return typeof cause === 'string' && cause !== 'server';\n}\n\n/**\n * The low-cardinality reason a statewire send settled as transport weather\n * rather than a defect, or `null` when the failure is a real error.\n *\n * Three families qualify: a channel death the client settled locally\n * ({@link isStatewireChannelTeardown} — the cause: `unmount`, `stream-gone`,\n * `session-lost`), the host's `expired` verdict\n * ({@link isStatewireExpiredVerdict} — the answer outlived the host's\n * retention before the post-reconnect resend collected it), and a retryable\n * structured rejection ({@link readRetryableCommandRejection} — its code: the\n * host asked for a resend). In every case the sender's own retry or poll is\n * the recovery and the connection indicator already shows the channel, so\n * error reporting counts the outcome instead of paging on it. Handler\n * failures, crashes, and non-retryable rejections stay `null`: those are\n * defects to page on.\n */\nexport function statewireTransportOutcome(error: unknown): string | null {\n  const cause = (error as { failure?: { cause?: unknown } } | null | undefined)?.failure?.cause;\n  if (typeof cause === 'string' && cause !== 'server') return cause;\n  if (isStatewireExpiredVerdict(error)) return 'expired';\n  return readRetryableCommandRejection(error)?.code ?? null;\n}\n\nconst sanitizeConnectionMessage = (message: string): string | undefined => {\n  const printable = Array.from(message, (character) => {\n    const code = character.charCodeAt(0);\n    return code < 32 || code === 127 ? ' ' : character;\n  })\n    .join('')\n    .replace(/\\s+/g, ' ')\n    .trim();\n  return printable ? printable.slice(0, 200) : undefined;\n};\n\n/** Preserve the Statewire lifecycle and sanitize host detail for display. */\nexport function projectDeepAgentConnection(\n  connection: StatewireClient.ConnectionState\n): DeepAgentConnectionState {\n  const message =\n    'message' in connection && typeof connection.message === 'string'\n      ? sanitizeConnectionMessage(connection.message)\n      : undefined;\n  switch (connection.status) {\n    case 'standby':\n      return {\n        status: connection.status,\n        reason: connection.reason,\n        degraded: connection.degraded,\n        ...(message !== undefined && { message }),\n      };\n    case 'connecting':\n    case 'connected':\n      return { status: connection.status, degraded: connection.degraded };\n    case 'retrying':\n      return {\n        status: connection.status,\n        degraded: connection.degraded,\n        attempt: connection.attempt,\n        ...(connection.cause !== undefined && { cause: connection.cause }),\n        ...(connection.code !== undefined && { code: connection.code }),\n        ...(connection.nextRetryAt !== undefined && { nextRetryAt: connection.nextRetryAt }),\n        ...(connection.lastError !== undefined && { lastError: connection.lastError }),\n        ...(message !== undefined && { message }),\n      };\n    case 'stopped':\n      return {\n        status: connection.status,\n        degraded: connection.degraded,\n        reason: connection.reason,\n        ...(connection.payload !== undefined && { payload: connection.payload }),\n        ...(message !== undefined && { message }),\n      };\n    default:\n      return unknownConnectionStatus(connection);\n  }\n}\n\n/** Compile-time exhaustiveness: reachable only when the library grows a status this build does not project. */\nfunction unknownConnectionStatus(connection: never): never {\n  throw new Error(\n    `statewire: unknown connection status ${JSON.stringify(\n      (connection as { status?: unknown }).status\n    )}`\n  );\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.cjs","sources":["../../../../agent-runtime/src/errors.ts"],"sourcesContent":["import type { StatewireClient } from 'statewire';\nimport type { DeepAgentConnectionState } from './types';\n\n/** Structured payload attached to a server-rejected Statewire command. */\nexport interface StatewireRejectionPayload {\n  status: number;\n  detail: unknown;\n}\n\n/** Return a rejected command's structured `{ status, detail }` payload. */\nexport function statewireRejectionPayload(error: unknown): StatewireRejectionPayload | null {\n  const failure = (error as { failure?: { fate?: unknown; payload?: unknown } } | null)?.failure;\n  if (failure?.fate !== 'rejected') return null;\n\n  const payload = failure.payload as { status?: unknown; detail?: unknown } | undefined;\n  if (typeof payload?.status !== 'number') return null;\n  return { status: payload.status, detail: payload.detail };\n}\n\n/**\n * The server's human-readable reason for a rejected command — `detail.message`\n * (or a plain-string `detail`) — else `null`. Hosts surface it as send\n * feedback so the user sees the actionable cause instead of the generic\n * client-side `command rejected (<status>)`.\n */\nexport function statewireRejectionDetailMessage(error: unknown): string | null {\n  const detail = statewireRejectionPayload(error)?.detail;\n  if (typeof detail === 'string') return detail.length > 0 ? detail : null;\n  if (detail === null || typeof detail !== 'object' || Array.isArray(detail)) return null;\n  const message = (detail as { message?: unknown }).message;\n  return typeof message === 'string' && message.length > 0 ? message : null;\n}\n\n/**\n * A structured, retryable refusal the host recorded as the run error\n * (`runs.error`): the dispatch never started — the pod or instance was\n * closing (`pod_draining`) — and the entries stayed in their lanes for the\n * thread's next placement. Distinct from a rejected COMMAND\n * ({@link statewireRejectionPayload}): this is the shape harness-sdk writes\n * when the run executor raises the rejection, so it lives on the replicated\n * run entry, not on a command settle.\n */\nexport interface RetryableRunRefusal {\n  /** The structured `detail.code` (`pod_draining`). */\n  code: string;\n  /** The server's human-readable reason, when it sent one. */\n  message: string | null;\n}\n\n/** The `{ code, message, retryable: true }` detail of a structured refusal, or `null`. */\nfunction readRetryableDetail(detail: unknown): { code: string; message: string | null } | null {\n  if (detail === null || typeof detail !== 'object' || Array.isArray(detail)) return null;\n  const { code, message, retryable } = detail as {\n    code?: unknown;\n    message?: unknown;\n    retryable?: unknown;\n  };\n  if (retryable !== true || typeof code !== 'string' || code.length === 0) return null;\n  return { code, message: typeof message === 'string' && message.length > 0 ? message : null };\n}\n\nexport function readRetryableRunRefusal(error: unknown): RetryableRunRefusal | null {\n  if (error === null || typeof error !== 'object' || Array.isArray(error)) return null;\n  return readRetryableDetail((error as { detail?: unknown }).detail);\n}\n\n/**\n * The `detail.code` agora answers when a send names another channel of the\n * collab agent a session started on (`collab_agent_bridge.py`): a session\n * keeps its channel — the SDK app's Agent / Ask mode — for its lifetime, and\n * the way to the other mode is a new session. Wire-frozen.\n */\nexport const COLLAB_AGENT_CHANNEL_SESSION_MISMATCH = 'collab_agent_channel_session_mismatch';\n\n/**\n * A structured refusal the host recorded as the run error when the run could\n * not START: the run executor raised the gate's `{status, detail: {code,\n * message}}` envelope (agora's `_status_reject`) before it accepted the\n * dispatched input, so the message went back to its lane and the thread rests\n * `error` with it still queued. Unlike a retryable refusal\n * ({@link readRetryableRunRefusal}) nothing will dispatch it later: resending\n * the same input is refused the same way, so the server's message is the only\n * explanation the person gets.\n */\nexport interface RunStartRefusal {\n  /** The structured `detail.code` (`collab_agent_channel_session_mismatch`, …). */\n  code: string;\n  /** The server's human-readable reason, when it sent one. */\n  message: string | null;\n  /** The HTTP-style status the gate raised with, when recorded. */\n  status: number | null;\n}\n\n/**\n * The non-retryable structured refusal off a replicated run error\n * (`runs.error`), or `null` — for a run that failed while it was running (a\n * plain `{message}`), a retryable refusal, or no error at all.\n */\nexport function readRunStartRefusal(error: unknown): RunStartRefusal | null {\n  if (error === null || typeof error !== 'object' || Array.isArray(error)) return null;\n  const { detail, status } = error as { detail?: unknown; status?: unknown };\n  if (detail === null || typeof detail !== 'object' || Array.isArray(detail)) return null;\n  const { code, message, retryable } = detail as {\n    code?: unknown;\n    message?: unknown;\n    retryable?: unknown;\n  };\n  if (retryable === true || typeof code !== 'string' || code.length === 0) return null;\n  return {\n    code,\n    message: typeof message === 'string' && message.length > 0 ? message : null,\n    status: typeof status === 'number' ? status : null,\n  };\n}\n\n/**\n * The `payload.reason` codes agora's voice manager rejects `voice/*` commands\n * with (harness-sdk's `_reject` and `voice_host.py`). Wire-frozen.\n */\nconst VOICE_REJECTION_REASONS: ReadonlySet<string> = new Set([\n  'no-voice',\n  'not-voice-owner',\n  'voice-active',\n  'voice-stale-session',\n  'voice-unavailable',\n  'voice-not-enabled',\n  'voice-model-transport',\n  'text-too-long',\n]);\n\n/**\n * Whether a rejected command was a `voice/*` command, by its voice manager\n * `payload.reason`. The voice controller owns those outcomes (it settles to\n * idle, falls back to a typed send, or shows its own notice), so a chat's\n * \"Message was not sent\" banner must not repeat them: no message was sent.\n */\nexport function isVoiceCommandRejection(error: unknown): boolean {\n  const failure = (error as { failure?: { fate?: unknown; payload?: unknown } } | null)?.failure;\n  if (failure?.fate !== 'rejected') return false;\n  const reason = (failure.payload as { reason?: unknown } | null | undefined)?.reason;\n  return typeof reason === 'string' && VOICE_REJECTION_REASONS.has(reason);\n}\n\n/** The structured `detail.code` of a rejected command, or `null`. */\nexport function statewireRejectionCode(error: unknown): string | null {\n  const detail = statewireRejectionPayload(error)?.detail;\n  if (detail === null || typeof detail !== 'object' || Array.isArray(detail)) return null;\n  const code = (detail as { code?: unknown }).code;\n  return typeof code === 'string' && code.length > 0 ? code : null;\n}\n\n/**\n * A structured, retryable refusal of a COMMAND, read off its rejection\n * ({@link statewireRejectionPayload}): the host's `_structured_reject(...,\n * retryable=True)` envelope — `command_auth_context_expired` when a pod\n * replacement dropped the socket-scoped auth a replayed command needed,\n * `pod_draining` when the host was closing. The command never ran, and the\n * host itself says a resend after the reconnect will; `detail.code` is the\n * wire-frozen contract clients classify on. Same shape as\n * {@link readRetryableRunRefusal}, which reads it off a replicated run entry.\n */\nexport interface RetryableCommandRejection {\n  /** The structured `detail.code`. */\n  code: string;\n  /** The server's human-readable reason, when it sent one. */\n  message: string | null;\n}\n\nexport function readRetryableCommandRejection(error: unknown): RetryableCommandRejection | null {\n  const payload = statewireRejectionPayload(error);\n  return payload === null ? null : readRetryableDetail(payload.detail);\n}\n\n/** The host's `detail.code` for a command replayed onto a pod that could not restore its auth context. */\nexport const STATEWIRE_COMMAND_AUTH_CONTEXT_EXPIRED = 'command_auth_context_expired';\n\n/**\n * Whether a rejected command hit the host's fail-closed auth recovery: the\n * command was replayed onto a replacement pod that could not restore the\n * attach's auth context, so it was refused unrun (503, retryable). The\n * reconnect already under way restores the context; a single resend after it\n * is the recovery, not a failure to report.\n */\nexport function isStatewireCommandAuthContextExpired(error: unknown): boolean {\n  const payload = statewireRejectionPayload(error);\n  return (\n    payload?.status === 503 &&\n    readRetryableDetail(payload.detail)?.code === STATEWIRE_COMMAND_AUTH_CONTEXT_EXPIRED\n  );\n}\n\n/**\n * The `detail.code` agora answers for a write to an archived (trashed)\n * conversation (`host_rejects._conversation_archived_reject`, a 409): it\n * takes no new turns, config writes or approval answers until it is\n * restored, and stopping still works. Wire-frozen.\n */\nexport const CONVERSATION_ARCHIVED = 'conversation_archived';\n\n/** What a person is told when that refusal comes back (the server says the same). */\nexport const CONVERSATION_ARCHIVED_MESSAGE =\n  'This conversation is archived. Restore it to continue.';\n\n/**\n * Whether a rejected command was refused because the conversation is archived\n * ({@link CONVERSATION_ARCHIVED}). Not retriable: nothing changes until a\n * restore, so callers show {@link CONVERSATION_ARCHIVED_MESSAGE} rather than a\n * \"try again\".\n */\nexport function isConversationArchivedRejection(error: unknown): boolean {\n  return statewireRejectionCode(error) === CONVERSATION_ARCHIVED;\n}\n\n/**\n * Whether a rejected command hit the legacy-thread dispatch fence: the\n * structured 409 the server answers when an out-of-band run is writing a\n * pre-cutover thread (or its adoption failed). A per-send failure — the\n * snapshot never carries a standing read-only flag.\n */\nexport function isLegacyThreadReadOnlyRejection(error: unknown): boolean {\n  const payload = statewireRejectionPayload(error);\n  if (payload?.status !== 409) return false;\n\n  const detail = payload.detail as { code?: unknown } | undefined;\n  return detail?.code === 'legacy_thread_read_only';\n}\n\n/**\n * Whether a rejected command was refused because its rewind anchor no longer\n * matches the host's parent for the edited message (`wrong-anchor`).\n *\n * A retry/edit resubmit is dispatched optimistically, so this rejection lands\n * after the UI already cleared its edit affordances: the turn simply never\n * re-runs. Callers use this to tell the user the resubmit was dropped instead\n * of leaving a console-only failure.\n */\nexport function isStatewireRewindAnchorRejection(error: unknown): boolean {\n  const failure = (error as { failure?: { fate?: unknown; payload?: unknown } } | null | undefined)\n    ?.failure;\n  if (failure?.fate !== 'rejected') return false;\n  return (failure.payload as { reason?: unknown } | undefined)?.reason === 'wrong-anchor';\n}\n\n/**\n * Whether a statewire send failure is the host's `expired` verdict\n * (`result-unavailable`): the command's seq was at or below the host's\n * admitted watermark and no retained result was left for it. Either the\n * command ran and settled but the client re-asked for the answer (a resend\n * after the stream came back) only after the host had let the retained result\n * go, or the seq was already admitted and the command was absorbed as a\n * duplicate without ever running — a client whose shared session record fell\n * behind the watermark stays there until a reconnect re-syncs it. The library\n * never reruns the command on replay, so for an idempotent read the answer is\n * simply gone — asking again is the correct reaction, not reporting a failure;\n * a write cannot assume it was applied.\n */\nexport function isStatewireExpiredVerdict(error: unknown): boolean {\n  const failure = (error as { failure?: { fate?: unknown; cause?: unknown } | null | undefined })\n    ?.failure;\n  return failure?.fate === 'expired' && failure.cause === 'server';\n}\n\n/**\n * Whether a statewire send failure is a local channel death rather than a\n * command error.\n *\n * The library's contract for `SendFailure.cause`: `\"server\"` is the server's\n * own answer; every other cause is \"a channel death the client settled\n * locally\" — `unmount`, `stream-gone`, and `session-lost`. A thread switch\n * settles every in-flight command that way, so logging these at error level\n * reports two failures for an ordinary switch and buries the ones that mean\n * something.\n *\n * Channel health is already surfaced where it belongs: the connection\n * indicator renders the connection state. This\n * predicate only decides the log level.\n */\nexport function isStatewireChannelTeardown(error: unknown): boolean {\n  const cause = (error as { failure?: { cause?: unknown } } | null | undefined)?.failure?.cause;\n  return typeof cause === 'string' && cause !== 'server';\n}\n\n/**\n * The low-cardinality reason a statewire send settled as transport weather\n * rather than a defect, or `null` when the failure is a real error.\n *\n * Three families qualify: a channel death the client settled locally\n * ({@link isStatewireChannelTeardown} — the cause: `unmount`, `stream-gone`,\n * `session-lost`), the host's `expired` verdict\n * ({@link isStatewireExpiredVerdict} — the answer outlived the host's\n * retention before the post-reconnect resend collected it), and a retryable\n * structured rejection ({@link readRetryableCommandRejection} — its code: the\n * host asked for a resend). In every case the sender's own retry or poll is\n * the recovery and the connection indicator already shows the channel, so\n * error reporting counts the outcome instead of paging on it. Handler\n * failures, crashes, and non-retryable rejections stay `null`: those are\n * defects to page on.\n */\nexport function statewireTransportOutcome(error: unknown): string | null {\n  const cause = (error as { failure?: { cause?: unknown } } | null | undefined)?.failure?.cause;\n  if (typeof cause === 'string' && cause !== 'server') return cause;\n  if (isStatewireExpiredVerdict(error)) return 'expired';\n  return readRetryableCommandRejection(error)?.code ?? null;\n}\n\nconst sanitizeConnectionMessage = (message: string): string | undefined => {\n  const printable = Array.from(message, (character) => {\n    const code = character.charCodeAt(0);\n    return code < 32 || code === 127 ? ' ' : character;\n  })\n    .join('')\n    .replace(/\\s+/g, ' ')\n    .trim();\n  return printable ? printable.slice(0, 200) : undefined;\n};\n\n/** Preserve the Statewire lifecycle and sanitize host detail for display. */\nexport function projectDeepAgentConnection(\n  connection: StatewireClient.ConnectionState\n): DeepAgentConnectionState {\n  const message =\n    'message' in connection && typeof connection.message === 'string'\n      ? sanitizeConnectionMessage(connection.message)\n      : undefined;\n  switch (connection.status) {\n    case 'standby':\n      return {\n        status: connection.status,\n        reason: connection.reason,\n        degraded: connection.degraded,\n        ...(message !== undefined && { message }),\n      };\n    case 'connecting':\n    case 'connected':\n      return { status: connection.status, degraded: connection.degraded };\n    case 'retrying':\n      return {\n        status: connection.status,\n        degraded: connection.degraded,\n        attempt: connection.attempt,\n        ...(connection.cause !== undefined && { cause: connection.cause }),\n        ...(connection.code !== undefined && { code: connection.code }),\n        ...(connection.nextRetryAt !== undefined && { nextRetryAt: connection.nextRetryAt }),\n        ...(connection.lastError !== undefined && { lastError: connection.lastError }),\n        ...(message !== undefined && { message }),\n      };\n    case 'stopped':\n      return {\n        status: connection.status,\n        degraded: connection.degraded,\n        reason: connection.reason,\n        ...(connection.payload !== undefined && { payload: connection.payload }),\n        ...(message !== undefined && { message }),\n      };\n    default:\n      return unknownConnectionStatus(connection);\n  }\n}\n\n/** Compile-time exhaustiveness: reachable only when the library grows a status this build does not project. */\nfunction unknownConnectionStatus(connection: never): never {\n  throw new Error(\n    `statewire: unknown connection status ${JSON.stringify(\n      (connection as { status?: unknown }).status\n    )}`\n  );\n}\n"],"names":[],"mappings":"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"}

package/dist/agent-runtime/src/errors.d.ts

@@ -61,6 +61,13 @@ export interface RunStartRefusal {
  * plain `{message}`), a retryable refusal, or no error at all.
  */
 export declare function readRunStartRefusal(error: unknown): RunStartRefusal | null;
+/**
+ * Whether a rejected command was a `voice/*` command, by its voice manager
+ * `payload.reason`. The voice controller owns those outcomes (it settles to
+ * idle, falls back to a typed send, or shows its own notice), so a chat's
+ * "Message was not sent" banner must not repeat them: no message was sent.
+ */
+export declare function isVoiceCommandRejection(error: unknown): boolean;
 /** The structured `detail.code` of a rejected command, or `null`. */
 export declare function statewireRejectionCode(error: unknown): string | null;
 /**

package/dist/agent-runtime/src/errors.js

@@ -36,6 +36,23 @@ function readRunStartRefusal(error) {
     status: typeof status === "number" ? status : null
   };
 }
+const VOICE_REJECTION_REASONS = /* @__PURE__ */ new Set([
+  "no-voice",
+  "not-voice-owner",
+  "voice-active",
+  "voice-stale-session",
+  "voice-unavailable",
+  "voice-not-enabled",
+  "voice-model-transport",
+  "text-too-long"
+]);
+function isVoiceCommandRejection(error) {
+  var _a;
+  const failure = error == null ? void 0 : error.failure;
+  if ((failure == null ? void 0 : failure.fate) !== "rejected") return false;
+  const reason = (_a = failure.payload) == null ? void 0 : _a.reason;
+  return typeof reason === "string" && VOICE_REJECTION_REASONS.has(reason);
+}
 function statewireRejectionCode(error) {
   var _a;
   const detail = (_a = statewireRejectionPayload(error)) == null ? void 0 : _a.detail;
@@ -132,6 +149,7 @@ export {
   isLegacyThreadReadOnlyRejection,
   isStatewireChannelTeardown,
   isStatewireExpiredVerdict,
+  isVoiceCommandRejection,
   projectDeepAgentConnection,
   readRetryableCommandRejection,
   readRetryableRunRefusal,