@qodeca/xezar 0.10.1

package/dist/core/agent-runner.d.ts

@@ -0,0 +1,211 @@
+/**
+ * The backend-agnostic seam for running one agent task. Adapted from
+ * @xezar/core's `agents/agent-runner.ts`, trimmed for single-user local use:
+ * no token-budget circuit breaker, no zod response schemas — one run is one
+ * agent-CLI session streaming normalized events.
+ *
+ * Four interchangeable backends implement this seam, each as a persistent
+ * process so multi-turn follow-ups, `waiting`, interrupt and resume all work:
+ *  - `claude`   — Claude Code CLI, stream-json over stdin/stdout;
+ *  - `codex`    — `codex app-server`, JSON-RPC 2.0 (JSONL) over stdin/stdout;
+ *  - `opencode` — `opencode serve`, HTTP + SSE;
+ *  - `pi`       — pi coding CLI, RPC over JSONL stdin/stdout, selecting its
+ *                 model with `provider/model`.
+ */
+import type { UiEvent } from './ui-events.ts';
+/**
+ * The user-selectable runners (what config/GUI expose), in display order — the SINGLE source of
+ * truth for the set. Every runtime enumeration derives from this tuple (zod schemas, the
+ * server-install "at least one agent CLI" gate, the CLI-handoff registry) rather than repeating
+ * the literals, so adding runner #5 is a one-line change here and typecheck finds the rest.
+ */
+export declare const RUNNER_IDS: readonly ['claude', 'codex', 'opencode', 'pi'];
+/** The user-selectable runners (what config/GUI expose). */
+export type RunnerId = (typeof RUNNER_IDS)[number];
+/** `claude-cli` is the legacy id kept so old run records still parse. */
+export type AgentBackend = RunnerId | 'claude-cli';
+/** Narrow an arbitrary string (a config value, a check name) to a runner id. */
+export declare function isRunnerId(value: string): value is RunnerId;
+export interface AgentRunSpec {
+    /** Appended to the CLI's default system prompt (`--append-system-prompt`). */
+    systemPrompt?: string;
+    userPrompt: string;
+    /** Image blocks delivered with the first user message — screenshots pasted
+     *  into the new-task form (spec 002's paste path, at task start). */
+    images?: ContentBlock[];
+    /** The directory the agent runs in — also the only writable root. */
+    cwd: string;
+    /** Tool allowlist; the CLI is default-deny for anything not listed — but
+     *  the zero-config default (`DEFAULT_ALLOWED_TOOLS`) includes `Bash`
+     *  unrestricted unless `bashAllowlist` is set, so treat the default as
+     *  full shell access in `cwd`, not a sandboxed allowlist (#430). */
+    allowedTools?: string[];
+    /** When `Bash` is allowed, restrict it to commands starting with one of these. */
+    bashAllowlist?: string[];
+    /** Extra directories the agent may read/write besides `cwd`. */
+    additionalDirectories?: string[];
+    /** Extra env vars for the agent process (merged over `process.env`) —
+     *  e.g. XEZ_HANDOFF_FILE / XEZ_TODOS_FILE / XEZ_TASK_ID (spec 007). */
+    env?: Record<string, string>;
+    model?: string;
+    /** Wall-clock kill switch for the run (ms). */
+    timeoutMs?: number;
+    /**
+     * Stable session id (UUID) so the user can take over interactively later:
+     * `cd <repo> && claude --resume <sessionId>`.
+     */
+    sessionId?: string;
+    /**
+     * Spawn `claude --resume <sessionId>` instead of starting a fresh session —
+     * picks up the on-disk conversation (used by "Continue" after a run ends).
+     */
+    resume?: boolean;
+}
+/**
+ * Backends without a dedicated system-prompt channel (codex app-server,
+ * opencode serve) deliver `spec.systemPrompt` as a leading block of the
+ * opening user message — the documented per-backend mapping (spec §protocol
+ * v2: claude = `--append-system-prompt`, codex/opencode = prepended here).
+ */
+export declare function prependSystemPrompt(systemPrompt: string | undefined, userPrompt: string): string;
+/**
+ * True for the `128 + signal` exit codes an agent CLI reports when it handles
+ * a stop signal itself instead of dying from it (SIGINT/SIGKILL/SIGTERM).
+ *
+ * Every runner arms a SIGTERM→SIGKILL watchdog on `end()` and signals on
+ * `interrupt()` (#703): the CLIs install their own handlers, so a session the
+ * runner tore down on purpose comes back as a NON-ZERO exit. Paired with a
+ * "we sent the signal" flag, this predicate keeps that teardown out of the
+ * error path — an exit xezar caused is never an agent failure.
+ */
+export declare function isSignalTerminationExit(exitCode: number | null): boolean;
+/** The slice of `ChildProcess` a termination tracker needs — keeps the helper
+ *  usable from the transport layer and from test fakes alike. */
+export interface TrackableChild {
+    exitCode: number | null;
+    signalCode: NodeJS.Signals | null;
+    once(event: 'exit', listener: () => void): unknown;
+}
+/**
+ * Returns a predicate that answers "has this child actually terminated?".
+ *
+ * `ChildProcess.killed` answers a different question — it flips as soon as a
+ * signal is *delivered*, whether or not the child dies from it. Every agent CLI
+ * installs its own SIGTERM handler, so gating a SIGTERM→SIGKILL watchdog on
+ * `!child.killed` disables the escalation for exactly the child it exists for:
+ * `killed` is true, `exitCode` stays null, and the process outlives the whole
+ * grace window (#844, same defect fixed for the discovery probe in #841).
+ *
+ * Seeded from `exitCode`/`signalCode` so a child that died before the watchdog
+ * was armed is recognized without waiting for an event that already fired.
+ */
+export declare function trackChildExit(child: TrackableChild): () => boolean;
+/** One content block of a user message — mirrors the Anthropic wire format
+ *  so it can be written to the claude CLI's stdin verbatim. */
+export type ContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    source: {
+        type: 'base64';
+        media_type: string;
+        data: string;
+    };
+};
+/** Normalized event stream — the GUI renders these, the store persists them. */
+export type AgentEvent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool-call';
+    id: string;
+    tool: string;
+    input: unknown;
+} | {
+    type: 'tool-result';
+    toolCallId: string;
+    result: string;
+    isError: boolean;
+}
+/** An image inside a tool result (screenshot tools, Read on a PNG…) —
+ *  raw base64 here; the run manager persists it and re-emits a URL. */
+ | {
+    type: 'image';
+    mediaType: string;
+    data: string;
+} | {
+    type: 'token-usage';
+    tokensUsed: number;
+} | {
+    type: 'cost';
+    usd: number;
+}
+/** The backend's real session id, once known — codex threads and opencode
+ *  sessions mint their own id, so the run manager persists this to enable
+ *  resume ("Continue") and "open in CLI". Claude's equals `spec.sessionId`. */
+ | {
+    type: 'session';
+    sessionId: string;
+} | {
+    type: 'turn-end';
+} | {
+    type: 'note';
+    message: string;
+} | {
+    type: 'done';
+} | {
+    type: 'error';
+    message: string;
+};
+export interface AgentToolCallRecord {
+    id: string;
+    name: string;
+    input: unknown;
+}
+export interface AgentRunResult {
+    /** Concatenated assistant text across the run, trimmed. */
+    text: string;
+    toolCalls: AgentToolCallRecord[];
+    /** Cost-weighted token usage; 0 when the backend surfaced no telemetry. */
+    tokensUsed: number;
+    sessionId?: string;
+}
+export interface SessionOptions {
+    /** Close the session shortly after the first turn ends (single-turn
+     *  behavior, used for non-interactive workflow steps). Interactive
+     *  sessions omit this and control `end()` themselves. */
+    autoEndAfterFirstTurn?: boolean;
+    /** Protocol-v2 channel: receives the normalized `UiEvent` stream emitted
+     *  ALONGSIDE the v1 `AgentEvent`s (additive — v1 keeps flowing unchanged).
+     *  RunManager consumption lands in R2 step 2.1. */
+    onUiEvent?: (event: UiEvent) => void;
+}
+/**
+ * A live agent session over one spawned backend process. The process stays
+ * alive between turns and reads further user messages — that's what makes
+ * mid-task follow-ups possible. Implemented identically by every backend
+ * (claude stdin, codex app-server, opencode serve).
+ */
+export interface AgentSession {
+    /** Resolves when the backend process exits — the session is fully over. */
+    result: Promise<AgentRunResult>;
+    /** OS pid of the spawned backend process — the root of the run's process
+     *  tree (agents spawn Bash children under it). Absent when the spawn
+     *  failed before a pid existed. Feeds live resource telemetry (#348). */
+    readonly pid?: number;
+    /** Write a user message into the live session. False when it is closed. */
+    sendMessage(content: ContentBlock[]): boolean;
+    /** Graceful close: end input, then a SIGTERM→SIGKILL watchdog. */
+    end(): void;
+    /** Hard stop (used by cancel). */
+    interrupt(): void;
+    /** True while the session still accepts messages. */
+    readonly open: boolean;
+}
+export interface AgentRunner {
+    readonly backend: AgentBackend;
+    run(spec: AgentRunSpec, onEvent?: (event: AgentEvent) => void): Promise<AgentRunResult>;
+    startSession(spec: AgentRunSpec, onEvent?: (event: AgentEvent) => void, opts?: SessionOptions): AgentSession;
+    interrupt(): Promise<void>;
+}

package/dist/core/agent-runner.js

@@ -0,0 +1,68 @@
+/**
+ * The backend-agnostic seam for running one agent task. Adapted from
+ * @xezar/core's `agents/agent-runner.ts`, trimmed for single-user local use:
+ * no token-budget circuit breaker, no zod response schemas — one run is one
+ * agent-CLI session streaming normalized events.
+ *
+ * Four interchangeable backends implement this seam, each as a persistent
+ * process so multi-turn follow-ups, `waiting`, interrupt and resume all work:
+ *  - `claude`   — Claude Code CLI, stream-json over stdin/stdout;
+ *  - `codex`    — `codex app-server`, JSON-RPC 2.0 (JSONL) over stdin/stdout;
+ *  - `opencode` — `opencode serve`, HTTP + SSE;
+ *  - `pi`       — pi coding CLI, RPC over JSONL stdin/stdout, selecting its
+ *                 model with `provider/model`.
+ */
+/**
+ * The user-selectable runners (what config/GUI expose), in display order — the SINGLE source of
+ * truth for the set. Every runtime enumeration derives from this tuple (zod schemas, the
+ * server-install "at least one agent CLI" gate, the CLI-handoff registry) rather than repeating
+ * the literals, so adding runner #5 is a one-line change here and typecheck finds the rest.
+ */
+export const RUNNER_IDS = ['claude', 'codex', 'opencode', 'pi'];
+/** Narrow an arbitrary string (a config value, a check name) to a runner id. */
+export function isRunnerId(value) {
+    return RUNNER_IDS.includes(value);
+}
+/**
+ * Backends without a dedicated system-prompt channel (codex app-server,
+ * opencode serve) deliver `spec.systemPrompt` as a leading block of the
+ * opening user message — the documented per-backend mapping (spec §protocol
+ * v2: claude = `--append-system-prompt`, codex/opencode = prepended here).
+ */
+export function prependSystemPrompt(systemPrompt, userPrompt) {
+    return systemPrompt ? `${systemPrompt}\n\n---\n\n${userPrompt}` : userPrompt;
+}
+/**
+ * True for the `128 + signal` exit codes an agent CLI reports when it handles
+ * a stop signal itself instead of dying from it (SIGINT/SIGKILL/SIGTERM).
+ *
+ * Every runner arms a SIGTERM→SIGKILL watchdog on `end()` and signals on
+ * `interrupt()` (#703): the CLIs install their own handlers, so a session the
+ * runner tore down on purpose comes back as a NON-ZERO exit. Paired with a
+ * "we sent the signal" flag, this predicate keeps that teardown out of the
+ * error path — an exit xezar caused is never an agent failure.
+ */
+export function isSignalTerminationExit(exitCode) {
+    return exitCode === 130 || exitCode === 137 || exitCode === 143;
+}
+/**
+ * Returns a predicate that answers "has this child actually terminated?".
+ *
+ * `ChildProcess.killed` answers a different question — it flips as soon as a
+ * signal is *delivered*, whether or not the child dies from it. Every agent CLI
+ * installs its own SIGTERM handler, so gating a SIGTERM→SIGKILL watchdog on
+ * `!child.killed` disables the escalation for exactly the child it exists for:
+ * `killed` is true, `exitCode` stays null, and the process outlives the whole
+ * grace window (#844, same defect fixed for the discovery probe in #841).
+ *
+ * Seeded from `exitCode`/`signalCode` so a child that died before the watchdog
+ * was armed is recognized without waiting for an event that already fired.
+ */
+export function trackChildExit(child) {
+    let exited = child.exitCode != null || child.signalCode != null;
+    child.once('exit', () => {
+        exited = true;
+    });
+    return () => exited;
+}
+//# sourceMappingURL=agent-runner.js.map

package/dist/core/agent-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-runner.js","sourceRoot":"","sources":["../../src/core/agent-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,CAAU,CAAC;AAQzE,gFAAgF;AAChF,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAQ,UAAgC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC3D,CAAC;AAsCD;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,YAAgC,EAAE,UAAkB;IACtF,OAAO,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,cAAc,UAAU,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC;AAC/E,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CAAC,QAAuB;IAC7D,OAAO,QAAQ,KAAK,GAAG,IAAI,QAAQ,KAAK,GAAG,IAAI,QAAQ,KAAK,GAAG,CAAC;AAClE,CAAC;AAUD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAAC,KAAqB;IAClD,IAAI,MAAM,GAAG,KAAK,CAAC,QAAQ,IAAI,IAAI,IAAI,KAAK,CAAC,UAAU,IAAI,IAAI,CAAC;IAChE,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE;QACtB,MAAM,GAAG,IAAI,CAAC;IAChB,CAAC,CAAC,CAAC;IACH,OAAO,GAAG,EAAE,CAAC,MAAM,CAAC;AACtB,CAAC"}

package/dist/core/ask.d.ts

@@ -0,0 +1,115 @@
+/**
+ * AskUser payload — the structured multiple-choice question an agent asks the
+ * user, so the cockpit can render clickable option chips instead of the prose
+ * fallback ("AskUserQuestion isn't available…").
+ *
+ * The agent emits this as a `XEZ:ASK <compact-json>` control marker (a sibling
+ * of `XEZ:DONE` / `XEZ:MONITORING`), parsed on the assembled turn text in
+ * `src/workflows/run.ts` — uniform across claude, codex and opencode with no
+ * per-backend mapper work. The shape is modeled 1:1 on Claude Code's built-in
+ * `AskUserQuestion` (1–4 questions, 2–4 options each, `header` ≤12 chars,
+ * unique question texts and unique option labels) so a native bridge can map
+ * onto it later. A free-text "Other" is always available via the composer, so
+ * it is never an explicit option.
+ */
+import { z } from 'zod';
+export declare const askOptionSchema: z.ZodObject<{
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const askQuestionSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    header: z.ZodString;
+    question: z.ZodString;
+    options: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    multiSelect: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const askRequestSchema: z.ZodObject<{
+    questions: z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        header: z.ZodString;
+        question: z.ZodString;
+        options: z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        multiSelect: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type AskOption = z.infer<typeof askOptionSchema>;
+export type AskQuestion = z.infer<typeof askQuestionSchema>;
+export type AskRequest = z.infer<typeof askRequestSchema>;
+export interface AskParseIssue {
+    code: string;
+    path: PropertyKey[];
+    message: string;
+}
+/** The diagnostic parse result used at turn-end. The compatibility wrapper
+ * below deliberately keeps returning `AskRequest | null`. `repaired` marks a
+ * card that only exists because the payload's missing closers were appended
+ * (#936) — callers surface it as a note rather than claiming a clean parse. */
+export type AskMarkerParseResult = {
+    kind: 'none';
+} | {
+    kind: 'invalid-json';
+    message: string;
+} | {
+    kind: 'invalid-structure';
+    issues: AskParseIssue[];
+} | {
+    kind: 'valid';
+    request: AskRequest;
+    normalized: boolean;
+    repaired?: boolean;
+};
+/**
+ * Parse a value into a validated `AskRequest`, or `null` when it does not match
+ * (bad counts, over-length header, non-unique labels/questions, extra keys).
+ * Callers degrade to plain text on `null` — the feature never makes the prose
+ * fallback worse.
+ */
+export declare function parseAskRequest(value: unknown): AskRequest | null;
+/**
+ * The AskUser control marker: a trailing `XEZ:ASK <compact-json>` line (a
+ * sibling of `XEZ:DONE` / `XEZ:MONITORING`). Detected on the *assembled* turn
+ * text so delta-streaming backends can't split it — uniform across all three
+ * backends. The JSON is greedily captured from the first `{` after the keyword
+ * to the last `}` at end-of-text.
+ */
+export declare const ASK_MARKER_RE: RegExp;
+/**
+ * Parse a trailing marker with an actionable result for diagnostics. Two
+ * bounded forgiveness layers sit under the schema, and neither loosens it: a
+ * payload that fails `JSON.parse` only for missing closers is repaired
+ * (`closeUnbalancedJson`, #936), then a parseable near-valid request gets one
+ * normalization pass (`normalizeAskRequest`). Structural violations remain
+ * rejected so the raw fallback stays readable.
+ */
+export declare function parseAskMarkerResult(turnText: string): AskMarkerParseResult;
+/**
+ * Extract and validate a trailing `XEZ:ASK <json>` marker from assembled turn
+ * text. Returns a strict or safely normalized `AskRequest`, or `null` when
+ * there is no marker or its payload remains invalid (caller degrades to plain
+ * text — the prose fallback is never made worse).
+ */
+export declare function parseAskMarker(turnText: string): AskRequest | null;
+/**
+ * Strip a trailing `XEZ:ASK <json>` marker from one text event so transcripts
+ * stay free of protocol noise — but ONLY when the payload actually validates.
+ * An invalid payload never becomes an ask card (`parseAskMarker` → `null`), so
+ * stripping it would delete the agent's question from the transcript with
+ * nothing to replace it; it stays visible as raw text instead — degraded but
+ * answerable (the prose fallback is never made worse). Delta backends may split
+ * the marker across events — then it stays visible; detection on the assembled
+ * turn text is unaffected (same best-effort caveat as the `XEZ:DONE` /
+ * `XEZ:MONITORING` strippers).
+ *
+ * The strip runs from the `XEZ:ASK` keyword to end-of-text rather than to a
+ * trailing `}`: a repaired payload (#936) may end on `]`, or on the last
+ * character before the closers this module appended, and half a marker left
+ * under a rendered card is protocol noise the card already replaced.
+ */
+export declare function stripAskMarker(text: string): string;

package/dist/core/ask.js

@@ -0,0 +1,256 @@
+/**
+ * AskUser payload — the structured multiple-choice question an agent asks the
+ * user, so the cockpit can render clickable option chips instead of the prose
+ * fallback ("AskUserQuestion isn't available…").
+ *
+ * The agent emits this as a `XEZ:ASK <compact-json>` control marker (a sibling
+ * of `XEZ:DONE` / `XEZ:MONITORING`), parsed on the assembled turn text in
+ * `src/workflows/run.ts` — uniform across claude, codex and opencode with no
+ * per-backend mapper work. The shape is modeled 1:1 on Claude Code's built-in
+ * `AskUserQuestion` (1–4 questions, 2–4 options each, `header` ≤12 chars,
+ * unique question texts and unique option labels) so a native bridge can map
+ * onto it later. A free-text "Other" is always available via the composer, so
+ * it is never an explicit option.
+ */
+import { z } from 'zod';
+export const askOptionSchema = z
+    .object({
+    label: z.string().min(1).max(60),
+    description: z.string().max(280).optional(),
+})
+    .strict();
+export const askQuestionSchema = z
+    .object({
+    /** Stable key for the answer; defaults to the array index when omitted. */
+    id: z.string().min(1).max(64).optional(),
+    /** ≤12-char chip label (matches AskUserQuestion's `header`). */
+    header: z.string().min(1).max(12),
+    question: z.string().min(1).max(400),
+    options: z
+        .array(askOptionSchema)
+        .min(2)
+        .max(4)
+        .refine((opts) => new Set(opts.map((o) => o.label)).size === opts.length, {
+        message: 'option labels must be unique within a question',
+    }),
+    multiSelect: z.boolean().optional(),
+})
+    .strict();
+export const askRequestSchema = z
+    .object({
+    questions: z
+        .array(askQuestionSchema)
+        .min(1)
+        .max(4)
+        .refine((qs) => new Set(qs.map((q) => q.question)).size === qs.length, {
+        message: 'question texts must be unique',
+    }),
+})
+    .strict();
+/**
+ * Parse a value into a validated `AskRequest`, or `null` when it does not match
+ * (bad counts, over-length header, non-unique labels/questions, extra keys).
+ * Callers degrade to plain text on `null` — the feature never makes the prose
+ * fallback worse.
+ */
+export function parseAskRequest(value) {
+    const parsed = askRequestSchema.safeParse(value);
+    return parsed.success ? parsed.data : null;
+}
+/**
+ * The AskUser control marker: a trailing `XEZ:ASK <compact-json>` line (a
+ * sibling of `XEZ:DONE` / `XEZ:MONITORING`). Detected on the *assembled* turn
+ * text so delta-streaming backends can't split it — uniform across all three
+ * backends. The JSON is greedily captured from the first `{` after the keyword
+ * to the last `}` at end-of-text.
+ */
+export const ASK_MARKER_RE = /XEZ:ASK[ \t]+(\{[\s\S]*\})\s*$/;
+/** Looser than `ASK_MARKER_RE` so diagnostics can distinguish a malformed
+ * trailing marker from ordinary assistant prose. */
+const ASK_MARKER_CANDIDATE_RE = /XEZ:ASK[ \t]+([\s\S]*)$/;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasOwn(record, key) {
+    return Object.prototype.hasOwnProperty.call(record, key);
+}
+/**
+ * Recover only presentation drift that cannot change the user's available
+ * choices. Unknown keys are discarded, and the display-only header and option
+ * description are clipped to their documented bounds. Counts, required text,
+ * types, and uniqueness remain schema-enforced; questions/options are never
+ * dropped to manufacture validity.
+ */
+function normalizeAskRequest(value) {
+    if (!isRecord(value))
+        return value;
+    const request = {};
+    if (!hasOwn(value, 'questions'))
+        return request;
+    request.questions = Array.isArray(value.questions)
+        ? value.questions.map((question) => {
+            if (!isRecord(question))
+                return question;
+            const normalized = {};
+            for (const key of ['id', 'question', 'multiSelect']) {
+                if (hasOwn(question, key))
+                    normalized[key] = question[key];
+            }
+            if (hasOwn(question, 'header')) {
+                normalized.header =
+                    typeof question.header === 'string' ? question.header.slice(0, 12) : question.header;
+            }
+            if (hasOwn(question, 'options')) {
+                normalized.options = Array.isArray(question.options)
+                    ? question.options.map((option) => {
+                        if (!isRecord(option))
+                            return option;
+                        const next = {};
+                        if (hasOwn(option, 'label'))
+                            next.label = option.label;
+                        if (hasOwn(option, 'description')) {
+                            next.description =
+                                typeof option.description === 'string'
+                                    ? option.description.slice(0, 280)
+                                    : option.description;
+                        }
+                        return next;
+                    })
+                    : question.options;
+            }
+            return normalized;
+        })
+        : value.questions;
+    return request;
+}
+/**
+ * Repair the one syntax slip that actually happens (#936): a payload complete
+ * except for its closing brackets, because an agent hand-writing a long
+ * one-line JSON blob dropped a trailing `}` or the output-token limit cut the
+ * stream. Scan `src` tracking string/escape state and the stack of open
+ * `{` / `[`, then append the missing closers in reverse. Returns `null` when
+ * the text is not *only* missing closers.
+ *
+ * The guards keep a genuinely truncated stream refused rather than silently
+ * turned into a half-question: the payload must end on a **completed**
+ * structural value (`}` or `]` — never mid-string, after a `,`, or after a
+ * `:`), the scan must end outside a string literal, every closer must match its
+ * opener, and at least one opener must still be unclosed (an already-balanced
+ * payload has nothing to repair — it failed `JSON.parse` for some other reason,
+ * e.g. a trailing comma, and stays rejected). Only syntax is repaired: the
+ * result goes through the unchanged `askRequestSchema`, so a repair that yields
+ * fewer than 2 options or a bad header still degrades to plain text.
+ */
+function closeUnbalancedJson(src) {
+    const text = src.trimEnd();
+    if (!/[}\]]$/.test(text))
+        return null;
+    const stack = [];
+    let inString = false;
+    let escaped = false;
+    for (const ch of text) {
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (ch === '\\')
+                escaped = true;
+            else if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (ch === '{')
+            stack.push('}');
+        else if (ch === '[')
+            stack.push(']');
+        else if (ch === '}' || ch === ']') {
+            if (stack.pop() !== ch)
+                return null;
+        }
+    }
+    if (inString || stack.length === 0)
+        return null;
+    return text + stack.reverse().join('');
+}
+function issuesOf(error) {
+    return error.issues.map((issue) => ({
+        code: issue.code,
+        path: issue.path,
+        message: issue.message,
+    }));
+}
+/**
+ * Parse a trailing marker with an actionable result for diagnostics. Two
+ * bounded forgiveness layers sit under the schema, and neither loosens it: a
+ * payload that fails `JSON.parse` only for missing closers is repaired
+ * (`closeUnbalancedJson`, #936), then a parseable near-valid request gets one
+ * normalization pass (`normalizeAskRequest`). Structural violations remain
+ * rejected so the raw fallback stays readable.
+ */
+export function parseAskMarkerResult(turnText) {
+    const match = ASK_MARKER_CANDIDATE_RE.exec(turnText.trimEnd());
+    if (!match || match[1] === undefined)
+        return { kind: 'none' };
+    let raw;
+    let repaired = false;
+    try {
+        raw = JSON.parse(match[1]);
+    }
+    catch (error) {
+        const closed = closeUnbalancedJson(match[1]);
+        try {
+            if (closed === null)
+                throw error;
+            raw = JSON.parse(closed);
+            repaired = true;
+        }
+        catch {
+            return {
+                kind: 'invalid-json',
+                message: error instanceof Error ? error.message : 'invalid JSON',
+            };
+        }
+    }
+    const strict = askRequestSchema.safeParse(raw);
+    if (strict.success)
+        return { kind: 'valid', request: strict.data, normalized: false, repaired };
+    const normalized = askRequestSchema.safeParse(normalizeAskRequest(raw));
+    if (normalized.success)
+        return { kind: 'valid', request: normalized.data, normalized: true, repaired };
+    return { kind: 'invalid-structure', issues: issuesOf(normalized.error) };
+}
+/**
+ * Extract and validate a trailing `XEZ:ASK <json>` marker from assembled turn
+ * text. Returns a strict or safely normalized `AskRequest`, or `null` when
+ * there is no marker or its payload remains invalid (caller degrades to plain
+ * text — the prose fallback is never made worse).
+ */
+export function parseAskMarker(turnText) {
+    const parsed = parseAskMarkerResult(turnText);
+    return parsed.kind === 'valid' ? parsed.request : null;
+}
+/**
+ * Strip a trailing `XEZ:ASK <json>` marker from one text event so transcripts
+ * stay free of protocol noise — but ONLY when the payload actually validates.
+ * An invalid payload never becomes an ask card (`parseAskMarker` → `null`), so
+ * stripping it would delete the agent's question from the transcript with
+ * nothing to replace it; it stays visible as raw text instead — degraded but
+ * answerable (the prose fallback is never made worse). Delta backends may split
+ * the marker across events — then it stays visible; detection on the assembled
+ * turn text is unaffected (same best-effort caveat as the `XEZ:DONE` /
+ * `XEZ:MONITORING` strippers).
+ *
+ * The strip runs from the `XEZ:ASK` keyword to end-of-text rather than to a
+ * trailing `}`: a repaired payload (#936) may end on `]`, or on the last
+ * character before the closers this module appended, and half a marker left
+ * under a rendered card is protocol noise the card already replaced.
+ */
+export function stripAskMarker(text) {
+    if (parseAskMarker(text) === null)
+        return text;
+    return text.replace(/\s*XEZ:ASK[ \t]+[\s\S]*$/, '');
+}
+//# sourceMappingURL=ask.js.map

package/dist/core/ask.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask.js","sourceRoot":"","sources":["../../src/core/ask.ts"],"names":[],"mappings":"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"}