@moxxy/sdk 0.43.0 → 0.45.0

package/src/npm-registry.ts

@@ -0,0 +1,57 @@
+/**
+ * Ask the npm registry what version a package's `latest` dist-tag points at.
+ * Pure transport over global `fetch` — no `npm` dependency, no child process —
+ * so `moxxy update`, the TUI's "new version" banner and the agent CLI checks
+ * share one cheap call.
+ *
+ * Fail-soft by contract: every error (offline, timeout, 404, malformed body)
+ * resolves to `null`, never throws. A version check must never break a caller.
+ */
+
+const REGISTRY = 'https://registry.npmjs.org';
+const DEFAULT_TIMEOUT_MS = 4000;
+const STABLE_SEMVER_RE = /^(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})$/;
+
+function normalizeStableSemver(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const match = STABLE_SEMVER_RE.exec(value);
+  if (!match) return null;
+  const [, major, minor, patch] = match;
+  if (major === undefined || minor === undefined || patch === undefined) return null;
+  return `${Number(major)}.${Number(minor)}.${Number(patch)}`;
+}
+
+export interface FetchNpmLatestOptions {
+  /** Override the fetch implementation (tests inject a stub). */
+  fetchImpl?: typeof fetch;
+  /** Abort the request after this many ms (default 4000). */
+  timeoutMs?: number;
+}
+
+/**
+ * The version under the `latest` dist-tag for `pkg`, or `null` if it can't be
+ * resolved. Uses the per-tag manifest endpoint
+ * (`/<pkg>/latest`) so we transfer a tiny document, not the full packument.
+ */
+export async function fetchNpmLatest(pkg: string, opts: FetchNpmLatestOptions = {}): Promise<string | null> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  // Encode the whole package name (incl. the scope slash) so an arbitrary or
+  // attacker-influenced `pkg` can't inject path traversal / a query string /
+  // another host segment into the registry URL. npm accepts `@scope%2Fname`.
+  const url = `${REGISTRY}/${encodeURIComponent(pkg)}/latest`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  try {
+    const res = await fetchImpl(url, {
+      signal: controller.signal,
+      headers: { accept: 'application/json' },
+    });
+    if (!res.ok) return null;
+    const json = (await res.json()) as { version?: unknown };
+    return normalizeStableSemver(json.version);
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/permission.ts

@@ -30,6 +30,13 @@ export interface PermissionRule {
     }>;
   };
   readonly reason?: string;
+  /**
+   * How far an "allow for this session" answer reaches for this tool: only
+   * later calls with the same values under these input keys. For a tool whose
+   * approval grants something by itself (access to an app), where a grant of
+   * the whole tool would let every later, wider request through unasked.
+   */
+  readonly sessionScope?: { readonly inputKeys: ReadonlyArray<string> };
 }
 
 export interface PendingToolCall {
@@ -44,9 +51,32 @@ export interface PendingToolCall {
   readonly requestedAtSeq?: number;
 }
 
+/**
+ * A standing "allow" rule a channel saves to the person's permissions.json:
+ * the whole tool, or with `inputEquals` only calls whose inputs have exactly
+ * these values (`null` for a left-out one).
+ */
+export interface StandingAllowRule {
+  readonly name: string;
+  readonly reason?: string;
+  readonly inputEquals?: Readonly<Record<string, unknown>>;
+}
+
 export interface PermissionContext {
   readonly turnId?: string;
   readonly toolDescription?: string;
+  /**
+   * The rule declared by the tool this turn offers under the call's name. A
+   * mode may offer tools the session registry does not hold (plan mode's
+   * `plan_complete`), so the resolver needs it from the call site.
+   */
+  readonly toolPermission?: PermissionRule;
+  /**
+   * The person answers even while auto-approve is on (standing rules still
+   * decide first): the agent's own setting would have asked them, and they
+   * never chose auto-approve for it.
+   */
+  readonly askPerson?: boolean;
   readonly skillContext?: string;
   readonly sessionId: string;
 }

package/src/process-invocation.test.ts

@@ -272,4 +272,29 @@ describe('spawnExecutableTarget', () => {
 
     expect(JSON.parse(readFileSync(observed, 'utf8'))).toEqual(args.slice(1));
   });
+
+  it("gives a native program the environment its target carries, over the caller's", () => {
+    const child = spawnExecutableTarget(
+      { kind: 'direct', command: process.execPath, env: { MOXXY_TARGET_ENV: 'from target' } },
+      ['-e', 'process.stdout.write(String(process.env.MOXXY_TARGET_ENV))'],
+      { stdio: ['ignore', 'pipe', 'pipe'], env: { MOXXY_TARGET_ENV: 'from caller' } },
+    );
+    let stdout = '';
+    child.stdout?.setEncoding('utf8');
+    child.stdout?.on('data', (chunk: string) => {
+      stdout += chunk;
+    });
+
+    return new Promise<void>((resolve, reject) => {
+      child.once('error', reject);
+      child.once('close', () => {
+        try {
+          expect(stdout).toBe('from target');
+          resolve();
+        } catch (error) {
+          reject(error);
+        }
+      });
+    });
+  });
 });

package/src/process-invocation.ts

@@ -16,7 +16,12 @@ const KNOWN_NODE_CLIS = new Set<KnownNodeCli>(['moxxy', 'npm', 'pnpm', 'yarn']);
 type KnownNodeCli = 'moxxy' | 'npm' | 'pnpm' | 'yarn';
 
 export type ExecutableTarget =
-  | { readonly kind: 'direct'; readonly command: string }
+  | {
+      readonly kind: 'direct';
+      readonly command: string;
+      /** Environment the program needs, set over the caller's. */
+      readonly env?: Readonly<Record<string, string>>;
+    }
   | {
       readonly kind: 'node';
       readonly command: string;
@@ -155,7 +160,7 @@ export function spawnExecutableTarget(
   opts: SafeSpawnOptions = {},
 ): ChildProcess {
   const argv = target.kind === 'node' ? [target.entry, ...args] : [...args];
-  const targetEnv = target.kind === 'node' ? target.env : {};
+  const targetEnv = target.env ?? {};
   return spawn(target.command, argv, {
     ...opts,
     env: { ...process.env, ...opts.env, ...targetEnv },
@@ -170,7 +175,7 @@ export function execExecutableTargetSync(
   opts: SafeExecFileSyncOptions = {},
 ): void {
   const argv = target.kind === 'node' ? [target.entry, ...args] : [...args];
-  const targetEnv = target.kind === 'node' ? target.env : {};
+  const targetEnv = target.env ?? {};
   execFileSync(target.command, argv, {
     ...opts,
     env: { ...process.env, ...opts.env, ...targetEnv },

package/src/process-tree.ts

@@ -0,0 +1,37 @@
+import { spawn, type ChildProcess } from 'node:child_process';
+import * as path from 'node:path';
+
+/**
+ * Signal the child's whole process group, not just the shell. The child must
+ * be spawned `detached` on POSIX so it leads its own group; a negative-pid kill
+ * then reaches every descendant (`sh -c 'sleep 1000 & wait'`, build workers,
+ * …) instead of orphaning them.
+ */
+export function killTree(child: ChildProcess, signal: NodeJS.Signals): void {
+  if (child.pid === undefined) return;
+  if (process.platform === 'win32') {
+    // Windows has no process groups; taskkill /T walks the tree down from the
+    // shell. Always forced: a console program has no SIGTERM handler to run.
+    if (child.exitCode !== null || child.signalCode !== null) return;
+    const taskkill = path.win32.join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'taskkill.exe');
+    spawn(taskkill, ['/PID', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true }).on('error', () => {
+      child.kill(signal);
+    });
+    return;
+  }
+  try {
+    // Deliberately *no* "child already exited" guard here: the group outlives
+    // its leader (SIGTERM may kill the shell while a TERM-ignoring descendant
+    // lives on), and the pgid stays valid — and un-reusable — while any
+    // member survives. ESRCH below covers the fully-gone case.
+    process.kill(-child.pid, signal);
+  } catch (e) {
+    // ESRCH: the group is already gone — nothing to do. Anything else
+    // (e.g. EPERM, or the child somehow not leading a group): fall back to
+    // signalling the shell itself so we at least keep the old behavior.
+    if ((e as NodeJS.ErrnoException).code !== 'ESRCH') {
+      if (child.exitCode === null && child.signalCode === null) child.kill(signal);
+    }
+  }
+}
+

package/src/provider-login-bridge.ts

@@ -17,7 +17,7 @@
  * depend on, so the two ends can never drift.
  */
 
-import { z } from 'zod';
+import { z } from 'zod/v3';
 
 /** The byte that brackets a prompt marker. Absent from normal CLI output. */
 const NUL = '\u0000';

package/src/provider-schema-constraints.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { z } from 'zod';
+import { z } from 'zod/v3';
 import { zodToJsonSchema } from './provider-utils.js';
 
 describe('model-visible validation constraints', () => {

package/src/provider-utils.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { z } from 'zod';
+import { z } from 'zod/v3';
 import { zodToJsonSchema } from './provider-utils.js';
 import { resolveProviderTools } from './provider-tool-utils.js';
 import { defineTool } from './define.js';

package/src/provider.ts

@@ -1,5 +1,9 @@
 import type { HostedTool, ToolDef } from './tool.js';
 import type { ReasoningReplayItem } from './events.js';
+import type { StopReason } from './provider-utils.js';
+import type { QuestionAskOptions, QuestionItem, QuestionOutcome } from './question.js';
+import type { AgentAccountLimit } from './agent-account-limit.js';
+import type { Skill } from './skill.js';
 
 export interface ProviderMessage {
   readonly role: 'system' | 'user' | 'assistant' | 'tool_result';
@@ -173,6 +177,14 @@ export interface ModelDescriptor {
 export interface LLMProvider {
   readonly name: string;
   readonly models: ReadonlyArray<ModelDescriptor>;
+  /**
+   * The model a new conversation starts on while the person chose no default
+   * for this provider: a light one, so an unset default does not spend their
+   * plan on the biggest model. Ignored when the provider does not list it.
+   */
+  readonly starterModel?: string;
+  /** For an agent connection, the agent's name as the person knows it ("Codex"), the same as its `ProviderDef.agentName`. */
+  readonly agentName?: string;
   /**
    * Optional provider-owned metadata preparation for a dynamically selected
    * model. The runtime awaits it before it calculates context budgets, so a
@@ -184,6 +196,41 @@ export interface LLMProvider {
     options?: { readonly signal?: AbortSignal },
   ): Promise<void>;
   stream(req: ProviderRequest): AsyncIterable<ProviderEvent>;
+  /**
+   * Present on an agent connection: run one turn of the vendor's own coding
+   * agent. The shared loop then calls this instead of {@link stream} for the
+   * conversation's turns; `stream` still serves one-shot text calls.
+   */
+  agentStep?(req: AgentStepRequest): AsyncIterable<AgentStepEvent>;
+  /**
+   * On an agent connection: the plan and goal the vendor's agent keeps itself
+   * (Claude, Codex), handed back as `plan` and `goal` events. Moxxy's plan and
+   * goal modes steer an agent without them like any model: through
+   * `plan_complete` / `goal_complete` it calls over MCP, and a nudge when it
+   * stops without one.
+   */
+  readonly agentOwns?: AgentOwnModes;
+  /**
+   * On an agent connection whose agent can start a turn by itself (Claude after
+   * a task it ran in the background finished): tell the listener when it does
+   * while no Moxxy turn is running, so the conversation opens a turn for it
+   * (`origin.kind: 'agent'`) whose `agentStep` reads the agent's turn
+   * (`continuesAgentTurn`). Returns the unsubscribe.
+   */
+  onAgentTurn?(listener: (start: AgentTurnStart) => void): () => void;
+  /**
+   * On an agent connection: what the agent's background work does while no
+   * Moxxy turn runs (its helpers' steps, `background_work` as it changes), for
+   * the conversation to record at once rather than at its next turn. Returns
+   * the unsubscribe.
+   */
+  onAgentActivity?(listener: (activity: AgentActivity) => void): () => void;
+  /**
+   * On an agent connection: stop one work the agent runs in the background in
+   * the conversation (`AgentBackgroundWork.id`). Resolves `false` when the
+   * agent has no such work running.
+   */
+  stopBackgroundWork?(sessionId: string, workId: string): Promise<boolean>;
   countTokens(req: Pick<ProviderRequest, 'model' | 'messages' | 'system' | 'tools'>): Promise<number>;
 }
 
@@ -337,9 +384,74 @@ export interface ProviderOAuthStatus {
   readonly message?: string;
 }
 
+/**
+ * Where an agent connection's CLI stands on this computer:
+ * - `missing`: not found, so the connection cannot work until it is installed;
+ * - `update-required`: older than the oldest version Moxxy was checked against;
+ * - `update-available`: works, and the vendor has published a newer one;
+ * - `current`: works, and nothing newer is known;
+ * - `unknown`: found, but its version could not be read.
+ */
+export type AgentCliState = 'missing' | 'update-required' | 'update-available' | 'current' | 'unknown';
+
+/**
+ * Where an agent CLI came from, by where its file really is: the vendor's
+ * installer, Homebrew, a global npm install, inside an app (which updates it
+ * itself), or none of these.
+ */
+export type AgentCliOrigin = 'installer' | 'homebrew' | 'npm' | 'app' | 'unknown';
+
+/** The last check of an agent connection's CLI, as every surface shows it. */
+export interface AgentCliReport {
+  readonly state: AgentCliState;
+  /** The CLI's command ("codex"), which also names it to `moxxy agents`. */
+  readonly command: string;
+  /** The version found on this computer; null when missing or unreadable. */
+  readonly installed: string | null;
+  /** The file that was checked, which a conversation also runs; absent when missing. */
+  readonly path?: string;
+  /** Where that file came from; absent when missing. */
+  readonly origin?: AgentCliOrigin;
+  /** The vendor's latest published version; null when the registry could not be asked. */
+  readonly latest: string | null;
+  /** The oldest version Moxxy works with. */
+  readonly minimum: string;
+  /** When the check ran, in epoch milliseconds. */
+  readonly checkedAt: number;
+  /** Whether the agent is signed in; absent when the CLI is missing or the connection does not say. */
+  readonly signedIn?: boolean;
+  /** Who it is signed in as, in the agent's words (Claude's e-mail, "ChatGPT" for Codex); null when it does not say. */
+  readonly account?: string | null;
+}
+
+/** How an agent connection's CLI is checked; the host runs it at start and every hour. */
+export interface ProviderAgentCli {
+  /** `refresh` asks the vendor's registry again instead of trusting a recent answer. */
+  check(opts?: { readonly refresh?: boolean }): Promise<AgentCliReport>;
+  /**
+   * The models the agent offers the signed-in account now, as its own picker
+   * lists them. Asked after a check finds the agent installed and signed in;
+   * the connection's built-in `models` stay the answer until it succeeds.
+   */
+  models?(): Promise<ReadonlyArray<ModelDescriptor>>;
+}
+
 export interface ProviderDef {
   readonly name: string;
   readonly models: ReadonlyArray<ModelDescriptor>;
+  /** What {@link LLMProvider.starterModel} says, known before the provider is built. */
+  readonly starterModel?: string;
+  /** For an agent connection, the agent's name as the person knows it ("Codex"), which surfaces use to say what it does. */
+  readonly agentName?: string;
+  /** For an agent connection, how its CLI is checked for presence and updates. */
+  readonly agentCli?: ProviderAgentCli;
+  /**
+   * For an agent connection, whether the agent as the person set it up acts
+   * without asking in `cwd` (`undefined` when it cannot tell). Read as a
+   * conversation starts on the connection, so its auto-approve is the truth
+   * from the first moment; a switch the conversation recorded always wins.
+   */
+  ownAutoApprove?(opts: { readonly cwd: string }): Promise<boolean | undefined>;
   /**
    * True when the provider can return its current model catalog at runtime.
    * Hosts use this capability signal to offer live discovery instead of
@@ -367,3 +479,237 @@ export interface ProviderDef {
    */
   readonly auth?: ProviderAuthDescriptor;
 }
+
+/**
+ * Agent connections: the vendor's own coding agent (Claude, Codex, OpenCode)
+ * does the turn, unmodified. A provider that runs one implements
+ * `LLMProvider.agentStep`; the shared loop then runs one agent turn instead of
+ * "call the model, run the tools, repeat" and records what the agent did as
+ * ordinary Moxxy events. Everything the agent needs from Moxxy (its tools, the
+ * person's approval, a Question) goes through {@link AgentStepHost}.
+ */
+
+/** One turn of the vendor's agent. */
+export interface AgentStepRequest {
+  /** The Moxxy conversation, so an adapter keeps one live agent per conversation. */
+  readonly sessionId: string;
+  /** The model the person picked, exactly as the agent names it. */
+  readonly model: string;
+  /** The person's message for this turn (or the loop's follow-up), with its images and documents. */
+  readonly prompt: ReadonlyArray<ContentBlock>;
+  readonly cwd: string;
+  /** The active Moxxy mode (`default`, `plan`, `goal`, …), mapped by the adapter onto the agent's own. */
+  readonly mode: string;
+  /** Moxxy tools this mode offers; the adapter lends the ones the agent lacks over Moxxy's MCP server. */
+  readonly tools: ReadonlyArray<ToolDef>;
+  /**
+   * Every Moxxy tool of the conversation, in any mode. Agents read their tool
+   * list once (Codex as a thread opens, Claude as it starts), so the adapter
+   * lists these and refuses, with the reason, a call to one `tools` lacks.
+   */
+  readonly allTools?: ReadonlyArray<ToolDef>;
+  /** The conversation's Moxxy skills now; the adapter offers the agent those meant for it, through Moxxy's MCP server. */
+  readonly skills?: ReadonlyArray<Skill>;
+  /** The agent's own session from an earlier turn of this conversation, to resume. */
+  readonly resumeSessionId?: string;
+  /**
+   * The conversation before this turn, from Moxxy's record, for an agent that
+   * starts a new session of its own while the conversation already has turns
+   * (its earlier session is gone, or it joins partway). `undefined` when no
+   * turn came before. Built only when called.
+   */
+  readonly earlierConversation?: () => string | undefined;
+  /**
+   * The turns that ran on another connection since this agent's own last turn
+   * of the conversation, from Moxxy's record, for an agent that goes on in its
+   * own session: it was away for them. `undefined` when it missed none or
+   * never ran here. Built only when called.
+   */
+  readonly missedTurns?: () => string | undefined;
+  /** The conversation's auto-approve, one state with the agent's approval policy. */
+  readonly autoApprove: boolean;
+  /**
+   * The conversation recorded a switch: the adapter keeps `autoApprove` as it
+   * is, never the agent's own setup over it. Until one is recorded, the agent
+   * runs and shows the way the person set it up.
+   */
+  readonly autoApproveRecorded?: boolean;
+  /**
+   * The switch in force is the agent's own setup Moxxy took on, not the
+   * person's choice; an agent whose own setup still asks the person about
+   * something (OpenCode: work outside the project) keeps asking then.
+   */
+  readonly autoApproveFromAgent?: boolean;
+  readonly reasoning?: { readonly effort?: ReasoningEffort } | boolean;
+  /** The person asked for fast mode; the adapter runs the agent on its own faster tier, where it has one. */
+  readonly fast?: boolean;
+  readonly signal: AbortSignal;
+  readonly host: AgentStepHost;
+  /**
+   * The turn is one the agent started by itself (see `onAgentTurn`): read the
+   * agent's turn through to its end and send it nothing; `prompt` is only the
+   * marker Moxxy recorded for it.
+   */
+  readonly continuesAgentTurn?: true;
+}
+
+/** The agent started a turn by itself in a Moxxy conversation. */
+export interface AgentTurnStart {
+  /** The Moxxy conversation (`AgentStepRequest.sessionId`). */
+  readonly sessionId: string;
+  /** What the agent took up, for the marker that opens the turn ("List files finished in the background"). */
+  readonly name: string;
+  /** The background work whose end it took up (`AgentBackgroundWork.id`), when the agent says. */
+  readonly workId?: string;
+}
+
+/** What Moxxy does for the agent during its turn. */
+export interface AgentStepHost {
+  /** Run a Moxxy tool the agent called (over MCP) through Moxxy's hooks, permissions and log. */
+  runTool(call: AgentToolCall): Promise<AgentToolOutcome>;
+  /**
+   * Decide whether the agent may run one of its own tools. The person answers
+   * unless auto-approve or a standing rule does; with `policyOnly` only hooks
+   * and standing rules (`permissions.json`) are consulted, never the person;
+   * with `askPerson` the person answers even while auto-approve is on.
+   */
+  approve(request: AgentApprovalRequest): Promise<AgentApprovalDecision>;
+  /** Show the agent's Question in every Moxxy window of the conversation. */
+  ask(questions: ReadonlyArray<QuestionItem>, opts?: QuestionAskOptions): Promise<QuestionOutcome>;
+}
+
+export interface AgentToolCall {
+  readonly callId: string;
+  readonly name: string;
+  readonly input: unknown;
+}
+
+export type AgentToolOutcome =
+  | { readonly ok: true; readonly output: unknown }
+  | {
+      readonly ok: false;
+      readonly message: string;
+      /** The person refused a tool whose refusal ends the turn: stop the agent's turn. */
+      readonly endsTurn?: boolean;
+    };
+
+export interface AgentApprovalRequest extends AgentToolCall {
+  readonly description?: string;
+  readonly policyOnly?: boolean;
+  /** The agent's own setting would have asked the person about this call, and auto-approve was not their choice. */
+  readonly askPerson?: boolean;
+}
+
+export type AgentApprovalDecision =
+  | { readonly allow: true; /** The person allowed it for the rest of the session. */ readonly always?: boolean }
+  | { readonly allow: false; readonly reason: string };
+
+export type AgentGoalStatus = 'active' | 'complete';
+
+export interface AgentOwnModes {
+  readonly plan?: boolean;
+  readonly goal?: boolean;
+}
+
+/**
+ * Work an agent connection's agent runs in the background: a command it left
+ * running, or a helper agent going on after the turn that started it.
+ */
+export interface AgentBackgroundWork {
+  /** The agent's id for it; a helper's is the `id` of its `subagent_*` events. */
+  readonly id: string;
+  readonly kind: 'command' | 'agent';
+  /** What it does, as the agent names it ("npm run dev", "inspect folder"). */
+  readonly label: string;
+}
+
+/**
+ * A time the agent of an agent connection set itself to come back to the
+ * conversation by itself (Claude's ScheduleWakeup, `/loop`, CronCreate).
+ */
+export interface AgentScheduledWakeup {
+  /** The agent's id for it. */
+  readonly id: string;
+  /** What the agent is told when it comes back. */
+  readonly prompt: string;
+  /** When it comes back next (epoch ms); null when it cannot be told. */
+  readonly dueAtMs: number | null;
+  /** Comes back on every match of its schedule, not once. */
+  readonly recurring: boolean;
+}
+
+/** How a background work ended. */
+export type AgentWorkEnd = 'completed' | 'failed' | 'stopped';
+
+/** What the agent's background work did while no Moxxy turn ran, for the conversation `sessionId`. */
+export interface AgentActivity {
+  readonly sessionId: string;
+  readonly events: ReadonlyArray<AgentStepEvent>;
+}
+
+/** What the agent did, in the order it did it. */
+export type AgentStepEvent =
+  | { readonly type: 'text_delta'; readonly delta: string }
+  | { readonly type: 'reasoning_delta'; readonly delta: string }
+  /** A finished assistant message; `tool_use` when the agent went on to call tools. */
+  | { readonly type: 'message'; readonly text: string; readonly stopReason?: StopReason }
+  | { readonly type: 'reasoning'; readonly text: string }
+  /** A tool the agent runs itself (its Bash, Edit, …). */
+  | { readonly type: 'tool_call'; readonly callId: string; readonly name: string; readonly input: unknown }
+  | { readonly type: 'tool_result'; readonly callId: string; readonly ok: boolean; readonly output?: unknown; readonly error?: string }
+  /** The agent's own session id, kept to resume it. */
+  | { readonly type: 'session'; readonly sessionId: string }
+  /**
+   * The agent's real approval policy; it becomes the conversation's auto-approve.
+   * `elsewhere` when it changed without Moxxy (a hook, another client, the agent itself).
+   */
+  | { readonly type: 'auto_approve'; readonly enabled: boolean; readonly elsewhere?: true }
+  /**
+   * Something outside Moxxy let the agent act without asking while auto-approve
+   * was off, and the connection set it back: only the person turns auto-approve on.
+   */
+  | { readonly type: 'auto_approve_restored' }
+  /** The state of the agent's own goal after its turn: still open, or met. */
+  | { readonly type: 'goal'; readonly status: AgentGoalStatus }
+  /** The agent's own finished plan (Markdown), waiting for the person to carry it out. */
+  | { readonly type: 'plan'; readonly text: string }
+  /**
+   * A helper agent the agent started itself (Claude's Agent tool, a Codex subagent, OpenCode's task),
+   * its tool calls, and its end. `id` ties them together; it need not be a Moxxy session.
+   */
+  /** `toolsUnseen` when the agent does not report the subagent's own tool calls (OpenCode). */
+  | { readonly type: 'subagent_started'; readonly id: string; readonly label: string; readonly agentType: string; readonly prompt?: string; readonly toolsUnseen?: true }
+  | { readonly type: 'subagent_tool_call'; readonly id: string; readonly name: string; readonly input: unknown }
+  /** What a subagent said as it worked, before its answer. */
+  | { readonly type: 'subagent_message'; readonly id: string; readonly text: string }
+  | {
+      readonly type: 'subagent_completed';
+      readonly id: string;
+      readonly text: string;
+      readonly tokensUsed?: number;
+      readonly error?: string;
+      /** It ended because it was stopped (by the person, or by the agent), not because it failed. */
+      readonly stopped?: true;
+    }
+  /** Everything the agent runs in the background now; it replaces the list before, so a missed end cannot leave work shown running. */
+  | { readonly type: 'background_work'; readonly work: ReadonlyArray<AgentBackgroundWork> }
+  /** Every time the agent set itself to come back; it replaces the list before. Not recorded in the log: it is what is planned now. */
+  | { readonly type: 'scheduled_wakeups'; readonly wakeups: ReadonlyArray<AgentScheduledWakeup> }
+  /** One background work ended; `output` is what a command printed last. */
+  | {
+      readonly type: 'background_work_ended';
+      readonly id: string;
+      readonly kind: AgentBackgroundWork['kind'];
+      readonly label: string;
+      readonly status: AgentWorkEnd;
+      readonly summary?: string;
+      readonly output?: string;
+    }
+  /** How much of the person's account the agent may still use; a reached limit ends the turn without a raw error. */
+  | { readonly type: 'account_limit'; readonly limit: AgentAccountLimit }
+  | { readonly type: 'usage'; readonly usage: TokenUsage }
+  /** How many tokens the agent's context holds now, when its usage is not per call (a whole turn's total). */
+  | { readonly type: 'context_used'; readonly tokens: number }
+  /** The context window the agent runs the model with, as it reports it after a response. */
+  | { readonly type: 'context_window'; readonly model: string; readonly tokens: number }
+  | { readonly type: 'error'; readonly message: string; readonly retryable: boolean };

package/src/question-draft.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+import type { QuestionItem } from './question.js';
+import { chooseOption, draftAnswers, emptyDraft, typeOwnAnswer } from './question-draft.js';
+
+const colour: QuestionItem = {
+  id: 'q1',
+  question: 'Which colour?',
+  options: [
+    { id: 'red', label: 'Red' },
+    { id: 'blue', label: 'Blue' },
+  ],
+  multiSelect: false,
+  allowOther: true,
+};
+const parts: QuestionItem = {
+  id: 'q2',
+  question: 'Which parts?',
+  options: [
+    { id: 'auth', label: 'Auth' },
+    { id: 'billing', label: 'Billing' },
+  ],
+  multiSelect: true,
+  allowOther: true,
+};
+
+describe('answering in the card', () => {
+  it('takes one choice where only one fits, replacing the earlier one and any typed answer', () => {
+    let draft = typeOwnAnswer(emptyDraft([colour]), colour, 'Teal');
+    draft = chooseOption(draft, colour, 'red');
+    draft = chooseOption(draft, colour, 'blue');
+
+    expect(draftAnswers(draft)).toEqual({ q1: { selected: ['blue'] } });
+  });
+
+  it('toggles choices where several fit, and keeps typed words beside them', () => {
+    let draft = emptyDraft([parts]);
+    draft = chooseOption(draft, parts, 'auth');
+    draft = chooseOption(draft, parts, 'billing');
+    draft = chooseOption(draft, parts, 'auth');
+    draft = typeOwnAnswer(draft, parts, 'Logs');
+
+    expect(draftAnswers(draft)).toEqual({ q2: { selected: ['billing'], other: 'Logs' } });
+  });
+
+  it('lets typed words stand alone as the one answer, clearing the choice', () => {
+    let draft = chooseOption(emptyDraft([colour]), colour, 'red');
+    draft = typeOwnAnswer(draft, colour, 'Teal');
+
+    expect(draftAnswers(draft)).toEqual({ q1: { selected: [], other: 'Teal' } });
+  });
+
+  it('sends no empty typed answer', () => {
+    const draft = typeOwnAnswer(chooseOption(emptyDraft([parts]), parts, 'auth'), parts, '   ');
+
+    expect(draftAnswers(draft)).toEqual({ q2: { selected: ['auth'] } });
+  });
+});