agent-nuvira 3.3.7 → 3.3.9

package/dist/parity/wire-fixtures.js

@@ -0,0 +1,405 @@
+/**
+ * Golden provider-wire fixtures — record/replay guard for the REQUEST we send.
+ *
+ * WHY THIS EXISTS. nuvira's largest failure mode is silent drift on a huge
+ * surface: a tool schema, a message-ordering rule, or a serialization detail
+ * changes and nothing notices, because every existing test asserts on a
+ * RESPONSE (what the engine did) rather than on the REQUEST (what we sent). A
+ * recorded golden request catches exactly that class — "the bytes we put on the
+ * provider wire changed shape" — and it does so deterministically, with no
+ * network and no model.
+ *
+ * HOW IT CAPTURES, WITHOUT A TEST SEAM IN PRODUCTION CODE. A loopback
+ * OpenAI-compatible server stands in for the provider (the same transport-depth
+ * seam `src/parity/drivers.ts` uses). A REAL adapter (`GroqAdapter`) is pointed
+ * at it, and the REAL tool loop drives the adapter. The server records each
+ * request body verbatim. Nothing in `chat.ts`, `tool-loop.ts`, `tools.ts` or the
+ * adapters is modified — the seam is configuration, not a mock.
+ *
+ * WHAT IS NORMALIZED, AND WHY SO LITTLE. The fixture is the request as sent:
+ * model, messages (in order), tool schemas (in order), temperature, max_tokens,
+ * stream. Object keys are sorted so JSON key order is not drift; array order is
+ * PRESERVED because message and tool ordering is exactly the kind of thing this
+ * guard exists to protect. Inputs are fixed by the harness, so the request is
+ * fully deterministic — there is no timestamp or path to scrub.
+ *
+ * ADOPTED FROM claw-code's mock parity harness (`mock-anthropic-service` + 21
+ * captured `/v1/messages` requests), reimplemented for nuvira's loop and wire.
+ */
+import { createServer } from 'node:http';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+import { GroqAdapter } from '../inference/groq-adapter.js';
+import { runToolLoop } from '../tools/tool-loop.js';
+// ─── Locations ──────────────────────────────────────────────────────────────
+/** The committed fixture directory (resolved from this module, not cwd). */
+export const WIRE_FIXTURE_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', 'tests', 'fixtures', 'provider-wire');
+/** A fixture file path for a named case. */
+export function wireFixturePath(name) {
+    return join(WIRE_FIXTURE_DIR, `${name}.json`);
+}
+/** Read a committed fixture, or null when it does not exist yet. */
+export function readWireFixture(name) {
+    try {
+        const path = wireFixturePath(name);
+        if (!existsSync(path))
+            return null;
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Write a fixture (used by the record mode). */
+export function writeWireFixture(name, fixture) {
+    mkdirSync(WIRE_FIXTURE_DIR, { recursive: true });
+    writeFileSync(wireFixturePath(name), `${JSON.stringify(fixture, null, 2)}\n`, 'utf-8');
+}
+/** Every committed fixture case name (sorted), for the check loop. */
+export function listWireFixtures() {
+    try {
+        return readdirSync(WIRE_FIXTURE_DIR)
+            .filter((f) => f.endsWith('.json'))
+            .map((f) => f.slice(0, -'.json'.length))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Recursively sort object keys so JSON key order is never reported as drift.
+ * Arrays keep their order (message/tool ordering IS the contract).
+ */
+export function normalizeWireRequest(value) {
+    if (Array.isArray(value))
+        return value.map((v) => normalizeWireRequest(v));
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            out[key] = normalizeWireRequest(value[key]);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Structural diff of two normalized wire values. Returns [] when identical.
+ * Paths read like `messages[1].tool_calls[0].function.name`, so a failure names
+ * the exact field that drifted rather than dumping two JSON blobs.
+ */
+export function wireDiff(golden, actual, path = '$') {
+    if (golden === actual)
+        return [];
+    if (Array.isArray(golden) || Array.isArray(actual)) {
+        if (!Array.isArray(golden) || !Array.isArray(actual)) {
+            return [{ path, golden, actual }];
+        }
+        if (golden.length !== actual.length) {
+            return [{ path: `${path}.length`, golden: golden.length, actual: actual.length }];
+        }
+        const out = [];
+        for (let i = 0; i < golden.length; i += 1) {
+            out.push(...wireDiff(golden[i], actual[i], `${path}[${i}]`));
+        }
+        return out;
+    }
+    if (golden && actual && typeof golden === 'object' && typeof actual === 'object') {
+        const g = golden;
+        const a = actual;
+        const keys = [...new Set([...Object.keys(g), ...Object.keys(a)])].sort();
+        const out = [];
+        for (const key of keys) {
+            if (!(key in g))
+                out.push({ path: `${path}.${key}`, golden: undefined, actual: a[key] });
+            else if (!(key in a))
+                out.push({ path: `${path}.${key}`, golden: g[key], actual: undefined });
+            else
+                out.push(...wireDiff(g[key], a[key], `${path}.${key}`));
+        }
+        return out;
+    }
+    return [{ path, golden, actual }];
+}
+/**
+ * Start a loopback OpenAI-compatible endpoint that records requests.
+ *
+ * The responder decides what to answer (deterministic, per case). It receives
+ * the parsed body and the number of requests seen so far, so a case can script
+ * "tool call first, final answer after the tool result".
+ */
+export async function startWireRecorder(respond) {
+    const requests = [];
+    const server = createServer((req, res) => {
+        const chunks = [];
+        req.on('data', (c) => chunks.push(c));
+        req.on('end', () => {
+            if (req.url?.endsWith('/models')) {
+                res.writeHead(200, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ data: [{ id: 'wire-stub-model', object: 'model' }] }));
+                return;
+            }
+            if (req.url?.endsWith('/chat/completions')) {
+                let body = {};
+                try {
+                    body = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
+                }
+                catch {
+                    body = {};
+                }
+                const callIndex = requests.length;
+                requests.push(body);
+                const answer = respond(body, callIndex);
+                // A `{ __sse: [...] }` marker means the case is exercising the STREAMING
+                // path (the dashboard typewriter), so answer as a server-sent-event body
+                // exactly the way an OpenAI-compatible provider does.
+                if (answer && typeof answer === 'object' && Array.isArray(answer.__sse)) {
+                    res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache' });
+                    const lines = (answer.__sse)
+                        .map((chunk) => `data: ${JSON.stringify({ choices: [chunk] })}\n\n`)
+                        .join('');
+                    res.end(`${lines}data: [DONE]\n\n`);
+                    return;
+                }
+                res.writeHead(200, { 'content-type': 'application/json' });
+                res.end(JSON.stringify(answer));
+                return;
+            }
+            res.writeHead(404, { 'content-type': 'application/json' });
+            res.end('{}');
+        });
+    });
+    await new Promise((done) => server.listen(0, '127.0.0.1', done));
+    const { port } = server.address();
+    return {
+        baseUrl: `http://127.0.0.1:${port}/v1`,
+        requests: () => requests.map((r) => r),
+        close: () => new Promise((done) => {
+            server.close(() => done());
+        }),
+    };
+}
+// ─── The core-loop cases ────────────────────────────────────────────────────
+/**
+ * The narrow, fixed tool set the core-loop cases expose. Deliberately SMALL:
+ * the fixture is a human-reviewable record of the wire SHAPE (message ordering,
+ * tool_call / tool-result serialization, model params), not a dump of every
+ * schema. Schema-count drift is a different guard.
+ */
+const CASE_TOOL_NAMES = ['read_file', 'run_terminal'];
+/** The fixed opening thread every case starts from. */
+function caseMessages() {
+    return [
+        { role: 'system', content: 'You are a coding agent. Use the tools to complete the task.' },
+        { role: 'user', content: 'Read package.json and report the version.' },
+    ];
+}
+/** A tool-call response asking for `read_file`, then a final answer. */
+function toolThenAnswer(body) {
+    const messages = Array.isArray(body.messages) ? body.messages : [];
+    const toolAlreadyRan = messages.some((m) => m?.role === 'tool');
+    if (!toolAlreadyRan) {
+        return {
+            choices: [
+                {
+                    message: {
+                        content: null,
+                        tool_calls: [
+                            {
+                                id: 'wire_call_1',
+                                type: 'function',
+                                function: { name: 'read_file', arguments: JSON.stringify({ path: 'package.json' }) },
+                            },
+                        ],
+                    },
+                },
+            ],
+        };
+    }
+    return { choices: [{ message: { content: 'The version is 3.3.8.' } }] };
+}
+/**
+ * Capture the exact wire requests the REAL core loop sends, for the committed
+ * cases. Runs entirely in-process against the loopback recorder: a real Groq
+ * adapter, the real `runToolLoop`, a fixed tool set, and a deterministic tool
+ * executor. No network, no model, no API key beyond the stub's dummy.
+ */
+export async function captureCoreLoopRequests() {
+    const out = [];
+    // Case 1 — a tool-calling turn: the first request carries the tool schemas and
+    // the opening thread; the second carries the assistant tool_call and the tool
+    // result. Both are pinned, because both are things that can drift silently.
+    {
+        const recorder = await startWireRecorder((body) => toolThenAnswer(body));
+        const adapter = new GroqAdapter({
+            apiKey: 'wire-stub-key',
+            model: 'wire-stub-model',
+            baseUrl: recorder.baseUrl,
+        });
+        const context = {
+            configManager: {},
+            cwd: process.cwd(),
+            authorizationRequest: 'Read package.json and report the version.',
+        };
+        const deps = {
+            callModel: async (messages, tools) => (await adapter.generateTools(messages, tools)),
+            executeTool: async () => '{\n  "name": "agent-nuvira",\n  "version": "3.3.8"\n}',
+            onEvent: () => { },
+        };
+        try {
+            await runToolLoop({
+                messages: caseMessages(),
+                context,
+                deps,
+                // Narrow the exposed tools so the fixture pins the CORE wire shape
+                // (message ordering, tool_call/tool-result serialization) rather than
+                // the full ~112-schema catalogue, which would make a 300KB fixture no
+                // human can review. Schema-count/shape drift is a separate concern.
+                tools: CASE_TOOL_NAMES,
+                maxSteps: 4,
+                requireVerification: false,
+                requireDeliverable: false,
+            });
+        }
+        finally {
+            await recorder.close();
+        }
+        out.push({
+            case: 'tool-call-roundtrip',
+            proves: 'The core loop puts the tool schemas, the opening thread, the assistant tool_call and the tool result on the wire in this exact shape and order.',
+            requests: recorder.requests().map((r) => normalizeWireRequest(r)),
+        });
+    }
+    // Case 2 — a plain turn (no tools): the request the adapter sends when the loop
+    // finishes without a tool call. Pins model/temperature/max_tokens/stream and
+    // the messages-only body shape.
+    {
+        const recorder = await startWireRecorder(() => ({
+            choices: [{ message: { content: 'Done — no tools needed.' } }],
+        }));
+        const adapter = new GroqAdapter({
+            apiKey: 'wire-stub-key',
+            model: 'wire-stub-model',
+            baseUrl: recorder.baseUrl,
+        });
+        const context = {
+            configManager: {},
+            cwd: process.cwd(),
+            authorizationRequest: 'Say hello.',
+        };
+        const deps = {
+            callModel: async (messages, tools) => (await adapter.generateTools(messages, tools)),
+            executeTool: async () => '',
+            onEvent: () => { },
+        };
+        try {
+            await runToolLoop({
+                messages: [
+                    { role: 'system', content: 'You are a coding agent.' },
+                    { role: 'user', content: 'Say hello.' },
+                ],
+                context,
+                deps,
+                tools: CASE_TOOL_NAMES,
+                maxSteps: 2,
+                requireVerification: false,
+                requireDeliverable: false,
+            });
+        }
+        finally {
+            await recorder.close();
+        }
+        out.push({
+            case: 'plain-turn',
+            proves: 'A tool-less turn still sends the full tool schema set (native tool-calling) with this body shape; model/temperature/max_tokens drift shows up here.',
+            requests: recorder.requests().map((r) => normalizeWireRequest(r)),
+        });
+    }
+    // Case 3 — the STREAMING tool-calling wire (the dashboard answer typewriter).
+    // It adds `stream: true` and `stream_options.include_usage`, and that shape is
+    // exactly the one the dashboard depends on — a change here silently breaks the
+    // typewriter, which no response-side test catches.
+    {
+        const recorder = await startWireRecorder((body) => {
+            const messages = Array.isArray(body.messages) ? body.messages : [];
+            const toolAlreadyRan = messages.some((m) => m?.role === 'tool');
+            // Streaming responses are SSE, not JSON — the recorder's responder returns
+            // a marker the server turns into an SSE body below.
+            return toolAlreadyRan
+                ? { __sse: [{ delta: { content: 'The version is 3.3.8.' } }, { delta: {}, finish_reason: 'stop' }] }
+                : {
+                    __sse: [
+                        {
+                            delta: {
+                                tool_calls: [
+                                    {
+                                        index: 0,
+                                        id: 'wire_call_1',
+                                        type: 'function',
+                                        function: { name: 'read_file', arguments: '{"path":"package.json"}' },
+                                    },
+                                ],
+                            },
+                        },
+                        { delta: {}, finish_reason: 'tool_calls' },
+                    ],
+                };
+        });
+        const adapter = new GroqAdapter({
+            apiKey: 'wire-stub-key',
+            model: 'wire-stub-model',
+            baseUrl: recorder.baseUrl,
+        });
+        const context = {
+            configManager: {},
+            cwd: process.cwd(),
+            authorizationRequest: 'Read package.json and report the version.',
+        };
+        const deps = {
+            callModel: async (messages, tools, onToken) => (await adapter.generateToolsStream(messages, tools, undefined, onToken ?? (() => { }))),
+            executeTool: async () => '{\n  "name": "agent-nuvira",\n  "version": "3.3.8"\n}',
+            onEvent: () => { },
+        };
+        try {
+            await runToolLoop({
+                messages: caseMessages(),
+                context,
+                deps,
+                tools: CASE_TOOL_NAMES,
+                maxSteps: 4,
+                requireVerification: false,
+                requireDeliverable: false,
+            });
+        }
+        finally {
+            await recorder.close();
+        }
+        out.push({
+            case: 'streaming-tool-call',
+            proves: 'The streaming path sends stream:true and stream_options.include_usage with this body — the dashboard typewriter depends on it.',
+            requests: recorder.requests().map((r) => normalizeWireRequest(r)),
+        });
+    }
+    // Case 4 — the plain `generate()` wire (non-tool path used by single-shot
+    // calls and the plan/reasoner prompts). Pins the messages-only body shape.
+    {
+        const recorder = await startWireRecorder(() => ({
+            choices: [{ message: { content: 'Hello.' } }],
+        }));
+        const adapter = new GroqAdapter({
+            apiKey: 'wire-stub-key',
+            model: 'wire-stub-model',
+            baseUrl: recorder.baseUrl,
+        });
+        await adapter.generate('Say hello.');
+        await recorder.close();
+        out.push({
+            case: 'plain-generate',
+            proves: 'The non-tool generate() path sends this body shape (single user message, no tools); the plan/reasoner single-shot calls depend on it.',
+            requests: recorder.requests().map((r) => normalizeWireRequest(r)),
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=wire-fixtures.js.map

package/dist/parity/wire-fixtures.js.map

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

package/dist/tools/artifact-append.d.ts

@@ -33,6 +33,29 @@ export declare function extractToolArtifact(text: string): {
     artifact: ToolArtifact;
     result: string;
 } | null;
+/**
+ * A deliverable a PRODUCER describes: everything a tool knows about what it
+ * made, with the bookkeeping fields optional (filled by `recordArtifact`).
+ */
+export type ArtifactDraft = Omit<ToolArtifact, 'id' | 'createdAt' | 'source'> & {
+    id?: string;
+    createdAt?: number;
+    source?: ToolArtifact['source'];
+};
+/**
+ * Record a deliverable directly on the session's artifact sink.
+ *
+ * The `{artifact, result}` payload contract works for a tool that can wrap its
+ * whole result, but most tools return prose the model must read verbatim
+ * (`write_file: created 'src/x.ts' (412 chars).`) — rewriting those into JSON
+ * just to register a deliverable would change every caller's output. This is
+ * the other half: a tool that ALREADY has the deliverable (the path it wrote,
+ * the file it generated) hands it over directly and returns its text unchanged.
+ *
+ * No-op without a sink (the CLI, a unit test, a pure run) and never throws —
+ * exactly the guarantees the payload path makes.
+ */
+export declare function recordArtifact(sink: ArtifactSink | undefined, artifact: ArtifactDraft): void;
 /**
  * Append an extracted artifact to the sink and return the CLEAN result text.
  * A non-payload result is returned unchanged. This is the tool-loop hook.

package/dist/tools/artifact-append.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"artifact-append.d.ts","sourceRoot":"","sources":["../../src/tools/artifact-append.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,EAAqC,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AA2B9G;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAiDnG;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,MAAM,CAK5E;AAID,6DAA6D;AAC7D,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAE9C;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,SAA6B,GAAG,MAAM,GAAG,SAAS,CAoB/G"}
+{"version":3,"file":"artifact-append.d.ts","sourceRoot":"","sources":["../../src/tools/artifact-append.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,EAAqC,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AA2B9G;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAiDnG;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,EAAE,IAAI,GAAG,WAAW,GAAG,QAAQ,CAAC,GAAG;IAC9E,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;CACjC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,SAAS,EAAE,QAAQ,EAAE,aAAa,GAAG,IAAI,CAY5F;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,MAAM,CAK5E;AAID,6DAA6D;AAC7D,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAE9C;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,SAA6B,GAAG,MAAM,GAAG,SAAS,CAoB/G"}

package/dist/tools/artifact-append.js

@@ -113,6 +113,34 @@ export function extractToolArtifact(text) {
         return { artifact, result: resultText };
     }
 }
+/**
+ * Record a deliverable directly on the session's artifact sink.
+ *
+ * The `{artifact, result}` payload contract works for a tool that can wrap its
+ * whole result, but most tools return prose the model must read verbatim
+ * (`write_file: created 'src/x.ts' (412 chars).`) — rewriting those into JSON
+ * just to register a deliverable would change every caller's output. This is
+ * the other half: a tool that ALREADY has the deliverable (the path it wrote,
+ * the file it generated) hands it over directly and returns its text unchanged.
+ *
+ * No-op without a sink (the CLI, a unit test, a pure run) and never throws —
+ * exactly the guarantees the payload path makes.
+ */
+export function recordArtifact(sink, artifact) {
+    if (!sink)
+        return;
+    try {
+        sink.push({
+            ...artifact,
+            id: artifact.id ?? randomUUID(),
+            source: artifact.source ?? 'tool',
+            createdAt: artifact.createdAt ?? Date.now(),
+        });
+    }
+    catch {
+        /* best-effort — persistence must never break the tool that produced it */
+    }
+}
 /**
  * Append an extracted artifact to the sink and return the CLEAN result text.
  * A non-payload result is returned unchanged. This is the tool-loop hook.

package/dist/tools/artifact-append.js.map

@@ -1 +1 @@
-{"version":3,"file":"artifact-append.js","sourceRoot":"","sources":["../../src/tools/artifact-append.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,cAAc,EAA2D,MAAM,qBAAqB,CAAC;AAE9G,+EAA+E;AAE/E,8EAA8E;AAC9E,SAAS,aAAa,CAAC,IAAY,EAAE,KAAa;IAChD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,KAAK,IAAI,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACnB,IAAI,QAAQ,EAAE,CAAC;YACb,IAAI,OAAO;gBAAE,OAAO,GAAG,KAAK,CAAC;iBACxB,IAAI,EAAE,KAAK,IAAI;gBAAE,OAAO,GAAG,IAAI,CAAC;iBAChC,IAAI,EAAE,KAAK,GAAG;gBAAE,QAAQ,GAAG,KAAK,CAAC;YACtC,SAAS;QACX,CAAC;QACD,IAAI,EAAE,KAAK,GAAG;YAAE,QAAQ,GAAG,IAAI,CAAC;aAC3B,IAAI,EAAE,KAAK,GAAG;YAAE,KAAK,EAAE,CAAC;aACxB,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YACpB,KAAK,EAAE,CAAC;YACR,IAAI,KAAK,KAAK,CAAC;gBAAE,OAAO,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IACD,OAAO,CAAC,CAAC,CAAC;AACZ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,SAAS,CAAC;QACR,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;QAC5C,IAAI,KAAK,KAAK,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QAC9B,MAAM,GAAG,GAAG,aAAa,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACvC,IAAI,GAAG,KAAK,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QAC5B,UAAU,GAAG,KAAK,GAAG,CAAC,CAAC;QAEvB,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QAClD,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,CAAC,0CAA0C;QACtD,CAAC;QACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;YAAE,SAAS;QAC5D,MAAM,GAAG,GAAG,MAAiC,CAAC;QAC9C,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ;YAAE,SAAS;QAChE,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS;YAAE,SAAS;QAEvC,MAAM,CAAC,GAAG,GAAG,CAAC,QAAmC,CAAC;QAClD,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC;QACpB,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;QACtB,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC;QACpB,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YACnF,SAAS;QACX,CAAC;QAED,MAAM,QAAQ,GAAiB;YAC7B,EAAE,EAAE,OAAO,CAAC,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE;YAClD,IAAI;YACJ,KAAK;YACL,IAAI;YACJ,IAAI,EAAE,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;YACrD,SAAS,EAAE,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;YACpE,OAAO,EAAE,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;YAC9D,MAAM,EAAE,CAAC,CAAC,MAAM,KAAK,OAAO,IAAI,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;YACzE,SAAS,EAAE,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;SACtE,CAAC;QACF,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;QAC1B,MAAM,UAAU,GACd,OAAO,MAAM,KAAK,QAAQ;YACxB,CAAC,CAAC,MAAM;YACR,CAAC,CAAC,OAAO,MAAM,KAAK,QAAQ;gBAC1B,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;gBACxB,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACvB,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAC1C,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY,EAAE,IAAmB;IAClE,MAAM,MAAM,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;IACzC,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC5B,OAAO,MAAM,CAAC,MAAM,CAAC;AACvB,CAAC;AAED,+EAA+E;AAE/E,6DAA6D;AAC7D,MAAM,CAAC,MAAM,0BAA0B,GAAG,GAAG,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAgB,EAAE,QAAQ,GAAG,0BAA0B;IACzF,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAC9B,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE;YAAE,OAAO,SAAS,CAAC;QACnC,gEAAgE;QAChE,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,QAAQ,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC;QAC1D,MAAM,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QACvC,MAAM,EAAE,GAAG,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QACnC,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,QAAQ,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;YAC9C,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YACtD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;YACxC,MAAM,SAAS,GAAG,KAAK,GAAG,EAAE,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC;YAC5D,OAAO,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;QAC7C,CAAC;gBAAS,CAAC;YACT,SAAS,CAAC,EAAE,CAAC,CAAC;QAChB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}
+{"version":3,"file":"artifact-append.js","sourceRoot":"","sources":["../../src/tools/artifact-append.ts"],"names":[],"mappings":"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"}

package/dist/tools/ask-user.d.ts

@@ -7,6 +7,11 @@
  * Injectable via ToolContext.askUser so tests never touch a real TTY.
  */
 import type { AskUserAnswer, AskUserChoice } from './registry.js';
+/**
+ * C1 — the label of the "type my own answer" choice appended to every ask_user
+ * list. Exported so surfaces and tests agree on the exact wording.
+ */
+export declare const OTHER_CHOICE_LABEL = "\u270F\uFE0F Other \u2014 type my own answer";
 /**
  * Render an in-loop clarification.
  *

package/dist/tools/ask-user.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ask-user.d.ts","sourceRoot":"","sources":["../../src/tools/ask-user.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAElE;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,aAAa,EAAE,EACxB,WAAW,EAAE,OAAO,GACnB,OAAO,CAAC,aAAa,CAAC,CA+DxB"}
+{"version":3,"file":"ask-user.d.ts","sourceRoot":"","sources":["../../src/tools/ask-user.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAElE;;;GAGG;AACH,eAAO,MAAM,kBAAkB,iDAAkC,CAAC;AAElE;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,aAAa,EAAE,EACxB,WAAW,EAAE,OAAO,GACnB,OAAO,CAAC,aAAa,CAAC,CAyFxB"}

package/dist/tools/ask-user.js

@@ -8,6 +8,11 @@
  */
 import inquirer from 'inquirer';
 import { logger } from '../utils/logger.js';
+/**
+ * C1 — the label of the "type my own answer" choice appended to every ask_user
+ * list. Exported so surfaces and tests agree on the exact wording.
+ */
+export const OTHER_CHOICE_LABEL = '✏️ Other — type my own answer';
 /**
  * Render an in-loop clarification.
  *
@@ -52,13 +57,21 @@ export async function renderAskUser(question, choices, multiSelect) {
                 'if you would prefer something else"), then continue with that assumption.',
         };
     }
+    // C1 — the model offers 2–4 choices, but the user's real answer is sometimes
+    // none of them. Without this the only ways out were picking a wrong option or
+    // Skip; the `custom` field was plumbed end-to-end (AskUserAnswer.custom →
+    // registry → dashboard `chatRespond`) yet no surface ever let a human type one.
+    const other = {
+        label: OTHER_CHOICE_LABEL,
+        description: 'type an answer that is not in the list',
+    };
     const prompt = multiSelect
         ? {
             type: 'checkbox',
             name: 'answer',
             message: 'Select all that apply (space to toggle, Enter to confirm):',
             prefix: '🔀',
-            choices: choices.map((c) => ({ name: c.label, value: c.label })),
+            choices: [...choices, other].map((c) => ({ name: c.label, value: c.label })),
             pageSize: 8,
         }
         : {
@@ -66,19 +79,52 @@ export async function renderAskUser(question, choices, multiSelect) {
             name: 'answer',
             message: 'Choose one:',
             prefix: '🔀',
-            choices: choices.map((c) => ({
+            choices: [...choices, other].map((c) => ({
                 name: c.description ? `${c.label} — ${c.description}` : c.label,
                 value: c.label,
             })),
-            pageSize: 8,
+            pageSize: 9,
         };
     const { answer } = await inquirer.prompt(prompt);
     console.log('');
-    const labels = Array.isArray(answer) ? answer : [answer];
+    // Single-select "Other": ask for the free text and return it as the answer.
+    if (!multiSelect && answer === OTHER_CHOICE_LABEL) {
+        const typed = await promptForCustomText();
+        if (!typed) {
+            // An empty entry is a decline, not an answer of "other").
+            return { answer: '', index: -1 };
+        }
+        return { answer: typed, index: -1, custom: typed };
+    }
+    const labels = (Array.isArray(answer) ? answer : [answer]).filter((l) => l !== OTHER_CHOICE_LABEL);
     const indices = labels.map((label) => choices.findIndex((c) => c.label === label));
+    // Multi-select "Other": the typed text joins the selection.
+    let custom;
+    if (multiSelect && (Array.isArray(answer) ? answer : [answer]).includes(OTHER_CHOICE_LABEL)) {
+        custom = await promptForCustomText();
+    }
+    const finalLabels = custom ? [...labels, custom] : labels;
     return {
-        answer,
+        answer: multiSelect ? finalLabels : finalLabels[0] ?? '',
         index: multiSelect ? indices : indices[0] ?? -1,
+        ...(custom ? { custom } : {}),
     };
 }
+/** Ask for the free-text answer behind the "Other" choice. */
+async function promptForCustomText() {
+    try {
+        const { text } = await inquirer.prompt([
+            {
+                type: 'input',
+                name: 'text',
+                message: 'Type your answer (Enter to skip):',
+                prefix: '✏️',
+            },
+        ]);
+        return String(text ?? '').trim();
+    }
+    catch {
+        return '';
+    }
+}
 //# sourceMappingURL=ask-user.js.map

package/dist/tools/ask-user.js.map

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