@athenaintel/react 0.57.2 → 0.60.0

package/dist/runtime/statewire-plan-mode.cjs

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const PLAN_MODE_TOOL = "write_todos";
+const PLAN_MODE_MIDDLEWARE = "TodoListMiddleware";
+const EXCLUDED_TOOLS = "excluded_tools";
+const EXCLUDED_MIDDLEWARE = "excluded_middleware";
+const PLAN_MODE_EXCLUSIONS = [
+  { key: EXCLUDED_TOOLS, name: PLAN_MODE_TOOL },
+  { key: EXCLUDED_MIDDLEWARE, name: PLAN_MODE_MIDDLEWARE }
+];
+const stringItems = (value) => Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+function planModeOf(custom) {
+  return PLAN_MODE_EXCLUSIONS.every(({ key, name }) => !stringItems(custom[key]).includes(name));
+}
+function planModeListEdits({
+  custom,
+  planMode
+}) {
+  const edits = {};
+  if (planModeOf(custom) === planMode) return edits;
+  for (const { key, name } of PLAN_MODE_EXCLUSIONS) {
+    const items = stringItems(custom[key]);
+    const excluded = items.includes(name);
+    if (planMode && excluded) {
+      const kept = items.filter((item) => item !== name);
+      edits[key] = kept.length > 0 ? kept : null;
+    } else if (!planMode && !excluded) {
+      edits[key] = [...items, name];
+    }
+  }
+  return edits;
+}
+function withPlanMode({
+  custom,
+  planMode
+}) {
+  if (planMode === void 0) return custom;
+  const edits = planModeListEdits({ custom, planMode });
+  if (Object.keys(edits).length === 0) return custom;
+  const next = { ...custom };
+  for (const [key, value] of Object.entries(edits)) {
+    if (value === null) delete next[key];
+    else next[key] = value;
+  }
+  return next;
+}
+function threadPlanModeFromLane({
+  lane,
+  ready
+}) {
+  if (!ready || lane === null) return { planMode: null, configured: false, ready };
+  return { planMode: planModeOf(lane.custom), configured: true, ready };
+}
+function decidePlanModeLanePatch({
+  planMode,
+  landed,
+  configVersion,
+  custom
+}) {
+  if (!landed || configVersion <= 0) return { kind: "wait" };
+  const patch = planModeListEdits({ custom, planMode });
+  return Object.keys(patch).length === 0 ? { kind: "done" } : { kind: "patch", patch };
+}
+exports.PLAN_MODE_MIDDLEWARE = PLAN_MODE_MIDDLEWARE;
+exports.PLAN_MODE_TOOL = PLAN_MODE_TOOL;
+exports.decidePlanModeLanePatch = decidePlanModeLanePatch;
+exports.planModeListEdits = planModeListEdits;
+exports.planModeOf = planModeOf;
+exports.threadPlanModeFromLane = threadPlanModeFromLane;
+exports.withPlanMode = withPlanMode;
+//# sourceMappingURL=statewire-plan-mode.cjs.map

package/dist/runtime/statewire-plan-mode.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"statewire-plan-mode.cjs","sources":["../../src/runtime/statewire-plan-mode.ts"],"sourcesContent":["import type {\n  DeepAgentServerConfig,\n  ThreadConfigCustom,\n  ThreadConfigPatch,\n} from '@athenaintel/agent-runtime';\n\n/**\n * Plan mode: the deep agent keeps a to-do plan for multi-step work and checks\n * its steps off as it goes. That is the `write_todos` tool and the\n * `TodoListMiddleware` that provides it with its planning prompt, which agora\n * binds on every run unless the run's config excludes either one\n * (`excluded_tools`, `excluded_middleware`). The two go together, as Olympus's\n * Plan Mode switch flips them (`applyPlanningEnabled`): a config plans unless\n * it excludes either.\n */\nexport const PLAN_MODE_TOOL = 'write_todos';\n\n/** The middleware that provides {@link PLAN_MODE_TOOL} and its planning prompt. */\nexport const PLAN_MODE_MIDDLEWARE = 'TodoListMiddleware';\n\nconst EXCLUDED_TOOLS = 'excluded_tools';\nconst EXCLUDED_MIDDLEWARE = 'excluded_middleware';\n\n/** The two lists plan mode edits, each with the one name plan mode owns in it. */\nconst PLAN_MODE_EXCLUSIONS = [\n  { key: EXCLUDED_TOOLS, name: PLAN_MODE_TOOL },\n  { key: EXCLUDED_MIDDLEWARE, name: PLAN_MODE_MIDDLEWARE },\n] as const;\n\nconst stringItems = (value: unknown): string[] =>\n  Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : [];\n\n/** Whether a config (a send's `runConfig.custom`, or a thread's server config) plans. Pure. */\nexport function planModeOf(custom: ThreadConfigCustom): boolean {\n  return PLAN_MODE_EXCLUSIONS.every(({ key, name }) => !stringItems(custom[key]).includes(name));\n}\n\n/**\n * The exclusion lists that put `custom` in plan mode `planMode`, keyed as a\n * config carries them, and only those that change: plan mode off adds\n * `write_todos` to `excluded_tools` and `TodoListMiddleware` to\n * `excluded_middleware` after what each already lists; on takes them out, and\n * a list left empty is `null` (a `config/patch` unsets it). Every other name in\n * either list stays where it is. `{}` when `custom` is in that plan mode\n * already (off: it excludes either one). Pure.\n */\nexport function planModeListEdits({\n  custom,\n  planMode,\n}: {\n  custom: ThreadConfigCustom;\n  planMode: boolean;\n}): ThreadConfigPatch {\n  const edits: ThreadConfigPatch = {};\n  if (planModeOf(custom) === planMode) return edits;\n  for (const { key, name } of PLAN_MODE_EXCLUSIONS) {\n    const items = stringItems(custom[key]);\n    const excluded = items.includes(name);\n    if (planMode && excluded) {\n      const kept = items.filter((item) => item !== name);\n      edits[key] = kept.length > 0 ? kept : null;\n    } else if (!planMode && !excluded) {\n      edits[key] = [...items, name];\n    }\n  }\n  return edits;\n}\n\n/**\n * A send's `runConfig.custom` in plan mode `planMode`, after everything else\n * (the host's `extraRunConfig` included) is merged: `undefined` leaves it as it\n * is; otherwise {@link planModeListEdits}, an emptied list omitted. Pure.\n */\nexport function withPlanMode({\n  custom,\n  planMode,\n}: {\n  custom: Record<string, unknown>;\n  planMode: boolean | undefined;\n}): Record<string, unknown> {\n  if (planMode === undefined) return custom;\n  const edits = planModeListEdits({ custom, planMode });\n  if (Object.keys(edits).length === 0) return custom;\n  const next: Record<string, unknown> = { ...custom };\n  for (const [key, value] of Object.entries(edits)) {\n    if (value === null) delete next[key];\n    else next[key] = value;\n  }\n  return next;\n}\n\n/** A thread's plan mode, read from its server config lane. */\nexport interface AthenaThreadPlanMode {\n  /**\n   * Whether the thread's server config plans (`true`) or not (`false`); `null`\n   * while it has none, when every turn runs with what the send carries (the\n   * provider's `planMode`, and a plan when the provider sets none).\n   */\n  planMode: boolean | null;\n  /** `true` once the thread has a server config lane (version > 0). */\n  configured: boolean;\n  /**\n   * `true` once the statewire host's snapshot of this thread has arrived (the\n   * placeholder or remembered snapshot a thread shows while it loads may carry\n   * no lane, or an older one). Before that `planMode` is `null`.\n   */\n  ready: boolean;\n}\n\n/** {@link AthenaThreadPlanMode} from the lane and the landed flag. Pure. */\nexport function threadPlanModeFromLane({\n  lane,\n  ready,\n}: {\n  lane: DeepAgentServerConfig | null;\n  ready: boolean;\n}): AthenaThreadPlanMode {\n  if (!ready || lane === null) return { planMode: null, configured: false, ready };\n  return { planMode: planModeOf(lane.custom), configured: true, ready };\n}\n\n/**\n * What to do with a `planMode` change the host made during an attach, decided\n * as every provider-owned thread-config key is (`decideThreadConfigLanePatch`):\n *\n * - `wait`: keep it pending. The thread's snapshot has not landed, or the\n *   thread has no lane yet (version 0), where the next send carries plan mode.\n *   It stays pending so that a lane an EARLIER send seeds is corrected once it\n *   lands.\n * - `done`: the lane already plans that way (this client's own unacknowledged\n *   writes folded over); nothing to write.\n * - `patch`: issue one `config/patch` carrying the exclusion lists that change,\n *   computed from the lane's own, so a name another client excluded stays.\n */\nexport type PlanModeLaneDecision =\n  | { kind: 'wait' }\n  | { kind: 'done' }\n  | { kind: 'patch'; patch: ThreadConfigPatch };\n\nexport function decidePlanModeLanePatch({\n  planMode,\n  landed,\n  configVersion,\n  custom,\n}: {\n  /** The provider's `planMode` after the change. */\n  planMode: boolean;\n  landed: boolean;\n  configVersion: number;\n  /** The effective lane: the server config with this client's pending writes folded over. */\n  custom: ThreadConfigCustom;\n}): PlanModeLaneDecision {\n  if (!landed || configVersion <= 0) return { kind: 'wait' };\n  const patch = planModeListEdits({ custom, planMode });\n  return Object.keys(patch).length === 0 ? { kind: 'done' } : { kind: 'patch', patch };\n}\n"],"names":[],"mappings":";;AAeO,MAAM,iBAAiB;AAGvB,MAAM,uBAAuB;AAEpC,MAAM,iBAAiB;AACvB,MAAM,sBAAsB;AAG5B,MAAM,uBAAuB;AAAA,EAC3B,EAAE,KAAK,gBAAgB,MAAM,eAAA;AAAA,EAC7B,EAAE,KAAK,qBAAqB,MAAM,qBAAA;AACpC;AAEA,MAAM,cAAc,CAAC,UACnB,MAAM,QAAQ,KAAK,IAAI,MAAM,OAAO,CAAC,SAAyB,OAAO,SAAS,QAAQ,IAAI,CAAA;AAGrF,SAAS,WAAW,QAAqC;AAC9D,SAAO,qBAAqB,MAAM,CAAC,EAAE,KAAK,KAAA,MAAW,CAAC,YAAY,OAAO,GAAG,CAAC,EAAE,SAAS,IAAI,CAAC;AAC/F;AAWO,SAAS,kBAAkB;AAAA,EAChC;AAAA,EACA;AACF,GAGsB;AACpB,QAAM,QAA2B,CAAA;AACjC,MAAI,WAAW,MAAM,MAAM,SAAU,QAAO;AAC5C,aAAW,EAAE,KAAK,KAAA,KAAU,sBAAsB;AAChD,UAAM,QAAQ,YAAY,OAAO,GAAG,CAAC;AACrC,UAAM,WAAW,MAAM,SAAS,IAAI;AACpC,QAAI,YAAY,UAAU;AACxB,YAAM,OAAO,MAAM,OAAO,CAAC,SAAS,SAAS,IAAI;AACjD,YAAM,GAAG,IAAI,KAAK,SAAS,IAAI,OAAO;AAAA,IACxC,WAAW,CAAC,YAAY,CAAC,UAAU;AACjC,YAAM,GAAG,IAAI,CAAC,GAAG,OAAO,IAAI;AAAA,IAC9B;AAAA,EACF;AACA,SAAO;AACT;AAOO,SAAS,aAAa;AAAA,EAC3B;AAAA,EACA;AACF,GAG4B;AAC1B,MAAI,aAAa,OAAW,QAAO;AACnC,QAAM,QAAQ,kBAAkB,EAAE,QAAQ,UAAU;AACpD,MAAI,OAAO,KAAK,KAAK,EAAE,WAAW,EAAG,QAAO;AAC5C,QAAM,OAAgC,EAAE,GAAG,OAAA;AAC3C,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,KAAK,GAAG;AAChD,QAAI,UAAU,KAAM,QAAO,KAAK,GAAG;AAAA,QAC9B,MAAK,GAAG,IAAI;AAAA,EACnB;AACA,SAAO;AACT;AAqBO,SAAS,uBAAuB;AAAA,EACrC;AAAA,EACA;AACF,GAGyB;AACvB,MAAI,CAAC,SAAS,SAAS,KAAM,QAAO,EAAE,UAAU,MAAM,YAAY,OAAO,MAAA;AACzE,SAAO,EAAE,UAAU,WAAW,KAAK,MAAM,GAAG,YAAY,MAAM,MAAA;AAChE;AAoBO,SAAS,wBAAwB;AAAA,EACtC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAOyB;AACvB,MAAI,CAAC,UAAU,iBAAiB,EAAG,QAAO,EAAE,MAAM,OAAA;AAClD,QAAM,QAAQ,kBAAkB,EAAE,QAAQ,UAAU;AACpD,SAAO,OAAO,KAAK,KAAK,EAAE,WAAW,IAAI,EAAE,MAAM,OAAA,IAAW,EAAE,MAAM,SAAS,MAAA;AAC/E;;;;;;;;"}

package/dist/runtime/statewire-plan-mode.d.ts

@@ -0,0 +1,88 @@
+import type { DeepAgentServerConfig, ThreadConfigCustom, ThreadConfigPatch } from '../agent-runtime/src/index';
+/**
+ * Plan mode: the deep agent keeps a to-do plan for multi-step work and checks
+ * its steps off as it goes. That is the `write_todos` tool and the
+ * `TodoListMiddleware` that provides it with its planning prompt, which agora
+ * binds on every run unless the run's config excludes either one
+ * (`excluded_tools`, `excluded_middleware`). The two go together, as Olympus's
+ * Plan Mode switch flips them (`applyPlanningEnabled`): a config plans unless
+ * it excludes either.
+ */
+export declare const PLAN_MODE_TOOL = "write_todos";
+/** The middleware that provides {@link PLAN_MODE_TOOL} and its planning prompt. */
+export declare const PLAN_MODE_MIDDLEWARE = "TodoListMiddleware";
+/** Whether a config (a send's `runConfig.custom`, or a thread's server config) plans. Pure. */
+export declare function planModeOf(custom: ThreadConfigCustom): boolean;
+/**
+ * The exclusion lists that put `custom` in plan mode `planMode`, keyed as a
+ * config carries them, and only those that change: plan mode off adds
+ * `write_todos` to `excluded_tools` and `TodoListMiddleware` to
+ * `excluded_middleware` after what each already lists; on takes them out, and
+ * a list left empty is `null` (a `config/patch` unsets it). Every other name in
+ * either list stays where it is. `{}` when `custom` is in that plan mode
+ * already (off: it excludes either one). Pure.
+ */
+export declare function planModeListEdits({ custom, planMode, }: {
+    custom: ThreadConfigCustom;
+    planMode: boolean;
+}): ThreadConfigPatch;
+/**
+ * A send's `runConfig.custom` in plan mode `planMode`, after everything else
+ * (the host's `extraRunConfig` included) is merged: `undefined` leaves it as it
+ * is; otherwise {@link planModeListEdits}, an emptied list omitted. Pure.
+ */
+export declare function withPlanMode({ custom, planMode, }: {
+    custom: Record<string, unknown>;
+    planMode: boolean | undefined;
+}): Record<string, unknown>;
+/** A thread's plan mode, read from its server config lane. */
+export interface AthenaThreadPlanMode {
+    /**
+     * Whether the thread's server config plans (`true`) or not (`false`); `null`
+     * while it has none, when every turn runs with what the send carries (the
+     * provider's `planMode`, and a plan when the provider sets none).
+     */
+    planMode: boolean | null;
+    /** `true` once the thread has a server config lane (version > 0). */
+    configured: boolean;
+    /**
+     * `true` once the statewire host's snapshot of this thread has arrived (the
+     * placeholder or remembered snapshot a thread shows while it loads may carry
+     * no lane, or an older one). Before that `planMode` is `null`.
+     */
+    ready: boolean;
+}
+/** {@link AthenaThreadPlanMode} from the lane and the landed flag. Pure. */
+export declare function threadPlanModeFromLane({ lane, ready, }: {
+    lane: DeepAgentServerConfig | null;
+    ready: boolean;
+}): AthenaThreadPlanMode;
+/**
+ * What to do with a `planMode` change the host made during an attach, decided
+ * as every provider-owned thread-config key is (`decideThreadConfigLanePatch`):
+ *
+ * - `wait`: keep it pending. The thread's snapshot has not landed, or the
+ *   thread has no lane yet (version 0), where the next send carries plan mode.
+ *   It stays pending so that a lane an EARLIER send seeds is corrected once it
+ *   lands.
+ * - `done`: the lane already plans that way (this client's own unacknowledged
+ *   writes folded over); nothing to write.
+ * - `patch`: issue one `config/patch` carrying the exclusion lists that change,
+ *   computed from the lane's own, so a name another client excluded stays.
+ */
+export type PlanModeLaneDecision = {
+    kind: 'wait';
+} | {
+    kind: 'done';
+} | {
+    kind: 'patch';
+    patch: ThreadConfigPatch;
+};
+export declare function decidePlanModeLanePatch({ planMode, landed, configVersion, custom, }: {
+    /** The provider's `planMode` after the change. */
+    planMode: boolean;
+    landed: boolean;
+    configVersion: number;
+    /** The effective lane: the server config with this client's pending writes folded over. */
+    custom: ThreadConfigCustom;
+}): PlanModeLaneDecision;

package/dist/runtime/statewire-plan-mode.js

@@ -0,0 +1,71 @@
+const PLAN_MODE_TOOL = "write_todos";
+const PLAN_MODE_MIDDLEWARE = "TodoListMiddleware";
+const EXCLUDED_TOOLS = "excluded_tools";
+const EXCLUDED_MIDDLEWARE = "excluded_middleware";
+const PLAN_MODE_EXCLUSIONS = [
+  { key: EXCLUDED_TOOLS, name: PLAN_MODE_TOOL },
+  { key: EXCLUDED_MIDDLEWARE, name: PLAN_MODE_MIDDLEWARE }
+];
+const stringItems = (value) => Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+function planModeOf(custom) {
+  return PLAN_MODE_EXCLUSIONS.every(({ key, name }) => !stringItems(custom[key]).includes(name));
+}
+function planModeListEdits({
+  custom,
+  planMode
+}) {
+  const edits = {};
+  if (planModeOf(custom) === planMode) return edits;
+  for (const { key, name } of PLAN_MODE_EXCLUSIONS) {
+    const items = stringItems(custom[key]);
+    const excluded = items.includes(name);
+    if (planMode && excluded) {
+      const kept = items.filter((item) => item !== name);
+      edits[key] = kept.length > 0 ? kept : null;
+    } else if (!planMode && !excluded) {
+      edits[key] = [...items, name];
+    }
+  }
+  return edits;
+}
+function withPlanMode({
+  custom,
+  planMode
+}) {
+  if (planMode === void 0) return custom;
+  const edits = planModeListEdits({ custom, planMode });
+  if (Object.keys(edits).length === 0) return custom;
+  const next = { ...custom };
+  for (const [key, value] of Object.entries(edits)) {
+    if (value === null) delete next[key];
+    else next[key] = value;
+  }
+  return next;
+}
+function threadPlanModeFromLane({
+  lane,
+  ready
+}) {
+  if (!ready || lane === null) return { planMode: null, configured: false, ready };
+  return { planMode: planModeOf(lane.custom), configured: true, ready };
+}
+function decidePlanModeLanePatch({
+  planMode,
+  landed,
+  configVersion,
+  custom
+}) {
+  if (!landed || configVersion <= 0) return { kind: "wait" };
+  const patch = planModeListEdits({ custom, planMode });
+  return Object.keys(patch).length === 0 ? { kind: "done" } : { kind: "patch", patch };
+}
+export {
+  PLAN_MODE_MIDDLEWARE,
+  PLAN_MODE_TOOL,
+  decidePlanModeLanePatch,
+  planModeListEdits,
+  planModeOf,
+  threadPlanModeFromLane,
+  withPlanMode
+};
+//# sourceMappingURL=statewire-plan-mode.js.map

package/dist/runtime/statewire-plan-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"statewire-plan-mode.js","sources":["../../src/runtime/statewire-plan-mode.ts"],"sourcesContent":["import type {\n  DeepAgentServerConfig,\n  ThreadConfigCustom,\n  ThreadConfigPatch,\n} from '@athenaintel/agent-runtime';\n\n/**\n * Plan mode: the deep agent keeps a to-do plan for multi-step work and checks\n * its steps off as it goes. That is the `write_todos` tool and the\n * `TodoListMiddleware` that provides it with its planning prompt, which agora\n * binds on every run unless the run's config excludes either one\n * (`excluded_tools`, `excluded_middleware`). The two go together, as Olympus's\n * Plan Mode switch flips them (`applyPlanningEnabled`): a config plans unless\n * it excludes either.\n */\nexport const PLAN_MODE_TOOL = 'write_todos';\n\n/** The middleware that provides {@link PLAN_MODE_TOOL} and its planning prompt. */\nexport const PLAN_MODE_MIDDLEWARE = 'TodoListMiddleware';\n\nconst EXCLUDED_TOOLS = 'excluded_tools';\nconst EXCLUDED_MIDDLEWARE = 'excluded_middleware';\n\n/** The two lists plan mode edits, each with the one name plan mode owns in it. */\nconst PLAN_MODE_EXCLUSIONS = [\n  { key: EXCLUDED_TOOLS, name: PLAN_MODE_TOOL },\n  { key: EXCLUDED_MIDDLEWARE, name: PLAN_MODE_MIDDLEWARE },\n] as const;\n\nconst stringItems = (value: unknown): string[] =>\n  Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : [];\n\n/** Whether a config (a send's `runConfig.custom`, or a thread's server config) plans. Pure. */\nexport function planModeOf(custom: ThreadConfigCustom): boolean {\n  return PLAN_MODE_EXCLUSIONS.every(({ key, name }) => !stringItems(custom[key]).includes(name));\n}\n\n/**\n * The exclusion lists that put `custom` in plan mode `planMode`, keyed as a\n * config carries them, and only those that change: plan mode off adds\n * `write_todos` to `excluded_tools` and `TodoListMiddleware` to\n * `excluded_middleware` after what each already lists; on takes them out, and\n * a list left empty is `null` (a `config/patch` unsets it). Every other name in\n * either list stays where it is. `{}` when `custom` is in that plan mode\n * already (off: it excludes either one). Pure.\n */\nexport function planModeListEdits({\n  custom,\n  planMode,\n}: {\n  custom: ThreadConfigCustom;\n  planMode: boolean;\n}): ThreadConfigPatch {\n  const edits: ThreadConfigPatch = {};\n  if (planModeOf(custom) === planMode) return edits;\n  for (const { key, name } of PLAN_MODE_EXCLUSIONS) {\n    const items = stringItems(custom[key]);\n    const excluded = items.includes(name);\n    if (planMode && excluded) {\n      const kept = items.filter((item) => item !== name);\n      edits[key] = kept.length > 0 ? kept : null;\n    } else if (!planMode && !excluded) {\n      edits[key] = [...items, name];\n    }\n  }\n  return edits;\n}\n\n/**\n * A send's `runConfig.custom` in plan mode `planMode`, after everything else\n * (the host's `extraRunConfig` included) is merged: `undefined` leaves it as it\n * is; otherwise {@link planModeListEdits}, an emptied list omitted. Pure.\n */\nexport function withPlanMode({\n  custom,\n  planMode,\n}: {\n  custom: Record<string, unknown>;\n  planMode: boolean | undefined;\n}): Record<string, unknown> {\n  if (planMode === undefined) return custom;\n  const edits = planModeListEdits({ custom, planMode });\n  if (Object.keys(edits).length === 0) return custom;\n  const next: Record<string, unknown> = { ...custom };\n  for (const [key, value] of Object.entries(edits)) {\n    if (value === null) delete next[key];\n    else next[key] = value;\n  }\n  return next;\n}\n\n/** A thread's plan mode, read from its server config lane. */\nexport interface AthenaThreadPlanMode {\n  /**\n   * Whether the thread's server config plans (`true`) or not (`false`); `null`\n   * while it has none, when every turn runs with what the send carries (the\n   * provider's `planMode`, and a plan when the provider sets none).\n   */\n  planMode: boolean | null;\n  /** `true` once the thread has a server config lane (version > 0). */\n  configured: boolean;\n  /**\n   * `true` once the statewire host's snapshot of this thread has arrived (the\n   * placeholder or remembered snapshot a thread shows while it loads may carry\n   * no lane, or an older one). Before that `planMode` is `null`.\n   */\n  ready: boolean;\n}\n\n/** {@link AthenaThreadPlanMode} from the lane and the landed flag. Pure. */\nexport function threadPlanModeFromLane({\n  lane,\n  ready,\n}: {\n  lane: DeepAgentServerConfig | null;\n  ready: boolean;\n}): AthenaThreadPlanMode {\n  if (!ready || lane === null) return { planMode: null, configured: false, ready };\n  return { planMode: planModeOf(lane.custom), configured: true, ready };\n}\n\n/**\n * What to do with a `planMode` change the host made during an attach, decided\n * as every provider-owned thread-config key is (`decideThreadConfigLanePatch`):\n *\n * - `wait`: keep it pending. The thread's snapshot has not landed, or the\n *   thread has no lane yet (version 0), where the next send carries plan mode.\n *   It stays pending so that a lane an EARLIER send seeds is corrected once it\n *   lands.\n * - `done`: the lane already plans that way (this client's own unacknowledged\n *   writes folded over); nothing to write.\n * - `patch`: issue one `config/patch` carrying the exclusion lists that change,\n *   computed from the lane's own, so a name another client excluded stays.\n */\nexport type PlanModeLaneDecision =\n  | { kind: 'wait' }\n  | { kind: 'done' }\n  | { kind: 'patch'; patch: ThreadConfigPatch };\n\nexport function decidePlanModeLanePatch({\n  planMode,\n  landed,\n  configVersion,\n  custom,\n}: {\n  /** The provider's `planMode` after the change. */\n  planMode: boolean;\n  landed: boolean;\n  configVersion: number;\n  /** The effective lane: the server config with this client's pending writes folded over. */\n  custom: ThreadConfigCustom;\n}): PlanModeLaneDecision {\n  if (!landed || configVersion <= 0) return { kind: 'wait' };\n  const patch = planModeListEdits({ custom, planMode });\n  return Object.keys(patch).length === 0 ? { kind: 'done' } : { kind: 'patch', patch };\n}\n"],"names":[],"mappings":"AAeO,MAAM,iBAAiB;AAGvB,MAAM,uBAAuB;AAEpC,MAAM,iBAAiB;AACvB,MAAM,sBAAsB;AAG5B,MAAM,uBAAuB;AAAA,EAC3B,EAAE,KAAK,gBAAgB,MAAM,eAAA;AAAA,EAC7B,EAAE,KAAK,qBAAqB,MAAM,qBAAA;AACpC;AAEA,MAAM,cAAc,CAAC,UACnB,MAAM,QAAQ,KAAK,IAAI,MAAM,OAAO,CAAC,SAAyB,OAAO,SAAS,QAAQ,IAAI,CAAA;AAGrF,SAAS,WAAW,QAAqC;AAC9D,SAAO,qBAAqB,MAAM,CAAC,EAAE,KAAK,KAAA,MAAW,CAAC,YAAY,OAAO,GAAG,CAAC,EAAE,SAAS,IAAI,CAAC;AAC/F;AAWO,SAAS,kBAAkB;AAAA,EAChC;AAAA,EACA;AACF,GAGsB;AACpB,QAAM,QAA2B,CAAA;AACjC,MAAI,WAAW,MAAM,MAAM,SAAU,QAAO;AAC5C,aAAW,EAAE,KAAK,KAAA,KAAU,sBAAsB;AAChD,UAAM,QAAQ,YAAY,OAAO,GAAG,CAAC;AACrC,UAAM,WAAW,MAAM,SAAS,IAAI;AACpC,QAAI,YAAY,UAAU;AACxB,YAAM,OAAO,MAAM,OAAO,CAAC,SAAS,SAAS,IAAI;AACjD,YAAM,GAAG,IAAI,KAAK,SAAS,IAAI,OAAO;AAAA,IACxC,WAAW,CAAC,YAAY,CAAC,UAAU;AACjC,YAAM,GAAG,IAAI,CAAC,GAAG,OAAO,IAAI;AAAA,IAC9B;AAAA,EACF;AACA,SAAO;AACT;AAOO,SAAS,aAAa;AAAA,EAC3B;AAAA,EACA;AACF,GAG4B;AAC1B,MAAI,aAAa,OAAW,QAAO;AACnC,QAAM,QAAQ,kBAAkB,EAAE,QAAQ,UAAU;AACpD,MAAI,OAAO,KAAK,KAAK,EAAE,WAAW,EAAG,QAAO;AAC5C,QAAM,OAAgC,EAAE,GAAG,OAAA;AAC3C,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,KAAK,GAAG;AAChD,QAAI,UAAU,KAAM,QAAO,KAAK,GAAG;AAAA,QAC9B,MAAK,GAAG,IAAI;AAAA,EACnB;AACA,SAAO;AACT;AAqBO,SAAS,uBAAuB;AAAA,EACrC;AAAA,EACA;AACF,GAGyB;AACvB,MAAI,CAAC,SAAS,SAAS,KAAM,QAAO,EAAE,UAAU,MAAM,YAAY,OAAO,MAAA;AACzE,SAAO,EAAE,UAAU,WAAW,KAAK,MAAM,GAAG,YAAY,MAAM,MAAA;AAChE;AAoBO,SAAS,wBAAwB;AAAA,EACtC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAOyB;AACvB,MAAI,CAAC,UAAU,iBAAiB,EAAG,QAAO,EAAE,MAAM,OAAA;AAClD,QAAM,QAAQ,kBAAkB,EAAE,QAAQ,UAAU;AACpD,SAAO,OAAO,KAAK,KAAK,EAAE,WAAW,IAAI,EAAE,MAAM,OAAA,IAAW,EAAE,MAAM,SAAS,MAAA;AAC/E;"}

package/dist/runtime/statewire-run-config.cjs

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const statewirePlanMode = require("./statewire-plan-mode.cjs");
 const DEEP_AGENT_RUNTIME_MARKER = "athena_deep_agent";
 const STATEWIRE_START_CHANNEL = "web";
 const STATEWIRE_RUN_LABEL = "Athena SDK";
@@ -54,7 +55,7 @@ function buildStatewireRunConfig(options = {}) {
     /* @__PURE__ */ new Set([...options.tools ?? [], ...options.frontendToolIds ?? []])
   );
   const systemPrompt = ((_c = options.systemPrompt) == null ? void 0 : _c.trim()) ?? "";
-  return {
+  const built = {
     custom: {
       runtime: DEEP_AGENT_RUNTIME_MARKER,
       // With a collab channel selected, omit the SDK's own 'web' stamp: the
@@ -88,6 +89,7 @@ function buildStatewireRunConfig(options = {}) {
       ...options.extraRunConfig ?? {}
     }
   };
+  return { custom: statewirePlanMode.withPlanMode({ custom: built.custom, planMode: options.planMode }) };
 }
 exports.COLLAB_AGENT_REF_PREFIX = COLLAB_AGENT_REF_PREFIX;
 exports.COLLAB_AGENT_REF_SHAPE = COLLAB_AGENT_REF_SHAPE;

package/dist/runtime/statewire-run-config.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"statewire-run-config.cjs","sources":["../../src/runtime/statewire-run-config.ts"],"sourcesContent":["/** Runtime marker the deep-agent session substrate stamps on sessions. */\nconst DEEP_AGENT_RUNTIME_MARKER = 'athena_deep_agent';\n\n/** Session-origin channel. The backend clamps unknown values to 'web', which\n *  is how every SDK-started session has always classified. */\n/** The start channel every run this SDK starts is stamped with (unless a collab channel decides). */\nexport const STATEWIRE_START_CHANNEL = 'web';\n\n/** Session label persisted in the thread's panel config (mirrors\n *  'Athena Chrome' / 'Athena mobile' in the sibling statewire hosts). */\nconst STATEWIRE_RUN_LABEL = 'Athena SDK';\n\n/** Deep-agent default model — matches the Olympus and mobile statewire hosts. */\nexport const DEFAULT_STATEWIRE_MODEL = 'claude-sonnet-5-5';\n\n/** Agent-id namespace for collab agents (`collab_agent:<asset_id>`). */\nexport const COLLAB_AGENT_REF_PREFIX = 'collab_agent:';\n\n/** The only shape the `agent` prop accepts, for error messages and docs. */\nexport const COLLAB_AGENT_REF_SHAPE = 'collab_agent:<asset_id>';\n\n/** The asset id when `agent` is a `collab_agent:<asset_id>` ref, else null. */\nexport function parseCollabAgentRef(agent: string | undefined | null): string | null {\n  if (typeof agent !== 'string' || !agent.startsWith(COLLAB_AGENT_REF_PREFIX)) return null;\n  const assetId = agent.slice(COLLAB_AGENT_REF_PREFIX.length).trim();\n  return assetId || null;\n}\n\n/**\n * Resolve the provider's `agent` prop to a collab-agent asset id.\n *\n * An omitted or blank `agent` means \"no agent selected\" — the thread runs the\n * Athena deep agent — and resolves to `null`. A `collab_agent:<asset_id>` ref\n * resolves to the asset id. Any other non-blank value throws: the statewire\n * host cannot honour it, and a selector that is silently dropped would let a\n * misconfigured deployment ship answers from the wrong agent.\n */\nexport function resolveAgentProp({ agent }: { agent: string | undefined | null }): string | null {\n  if (agent === undefined || agent === null || agent.trim() === '') return null;\n  const assetId = parseCollabAgentRef(agent.trim());\n  if (assetId) return assetId;\n  throw new Error(\n    `[AthenaSDK] Unsupported \\`agent\\` prop ${JSON.stringify(agent)}. The only accepted shape is '${COLLAB_AGENT_REF_SHAPE}' (the asset id of a published collab agent). Named agents are not supported — the statewire host always runs the Athena deep agent; omit \\`agent\\` to use it.`,\n  );\n}\n\nexport interface StatewireRunConfigOptions {\n  /** LLM model identifier. Defaults to the deep-agent default model — unless a\n   *  collab agent is selected and its author set one (the backend overlay\n   *  applies the agent's model when the run sends none), in which case no\n   *  model is sent so the agent's choice wins. */\n  model?: string;\n  /** Agent selector. Only the `collab_agent:<asset_id>` shape is accepted: the\n   *  run executes AS that published collab agent (prompt, tools, model\n   *  default). Any other non-empty value throws (see {@link resolveAgentProp}). */\n  agent?: string;\n  /** Collab-agent channel id (built-in like `email`/`sms`, or a user-defined\n   *  custom channel id) selecting that channel's configuration overrides.\n   *  Sent as `collab_channel_id`; only meaningful with a collab `agent`. */\n  channel?: string;\n  /** The agent's mode this send runs in, picked from the chat's mode menu\n   *  (`AthenaProvider` `modes`): `base` or a mode's id. Sent as\n   *  `collab_channel_id` in place of `channel`, which then rides as\n   *  `collab_entry_channel_id` so a session the pick starts still enters\n   *  through the channel (its switch list, lock and thread list). Only\n   *  meaningful with a collab `agent`. */\n  mode?: string;\n  /** Backend toolkit IDs to enable. */\n  tools?: string[];\n  /** Frontend tool IDs to include in enabled_tools. */\n  frontendToolIds?: string[];\n  /** Asset IDs to include in the workbench. */\n  workbench?: string[];\n  /** Knowledge base IDs for RAG context. */\n  knowledgeBase?: string[];\n  /** System prompt override. */\n  systemPrompt?: string;\n  /** Client app identifier, passed through as app_id. */\n  appId?: string;\n  /** Client-executed tool declarations, passed through as client_tools. The\n   *  deep-agent runtime binds each as an interrupt-backed tool the client\n   *  answers via the statewire client-tool bridge. */\n  clientTools?: Record<string, unknown>[];\n  /** Additional fields merged into runConfig.custom. */\n  extraRunConfig?: Record<string, unknown>;\n}\n\n/**\n * The model a send carries for the host's `model` and `extraRunConfig`, with\n * the precedence {@link buildStatewireRunConfig} applies: `extraRunConfig` is\n * merged last, so its `model` key (when it has one) wins over the `model`\n * prop. `undefined` when the send carries no explicit model.\n */\nexport function effectiveStatewireModel({\n  model,\n  extraRunConfig,\n}: {\n  model: string | undefined;\n  extraRunConfig: Record<string, unknown> | undefined;\n}): string | undefined {\n  if (extraRunConfig !== undefined && Object.hasOwn(extraRunConfig, 'model')) {\n    const override = extraRunConfig.model;\n    return typeof override === 'string' && override !== '' ? override : undefined;\n  }\n  return model === '' ? undefined : model;\n}\n\n/**\n * The `start_channel` a send stamps on its run, with the precedence\n * {@link buildStatewireRunConfig} applies: the host's\n * `extraRunConfig.start_channel` wins; a selected collab channel (or mode)\n * stamps nothing, so the backend stamps that channel's own kind; otherwise the\n * SDK's own {@link STATEWIRE_START_CHANNEL}. `null` when the backend decides,\n * since the provenance is then unknown until the server reports the session.\n */\nexport function effectiveStatewireStartChannel({\n  agent,\n  channel,\n  mode,\n  extraRunConfig,\n}: Pick<StatewireRunConfigOptions, 'agent' | 'channel' | 'mode' | 'extraRunConfig'>): string | null {\n  if (extraRunConfig !== undefined && Object.hasOwn(extraRunConfig, 'start_channel')) {\n    const override = extraRunConfig.start_channel;\n    return typeof override === 'string' && override.trim() !== '' ? override : null;\n  }\n  // The non-throwing parse: an agent prop of another shape makes the runtime\n  // refuse to start (`resolveAgentProp`), so nothing is sent to stamp.\n  const collabChannelSelected =\n    parseCollabAgentRef(agent?.trim()) !== null && Boolean(mode?.trim() || channel?.trim());\n  return collabChannelSelected ? null : STATEWIRE_START_CHANNEL;\n}\n\n/**\n * Build the `runConfig` a deep-agent statewire run is driven by. Commands\n * travel bare on the statewire channel, so this payload rides the ambient\n * model context (`config.runConfig`) instead of the request body.\n *\n * The flattened `custom` fields drive the run, while `panel_config` carries a\n * minimal panel state the backend persists per thread and replays on the\n * statewire snapshot — so a session started from the SDK stays configured\n * when reopened elsewhere.\n */\nexport function buildStatewireRunConfig(\n  options: StatewireRunConfigOptions = {},\n): Record<string, unknown> {\n  const collabAgentId = resolveAgentProp({ agent: options.agent });\n  const channel = collabAgentId ? options.channel?.trim() || undefined : undefined;\n  const mode = collabAgentId ? options.mode?.trim() || undefined : undefined;\n  const collabChannelId = mode ?? channel;\n  const collabEntryChannelId = mode && channel && mode !== channel ? channel : undefined;\n  // With a collab agent selected and no explicit model, send NO model: the\n  // backend overlay then applies the model the agent's author configured\n  // instead of the SDK default overriding it.\n  const model = options.model ?? (collabAgentId ? undefined : DEFAULT_STATEWIRE_MODEL);\n  const enabledTools = Array.from(\n    new Set([...(options.tools ?? []), ...(options.frontendToolIds ?? [])]),\n  );\n  const systemPrompt = options.systemPrompt?.trim() ?? '';\n\n  return {\n    custom: {\n      runtime: DEEP_AGENT_RUNTIME_MARKER,\n      // With a collab channel selected, omit the SDK's own 'web' stamp: the\n      // request's explicit start_channel would win over the backend overlay's\n      // kind-mapped provenance (a custom SMS channel must stamp 'sms').\n      ...(collabChannelId ? {} : { start_channel: STATEWIRE_START_CHANNEL }),\n      ...(model ? { model } : {}),\n      // An empty list is behavior-identical to an absent key for the parser\n      // (both coerce to []), but the collab-agent overlay merges request keys\n      // OVER the agent definition — so an explicit empty list would erase the\n      // agent's configured tools. Omit it when empty.\n      ...(enabledTools.length > 0 ? { enabled_tools: enabledTools } : {}),\n      panel_config: {\n        // A collab agent's thread with no explicit model names none here\n        // either: agora stores this panel on the thread's first run and\n        // replays it to every client, and a stored SDK default would show as\n        // the session's model while the agent's own model runs.\n        ...(model ? { model } : {}),\n        enabled_tools: enabledTools,\n        system_prompt: systemPrompt,\n        run_label: STATEWIRE_RUN_LABEL,\n      },\n      ...(collabAgentId ? { collab_agent_id: collabAgentId } : {}),\n      ...(collabChannelId ? { collab_channel_id: collabChannelId } : {}),\n      ...(collabEntryChannelId ? { collab_entry_channel_id: collabEntryChannelId } : {}),\n      ...(systemPrompt ? { system_prompt: systemPrompt } : {}),\n      ...(options.workbench?.length ? { workbench: options.workbench } : {}),\n      ...(options.knowledgeBase?.length\n        ? { knowledge_base: options.knowledgeBase }\n        : {}),\n      ...(options.appId ? { app_id: options.appId } : {}),\n      ...(options.clientTools?.length ? { client_tools: options.clientTools } : {}),\n      ...(options.extraRunConfig ?? {}),\n    },\n  };\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"statewire-run-config.cjs","sources":["../../src/runtime/statewire-run-config.ts"],"sourcesContent":["import { withPlanMode } from './statewire-plan-mode';\n\n/** Runtime marker the deep-agent session substrate stamps on sessions. */\nconst DEEP_AGENT_RUNTIME_MARKER = 'athena_deep_agent';\n\n/** Session-origin channel. The backend clamps unknown values to 'web', which\n *  is how every SDK-started session has always classified. */\n/** The start channel every run this SDK starts is stamped with (unless a collab channel decides). */\nexport const STATEWIRE_START_CHANNEL = 'web';\n\n/** Session label persisted in the thread's panel config (mirrors\n *  'Athena Chrome' / 'Athena mobile' in the sibling statewire hosts). */\nconst STATEWIRE_RUN_LABEL = 'Athena SDK';\n\n/** Deep-agent default model — matches the Olympus and mobile statewire hosts. */\nexport const DEFAULT_STATEWIRE_MODEL = 'claude-sonnet-5-5';\n\n/** Agent-id namespace for collab agents (`collab_agent:<asset_id>`). */\nexport const COLLAB_AGENT_REF_PREFIX = 'collab_agent:';\n\n/** The only shape the `agent` prop accepts, for error messages and docs. */\nexport const COLLAB_AGENT_REF_SHAPE = 'collab_agent:<asset_id>';\n\n/** The asset id when `agent` is a `collab_agent:<asset_id>` ref, else null. */\nexport function parseCollabAgentRef(agent: string | undefined | null): string | null {\n  if (typeof agent !== 'string' || !agent.startsWith(COLLAB_AGENT_REF_PREFIX)) return null;\n  const assetId = agent.slice(COLLAB_AGENT_REF_PREFIX.length).trim();\n  return assetId || null;\n}\n\n/**\n * Resolve the provider's `agent` prop to a collab-agent asset id.\n *\n * An omitted or blank `agent` means \"no agent selected\" — the thread runs the\n * Athena deep agent — and resolves to `null`. A `collab_agent:<asset_id>` ref\n * resolves to the asset id. Any other non-blank value throws: the statewire\n * host cannot honour it, and a selector that is silently dropped would let a\n * misconfigured deployment ship answers from the wrong agent.\n */\nexport function resolveAgentProp({ agent }: { agent: string | undefined | null }): string | null {\n  if (agent === undefined || agent === null || agent.trim() === '') return null;\n  const assetId = parseCollabAgentRef(agent.trim());\n  if (assetId) return assetId;\n  throw new Error(\n    `[AthenaSDK] Unsupported \\`agent\\` prop ${JSON.stringify(agent)}. The only accepted shape is '${COLLAB_AGENT_REF_SHAPE}' (the asset id of a published collab agent). Named agents are not supported — the statewire host always runs the Athena deep agent; omit \\`agent\\` to use it.`,\n  );\n}\n\nexport interface StatewireRunConfigOptions {\n  /** LLM model identifier. Defaults to the deep-agent default model — unless a\n   *  collab agent is selected and its author set one (the backend overlay\n   *  applies the agent's model when the run sends none), in which case no\n   *  model is sent so the agent's choice wins. */\n  model?: string;\n  /** Agent selector. Only the `collab_agent:<asset_id>` shape is accepted: the\n   *  run executes AS that published collab agent (prompt, tools, model\n   *  default). Any other non-empty value throws (see {@link resolveAgentProp}). */\n  agent?: string;\n  /** Collab-agent channel id (built-in like `email`/`sms`, or a user-defined\n   *  custom channel id) selecting that channel's configuration overrides.\n   *  Sent as `collab_channel_id`; only meaningful with a collab `agent`. */\n  channel?: string;\n  /** The agent's mode this send runs in, picked from the chat's mode menu\n   *  (`AthenaProvider` `modes`): `base` or a mode's id. Sent as\n   *  `collab_channel_id` in place of `channel`, which then rides as\n   *  `collab_entry_channel_id` so a session the pick starts still enters\n   *  through the channel (its switch list, lock and thread list). Only\n   *  meaningful with a collab `agent`. */\n  mode?: string;\n  /** Backend toolkit IDs to enable. */\n  tools?: string[];\n  /** Frontend tool IDs to include in enabled_tools. */\n  frontendToolIds?: string[];\n  /** Asset IDs to include in the workbench. */\n  workbench?: string[];\n  /** Knowledge base IDs for RAG context. */\n  knowledgeBase?: string[];\n  /** System prompt override. */\n  systemPrompt?: string;\n  /** Client app identifier, passed through as app_id. */\n  appId?: string;\n  /** Client-executed tool declarations, passed through as client_tools. The\n   *  deep-agent runtime binds each as an interrupt-backed tool the client\n   *  answers via the statewire client-tool bridge. */\n  clientTools?: Record<string, unknown>[];\n  /** Additional fields merged into runConfig.custom. */\n  extraRunConfig?: Record<string, unknown>;\n  /**\n   * Plan mode (`AthenaProviderProps.planMode`), applied last: `false` adds\n   * `write_todos` and `TodoListMiddleware` to the exclusion lists, after\n   * anything `extraRunConfig` excludes; `true` takes them out; `undefined`\n   * leaves the lists as they are.\n   */\n  planMode?: boolean;\n}\n\n/**\n * The model a send carries for the host's `model` and `extraRunConfig`, with\n * the precedence {@link buildStatewireRunConfig} applies: `extraRunConfig` is\n * merged last, so its `model` key (when it has one) wins over the `model`\n * prop. `undefined` when the send carries no explicit model.\n */\nexport function effectiveStatewireModel({\n  model,\n  extraRunConfig,\n}: {\n  model: string | undefined;\n  extraRunConfig: Record<string, unknown> | undefined;\n}): string | undefined {\n  if (extraRunConfig !== undefined && Object.hasOwn(extraRunConfig, 'model')) {\n    const override = extraRunConfig.model;\n    return typeof override === 'string' && override !== '' ? override : undefined;\n  }\n  return model === '' ? undefined : model;\n}\n\n/**\n * The `start_channel` a send stamps on its run, with the precedence\n * {@link buildStatewireRunConfig} applies: the host's\n * `extraRunConfig.start_channel` wins; a selected collab channel (or mode)\n * stamps nothing, so the backend stamps that channel's own kind; otherwise the\n * SDK's own {@link STATEWIRE_START_CHANNEL}. `null` when the backend decides,\n * since the provenance is then unknown until the server reports the session.\n */\nexport function effectiveStatewireStartChannel({\n  agent,\n  channel,\n  mode,\n  extraRunConfig,\n}: Pick<StatewireRunConfigOptions, 'agent' | 'channel' | 'mode' | 'extraRunConfig'>): string | null {\n  if (extraRunConfig !== undefined && Object.hasOwn(extraRunConfig, 'start_channel')) {\n    const override = extraRunConfig.start_channel;\n    return typeof override === 'string' && override.trim() !== '' ? override : null;\n  }\n  // The non-throwing parse: an agent prop of another shape makes the runtime\n  // refuse to start (`resolveAgentProp`), so nothing is sent to stamp.\n  const collabChannelSelected =\n    parseCollabAgentRef(agent?.trim()) !== null && Boolean(mode?.trim() || channel?.trim());\n  return collabChannelSelected ? null : STATEWIRE_START_CHANNEL;\n}\n\n/**\n * Build the `runConfig` a deep-agent statewire run is driven by. Commands\n * travel bare on the statewire channel, so this payload rides the ambient\n * model context (`config.runConfig`) instead of the request body.\n *\n * The flattened `custom` fields drive the run, while `panel_config` carries a\n * minimal panel state the backend persists per thread and replays on the\n * statewire snapshot — so a session started from the SDK stays configured\n * when reopened elsewhere.\n */\nexport function buildStatewireRunConfig(\n  options: StatewireRunConfigOptions = {},\n): Record<string, unknown> {\n  const collabAgentId = resolveAgentProp({ agent: options.agent });\n  const channel = collabAgentId ? options.channel?.trim() || undefined : undefined;\n  const mode = collabAgentId ? options.mode?.trim() || undefined : undefined;\n  const collabChannelId = mode ?? channel;\n  const collabEntryChannelId = mode && channel && mode !== channel ? channel : undefined;\n  // With a collab agent selected and no explicit model, send NO model: the\n  // backend overlay then applies the model the agent's author configured\n  // instead of the SDK default overriding it.\n  const model = options.model ?? (collabAgentId ? undefined : DEFAULT_STATEWIRE_MODEL);\n  const enabledTools = Array.from(\n    new Set([...(options.tools ?? []), ...(options.frontendToolIds ?? [])]),\n  );\n  const systemPrompt = options.systemPrompt?.trim() ?? '';\n\n  const built: { custom: Record<string, unknown> } = {\n    custom: {\n      runtime: DEEP_AGENT_RUNTIME_MARKER,\n      // With a collab channel selected, omit the SDK's own 'web' stamp: the\n      // request's explicit start_channel would win over the backend overlay's\n      // kind-mapped provenance (a custom SMS channel must stamp 'sms').\n      ...(collabChannelId ? {} : { start_channel: STATEWIRE_START_CHANNEL }),\n      ...(model ? { model } : {}),\n      // An empty list is behavior-identical to an absent key for the parser\n      // (both coerce to []), but the collab-agent overlay merges request keys\n      // OVER the agent definition — so an explicit empty list would erase the\n      // agent's configured tools. Omit it when empty.\n      ...(enabledTools.length > 0 ? { enabled_tools: enabledTools } : {}),\n      panel_config: {\n        // A collab agent's thread with no explicit model names none here\n        // either: agora stores this panel on the thread's first run and\n        // replays it to every client, and a stored SDK default would show as\n        // the session's model while the agent's own model runs.\n        ...(model ? { model } : {}),\n        enabled_tools: enabledTools,\n        system_prompt: systemPrompt,\n        run_label: STATEWIRE_RUN_LABEL,\n      },\n      ...(collabAgentId ? { collab_agent_id: collabAgentId } : {}),\n      ...(collabChannelId ? { collab_channel_id: collabChannelId } : {}),\n      ...(collabEntryChannelId ? { collab_entry_channel_id: collabEntryChannelId } : {}),\n      ...(systemPrompt ? { system_prompt: systemPrompt } : {}),\n      ...(options.workbench?.length ? { workbench: options.workbench } : {}),\n      ...(options.knowledgeBase?.length\n        ? { knowledge_base: options.knowledgeBase }\n        : {}),\n      ...(options.appId ? { app_id: options.appId } : {}),\n      ...(options.clientTools?.length ? { client_tools: options.clientTools } : {}),\n      ...(options.extraRunConfig ?? {}),\n    },\n  };\n  // Plan mode edits the exclusion lists last, so it composes with an\n  // `extraRunConfig` that excludes other tools or middleware.\n  return { custom: withPlanMode({ custom: built.custom, planMode: options.planMode }) };\n}\n"],"names":["withPlanMode"],"mappings":"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"}

package/dist/runtime/statewire-run-config.d.ts

@@ -61,6 +61,13 @@ export interface StatewireRunConfigOptions {
     clientTools?: Record<string, unknown>[];
     /** Additional fields merged into runConfig.custom. */
     extraRunConfig?: Record<string, unknown>;
+    /**
+     * Plan mode (`AthenaProviderProps.planMode`), applied last: `false` adds
+     * `write_todos` and `TodoListMiddleware` to the exclusion lists, after
+     * anything `extraRunConfig` excludes; `true` takes them out; `undefined`
+     * leaves the lists as they are.
+     */
+    planMode?: boolean;
 }
 /**
  * The model a send carries for the host's `model` and `extraRunConfig`, with

package/dist/runtime/statewire-run-config.js

@@ -1,3 +1,4 @@
+import { withPlanMode } from "./statewire-plan-mode.js";
 const DEEP_AGENT_RUNTIME_MARKER = "athena_deep_agent";
 const STATEWIRE_START_CHANNEL = "web";
 const STATEWIRE_RUN_LABEL = "Athena SDK";
@@ -52,7 +53,7 @@ function buildStatewireRunConfig(options = {}) {
     /* @__PURE__ */ new Set([...options.tools ?? [], ...options.frontendToolIds ?? []])
   );
   const systemPrompt = ((_c = options.systemPrompt) == null ? void 0 : _c.trim()) ?? "";
-  return {
+  const built = {
     custom: {
       runtime: DEEP_AGENT_RUNTIME_MARKER,
       // With a collab channel selected, omit the SDK's own 'web' stamp: the
@@ -86,6 +87,7 @@ function buildStatewireRunConfig(options = {}) {
       ...options.extraRunConfig ?? {}
     }
   };
+  return { custom: withPlanMode({ custom: built.custom, planMode: options.planMode }) };
 }
 export {
   COLLAB_AGENT_REF_PREFIX,

package/dist/runtime/statewire-run-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"statewire-run-config.js","sources":["../../src/runtime/statewire-run-config.ts"],"sourcesContent":["/** Runtime marker the deep-agent session substrate stamps on sessions. */\nconst DEEP_AGENT_RUNTIME_MARKER = 'athena_deep_agent';\n\n/** Session-origin channel. The backend clamps unknown values to 'web', which\n *  is how every SDK-started session has always classified. */\n/** The start channel every run this SDK starts is stamped with (unless a collab channel decides). */\nexport const STATEWIRE_START_CHANNEL = 'web';\n\n/** Session label persisted in the thread's panel config (mirrors\n *  'Athena Chrome' / 'Athena mobile' in the sibling statewire hosts). */\nconst STATEWIRE_RUN_LABEL = 'Athena SDK';\n\n/** Deep-agent default model — matches the Olympus and mobile statewire hosts. */\nexport const DEFAULT_STATEWIRE_MODEL = 'claude-sonnet-5-5';\n\n/** Agent-id namespace for collab agents (`collab_agent:<asset_id>`). */\nexport const COLLAB_AGENT_REF_PREFIX = 'collab_agent:';\n\n/** The only shape the `agent` prop accepts, for error messages and docs. */\nexport const COLLAB_AGENT_REF_SHAPE = 'collab_agent:<asset_id>';\n\n/** The asset id when `agent` is a `collab_agent:<asset_id>` ref, else null. */\nexport function parseCollabAgentRef(agent: string | undefined | null): string | null {\n  if (typeof agent !== 'string' || !agent.startsWith(COLLAB_AGENT_REF_PREFIX)) return null;\n  const assetId = agent.slice(COLLAB_AGENT_REF_PREFIX.length).trim();\n  return assetId || null;\n}\n\n/**\n * Resolve the provider's `agent` prop to a collab-agent asset id.\n *\n * An omitted or blank `agent` means \"no agent selected\" — the thread runs the\n * Athena deep agent — and resolves to `null`. A `collab_agent:<asset_id>` ref\n * resolves to the asset id. Any other non-blank value throws: the statewire\n * host cannot honour it, and a selector that is silently dropped would let a\n * misconfigured deployment ship answers from the wrong agent.\n */\nexport function resolveAgentProp({ agent }: { agent: string | undefined | null }): string | null {\n  if (agent === undefined || agent === null || agent.trim() === '') return null;\n  const assetId = parseCollabAgentRef(agent.trim());\n  if (assetId) return assetId;\n  throw new Error(\n    `[AthenaSDK] Unsupported \\`agent\\` prop ${JSON.stringify(agent)}. The only accepted shape is '${COLLAB_AGENT_REF_SHAPE}' (the asset id of a published collab agent). Named agents are not supported — the statewire host always runs the Athena deep agent; omit \\`agent\\` to use it.`,\n  );\n}\n\nexport interface StatewireRunConfigOptions {\n  /** LLM model identifier. Defaults to the deep-agent default model — unless a\n   *  collab agent is selected and its author set one (the backend overlay\n   *  applies the agent's model when the run sends none), in which case no\n   *  model is sent so the agent's choice wins. */\n  model?: string;\n  /** Agent selector. Only the `collab_agent:<asset_id>` shape is accepted: the\n   *  run executes AS that published collab agent (prompt, tools, model\n   *  default). Any other non-empty value throws (see {@link resolveAgentProp}). */\n  agent?: string;\n  /** Collab-agent channel id (built-in like `email`/`sms`, or a user-defined\n   *  custom channel id) selecting that channel's configuration overrides.\n   *  Sent as `collab_channel_id`; only meaningful with a collab `agent`. */\n  channel?: string;\n  /** The agent's mode this send runs in, picked from the chat's mode menu\n   *  (`AthenaProvider` `modes`): `base` or a mode's id. Sent as\n   *  `collab_channel_id` in place of `channel`, which then rides as\n   *  `collab_entry_channel_id` so a session the pick starts still enters\n   *  through the channel (its switch list, lock and thread list). Only\n   *  meaningful with a collab `agent`. */\n  mode?: string;\n  /** Backend toolkit IDs to enable. */\n  tools?: string[];\n  /** Frontend tool IDs to include in enabled_tools. */\n  frontendToolIds?: string[];\n  /** Asset IDs to include in the workbench. */\n  workbench?: string[];\n  /** Knowledge base IDs for RAG context. */\n  knowledgeBase?: string[];\n  /** System prompt override. */\n  systemPrompt?: string;\n  /** Client app identifier, passed through as app_id. */\n  appId?: string;\n  /** Client-executed tool declarations, passed through as client_tools. The\n   *  deep-agent runtime binds each as an interrupt-backed tool the client\n   *  answers via the statewire client-tool bridge. */\n  clientTools?: Record<string, unknown>[];\n  /** Additional fields merged into runConfig.custom. */\n  extraRunConfig?: Record<string, unknown>;\n}\n\n/**\n * The model a send carries for the host's `model` and `extraRunConfig`, with\n * the precedence {@link buildStatewireRunConfig} applies: `extraRunConfig` is\n * merged last, so its `model` key (when it has one) wins over the `model`\n * prop. `undefined` when the send carries no explicit model.\n */\nexport function effectiveStatewireModel({\n  model,\n  extraRunConfig,\n}: {\n  model: string | undefined;\n  extraRunConfig: Record<string, unknown> | undefined;\n}): string | undefined {\n  if (extraRunConfig !== undefined && Object.hasOwn(extraRunConfig, 'model')) {\n    const override = extraRunConfig.model;\n    return typeof override === 'string' && override !== '' ? override : undefined;\n  }\n  return model === '' ? undefined : model;\n}\n\n/**\n * The `start_channel` a send stamps on its run, with the precedence\n * {@link buildStatewireRunConfig} applies: the host's\n * `extraRunConfig.start_channel` wins; a selected collab channel (or mode)\n * stamps nothing, so the backend stamps that channel's own kind; otherwise the\n * SDK's own {@link STATEWIRE_START_CHANNEL}. `null` when the backend decides,\n * since the provenance is then unknown until the server reports the session.\n */\nexport function effectiveStatewireStartChannel({\n  agent,\n  channel,\n  mode,\n  extraRunConfig,\n}: Pick<StatewireRunConfigOptions, 'agent' | 'channel' | 'mode' | 'extraRunConfig'>): string | null {\n  if (extraRunConfig !== undefined && Object.hasOwn(extraRunConfig, 'start_channel')) {\n    const override = extraRunConfig.start_channel;\n    return typeof override === 'string' && override.trim() !== '' ? override : null;\n  }\n  // The non-throwing parse: an agent prop of another shape makes the runtime\n  // refuse to start (`resolveAgentProp`), so nothing is sent to stamp.\n  const collabChannelSelected =\n    parseCollabAgentRef(agent?.trim()) !== null && Boolean(mode?.trim() || channel?.trim());\n  return collabChannelSelected ? null : STATEWIRE_START_CHANNEL;\n}\n\n/**\n * Build the `runConfig` a deep-agent statewire run is driven by. Commands\n * travel bare on the statewire channel, so this payload rides the ambient\n * model context (`config.runConfig`) instead of the request body.\n *\n * The flattened `custom` fields drive the run, while `panel_config` carries a\n * minimal panel state the backend persists per thread and replays on the\n * statewire snapshot — so a session started from the SDK stays configured\n * when reopened elsewhere.\n */\nexport function buildStatewireRunConfig(\n  options: StatewireRunConfigOptions = {},\n): Record<string, unknown> {\n  const collabAgentId = resolveAgentProp({ agent: options.agent });\n  const channel = collabAgentId ? options.channel?.trim() || undefined : undefined;\n  const mode = collabAgentId ? options.mode?.trim() || undefined : undefined;\n  const collabChannelId = mode ?? channel;\n  const collabEntryChannelId = mode && channel && mode !== channel ? channel : undefined;\n  // With a collab agent selected and no explicit model, send NO model: the\n  // backend overlay then applies the model the agent's author configured\n  // instead of the SDK default overriding it.\n  const model = options.model ?? (collabAgentId ? undefined : DEFAULT_STATEWIRE_MODEL);\n  const enabledTools = Array.from(\n    new Set([...(options.tools ?? []), ...(options.frontendToolIds ?? [])]),\n  );\n  const systemPrompt = options.systemPrompt?.trim() ?? '';\n\n  return {\n    custom: {\n      runtime: DEEP_AGENT_RUNTIME_MARKER,\n      // With a collab channel selected, omit the SDK's own 'web' stamp: the\n      // request's explicit start_channel would win over the backend overlay's\n      // kind-mapped provenance (a custom SMS channel must stamp 'sms').\n      ...(collabChannelId ? {} : { start_channel: STATEWIRE_START_CHANNEL }),\n      ...(model ? { model } : {}),\n      // An empty list is behavior-identical to an absent key for the parser\n      // (both coerce to []), but the collab-agent overlay merges request keys\n      // OVER the agent definition — so an explicit empty list would erase the\n      // agent's configured tools. Omit it when empty.\n      ...(enabledTools.length > 0 ? { enabled_tools: enabledTools } : {}),\n      panel_config: {\n        // A collab agent's thread with no explicit model names none here\n        // either: agora stores this panel on the thread's first run and\n        // replays it to every client, and a stored SDK default would show as\n        // the session's model while the agent's own model runs.\n        ...(model ? { model } : {}),\n        enabled_tools: enabledTools,\n        system_prompt: systemPrompt,\n        run_label: STATEWIRE_RUN_LABEL,\n      },\n      ...(collabAgentId ? { collab_agent_id: collabAgentId } : {}),\n      ...(collabChannelId ? { collab_channel_id: collabChannelId } : {}),\n      ...(collabEntryChannelId ? { collab_entry_channel_id: collabEntryChannelId } : {}),\n      ...(systemPrompt ? { system_prompt: systemPrompt } : {}),\n      ...(options.workbench?.length ? { workbench: options.workbench } : {}),\n      ...(options.knowledgeBase?.length\n        ? { knowledge_base: options.knowledgeBase }\n        : {}),\n      ...(options.appId ? { app_id: options.appId } : {}),\n      ...(options.clientTools?.length ? { client_tools: options.clientTools } : {}),\n      ...(options.extraRunConfig ?? {}),\n    },\n  };\n}\n"],"names":[],"mappings":"AACA,MAAM,4BAA4B;AAK3B,MAAM,0BAA0B;AAIvC,MAAM,sBAAsB;AAGrB,MAAM,0BAA0B;AAGhC,MAAM,0BAA0B;AAGhC,MAAM,yBAAyB;AAG/B,SAAS,oBAAoB,OAAiD;AACnF,MAAI,OAAO,UAAU,YAAY,CAAC,MAAM,WAAW,uBAAuB,EAAG,QAAO;AACpF,QAAM,UAAU,MAAM,MAAM,wBAAwB,MAAM,EAAE,KAAA;AAC5D,SAAO,WAAW;AACpB;AAWO,SAAS,iBAAiB,EAAE,SAA8D;AAC/F,MAAI,UAAU,UAAa,UAAU,QAAQ,MAAM,KAAA,MAAW,GAAI,QAAO;AACzE,QAAM,UAAU,oBAAoB,MAAM,KAAA,CAAM;AAChD,MAAI,QAAS,QAAO;AACpB,QAAM,IAAI;AAAA,IACR,0CAA0C,KAAK,UAAU,KAAK,CAAC,iCAAiC,sBAAsB;AAAA,EAAA;AAE1H;AAiDO,SAAS,wBAAwB;AAAA,EACtC;AAAA,EACA;AACF,GAGuB;AACrB,MAAI,mBAAmB,UAAa,OAAO,OAAO,gBAAgB,OAAO,GAAG;AAC1E,UAAM,WAAW,eAAe;AAChC,WAAO,OAAO,aAAa,YAAY,aAAa,KAAK,WAAW;AAAA,EACtE;AACA,SAAO,UAAU,KAAK,SAAY;AACpC;AAUO,SAAS,+BAA+B;AAAA,EAC7C;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAAoG;AAClG,MAAI,mBAAmB,UAAa,OAAO,OAAO,gBAAgB,eAAe,GAAG;AAClF,UAAM,WAAW,eAAe;AAChC,WAAO,OAAO,aAAa,YAAY,SAAS,WAAW,KAAK,WAAW;AAAA,EAC7E;AAGA,QAAM,wBACJ,oBAAoB,+BAAO,MAAM,MAAM,QAAQ,SAAQ,6BAAM,YAAU,mCAAS,OAAM;AACxF,SAAO,wBAAwB,OAAO;AACxC;AAYO,SAAS,wBACd,UAAqC,IACZ;AA/I3B;AAgJE,QAAM,gBAAgB,iBAAiB,EAAE,OAAO,QAAQ,OAAO;AAC/D,QAAM,UAAU,kBAAgB,aAAQ,YAAR,mBAAiB,WAAU,SAAY;AACvE,QAAM,OAAO,kBAAgB,aAAQ,SAAR,mBAAc,WAAU,SAAY;AACjE,QAAM,kBAAkB,QAAQ;AAChC,QAAM,uBAAuB,QAAQ,WAAW,SAAS,UAAU,UAAU;AAI7E,QAAM,QAAQ,QAAQ,UAAU,gBAAgB,SAAY;AAC5D,QAAM,eAAe,MAAM;AAAA,IACzB,oBAAI,IAAI,CAAC,GAAI,QAAQ,SAAS,CAAA,GAAK,GAAI,QAAQ,mBAAmB,EAAG,CAAC;AAAA,EAAA;AAExE,QAAM,iBAAe,aAAQ,iBAAR,mBAAsB,WAAU;AAErD,SAAO;AAAA,IACL,QAAQ;AAAA,MACN,SAAS;AAAA;AAAA;AAAA;AAAA,MAIT,GAAI,kBAAkB,CAAA,IAAK,EAAE,eAAe,wBAAA;AAAA,MAC5C,GAAI,QAAQ,EAAE,MAAA,IAAU,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA,MAKxB,GAAI,aAAa,SAAS,IAAI,EAAE,eAAe,aAAA,IAAiB,CAAA;AAAA,MAChE,cAAc;AAAA;AAAA;AAAA;AAAA;AAAA,QAKZ,GAAI,QAAQ,EAAE,MAAA,IAAU,CAAA;AAAA,QACxB,eAAe;AAAA,QACf,eAAe;AAAA,QACf,WAAW;AAAA,MAAA;AAAA,MAEb,GAAI,gBAAgB,EAAE,iBAAiB,cAAA,IAAkB,CAAA;AAAA,MACzD,GAAI,kBAAkB,EAAE,mBAAmB,gBAAA,IAAoB,CAAA;AAAA,MAC/D,GAAI,uBAAuB,EAAE,yBAAyB,qBAAA,IAAyB,CAAA;AAAA,MAC/E,GAAI,eAAe,EAAE,eAAe,aAAA,IAAiB,CAAA;AAAA,MACrD,KAAI,aAAQ,cAAR,mBAAmB,UAAS,EAAE,WAAW,QAAQ,UAAA,IAAc,CAAA;AAAA,MACnE,KAAI,aAAQ,kBAAR,mBAAuB,UACvB,EAAE,gBAAgB,QAAQ,cAAA,IAC1B,CAAA;AAAA,MACJ,GAAI,QAAQ,QAAQ,EAAE,QAAQ,QAAQ,MAAA,IAAU,CAAA;AAAA,MAChD,KAAI,aAAQ,gBAAR,mBAAqB,UAAS,EAAE,cAAc,QAAQ,YAAA,IAAgB,CAAA;AAAA,MAC1E,GAAI,QAAQ,kBAAkB,CAAA;AAAA,IAAC;AAAA,EACjC;AAEJ;"}
+{"version":3,"file":"statewire-run-config.js","sources":["../../src/runtime/statewire-run-config.ts"],"sourcesContent":["import { withPlanMode } from './statewire-plan-mode';\n\n/** Runtime marker the deep-agent session substrate stamps on sessions. */\nconst DEEP_AGENT_RUNTIME_MARKER = 'athena_deep_agent';\n\n/** Session-origin channel. The backend clamps unknown values to 'web', which\n *  is how every SDK-started session has always classified. */\n/** The start channel every run this SDK starts is stamped with (unless a collab channel decides). */\nexport const STATEWIRE_START_CHANNEL = 'web';\n\n/** Session label persisted in the thread's panel config (mirrors\n *  'Athena Chrome' / 'Athena mobile' in the sibling statewire hosts). */\nconst STATEWIRE_RUN_LABEL = 'Athena SDK';\n\n/** Deep-agent default model — matches the Olympus and mobile statewire hosts. */\nexport const DEFAULT_STATEWIRE_MODEL = 'claude-sonnet-5-5';\n\n/** Agent-id namespace for collab agents (`collab_agent:<asset_id>`). */\nexport const COLLAB_AGENT_REF_PREFIX = 'collab_agent:';\n\n/** The only shape the `agent` prop accepts, for error messages and docs. */\nexport const COLLAB_AGENT_REF_SHAPE = 'collab_agent:<asset_id>';\n\n/** The asset id when `agent` is a `collab_agent:<asset_id>` ref, else null. */\nexport function parseCollabAgentRef(agent: string | undefined | null): string | null {\n  if (typeof agent !== 'string' || !agent.startsWith(COLLAB_AGENT_REF_PREFIX)) return null;\n  const assetId = agent.slice(COLLAB_AGENT_REF_PREFIX.length).trim();\n  return assetId || null;\n}\n\n/**\n * Resolve the provider's `agent` prop to a collab-agent asset id.\n *\n * An omitted or blank `agent` means \"no agent selected\" — the thread runs the\n * Athena deep agent — and resolves to `null`. A `collab_agent:<asset_id>` ref\n * resolves to the asset id. Any other non-blank value throws: the statewire\n * host cannot honour it, and a selector that is silently dropped would let a\n * misconfigured deployment ship answers from the wrong agent.\n */\nexport function resolveAgentProp({ agent }: { agent: string | undefined | null }): string | null {\n  if (agent === undefined || agent === null || agent.trim() === '') return null;\n  const assetId = parseCollabAgentRef(agent.trim());\n  if (assetId) return assetId;\n  throw new Error(\n    `[AthenaSDK] Unsupported \\`agent\\` prop ${JSON.stringify(agent)}. The only accepted shape is '${COLLAB_AGENT_REF_SHAPE}' (the asset id of a published collab agent). Named agents are not supported — the statewire host always runs the Athena deep agent; omit \\`agent\\` to use it.`,\n  );\n}\n\nexport interface StatewireRunConfigOptions {\n  /** LLM model identifier. Defaults to the deep-agent default model — unless a\n   *  collab agent is selected and its author set one (the backend overlay\n   *  applies the agent's model when the run sends none), in which case no\n   *  model is sent so the agent's choice wins. */\n  model?: string;\n  /** Agent selector. Only the `collab_agent:<asset_id>` shape is accepted: the\n   *  run executes AS that published collab agent (prompt, tools, model\n   *  default). Any other non-empty value throws (see {@link resolveAgentProp}). */\n  agent?: string;\n  /** Collab-agent channel id (built-in like `email`/`sms`, or a user-defined\n   *  custom channel id) selecting that channel's configuration overrides.\n   *  Sent as `collab_channel_id`; only meaningful with a collab `agent`. */\n  channel?: string;\n  /** The agent's mode this send runs in, picked from the chat's mode menu\n   *  (`AthenaProvider` `modes`): `base` or a mode's id. Sent as\n   *  `collab_channel_id` in place of `channel`, which then rides as\n   *  `collab_entry_channel_id` so a session the pick starts still enters\n   *  through the channel (its switch list, lock and thread list). Only\n   *  meaningful with a collab `agent`. */\n  mode?: string;\n  /** Backend toolkit IDs to enable. */\n  tools?: string[];\n  /** Frontend tool IDs to include in enabled_tools. */\n  frontendToolIds?: string[];\n  /** Asset IDs to include in the workbench. */\n  workbench?: string[];\n  /** Knowledge base IDs for RAG context. */\n  knowledgeBase?: string[];\n  /** System prompt override. */\n  systemPrompt?: string;\n  /** Client app identifier, passed through as app_id. */\n  appId?: string;\n  /** Client-executed tool declarations, passed through as client_tools. The\n   *  deep-agent runtime binds each as an interrupt-backed tool the client\n   *  answers via the statewire client-tool bridge. */\n  clientTools?: Record<string, unknown>[];\n  /** Additional fields merged into runConfig.custom. */\n  extraRunConfig?: Record<string, unknown>;\n  /**\n   * Plan mode (`AthenaProviderProps.planMode`), applied last: `false` adds\n   * `write_todos` and `TodoListMiddleware` to the exclusion lists, after\n   * anything `extraRunConfig` excludes; `true` takes them out; `undefined`\n   * leaves the lists as they are.\n   */\n  planMode?: boolean;\n}\n\n/**\n * The model a send carries for the host's `model` and `extraRunConfig`, with\n * the precedence {@link buildStatewireRunConfig} applies: `extraRunConfig` is\n * merged last, so its `model` key (when it has one) wins over the `model`\n * prop. `undefined` when the send carries no explicit model.\n */\nexport function effectiveStatewireModel({\n  model,\n  extraRunConfig,\n}: {\n  model: string | undefined;\n  extraRunConfig: Record<string, unknown> | undefined;\n}): string | undefined {\n  if (extraRunConfig !== undefined && Object.hasOwn(extraRunConfig, 'model')) {\n    const override = extraRunConfig.model;\n    return typeof override === 'string' && override !== '' ? override : undefined;\n  }\n  return model === '' ? undefined : model;\n}\n\n/**\n * The `start_channel` a send stamps on its run, with the precedence\n * {@link buildStatewireRunConfig} applies: the host's\n * `extraRunConfig.start_channel` wins; a selected collab channel (or mode)\n * stamps nothing, so the backend stamps that channel's own kind; otherwise the\n * SDK's own {@link STATEWIRE_START_CHANNEL}. `null` when the backend decides,\n * since the provenance is then unknown until the server reports the session.\n */\nexport function effectiveStatewireStartChannel({\n  agent,\n  channel,\n  mode,\n  extraRunConfig,\n}: Pick<StatewireRunConfigOptions, 'agent' | 'channel' | 'mode' | 'extraRunConfig'>): string | null {\n  if (extraRunConfig !== undefined && Object.hasOwn(extraRunConfig, 'start_channel')) {\n    const override = extraRunConfig.start_channel;\n    return typeof override === 'string' && override.trim() !== '' ? override : null;\n  }\n  // The non-throwing parse: an agent prop of another shape makes the runtime\n  // refuse to start (`resolveAgentProp`), so nothing is sent to stamp.\n  const collabChannelSelected =\n    parseCollabAgentRef(agent?.trim()) !== null && Boolean(mode?.trim() || channel?.trim());\n  return collabChannelSelected ? null : STATEWIRE_START_CHANNEL;\n}\n\n/**\n * Build the `runConfig` a deep-agent statewire run is driven by. Commands\n * travel bare on the statewire channel, so this payload rides the ambient\n * model context (`config.runConfig`) instead of the request body.\n *\n * The flattened `custom` fields drive the run, while `panel_config` carries a\n * minimal panel state the backend persists per thread and replays on the\n * statewire snapshot — so a session started from the SDK stays configured\n * when reopened elsewhere.\n */\nexport function buildStatewireRunConfig(\n  options: StatewireRunConfigOptions = {},\n): Record<string, unknown> {\n  const collabAgentId = resolveAgentProp({ agent: options.agent });\n  const channel = collabAgentId ? options.channel?.trim() || undefined : undefined;\n  const mode = collabAgentId ? options.mode?.trim() || undefined : undefined;\n  const collabChannelId = mode ?? channel;\n  const collabEntryChannelId = mode && channel && mode !== channel ? channel : undefined;\n  // With a collab agent selected and no explicit model, send NO model: the\n  // backend overlay then applies the model the agent's author configured\n  // instead of the SDK default overriding it.\n  const model = options.model ?? (collabAgentId ? undefined : DEFAULT_STATEWIRE_MODEL);\n  const enabledTools = Array.from(\n    new Set([...(options.tools ?? []), ...(options.frontendToolIds ?? [])]),\n  );\n  const systemPrompt = options.systemPrompt?.trim() ?? '';\n\n  const built: { custom: Record<string, unknown> } = {\n    custom: {\n      runtime: DEEP_AGENT_RUNTIME_MARKER,\n      // With a collab channel selected, omit the SDK's own 'web' stamp: the\n      // request's explicit start_channel would win over the backend overlay's\n      // kind-mapped provenance (a custom SMS channel must stamp 'sms').\n      ...(collabChannelId ? {} : { start_channel: STATEWIRE_START_CHANNEL }),\n      ...(model ? { model } : {}),\n      // An empty list is behavior-identical to an absent key for the parser\n      // (both coerce to []), but the collab-agent overlay merges request keys\n      // OVER the agent definition — so an explicit empty list would erase the\n      // agent's configured tools. Omit it when empty.\n      ...(enabledTools.length > 0 ? { enabled_tools: enabledTools } : {}),\n      panel_config: {\n        // A collab agent's thread with no explicit model names none here\n        // either: agora stores this panel on the thread's first run and\n        // replays it to every client, and a stored SDK default would show as\n        // the session's model while the agent's own model runs.\n        ...(model ? { model } : {}),\n        enabled_tools: enabledTools,\n        system_prompt: systemPrompt,\n        run_label: STATEWIRE_RUN_LABEL,\n      },\n      ...(collabAgentId ? { collab_agent_id: collabAgentId } : {}),\n      ...(collabChannelId ? { collab_channel_id: collabChannelId } : {}),\n      ...(collabEntryChannelId ? { collab_entry_channel_id: collabEntryChannelId } : {}),\n      ...(systemPrompt ? { system_prompt: systemPrompt } : {}),\n      ...(options.workbench?.length ? { workbench: options.workbench } : {}),\n      ...(options.knowledgeBase?.length\n        ? { knowledge_base: options.knowledgeBase }\n        : {}),\n      ...(options.appId ? { app_id: options.appId } : {}),\n      ...(options.clientTools?.length ? { client_tools: options.clientTools } : {}),\n      ...(options.extraRunConfig ?? {}),\n    },\n  };\n  // Plan mode edits the exclusion lists last, so it composes with an\n  // `extraRunConfig` that excludes other tools or middleware.\n  return { custom: withPlanMode({ custom: built.custom, planMode: options.planMode }) };\n}\n"],"names":[],"mappings":"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"}

package/dist/runtime/statewire-session-key.cjs

@@ -1,11 +1,16 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-function statewireSessionKey({
+const quotaSafeLocalStorageSession = require("../agent-runtime/src/quota-safe-local-storage-session.cjs");
+const ANONYMOUS_SESSION_PRINCIPAL = "anonymous";
+function statewireSessionLanes({
   syncUrl,
-  principal,
-  threadId
+  principal
 }) {
-  return `${syncUrl}:${principal || "anon"}:${threadId}`;
+  return {
+    namespace: `${syncUrl}:`,
+    principal: principal ? quotaSafeLocalStorageSession.sessionPrincipal(principal) : ANONYMOUS_SESSION_PRINCIPAL,
+    unscopedPrefix: `${syncUrl}:${principal || "anon"}:`
+  };
 }
 function statewireSessionPrincipal(auth) {
   var _a;
@@ -13,6 +18,7 @@ function statewireSessionPrincipal(auth) {
   if (userId) return userId;
   return (auth == null ? void 0 : auth.isLoading) ? null : "";
 }
-exports.statewireSessionKey = statewireSessionKey;
+exports.ANONYMOUS_SESSION_PRINCIPAL = ANONYMOUS_SESSION_PRINCIPAL;
+exports.statewireSessionLanes = statewireSessionLanes;
 exports.statewireSessionPrincipal = statewireSessionPrincipal;
 //# sourceMappingURL=statewire-session-key.cjs.map

package/dist/runtime/statewire-session-key.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"statewire-session-key.cjs","sources":["../../src/runtime/statewire-session-key.ts"],"sourcesContent":["import type { AthenaAuthState } from '../auth/types';\n\n/**\n * Scope of the persisted statewire command lane: the sync host, the signed-in\n * principal, and the thread. A thread id is only meaningful against the\n * backend that minted it, and a shared browser must never resend one user's\n * un-settled commands under the next user's token — so the key carries WHO is\n * signed in as well as where. The principal is a non-secret user id;\n * API-key-only hosts (no auth provider above) share one anonymous scope.\n */\nexport function statewireSessionKey({\n  syncUrl,\n  principal,\n  threadId,\n}: {\n  syncUrl: string;\n  principal: string;\n  threadId: string;\n}): string {\n  return `${syncUrl}:${principal || 'anon'}:${threadId}`;\n}\n\n/**\n * The principal a thread's persisted command lane is scoped by\n * ({@link statewireSessionKey}): the signed-in user's id (also while the\n * sign-in provider refreshes and still names them), `''` (the one anonymous\n * scope) with no sign-in provider above or none signed in, and `null` while\n * the sign-in provider is still resolving who is signed in.\n *\n * A lane belongs to one principal. When the principal changes under a mounted\n * chat (a provider signs a signed-out person in, or picks up another account),\n * the runtime remounts the conversation on the new principal's lane as a new\n * client: nothing the previous principal queued is sent as the new one, and\n * the previous principal's record stays for their next sign-in. While the\n * provider is still resolving who is signed in, the lane stays `pending`\n * (`null` here) rather than taking a stand-in key, which would make the first\n * sign-in a principal change and a second attach (see\n * `useAthenaStatewireRuntime`).\n */\nexport function statewireSessionPrincipal(\n  auth: Pick<AthenaAuthState, 'isLoading' | 'user'> | null,\n): string | null {\n  const userId = auth?.user?.userId;\n  if (userId) return userId;\n  return auth?.isLoading ? null : '';\n}\n"],"names":[],"mappings":";;AAUO,SAAS,oBAAoB;AAAA,EAClC;AAAA,EACA;AAAA,EACA;AACF,GAIW;AACT,SAAO,GAAG,OAAO,IAAI,aAAa,MAAM,IAAI,QAAQ;AACtD;AAmBO,SAAS,0BACd,MACe;;AACf,QAAM,UAAS,kCAAM,SAAN,mBAAY;AAC3B,MAAI,OAAQ,QAAO;AACnB,UAAO,6BAAM,aAAY,OAAO;AAClC;;;"}
+{"version":3,"file":"statewire-session-key.cjs","sources":["../../src/runtime/statewire-session-key.ts"],"sourcesContent":["import { sessionPrincipal } from '@athenaintel/agent-runtime';\nimport type { AthenaAuthState } from '../auth/types';\n\n/** The statewire principal of API-key-only hosts (no sign-in provider above, or none signed in). */\nexport const ANONYMOUS_SESSION_PRINCIPAL = 'anonymous';\n\n/** Where a principal's persisted statewire command lanes are kept in localStorage. */\nexport interface StatewireSessionLanes {\n  /** The backend the lanes belong to: the sync host and `:`. */\n  namespace: string;\n  /** Statewire's principal: `user:<userId>`, or {@link ANONYMOUS_SESSION_PRINCIPAL}. */\n  principal: string;\n  /** Where statewire 0.24 kept them (`<syncUrl>:<userId or \"anon\">:`), moved on mount. */\n  unscopedPrefix: string;\n}\n\n/**\n * Scope of the persisted statewire command lanes: the sync host and the\n * signed-in principal (a lane is stored at `<syncUrl>:<principal>:<threadId>`).\n * A thread id is only meaningful against the backend that minted it, and a\n * shared browser must never resend one user's un-settled commands under the\n * next user's token, so the lane carries WHO is signed in as well as where.\n * The principal is the signed-in user's id (`user:<userId>`); API-key-only\n * hosts (no auth provider above) share one anonymous scope.\n */\nexport function statewireSessionLanes({\n  syncUrl,\n  principal,\n}: {\n  syncUrl: string;\n  /** {@link statewireSessionPrincipal}: the user id, or `''` for the anonymous scope. */\n  principal: string;\n}): StatewireSessionLanes {\n  return {\n    namespace: `${syncUrl}:`,\n    principal: principal ? sessionPrincipal(principal) : ANONYMOUS_SESSION_PRINCIPAL,\n    unscopedPrefix: `${syncUrl}:${principal || 'anon'}:`,\n  };\n}\n\n/**\n * The principal a thread's persisted command lane is scoped by\n * ({@link statewireSessionLanes}): the signed-in user's id (also while the\n * sign-in provider refreshes and still names them), `''` (the one anonymous\n * scope) with no sign-in provider above or none signed in, and `null` while\n * the sign-in provider is still resolving who is signed in.\n *\n * A lane belongs to one principal. When the principal changes under a mounted\n * chat (a provider signs a signed-out person in, or picks up another account),\n * the runtime remounts the conversation on the new principal's lane as a new\n * client: nothing the previous principal queued is sent as the new one, and\n * the previous principal's record stays for their next sign-in. While the\n * provider is still resolving who is signed in, the lane stays `pending`\n * (`null` here) rather than taking a stand-in key, which would make the first\n * sign-in a principal change and a second attach (see\n * `useAthenaStatewireRuntime`).\n */\nexport function statewireSessionPrincipal(\n  auth: Pick<AthenaAuthState, 'isLoading' | 'user'> | null,\n): string | null {\n  const userId = auth?.user?.userId;\n  if (userId) return userId;\n  return auth?.isLoading ? null : '';\n}\n"],"names":["sessionPrincipal"],"mappings":";;;AAIO,MAAM,8BAA8B;AAqBpC,SAAS,sBAAsB;AAAA,EACpC;AAAA,EACA;AACF,GAI0B;AACxB,SAAO;AAAA,IACL,WAAW,GAAG,OAAO;AAAA,IACrB,WAAW,YAAYA,8CAAiB,SAAS,IAAI;AAAA,IACrD,gBAAgB,GAAG,OAAO,IAAI,aAAa,MAAM;AAAA,EAAA;AAErD;AAmBO,SAAS,0BACd,MACe;;AACf,QAAM,UAAS,kCAAM,SAAN,mBAAY;AAC3B,MAAI,OAAQ,QAAO;AACnB,UAAO,6BAAM,aAAY,OAAO;AAClC;;;;"}

package/dist/runtime/statewire-session-key.d.ts

@@ -1,20 +1,32 @@
 import type { AthenaAuthState } from '../auth/types';
+/** The statewire principal of API-key-only hosts (no sign-in provider above, or none signed in). */
+export declare const ANONYMOUS_SESSION_PRINCIPAL = "anonymous";
+/** Where a principal's persisted statewire command lanes are kept in localStorage. */
+export interface StatewireSessionLanes {
+    /** The backend the lanes belong to: the sync host and `:`. */
+    namespace: string;
+    /** Statewire's principal: `user:<userId>`, or {@link ANONYMOUS_SESSION_PRINCIPAL}. */
+    principal: string;
+    /** Where statewire 0.24 kept them (`<syncUrl>:<userId or "anon">:`), moved on mount. */
+    unscopedPrefix: string;
+}
 /**
- * Scope of the persisted statewire command lane: the sync host, the signed-in
- * principal, and the thread. A thread id is only meaningful against the
- * backend that minted it, and a shared browser must never resend one user's
- * un-settled commands under the next user's token — so the key carries WHO is
- * signed in as well as where. The principal is a non-secret user id;
- * API-key-only hosts (no auth provider above) share one anonymous scope.
+ * Scope of the persisted statewire command lanes: the sync host and the
+ * signed-in principal (a lane is stored at `<syncUrl>:<principal>:<threadId>`).
+ * A thread id is only meaningful against the backend that minted it, and a
+ * shared browser must never resend one user's un-settled commands under the
+ * next user's token, so the lane carries WHO is signed in as well as where.
+ * The principal is the signed-in user's id (`user:<userId>`); API-key-only
+ * hosts (no auth provider above) share one anonymous scope.
  */
-export declare function statewireSessionKey({ syncUrl, principal, threadId, }: {
+export declare function statewireSessionLanes({ syncUrl, principal, }: {
     syncUrl: string;
+    /** {@link statewireSessionPrincipal}: the user id, or `''` for the anonymous scope. */
     principal: string;
-    threadId: string;
-}): string;
+}): StatewireSessionLanes;
 /**
  * The principal a thread's persisted command lane is scoped by
- * ({@link statewireSessionKey}): the signed-in user's id (also while the
+ * ({@link statewireSessionLanes}): the signed-in user's id (also while the
  * sign-in provider refreshes and still names them), `''` (the one anonymous
  * scope) with no sign-in provider above or none signed in, and `null` while
  * the sign-in provider is still resolving who is signed in.

package/dist/runtime/statewire-session-key.js

@@ -1,9 +1,14 @@
-function statewireSessionKey({
+import { sessionPrincipal } from "../agent-runtime/src/quota-safe-local-storage-session.js";
+const ANONYMOUS_SESSION_PRINCIPAL = "anonymous";
+function statewireSessionLanes({
   syncUrl,
-  principal,
-  threadId
+  principal
 }) {
-  return `${syncUrl}:${principal || "anon"}:${threadId}`;
+  return {
+    namespace: `${syncUrl}:`,
+    principal: principal ? sessionPrincipal(principal) : ANONYMOUS_SESSION_PRINCIPAL,
+    unscopedPrefix: `${syncUrl}:${principal || "anon"}:`
+  };
 }
 function statewireSessionPrincipal(auth) {
   var _a;
@@ -12,7 +17,8 @@ function statewireSessionPrincipal(auth) {
   return (auth == null ? void 0 : auth.isLoading) ? null : "";
 }
 export {
-  statewireSessionKey,
+  ANONYMOUS_SESSION_PRINCIPAL,
+  statewireSessionLanes,
   statewireSessionPrincipal
 };
 //# sourceMappingURL=statewire-session-key.js.map

package/dist/runtime/statewire-session-key.js.map

@@ -1 +1 @@
-{"version":3,"file":"statewire-session-key.js","sources":["../../src/runtime/statewire-session-key.ts"],"sourcesContent":["import type { AthenaAuthState } from '../auth/types';\n\n/**\n * Scope of the persisted statewire command lane: the sync host, the signed-in\n * principal, and the thread. A thread id is only meaningful against the\n * backend that minted it, and a shared browser must never resend one user's\n * un-settled commands under the next user's token — so the key carries WHO is\n * signed in as well as where. The principal is a non-secret user id;\n * API-key-only hosts (no auth provider above) share one anonymous scope.\n */\nexport function statewireSessionKey({\n  syncUrl,\n  principal,\n  threadId,\n}: {\n  syncUrl: string;\n  principal: string;\n  threadId: string;\n}): string {\n  return `${syncUrl}:${principal || 'anon'}:${threadId}`;\n}\n\n/**\n * The principal a thread's persisted command lane is scoped by\n * ({@link statewireSessionKey}): the signed-in user's id (also while the\n * sign-in provider refreshes and still names them), `''` (the one anonymous\n * scope) with no sign-in provider above or none signed in, and `null` while\n * the sign-in provider is still resolving who is signed in.\n *\n * A lane belongs to one principal. When the principal changes under a mounted\n * chat (a provider signs a signed-out person in, or picks up another account),\n * the runtime remounts the conversation on the new principal's lane as a new\n * client: nothing the previous principal queued is sent as the new one, and\n * the previous principal's record stays for their next sign-in. While the\n * provider is still resolving who is signed in, the lane stays `pending`\n * (`null` here) rather than taking a stand-in key, which would make the first\n * sign-in a principal change and a second attach (see\n * `useAthenaStatewireRuntime`).\n */\nexport function statewireSessionPrincipal(\n  auth: Pick<AthenaAuthState, 'isLoading' | 'user'> | null,\n): string | null {\n  const userId = auth?.user?.userId;\n  if (userId) return userId;\n  return auth?.isLoading ? null : '';\n}\n"],"names":[],"mappings":"AAUO,SAAS,oBAAoB;AAAA,EAClC;AAAA,EACA;AAAA,EACA;AACF,GAIW;AACT,SAAO,GAAG,OAAO,IAAI,aAAa,MAAM,IAAI,QAAQ;AACtD;AAmBO,SAAS,0BACd,MACe;AA/BV;AAgCL,QAAM,UAAS,kCAAM,SAAN,mBAAY;AAC3B,MAAI,OAAQ,QAAO;AACnB,UAAO,6BAAM,aAAY,OAAO;AAClC;"}
+{"version":3,"file":"statewire-session-key.js","sources":["../../src/runtime/statewire-session-key.ts"],"sourcesContent":["import { sessionPrincipal } from '@athenaintel/agent-runtime';\nimport type { AthenaAuthState } from '../auth/types';\n\n/** The statewire principal of API-key-only hosts (no sign-in provider above, or none signed in). */\nexport const ANONYMOUS_SESSION_PRINCIPAL = 'anonymous';\n\n/** Where a principal's persisted statewire command lanes are kept in localStorage. */\nexport interface StatewireSessionLanes {\n  /** The backend the lanes belong to: the sync host and `:`. */\n  namespace: string;\n  /** Statewire's principal: `user:<userId>`, or {@link ANONYMOUS_SESSION_PRINCIPAL}. */\n  principal: string;\n  /** Where statewire 0.24 kept them (`<syncUrl>:<userId or \"anon\">:`), moved on mount. */\n  unscopedPrefix: string;\n}\n\n/**\n * Scope of the persisted statewire command lanes: the sync host and the\n * signed-in principal (a lane is stored at `<syncUrl>:<principal>:<threadId>`).\n * A thread id is only meaningful against the backend that minted it, and a\n * shared browser must never resend one user's un-settled commands under the\n * next user's token, so the lane carries WHO is signed in as well as where.\n * The principal is the signed-in user's id (`user:<userId>`); API-key-only\n * hosts (no auth provider above) share one anonymous scope.\n */\nexport function statewireSessionLanes({\n  syncUrl,\n  principal,\n}: {\n  syncUrl: string;\n  /** {@link statewireSessionPrincipal}: the user id, or `''` for the anonymous scope. */\n  principal: string;\n}): StatewireSessionLanes {\n  return {\n    namespace: `${syncUrl}:`,\n    principal: principal ? sessionPrincipal(principal) : ANONYMOUS_SESSION_PRINCIPAL,\n    unscopedPrefix: `${syncUrl}:${principal || 'anon'}:`,\n  };\n}\n\n/**\n * The principal a thread's persisted command lane is scoped by\n * ({@link statewireSessionLanes}): the signed-in user's id (also while the\n * sign-in provider refreshes and still names them), `''` (the one anonymous\n * scope) with no sign-in provider above or none signed in, and `null` while\n * the sign-in provider is still resolving who is signed in.\n *\n * A lane belongs to one principal. When the principal changes under a mounted\n * chat (a provider signs a signed-out person in, or picks up another account),\n * the runtime remounts the conversation on the new principal's lane as a new\n * client: nothing the previous principal queued is sent as the new one, and\n * the previous principal's record stays for their next sign-in. While the\n * provider is still resolving who is signed in, the lane stays `pending`\n * (`null` here) rather than taking a stand-in key, which would make the first\n * sign-in a principal change and a second attach (see\n * `useAthenaStatewireRuntime`).\n */\nexport function statewireSessionPrincipal(\n  auth: Pick<AthenaAuthState, 'isLoading' | 'user'> | null,\n): string | null {\n  const userId = auth?.user?.userId;\n  if (userId) return userId;\n  return auth?.isLoading ? null : '';\n}\n"],"names":[],"mappings":";AAIO,MAAM,8BAA8B;AAqBpC,SAAS,sBAAsB;AAAA,EACpC;AAAA,EACA;AACF,GAI0B;AACxB,SAAO;AAAA,IACL,WAAW,GAAG,OAAO;AAAA,IACrB,WAAW,YAAY,iBAAiB,SAAS,IAAI;AAAA,IACrD,gBAAgB,GAAG,OAAO,IAAI,aAAa,MAAM;AAAA,EAAA;AAErD;AAmBO,SAAS,0BACd,MACe;;AACf,QAAM,UAAS,kCAAM,SAAN,mBAAY;AAC3B,MAAI,OAAQ,QAAO;AACnB,UAAO,6BAAM,aAAY,OAAO;AAClC;"}