logisheets-logician 1.15.0 → 1.16.0

package/dist/agent/loop.d.ts

@@ -50,10 +50,16 @@ export interface LlmResponse {
         cache_read_input_tokens?: number;
     };
 }
+/**
+ * The one call the loop makes. Implementations translate to their wire format
+ * and back; a rejected promise (network, HTTP error, abort) propagates out of
+ * `Agent.runTurn` / `askAi` unchanged — neither retries.
+ */
 export interface LlmClient {
     createMessage(params: LlmCreateMessageParams): Promise<LlmResponse>;
 }
 export interface AgentOptions {
+    /** Must already hold the conversation `runTurn` is called with. */
     store: ConversationStore;
     registry: ToolRegistry;
     llm: LlmClient;
@@ -62,11 +68,22 @@ export interface AgentOptions {
     model?: string;
     /** Cap on tokens per response. Default 4096. */
     max_tokens?: number;
-    /** Base system prompt (instructions). Tool listing is auto-appended. */
+    /**
+     * System prompt, sent verbatim as the only system block. Tools travel in
+     * the request's `tools` field, not in this text.
+     */
     systemPrompt: string;
-    /** Defensive cap on tool calls per user turn to prevent runaway loops. */
+    /**
+     * Defensive cap on LLM round-trips per user turn (not individual tool
+     * calls — one response may hold several). Default 16. The check runs
+     * before each request as `iter++ > cap`, so up to cap + 1 requests go out.
+     */
     max_tool_iterations?: number;
-    /** Confirmation prompt for tools whose policy demands it. */
+    /**
+     * Confirmation prompt for tools whose policy demands it. Omitted means
+     * auto-approve everything, which suits tests and trusted headless hosts
+     * only. `'once'` is passed through as-is; remembering it is on the host.
+     */
     confirm?: (toolName: string, input: unknown, policy: 'once' | 'always' | 'destructive') => Promise<{
         approved: boolean;
         reason?: string;
@@ -78,6 +95,11 @@ export interface AgentOptions {
      *  overlay-widget state. Omit on headless hosts. */
     craftInteractions?: CraftInteractionsApi;
 }
+/**
+ * One agent bound to one workbook, store and registry. Reusable across
+ * conversations and turns; holds no per-conversation state of its own —
+ * everything is re-read from the store before each LLM request.
+ */
 export declare class Agent {
     private store;
     private registry;
@@ -94,6 +116,16 @@ export declare class Agent {
     /**
      * Run one user turn end-to-end: append the user_message, then loop
      * LLM ↔ tools until the model emits end_turn or we hit a safety cap.
+     *
+     * Requires `conversation_id` to exist in the store (create it first;
+     * `MemoryConversationStore.appendEvent` throws otherwise). Results arrive
+     * as appended events, not as a return value — subscribe to the store or
+     * re-list its events to render them.
+     *
+     * Failure: tool errors and declined confirmations become `tool_result`
+     * events and the loop continues; an `LlmClient` or store rejection
+     * propagates and ends the turn. Hitting the cap, max_tokens, or an abort
+     * seen at the top of the loop ends it with a `ui_only` system_note.
      */
     runTurn(conversation_id: string, userText: string, signal?: AbortSignal): Promise<void>;
     private executeToolCall;

package/dist/agent/loop.js

@@ -18,6 +18,11 @@
  * and lets us test it without a network.
  */
 import { toLlmMessages, } from '../projection.js';
+/**
+ * One agent bound to one workbook, store and registry. Reusable across
+ * conversations and turns; holds no per-conversation state of its own —
+ * everything is re-read from the store before each LLM request.
+ */
 export class Agent {
     constructor(opts) {
         var _a, _b, _c, _d, _e;
@@ -31,14 +36,23 @@ export class Agent {
         this.maxToolIters = (_c = opts.max_tool_iterations) !== null && _c !== void 0 ? _c : 16;
         // Default confirm: auto-approve. Browser host overrides with a
         // real modal. CLI host can override with stdin prompt.
-        this.confirm =
-            (_d = opts.confirm) !== null && _d !== void 0 ? _d : (async () => ({ approved: true }));
+        this.confirm = (_d = opts.confirm) !== null && _d !== void 0 ? _d : (async () => ({ approved: true }));
         this.log = (_e = opts.log) !== null && _e !== void 0 ? _e : (() => { });
         this.craftInteractions = opts.craftInteractions;
     }
     /**
      * Run one user turn end-to-end: append the user_message, then loop
      * LLM ↔ tools until the model emits end_turn or we hit a safety cap.
+     *
+     * Requires `conversation_id` to exist in the store (create it first;
+     * `MemoryConversationStore.appendEvent` throws otherwise). Results arrive
+     * as appended events, not as a return value — subscribe to the store or
+     * re-list its events to render them.
+     *
+     * Failure: tool errors and declined confirmations become `tool_result`
+     * events and the loop continues; an `LlmClient` or store rejection
+     * propagates and ends the turn. Hitting the cap, max_tokens, or an abort
+     * seen at the top of the loop ends it with a `ui_only` system_note.
      */
     async runTurn(conversation_id, userText, signal) {
         const userEvent = {
@@ -50,9 +64,10 @@ export class Agent {
         };
         await this.store.appendEvent(userEvent);
         const blobResolver = (ref) => {
-            // listEvents is async; the loop pre-hydrates blobs into a
-            // synchronous cache before each LLM call below. Default
-            // fallback returns null (projection emits a placeholder).
+            // Blob refs are NOT resolved yet: `getBlob` is async and nothing
+            // pre-hydrates a sync cache, so a `blob_ref` tool output reaches
+            // the model as the "(blob … not resolved)" placeholder. The loop
+            // itself never writes blob refs; only a host-written event would.
             return null;
         };
         let iter = 0;
@@ -117,6 +132,8 @@ export class Agent {
             // requires *all* tool_results for the previous turn before the
             // next request, so we walk them sequentially here.
             for (const call of toolCalls) {
+                // Returning here leaves the remaining tool_use blocks with no
+                // tool_result on record.
                 if (signal === null || signal === void 0 ? void 0 : signal.aborted)
                     return;
                 await this.executeToolCall(conversation_id, call, signal);
@@ -219,12 +236,10 @@ export class Agent {
         }
     }
     buildSystem() {
-        // Two blocks so prompt caching works cleanly:
-        //   [0] = user-supplied system prompt (stable, cached)
-        //   [1] = tool list (also stable across a turn; we cache here too
-        //         because the same tools are reused across many turns)
-        // The Messages API treats every block as a sub-prompt; the last
-        // cache_control marker wins for that prefix.
+        // A single cached block holding the host's system prompt. Tools are
+        // not repeated here: they go in the request's `tools` field, which
+        // precedes `system` in Anthropic's cache prefix, so this breakpoint
+        // covers them too.
         return [
             {
                 type: 'text',

package/dist/conversation.d.ts

@@ -37,7 +37,8 @@ export interface ToolCallEvent extends BaseEvent {
     tool_use_id: string;
     /** Fully-qualified tool name, e.g. "build__create_block". */
     name: string;
-    /** Validated input object. */
+    /** Input exactly as the model sent it — not validated against the
+     *  tool's schema. */
     input: unknown;
     turn_id: string;
 }
@@ -45,13 +46,18 @@ export interface ToolResultEvent extends BaseEvent {
     kind: 'tool_result';
     tool_use_id: string;
     /**
-     * Output payload, or a blob ref when the value is large. Large outputs
-     * (e.g. describe_block with include_rows=true) should be stored via
-     * `ConversationStore.putBlob` and referenced here as
-     * `{kind: 'blob_ref', ref: '...'}` to keep events table compact.
+     * Output payload, or a blob ref when the value is large. A host may store
+     * a large output via `ConversationStore.putBlob` and reference it here as
+     * `{kind: 'blob_ref', ref: '...'}` to keep the events table compact. The
+     * `Agent` never does this itself, and it does not resolve refs when
+     * projecting (see agent/loop.ts), so the model would see a placeholder.
      */
     output: unknown;
-    /** Set when the handler threw. `output` then holds an error summary. */
+    /**
+     * Set when the call failed: the handler threw, the tool was unknown, or
+     * the user declined. The `Agent` then writes `output: null`, and the
+     * projection sends this string as an `is_error` tool_result.
+     */
     error?: string;
     /** Total time the handler spent, ms. */
     duration_ms: number;

package/dist/craft-ai.d.ts

@@ -0,0 +1,67 @@
+/**
+ * `askAi` — the craft→AI direction.
+ *
+ * The three craft faces all run inward: something else calls the craft. This is
+ * the one that runs outward, so a craft can put a question to a model and get a
+ * schema-valid answer: a chess board asking for the opponent's move, a
+ * simulator asking what to look at next.
+ *
+ * Two properties make it different from `Agent`:
+ *
+ *   - **Stateless.** Nothing survives the call. A craft's state is queryable
+ *     from the workbook, so the model re-reads the live position every time
+ *     rather than replaying a history that can go stale.
+ *   - **Read-only.** The loop is offered the craft's own `@mutates none` tools
+ *     and nothing else — no `EDIT_TOOLS`, no workbook surface. The model
+ *     gathers; the craft decides what to do with the answer. That is what keeps
+ *     an `askAi` retryable and cancellable: abandoning one mid-loop cannot have
+ *     half-changed the workbook.
+ */
+import type { LlmClient } from './agent/loop.js';
+import { type JSONSchema, type Tool, type ToolContext } from './tool.js';
+/** One question a craft can ask, as `craftsmith` extracted it from `@aiRole`. */
+export interface AiRole {
+    /** Used only in error messages here; the host selects roles by it. */
+    name: string;
+    /** Sent verbatim as the (cached) system prompt. */
+    system: string;
+    /**
+     * Becomes the `reply` tool's input schema. Only checked shallowly: an
+     * object, `required` keys present, top-level primitive `type`s and
+     * `enum`s — nested shapes are the craft's to validate.
+     */
+    replySchema: JSONSchema;
+}
+export interface AskAiParams {
+    llm: LlmClient;
+    model: string;
+    role: AiRole;
+    /** The question. Not the state — that is what the tools are for. */
+    input: string;
+    /** The craft's read-only tools. A mutating tool here is a caller bug. */
+    tools: readonly Tool[];
+    /** Context handed to a dispatched craft tool; its `signal` also aborts us. */
+    ctx: ToolContext;
+    /** Per-response output cap. Default 16384 — see DEFAULT_MAX_TOKENS. */
+    max_tokens?: number;
+    /** LLM round-trips allowed, the answering one included. Default 8. */
+    max_iterations?: number;
+}
+export declare class AskAiError extends Error {
+    /** The turn the loop gave up on, for a host that wants to log it. */
+    readonly detail?: unknown | undefined;
+    constructor(message: string, 
+    /** The turn the loop gave up on, for a host that wants to log it. */
+    detail?: unknown | undefined);
+}
+/**
+ * Run one question to completion and return the model's parsed answer.
+ *
+ * Throws {@link AskAiError} if `tools` contains a mutating tool (before any
+ * request), a response stops at max_tokens, the model answers in prose twice,
+ * answers in the wrong shape twice, or runs past `max_iterations`. Anything
+ * else is not wrapped: an abort of `ctx.signal` throws the signal's reason
+ * and an `LlmClient` rejection propagates. A craft tool that throws does not
+ * end the call; the model gets the message as an `is_error` result.
+ */
+export declare function askAi<T = unknown>(params: AskAiParams): Promise<T>;

package/dist/craft-ai.js

@@ -0,0 +1,214 @@
+/**
+ * `askAi` — the craft→AI direction.
+ *
+ * The three craft faces all run inward: something else calls the craft. This is
+ * the one that runs outward, so a craft can put a question to a model and get a
+ * schema-valid answer: a chess board asking for the opponent's move, a
+ * simulator asking what to look at next.
+ *
+ * Two properties make it different from `Agent`:
+ *
+ *   - **Stateless.** Nothing survives the call. A craft's state is queryable
+ *     from the workbook, so the model re-reads the live position every time
+ *     rather than replaying a history that can go stale.
+ *   - **Read-only.** The loop is offered the craft's own `@mutates none` tools
+ *     and nothing else — no `EDIT_TOOLS`, no workbook surface. The model
+ *     gathers; the craft decides what to do with the answer. That is what keeps
+ *     an `askAi` retryable and cancellable: abandoning one mid-loop cannot have
+ *     half-changed the workbook.
+ */
+import { toLlmTool, } from './tool.js';
+/** The reply tool's id. Not namespaced — it is synthetic, not a craft tool. */
+const REPLY = 'reply';
+/** Safety and cost ceiling: how many times the model may go back for state. */
+const DEFAULT_MAX_ITERATIONS = 8;
+/**
+ * Room for one turn's output.
+ *
+ * Generous because a reasoning model spends nearly all of it on a `thinking`
+ * block before it emits anything. Measured against claude-opus-5 deciding a
+ * single 四象 draft pick: 1024 was cut off mid-thought every time, and 4096
+ * still was. The role's own prompt is what drives this — it says to work the
+ * position out rather than be handed a score — so the budget has to cover
+ * reasoning, not the answer, which is a few dozen tokens.
+ *
+ * A role that wants a tighter leash passes its own `max_tokens`.
+ */
+const DEFAULT_MAX_TOKENS = 16384;
+export class AskAiError extends Error {
+    constructor(message, 
+    /** The turn the loop gave up on, for a host that wants to log it. */
+    detail) {
+        super(message);
+        this.detail = detail;
+        this.name = 'AskAiError';
+    }
+}
+/**
+ * The reply schema as one more tool in the set. It cannot be forced with
+ * `tool_choice` — the model has to be free to read first — so termination is
+ * this loop's job: it ends when the model calls `reply`.
+ */
+function replyTool(role) {
+    return {
+        name: REPLY,
+        description: 'Give your final answer. Call this exactly once, when you have ' +
+            'read everything you need.',
+        input_schema: { type: 'object', ...role.replySchema },
+    };
+}
+/**
+ * Shallow structural check against the reply schema — enough to catch a model
+ * that answered with the wrong shape, which is the failure this guards. Deep
+ * validation is the craft's business; it knows what a legal move is.
+ */
+function schemaViolations(schema, value) {
+    var _a, _b;
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return ['the answer must be an object'];
+    const obj = value;
+    const out = [];
+    for (const key of (_a = schema.required) !== null && _a !== void 0 ? _a : [])
+        if (obj[key] === undefined)
+            out.push(`"${key}" is required but missing`);
+    for (const [key, spec] of Object.entries((_b = schema.properties) !== null && _b !== void 0 ? _b : {})) {
+        const v = obj[key];
+        if (v === undefined)
+            continue;
+        const want = spec.type;
+        const got = Array.isArray(v) ? 'array' : typeof v;
+        if (want === 'number' && got !== 'number')
+            out.push(`"${key}" must be a number, got ${got}`);
+        else if (want === 'string' && got !== 'string')
+            out.push(`"${key}" must be a string, got ${got}`);
+        else if (want === 'boolean' && got !== 'boolean')
+            out.push(`"${key}" must be a boolean, got ${got}`);
+        else if (want === 'array' && got !== 'array')
+            out.push(`"${key}" must be an array, got ${got}`);
+        const allowed = spec.enum;
+        if (allowed && !allowed.includes(v))
+            out.push(`"${key}" must be one of ${allowed.join(', ')}`);
+    }
+    return out;
+}
+function textOf(content) {
+    return content
+        .filter((b) => b.type === 'text')
+        .map((b) => b.text)
+        .join(' ')
+        .trim();
+}
+/**
+ * Run one question to completion and return the model's parsed answer.
+ *
+ * Throws {@link AskAiError} if `tools` contains a mutating tool (before any
+ * request), a response stops at max_tokens, the model answers in prose twice,
+ * answers in the wrong shape twice, or runs past `max_iterations`. Anything
+ * else is not wrapped: an abort of `ctx.signal` throws the signal's reason
+ * and an `LlmClient` rejection propagates. A craft tool that throws does not
+ * end the call; the model gets the message as an `is_error` result.
+ */
+export async function askAi(params) {
+    var _a, _b, _c, _d;
+    const { llm, model, role, input, tools, ctx } = params;
+    const maxIterations = (_a = params.max_iterations) !== null && _a !== void 0 ? _a : DEFAULT_MAX_ITERATIONS;
+    const mutating = tools.filter((t) => t.mutates);
+    if (mutating.length)
+        throw new AskAiError(`role "${role.name}" was given mutating tool(s) ` +
+            `${mutating
+                .map((t) => t.name)
+                .join(', ')}; an askAi loop reads only`);
+    const byId = new Map(tools.map((t) => [`${t.namespace}__${t.name}`, t]));
+    const llmTools = [...tools.map(toLlmTool), replyTool(role)];
+    const system = [
+        { type: 'text', text: role.system, cache_control: { type: 'ephemeral' } },
+    ];
+    const messages = [{ role: 'user', content: input }];
+    let retriedShape = false;
+    let noAnswerNudges = 0;
+    for (let i = 0; i < maxIterations; i++) {
+        ctx.signal.throwIfAborted();
+        const res = await llm.createMessage({
+            model,
+            system,
+            tools: llmTools,
+            messages,
+            max_tokens: (_b = params.max_tokens) !== null && _b !== void 0 ? _b : DEFAULT_MAX_TOKENS,
+            signal: ctx.signal,
+        });
+        messages.push({ role: 'assistant', content: res.content });
+        // A truncated turn can carry no usable tool call, so left alone it
+        // silently spends an iteration and the loop ends up reporting that the
+        // model never answered — which is not what went wrong.
+        if (res.stop_reason === 'max_tokens')
+            throw new AskAiError(`role "${role.name}" was cut off at max_tokens ` +
+                `(${(_c = params.max_tokens) !== null && _c !== void 0 ? _c : DEFAULT_MAX_TOKENS}) before it ` +
+                `could answer; raise max_tokens for this role`, textOf(res.content));
+        const calls = res.content.filter((b) => b.type === 'tool_use');
+        const answer = calls.find((c) => c.name === REPLY);
+        if (answer) {
+            const bad = schemaViolations(role.replySchema, answer.input);
+            if (!bad.length)
+                return answer.input;
+            if (retriedShape)
+                throw new AskAiError(`role "${role.name}" answered in the wrong shape: ${bad.join('; ')}`, answer.input);
+            retriedShape = true;
+            messages.push({
+                role: 'user',
+                content: [
+                    {
+                        type: 'tool_result',
+                        tool_use_id: answer.id,
+                        content: `That answer does not fit: ${bad.join('; ')}. Call ${REPLY} again, corrected.`,
+                        is_error: true,
+                    },
+                ],
+            });
+            continue;
+        }
+        if (!calls.length) {
+            // A turn of prose instead of an answer. Nudge once; a model that
+            // still will not use the tool is not going to.
+            if (noAnswerNudges++ > 0)
+                throw new AskAiError(`role "${role.name}" never called ${REPLY}`, textOf(res.content));
+            messages.push({
+                role: 'user',
+                content: `Answer by calling the ${REPLY} tool.`,
+            });
+            continue;
+        }
+        const results = [];
+        for (const call of calls) {
+            const tool = byId.get(call.name);
+            if (!tool) {
+                results.push({
+                    type: 'tool_result',
+                    tool_use_id: call.id,
+                    content: `No tool named ${call.name}.`,
+                    is_error: true,
+                });
+                continue;
+            }
+            try {
+                const out = await tool.handler(call.input, ctx);
+                results.push({
+                    type: 'tool_result',
+                    tool_use_id: call.id,
+                    content: JSON.stringify((_d = out.data) !== null && _d !== void 0 ? _d : null),
+                });
+            }
+            catch (e) {
+                // The model gets the reason and can try a different read; only
+                // the loop's own limits end the call.
+                results.push({
+                    type: 'tool_result',
+                    tool_use_id: call.id,
+                    content: e instanceof Error ? e.message : String(e),
+                    is_error: true,
+                });
+            }
+        }
+        messages.push({ role: 'user', content: results });
+    }
+    throw new AskAiError(`role "${role.name}" did not answer within ${maxIterations} steps`);
+}

package/dist/craft-ai.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/craft-ai.test.js

@@ -0,0 +1,201 @@
+import { describe, it, expect, vi } from 'vitest';
+import { askAi, AskAiError } from './craft-ai.js';
+const ROLE = {
+    name: 'opponent',
+    system: 'You play chess as Black.',
+    replySchema: {
+        type: 'object',
+        properties: { uci: { type: 'string' }, plies: { type: 'number' } },
+        required: ['uci'],
+    },
+};
+/**
+ * Replays a canned script of model turns, snapshotting each request. The loop
+ * appends to one `messages` array as it goes, so recording the reference would
+ * make every turn look like the last one.
+ */
+function fakeLlm(turns) {
+    const sent = [];
+    let i = 0;
+    return {
+        sent,
+        async createMessage(params) {
+            sent.push({
+                system: structuredClone(params.system),
+                tools: params.tools.map((t) => ({ name: t.name })),
+                messages: structuredClone(params.messages),
+            });
+            const content = turns[i++];
+            if (!content)
+                throw new Error('fake llm ran out of turns');
+            return {
+                content,
+                stop_reason: content.some((b) => b.type === 'tool_use')
+                    ? 'tool_use'
+                    : 'end_turn',
+            };
+        },
+    };
+}
+const use = (name, input = {}, id = name) => ({
+    type: 'tool_use',
+    id,
+    name,
+    input,
+});
+const say = (text) => ({ type: 'text', text });
+function readTool(name, data, mutates = false) {
+    return {
+        namespace: 'chess',
+        name,
+        description: name,
+        inputSchema: { type: 'object', properties: {} },
+        mutates,
+        handler: vi.fn(async () => ({ data })),
+    };
+}
+function ctx(signal = new AbortController().signal) {
+    return {
+        workbook: {},
+        signal,
+        confirm: async () => true,
+        log: () => { },
+    };
+}
+const run = (llm, tools = [], over) => askAi({
+    llm,
+    model: 'test',
+    role: ROLE,
+    input: 'Your move.',
+    tools,
+    ctx: ctx(),
+    ...over,
+});
+describe('askAi', () => {
+    it('returns the reply the model gives', async () => {
+        const llm = fakeLlm([[use('reply', { uci: 'g8f6' })]]);
+        await expect(run(llm)).resolves.toEqual({ uci: 'g8f6' });
+    });
+    it('lets the model read through the craft tools before answering', async () => {
+        const position = readTool('get_position', { fen: 'startpos' });
+        const legal = readTool('get_legal_moves', { moves: ['g8f6'] });
+        const llm = fakeLlm([
+            [use('chess__get_position')],
+            [use('chess__get_legal_moves')],
+            [use('reply', { uci: 'g8f6' })],
+        ]);
+        await expect(run(llm, [position, legal])).resolves.toEqual({
+            uci: 'g8f6',
+        });
+        expect(position.handler).toHaveBeenCalledOnce();
+        expect(legal.handler).toHaveBeenCalledOnce();
+        // The tool result has to come back as the model's next input.
+        expect(JSON.stringify(llm.sent[1].messages)).toContain('startpos');
+    });
+    it('offers the craft tools plus a reply tool, and nothing else', async () => {
+        const llm = fakeLlm([[use('reply', { uci: 'g8f6' })]]);
+        await run(llm, [readTool('get_position', {})]);
+        expect(llm.sent[0].tools.map((t) => t.name)).toEqual([
+            'chess__get_position',
+            'reply',
+        ]);
+    });
+    it('refuses a mutating tool rather than letting the model write', async () => {
+        const llm = fakeLlm([[use('reply', { uci: 'g8f6' })]]);
+        await expect(run(llm, [readTool('apply_move', {}, true)])).rejects.toThrow(/reads only/);
+    });
+    it('re-asks once when the reply has the wrong shape', async () => {
+        const llm = fakeLlm([
+            [use('reply', { plies: 3 })], // missing the required uci
+            [use('reply', { uci: 'g8f6' })],
+        ]);
+        await expect(run(llm)).resolves.toEqual({ uci: 'g8f6' });
+        expect(JSON.stringify(llm.sent[1].messages)).toContain('is required but missing');
+    });
+    it('gives up after a second wrong shape, saying what was wrong', async () => {
+        const llm = fakeLlm([
+            [use('reply', { uci: 1 })],
+            [use('reply', { uci: 2 })],
+        ]);
+        await expect(run(llm)).rejects.toThrow(/"uci" must be a string, got number/);
+    });
+    it('nudges a model that answers in prose, then gives up', async () => {
+        const llm = fakeLlm([[say("I'd play Nf6")], [say('Nf6, definitely')]]);
+        await expect(run(llm)).rejects.toThrow(/never called reply/);
+        expect(JSON.stringify(llm.sent[1].messages)).toContain('Answer by calling the reply tool');
+    });
+    it('hands a failing tool back to the model instead of ending the call', async () => {
+        const boom = {
+            ...readTool('get_position', null),
+            handler: async () => {
+                throw new Error('board not initialized');
+            },
+        };
+        const llm = fakeLlm([
+            [use('chess__get_position')],
+            [use('reply', { uci: 'g8f6' })],
+        ]);
+        await expect(run(llm, [boom])).resolves.toEqual({ uci: 'g8f6' });
+        expect(JSON.stringify(llm.sent[1].messages)).toContain('board not initialized');
+    });
+    it('tells the model when it invents a tool', async () => {
+        const llm = fakeLlm([
+            [use('chess__get_evaluation')],
+            [use('reply', { uci: 'g8f6' })],
+        ]);
+        await expect(run(llm, [readTool('get_position', {})])).resolves.toEqual({
+            uci: 'g8f6',
+        });
+        expect(JSON.stringify(llm.sent[1].messages)).toContain('No tool named chess__get_evaluation');
+    });
+    it('stops at max_iterations rather than looping on reads', async () => {
+        const llm = fakeLlm(Array.from({ length: 10 }, () => [use('chess__get_position')]));
+        await expect(run(llm, [readTool('get_position', {})], { max_iterations: 3 })).rejects.toThrow(/did not answer within 3 steps/);
+        expect(llm.sent).toHaveLength(3);
+    });
+    it('aborts when the craft cancels', async () => {
+        const ac = new AbortController();
+        ac.abort();
+        const llm = fakeLlm([[use('reply', { uci: 'g8f6' })]]);
+        await expect(askAi({
+            llm,
+            model: 'test',
+            role: ROLE,
+            input: 'Your move.',
+            tools: [],
+            ctx: ctx(ac.signal),
+        })).rejects.toThrow();
+        expect(llm.sent).toHaveLength(0);
+    });
+    it('sends the role system prompt as a cacheable block', async () => {
+        const llm = fakeLlm([[use('reply', { uci: 'g8f6' })]]);
+        await run(llm);
+        expect(llm.sent[0].system).toEqual([
+            {
+                type: 'text',
+                text: 'You play chess as Black.',
+                cache_control: { type: 'ephemeral' },
+            },
+        ]);
+    });
+    it('carries no state between calls', async () => {
+        const first = fakeLlm([[use('reply', { uci: 'g8f6' })]]);
+        const second = fakeLlm([[use('reply', { uci: 'b8c6' })]]);
+        await run(first);
+        await run(second);
+        // The second call starts from the question alone.
+        expect(second.sent[0].messages).toEqual([
+            { role: 'user', content: 'Your move.' },
+        ]);
+    });
+});
+describe('AskAiError', () => {
+    it('carries the turn it gave up on', async () => {
+        const llm = fakeLlm([[say('nope')], [say('still nope')]]);
+        await run(llm).catch((e) => {
+            expect(e).toBeInstanceOf(AskAiError);
+            expect(e.detail).toBe('still nope');
+        });
+        expect.assertions(2);
+    });
+});