@qodeca/xezar 0.10.1

package/dist/core/claude-model-catalog.js

@@ -0,0 +1,208 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { z } from 'zod';
+import { buildChildEnv } from './agent-env.js';
+import { readNdjson } from './ndjson.js';
+import { resolveClaudeExecutable } from './claude-cli-runner.js';
+/**
+ * One entry of the CLI's `list_models` answer. `value` is what `--model` accepts (an alias like
+ * `sonnet`, a pinned id like `claude-fable-5`, or a context-window variant like `opus[1m]`);
+ * `resolvedModel` is what that currently resolves to and is deliberately NOT surfaced — pinning
+ * xezar to a resolved id would re-create the drift this issue is about. Unknown fields pass
+ * through so a CLI that grows the payload does not fail the whole discovery.
+ */
+const modelSchema = z
+    .object({
+    value: z.string(),
+    displayName: z.string().optional(),
+    description: z.string().optional(),
+})
+    .passthrough();
+const listModelsSchema = z.object({ models: z.array(modelSchema) }).passthrough();
+const controlResponseSchema = z.object({
+    type: z.literal('control_response'),
+    response: z
+        .object({
+        subtype: z.string(),
+        request_id: z.string().optional(),
+        response: z.unknown().optional(),
+        error: z.string().optional(),
+    })
+        .passthrough(),
+});
+/**
+ * Wall-clock budget for one discovery. Generous next to Codex's 5 s because the Claude CLI has
+ * to boot a full session host (measured ~5.6 s cold on a developer laptop) before it will answer
+ * a control request.
+ */
+const DEFAULT_DISCOVERY_TIMEOUT_MS = 15_000;
+/** Defensive cap — a catalog this long is a malfunction, not a rollout. */
+const MAX_MODELS = 200;
+/** Grace between closing stdin and SIGTERM, then between SIGTERM and SIGKILL. */
+export const TERM_GRACE_MS = 2_000;
+export const KILL_GRACE_MS = 2_000;
+const REQUEST_ID = 'xez-list-models-1';
+/**
+ * The `value` that stands for "whatever the CLI would pick on its own". xezar already spells that
+ * `auto` (no `--model` flag at all), so surfacing the CLI's own entry too would put two rows in
+ * the picker meaning the same thing — and `default` is a picker token, not necessarily something
+ * `--model` accepts.
+ */
+const IMPLICIT_DEFAULT_VALUE = 'default';
+/**
+ * Spawn flags for a discovery probe. `--print` + stream-json is the same headless transport the
+ * runner uses, so the control channel is available; `--safe-mode` keeps a probe from executing
+ * the user's SessionStart hooks, MCP servers and plugins (discovery must not have side effects,
+ * and it needs none of them), while leaving auth and model selection — the only things it asks
+ * about — working normally. `--no-session-persistence` keeps a probe out of the resume picker.
+ */
+const DISCOVERY_ARGS = [
+    '--print',
+    '--input-format',
+    'stream-json',
+    '--output-format',
+    'stream-json',
+    '--verbose',
+    '--safe-mode',
+    '--no-session-persistence',
+];
+function spawnClaudeProbe(bin, cwd) {
+    return nodeSpawn(bin, DISCOVERY_ARGS, {
+        cwd,
+        env: buildChildEnv({ backend: 'claude' }),
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+}
+/**
+ * Discover the model catalog the host's authenticated Claude Code CLI actually offers.
+ *
+ * The CLI answers a `list_models` control request over the same stream-json channel the runner
+ * already speaks, which makes it the Claude counterpart of the Codex app-server's `model/list`.
+ * The probe never starts a turn,
+ * so it costs no tokens; it is bounded by a deadline and always terminates its child.
+ *
+ * Every failure — no CLI, a CLI too old to know `list_models`, not logged in, a malformed answer,
+ * a timeout — throws, so `RunnerModelCatalog` degrades to `unavailable` and the picker falls back
+ * to the static tier aliases rather than showing an empty list.
+ */
+export async function discoverClaudeModels(options) {
+    const child = (options.spawn ?? spawnClaudeProbe)(resolveClaudeExecutable(options.bin), options.cwd);
+    // A probe reads only stdout, but an undrained stderr pipe fills and wedges the child, and an
+    // unhandled stream `error` would take the whole server down with it.
+    child.stderr.resume();
+    child.stderr.on('error', () => { });
+    child.stdin.on('error', () => { });
+    const timeoutMs = options.timeoutMs ?? DEFAULT_DISCOVERY_TIMEOUT_MS;
+    let timeout;
+    try {
+        return await Promise.race([
+            readCatalog(child),
+            childFailure(child),
+            new Promise((_, reject) => {
+                timeout = setTimeout(() => reject(new Error('Claude model discovery timed out')), timeoutMs);
+                timeout.unref?.();
+            }),
+        ]);
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+        endClaudeProbe(child);
+    }
+}
+/** Rejects when the child dies before answering — a missing binary or an immediate exit. */
+function childFailure(child) {
+    return new Promise((_, reject) => {
+        child.once('error', () => reject(new Error('Claude model discovery child failed')));
+        child.once('exit', (code) => reject(new Error(`Claude model discovery child exited (${code ?? 'unknown'})`)));
+    });
+}
+async function readCatalog(child) {
+    try {
+        child.stdin.write(`${JSON.stringify({
+            type: 'control_request',
+            request_id: REQUEST_ID,
+            request: { subtype: 'list_models' },
+        })}\n`);
+    }
+    catch {
+        throw new Error('Claude model discovery could not reach the CLI');
+    }
+    for await (const line of readNdjson(child.stdout)) {
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            throw new Error('Claude model discovery returned malformed NDJSON');
+        }
+        // The CLI interleaves session/hook chatter with control traffic; ignore everything that is
+        // not the answer to our own request rather than guessing at the stream's shape.
+        const parsed = controlResponseSchema.safeParse(message);
+        if (!parsed.success)
+            continue;
+        const { response } = parsed.data;
+        if (response.request_id !== undefined && response.request_id !== REQUEST_ID)
+            continue;
+        if (response.subtype !== 'success') {
+            // An older CLI answers `Unsupported control request subtype: list_models` here. That is an
+            // unavailable catalog, not a broken xezar — the reason is never surfaced verbatim.
+            throw new Error('Claude model discovery is unsupported by this CLI');
+        }
+        return toModelOptions(response.response);
+    }
+    throw new Error('Claude model discovery ended without an answer');
+}
+function toModelOptions(payload) {
+    const parsed = listModelsSchema.safeParse(payload);
+    if (!parsed.success)
+        throw new Error('Claude model discovery returned malformed model data');
+    const models = [];
+    const ids = new Set();
+    for (const model of parsed.data.models) {
+        const id = model.value.trim();
+        if (!id || id === IMPLICIT_DEFAULT_VALUE || ids.has(id))
+            continue;
+        if (models.length >= MAX_MODELS)
+            throw new Error('Claude model discovery exceeded the size limit');
+        ids.add(id);
+        models.push({
+            id,
+            label: model.displayName?.trim() || id,
+            description: model.description?.trim() ?? '',
+        });
+    }
+    // A CLI that answers with lines but nothing usable is a protocol mismatch, not an account with
+    // no models — report it as unavailable so the static aliases keep the picker working.
+    if (models.length === 0)
+        throw new Error('Claude model discovery returned no usable models');
+    return models;
+}
+/** Close stdin, then escalate TERM → KILL so a wedged probe can never outlive its request. */
+function endClaudeProbe(child) {
+    try {
+        child.stdin.end();
+    }
+    catch {
+        // already gone
+    }
+    // `child.killed` only says a signal was *delivered* — Node flips it as soon as SIGTERM is sent,
+    // long before (and even if never) the child dies. Gating escalation on it would let a probe that
+    // ignores SIGTERM outlive the whole window, so track the actual termination instead.
+    let exited = child.exitCode != null || child.signalCode != null;
+    child.once('exit', () => {
+        exited = true;
+    });
+    const term = setTimeout(() => {
+        if (exited)
+            return;
+        child.kill('SIGTERM');
+        const kill = setTimeout(() => {
+            if (exited)
+                return;
+            child.kill('SIGKILL');
+        }, KILL_GRACE_MS);
+        kill.unref?.();
+    }, TERM_GRACE_MS);
+    term.unref?.();
+}
+//# sourceMappingURL=claude-model-catalog.js.map

package/dist/core/claude-model-catalog.js.map

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

package/dist/core/claude-ui-mapper.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Pure claude stream-json → protocol-v2 mapper. `mapClaudeMessage` folds one
+ * parsed NDJSON stdout line into `UiEvent`s plus the next mapper state; the
+ * runner calls it ALONGSIDE the v1 path (v1 events keep flowing unchanged).
+ *
+ * Contract: `AGENT_PROTOCOL.md` §4 (per-backend mapping). Golden
+ * fixtures replaying real wire shapes live in `__fixtures__/claude/`.
+ *
+ * Robustness rule: input is untrusted wire data — the mapper never throws;
+ * unknown message/block types map to zero events.
+ *
+ * State is explicit and treated as immutable: callers thread the returned
+ * `state` into the next call. Item ids are deterministic — tool items reuse
+ * the wire `tool_use` id; text/thinking blocks (which have no wire id) get
+ * sequential `item_<n>` ids, turns get `turn_<n>` — so replaying a stored
+ * transcript reproduces the exact event sequence.
+ *
+ * Plan/task rule: task ids are the harness's, and it only ever reports them in
+ * tool RESULT text (`Task #3 created successfully: …`, `#3 [pending] …`), never
+ * in the call. So a `TaskCreate` parks until its result lands. Inferring ids by
+ * counting creates looks equivalent and is not: `--resume` reopens a session
+ * whose list is already at 1..N while a fresh mapper state starts at zero, and
+ * the two id spaces then drift silently — updates land on the wrong row.
+ */
+import type { PlanEntry, UiEvent, UiToolItem } from './ui-events.ts';
+export interface ClaudeUiMapperState {
+    /** Used when `system/init` lacks `session_id` (the dry-run mock does). */
+    readonly fallbackSessionId?: string;
+    /** True once `system/init` produced `session.started`. */
+    readonly sessionStarted: boolean;
+    /** Turns begun before init arrived — their `turn.started` is queued so
+     *  `session.started` stays the first event on the wire. */
+    readonly pendingTurnIds: readonly string[];
+    readonly turnSeq: number;
+    readonly currentTurnId: string | null;
+    readonly itemSeq: number;
+    /** True once any assistant `text` block minted a message item. SESSION-scoped,
+     *  never reset per turn — it mirrors `ctx.textChunks` in claude-cli-runner.ts,
+     *  which is allocated once per `runAgent` and accumulates across turns. When a
+     *  session streams no text block at all, the runner falls back to emitting the
+     *  v1 `text` from `msg.result` (`textChunks.length === 0`), and `mapResult`
+     *  must mint the v2 twin under the SAME guard — otherwise that prose exists
+     *  only in v1 and the cockpit's "v2 wins per turn" dedup drops it with no
+     *  replacement, which is exactly the vanishing-message bug. */
+    readonly sawAssistantText: boolean;
+    /** `tool_use` items awaiting their `tool_result`, keyed by tool_use id. */
+    readonly openTools: ReadonlyMap<string, UiToolItem>;
+    /** The running plan built incrementally by Claude's task tools, keyed by the
+     *  task id the harness assigned — read from the `TaskCreate` result, never
+     *  guessed (see `applyTaskCreateResult`). */
+    readonly tasks: ReadonlyMap<string, PlanEntry>;
+    /** `TaskCreate` calls whose result has not arrived yet, keyed by tool_use id.
+     *  The entry parks here until the result reveals its real id. */
+    readonly pendingTaskCreates: ReadonlyMap<string, PlanEntry>;
+}
+export interface ClaudeUiMapping {
+    events: UiEvent[];
+    state: ClaudeUiMapperState;
+}
+export declare function createClaudeUiState(opts?: {
+    fallbackSessionId?: string;
+}): ClaudeUiMapperState;
+/**
+ * Claude has no wire-level turn-start — the runner writing a user message to
+ * stdin IS the turn boundary, so the runner calls this on each send. Until
+ * `init` arrives the event is queued (the seed message is written before the
+ * first stdout line is read).
+ */
+export declare function claudeTurnStarted(state: ClaudeUiMapperState): ClaudeUiMapping;
+/** Fold one parsed stream-json message into v2 events. Never throws. */
+export declare function mapClaudeMessage(msg: unknown, state: ClaudeUiMapperState): ClaudeUiMapping;
+/** Flatten a `tool_result.content` (string or block array) to display text.
+ *  Image blocks become a placeholder — they ride as their own events. */
+export declare function stringifyToolResultContent(content: unknown): string;
+/** base64 image blocks inside a tool_result's content, if any. */
+export declare function toolResultImageBlocks(content: unknown): Array<{
+    media_type: string;
+    data: string;
+}>;