@xingular/harness 1.0.0 → 1.2.0

package/dist/sdk/terminal/tui/sideQuestion.js

@@ -1,89 +1,79 @@
-// `/btw <question>`: a side question answered by a separate, tool-free session while the main
-// conversation carries on. It lives in a dock above the composer, never enters the transcript, the
-// queue or the run history, and is gone on dismiss, on a session change, or when a new one replaces it.
-import { createAgentSession, DefaultResourceLoader, SessionManager, SettingsManager } from '@earendil-works/pi-coding-agent';
 import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from '@earendil-works/pi-tui';
 import { contentWidth, footerRow, neutralRule, padded, safeText } from "./chrome.js";
 import { getWorkingSpinnerFrames, SPINNER_INTERVAL_MS, spinnerFrameAt } from "./workingStatus.js";
-export const SIDE_PROMPT = [
-    'You answer one short side question from a person whose main task is still running in another session.',
-    'You have no tools: you cannot read or change files, run commands, browse, or call anything, and you must not say you did.',
-    'Use the conversation excerpt for context and do not invent what it does not show. Answer briefly and plainly.'
-].join(' ');
-const TURNS = 6;
-const TURN_CHARS = 1_200;
-const TOTAL_CHARS = 6_000;
 const QUESTION_ROWS = 2;
-export const ANSWER_ROWS = 8;
+const ANSWER_ROWS = 8;
+const MAX_CLIENT_CONTEXT_CHARS = 300_000;
+const POLL_INTERVAL_MS = 160;
 function blocks(content) {
     if (typeof content === 'string')
         return [{ type: 'text', text: content }];
     return Array.isArray(content) ? content.filter((block) => typeof block === 'object' && block !== null) : [];
 }
-const clip = (text, limit) => text.length > limit ? `${text.slice(0, limit)}…` : text;
-/**
- * A bounded plain-text excerpt of the main conversation: the last few user and assistant turns, the
- * tools an assistant turn called by name, and whether the reply is still running. Hidden reasoning,
- * tool inputs and results, and images are left out.
- */
+function contentText(content) {
+    return blocks(content).filter(block => block.type === 'text' && typeof block.text === 'string').map(block => String(block.text)).join('\n').trim();
+}
+function serialized(value) {
+    if (typeof value === 'string')
+        return value;
+    try {
+        return JSON.stringify(value) ?? '';
+    }
+    catch {
+        return '[unavailable]';
+    }
+}
+/** Visible native history and tool activity, with hidden reasoning and image bytes omitted. */
 export function sideQuestionSnapshot(messages, running) {
-    const turns = [];
+    const lines = [];
     for (const message of messages) {
-        const { role, content } = (message ?? {});
-        if (role !== 'user' && role !== 'assistant')
-            continue;
-        const parts = blocks(content);
-        const text = parts.filter(block => block.type === 'text' && typeof block.text === 'string').map(block => String(block.text)).join('\n').trim();
-        const tools = [...new Set(parts.filter(block => block.type === 'toolCall' && typeof block.name === 'string').map(block => String(block.name)))];
-        if (!text && !tools.length)
+        if (!message || typeof message !== 'object')
             continue;
-        turns.push(`${role === 'user' ? 'User' : 'Assistant'}: ${clip(safeText(text).replace(/\s+/g, ' ').trim(), TURN_CHARS)}${tools.length ? ` [used tools: ${tools.join(', ')}]` : ''}`);
+        const item = message;
+        const parts = blocks(item.content);
+        if (item.role === 'user' || item.role === 'assistant') {
+            const text = parts.filter(block => block.type === 'text' && typeof block.text === 'string').map(block => String(block.text)).join('\n').trim();
+            if (text)
+                lines.push(`${item.role === 'user' ? 'User' : 'Assistant'}:\n${safeText(text)}`);
+            for (const call of parts.filter(block => block.type === 'toolCall')) {
+                const name = typeof call.name === 'string' ? call.name : 'unknown tool';
+                lines.push(`Assistant tool call (${name}):\n${safeText(serialized(call.arguments))}`);
+            }
+            if (parts.some(block => block.type === 'image'))
+                lines.push(`${item.role === 'user' ? 'User' : 'Assistant'} attached an image; image bytes are omitted.`);
+        }
+        else if (item.role === 'toolResult') {
+            const name = typeof item.toolName === 'string' ? item.toolName : typeof item.name === 'string' ? item.name : 'unknown tool';
+            const output = contentText(item.content);
+            lines.push(`Tool result (${name}${typeof item.toolCallId === 'string' ? `, ${item.toolCallId}` : ''}):\n${safeText(output || '(no text result)')}`);
+            if (parts.some(block => block.type === 'image'))
+                lines.push('Tool result also contained an image; image bytes are omitted.');
+        }
     }
-    let recent = turns.slice(-TURNS);
-    while (recent.length > 1 && recent.join('\n').length > TOTAL_CHARS)
-        recent = recent.slice(1);
-    const lines = ['Conversation excerpt, oldest first:', ...(recent.length ? recent : ['(nothing yet)'])];
+    if (!lines.length)
+        lines.push('(No visible conversation messages yet.)');
     if (running)
-        lines.push('', 'The main reply is still running; its latest turn above may be unfinished.');
-    return lines.join('\n');
+        lines.push('The main reply is still running; its latest message may be unfinished.');
+    const full = lines.join('\n\n');
+    return full.length > MAX_CLIENT_CONTEXT_CHARS
+        ? `[Earlier visible context omitted to fit the side-question request.]\n\n${full.slice(-MAX_CLIENT_CONTEXT_CHARS)}`
+        : full;
 }
-/** A separate in-memory session on the same account and model, with no tools, extensions, skills or project files. */
-export async function createSideSession(services, main) {
-    const model = main.model;
-    if (!model || model.id === 'unknown')
-        throw new Error('Choose a model before asking a side question.');
-    const settingsManager = SettingsManager.inMemory({});
-    const resourceLoader = new DefaultResourceLoader({
-        cwd: services.cwd, agentDir: services.agentDir, settingsManager,
-        noExtensions: true, noSkills: true, noPromptTemplates: true, noThemes: true, noContextFiles: true, systemPrompt: SIDE_PROMPT
-    });
-    await resourceLoader.reload();
-    const { session } = await createAgentSession({
-        cwd: services.cwd, agentDir: services.agentDir, modelRuntime: services.modelRuntime, settingsManager, resourceLoader,
-        sessionManager: SessionManager.inMemory(services.cwd), model, thinkingLevel: 'off', noTools: 'all'
-    });
-    return {
-        prompt: text => session.prompt(text),
-        abort: () => session.abort(),
-        subscribe: listener => session.subscribe(() => listener()),
-        answer: () => session.getLastAssistantText() ?? '',
-        failure: () => {
-            const last = session.messages.at(-1);
-            return last?.role === 'assistant' && last.stopReason === 'error' ? last.errorMessage ?? 'The provider returned an error.' : undefined;
-        },
-        dispose: () => session.dispose()
-    };
+function payload(event) {
+    return event.payload && typeof event.payload === 'object' ? event.payload : {};
 }
 export class SideQuestion {
     options;
-    session;
-    unsubscribe;
+    runId;
     generation = 0;
+    pollTimer;
     question = '';
     answerText = '';
     error;
     current;
     startedAt = 0;
+    afterSequence = -1;
+    answerOffset = 0;
     dock;
     constructor(options) {
         this.options = options;
@@ -91,6 +81,7 @@ export class SideQuestion {
     }
     get visible() { return this.current !== undefined; }
     get state() { return this.current; }
+    get answer() { return this.answerText; }
     /** Asks one question, replacing any earlier one. Empty text dismisses. */
     async ask(question) {
         const text = question.trim();
@@ -98,73 +89,111 @@ export class SideQuestion {
             await this.dismiss();
             return;
         }
-        await this.release();
         const generation = ++this.generation;
+        await this.release();
         this.question = text;
         this.startedAt = Date.now();
         this.answerText = '';
         this.error = undefined;
+        this.answerOffset = 0;
+        this.afterSequence = -1;
         this.current = 'thinking';
         this.options.mount(this.dock);
         this.options.changed();
         try {
-            const session = await this.options.create();
+            const started = await this.options.start(text, this.options.context());
             if (generation !== this.generation) {
-                session.dispose();
+                await this.options.interrupt(started.runId).catch(() => undefined);
                 return;
             }
-            this.session = session;
-            this.unsubscribe = session.subscribe(() => {
-                if (generation !== this.generation)
-                    return;
-                this.answerText = session.answer();
-                this.options.changed();
-            });
-            await session.prompt(`${this.options.snapshot()}\n\nSide question: ${text}`);
-            if (generation !== this.generation)
-                return;
-            this.answerText = session.answer();
-            const failure = session.failure();
-            if (failure) {
-                this.current = 'failed';
-                this.error = failure;
-            }
-            else
-                this.current = 'answered';
+            this.runId = started.runId;
+            void this.poll(generation);
         }
         catch (error) {
             if (generation !== this.generation)
                 return;
             this.current = 'failed';
             this.error = error instanceof Error ? error.message : String(error);
+            this.options.changed();
         }
+    }
+    /** Scrolls the answer while it is longer than the dock. */
+    scroll(direction) {
+        const step = Math.max(1, ANSWER_ROWS - 2);
+        this.answerOffset = Math.max(0, this.answerOffset + (direction === 'up' ? -step : step));
         this.options.changed();
     }
+    /** Copies the whole side answer, including any lines outside the dock. */
+    async copyAnswer() {
+        if (this.answerText)
+            await this.options.copyText(this.answerText);
+    }
     /** Interrupts a running side question and removes the dock. */
     async dismiss() {
         this.generation++;
-        this.current = undefined;
         await this.release();
+        this.current = undefined;
         this.options.mount(undefined);
         this.options.changed();
     }
-    async release() {
-        const session = this.session;
-        this.session = undefined;
-        this.unsubscribe?.();
-        this.unsubscribe = undefined;
-        if (!session)
+    async poll(generation) {
+        const runId = this.runId;
+        if (!runId || generation !== this.generation)
             return;
         try {
-            await session.abort();
+            const result = await this.options.read(runId, this.afterSequence);
+            if (generation !== this.generation)
+                return;
+            for (const event of result.events) {
+                this.afterSequence = Math.max(this.afterSequence, event.sequence);
+                const data = payload(event);
+                if (event.type === 'message.delta' && typeof data.text === 'string')
+                    this.answerText += data.text;
+                if (event.type === 'message.completed' && data.role === 'assistant' && typeof data.text === 'string')
+                    this.answerText = data.text;
+                if (event.type === 'failed')
+                    this.error = typeof data.message === 'string' ? data.message : 'The side question failed.';
+                if (event.type === 'status.changed' && data.status === 'failed')
+                    this.error = typeof data.reason === 'string' ? data.reason : 'The side question failed.';
+                if (event.type === 'status.changed' && data.status === 'interrupted')
+                    this.error = 'The side question was interrupted.';
+                if (event.type === 'completed')
+                    this.current = 'answered';
+                if (event.type === 'failed' || event.type === 'status.changed' && ['failed', 'interrupted'].includes(String(data.status)))
+                    this.current = 'failed';
+            }
+            if (result.run.status === 'completed')
+                this.current = 'answered';
+            if (result.run.status === 'failed' || result.run.status === 'interrupted') {
+                this.current = 'failed';
+                this.error ??= result.run.terminalReason ?? 'The side question did not complete.';
+            }
+            this.options.changed();
+            if (this.current === 'thinking')
+                this.pollTimer = setTimeout(() => { void this.poll(generation); }, POLL_INTERVAL_MS);
         }
-        catch { /* A side run that cannot be stopped is still dropped. */ }
+        catch (error) {
+            if (generation !== this.generation)
+                return;
+            this.current = 'failed';
+            this.error = error instanceof Error ? error.message : String(error);
+            this.options.changed();
+        }
+    }
+    async release() {
+        if (this.pollTimer)
+            clearTimeout(this.pollTimer);
+        this.pollTimer = undefined;
+        const runId = this.runId;
+        this.runId = undefined;
+        if (!runId || this.current !== 'thinking')
+            return;
         try {
-            session.dispose();
+            await this.options.interrupt(runId);
         }
-        catch { /* Cleanup cannot keep the dock open. */ }
+        catch { /* The dock can still be dismissed if a run already stopped. */ }
     }
-    /** The dock: a neutral rule, the inline question, its answer, and a hint, separated by blank rows. */
+    /** The dock: question, a scrollable answer window, and a hint for browsing or copying. */
     render(width) {
         if (width < 1 || !this.current)
             return [];
@@ -184,14 +213,18 @@ export class SideQuestion {
             question[QUESTION_ROWS - 1] = truncateToWidth(question[QUESTION_ROWS - 1], inner - 1, '') + theme.fg('muted', '…');
         const text = this.current === 'failed' ? `${this.answerText ? `${this.answerText}\n` : ''}${this.error ?? 'The side question failed.'}` : this.answerText;
         const wrapped = text ? text.split('\n').flatMap(line => line ? wrapTextWithAnsi(safeText(line), inner) : ['']) : [];
-        const shown = wrapped.slice(0, ANSWER_ROWS).map(line => this.current === 'failed' ? theme.fg('error', line) : line);
-        const more = wrapped.length - shown.length;
+        const maxOffset = Math.max(0, wrapped.length - ANSWER_ROWS);
+        this.answerOffset = Math.min(this.answerOffset, maxOffset);
+        const shown = wrapped.slice(this.answerOffset, this.answerOffset + ANSWER_ROWS).map(line => this.current === 'failed' ? theme.fg('error', line) : line);
+        const before = this.answerOffset;
+        const after = Math.max(0, wrapped.length - before - shown.length);
+        const textHint = before || after ? `PgUp/PgDn browse · ${before ? `${before} above` : ''}${before && after ? ' · ' : ''}${after ? `${after} below` : ''} · ` : '';
         return [
             neutralRule(width, theme),
             ...question.map(line => padded(line, width)),
             ...(shown.length ? ['', ...shown.map(line => padded(line, width))] : []),
             '',
-            footerRow(`${more > 0 ? `+${more} more lines · ` : ''}/btw or Esc to dismiss`, width, theme)
+            footerRow(`${textHint}Ctrl+X copy · /btw or Esc dismiss`, width, theme)
         ].map(line => truncateToWidth(line, width, ''));
     }
 }

package/dist/sdk/terminal/tui/ui.d.ts

@@ -1,5 +1,6 @@
 import { Theme, type AutocompleteProviderFactory, type ExtensionUIContext, type KeybindingsManager, type WorkingIndicatorOptions } from '@earendil-works/pi-coding-agent';
 import { type AutocompleteProvider, type EditorComponent, type TUI } from '@earendil-works/pi-tui';
+import { type GroupedSelectOption } from "./dialogs.js";
 type EditorFactory = Parameters<ExtensionUIContext['setEditorComponent']>[0];
 type HeaderFactory = Parameters<ExtensionUIContext['setHeader']>[0];
 type FooterFactory = Parameters<ExtensionUIContext['setFooter']>[0];
@@ -37,6 +38,7 @@ export interface TerminalUiOptions {
 export interface TerminalUi extends ExtensionUIContext {
     readonly state: TerminalUiState;
     secretInput: ExtensionUIContext['input'];
+    selectGrouped(title: string, options: readonly GroupedSelectOption[], opts?: Parameters<ExtensionUIContext['select']>[2]): Promise<string | undefined>;
     wrapAutocomplete(provider: AutocompleteProvider): AutocompleteProvider;
     reset(): void;
     setThemes(themes: Theme[]): void;

package/dist/sdk/terminal/tui/ui.js

@@ -22,6 +22,7 @@ export function createTerminalUi(options) {
     return {
         state,
         select: (title, items, opts) => dialogs.select(title, items, opts),
+        selectGrouped: (title, items, opts) => dialogs.selectGrouped(title, items, opts),
         confirm: (title, message, opts) => dialogs.confirm(title, message, opts),
         input: (title, placeholder, opts) => dialogs.input(title, placeholder, opts),
         secretInput: (title, placeholder, opts) => dialogs.input(title, placeholder, opts, true),

package/dist/sdk/tools/askUser.js

@@ -1,3 +1,5 @@
+// Asking the person a question and waiting for the answer: part of every session.
+import { QUESTION_SKETCH_MAX_LENGTH, QUESTION_SKETCH_PATTERN, questionSketchError } from "../sessions/contracts.js";
 export const ASK_USER = 'ask_user';
 const MAX_OPTIONS = 6;
 const text = (value) => (typeof value === 'string' ? value.trim() : '');
@@ -16,16 +18,18 @@ export function askUserTool(run) {
     return {
         name: ASK_USER,
         label: 'Ask the user',
-        description: 'Ask the user one to five related questions in one request and wait until they answer the batch. Give each question a concise 2–3 word summary and aim to keep each question to 25 words or fewer. ' +
-            'Every question must offer 1–6 short choices, each with a helpful description of 25 words or fewer, and at least one choice must be marked recommended: true. Recommendations are visual only: they never preselect an answer, and submitted choices keep their original labels. Mark at most one recommended choice for a single-choice question, or several when multiSelect is true. Every question also includes a free-text “Something else” answer. Set multiSelect when several can apply. Use it when you need a decision, not for small talk.',
+        description: 'Ask the user one to five related questions in one request and wait until they answer the batch. Give each question a concise 1–2 word label and aim to keep each question to 25 words or fewer. ' +
+            'Every question must offer 1–6 short choices, each with a helpful description of 25 words or fewer, and at least one choice must be marked recommended: true. Recommendations are visual only: they never preselect an answer, and submitted choices keep their original labels. Mark at most one recommended choice for a single-choice question, or several when multiSelect is true. Every question also includes a free-text “Something else” answer. Set multiSelect when several can apply. When a UI diagram helps compare choices, set uiSketch: true and give every choice a detailed, bounded ASCII wireframe. Use ASCII tables and panel borders to show the affected element with relevant neighboring UI, readable labels and spacing. Keep each panel’s outer `+` corners in fixed columns, include side edges at those same columns on every content row, and run horizontal borders corner to corner; if a title sits in a top border, leave at least two dashes on both sides. Keep framing consistent across alternatives and concentrate detail on what changes. Do not substitute a symbolic logo or one-line illustration. The preview supplies its outer border; draw internal borders only for actual UI panels. Use it when you need a decision, not for small talk.',
         parameters: (Type) => Type.Object({
             questions: Type.Array(Type.Object({
-                summary: Type.String({ description: 'A concise 2–3 word summary label' }),
+                summary: Type.String({ description: 'A concise label of one or two words' }),
                 question: Type.String({ description: 'A clear, standalone question; aim for 25 words or fewer' }),
+                uiSketch: Type.Optional(Type.Literal(true, { description: 'Enable an ASCII sketch preview; when true, every choice must include a sketch.' })),
                 options: Type.Array(Type.Object({
                     label: Type.String({ description: 'A short choice; do not add a recommendation suffix to the label' }),
                     description: Type.String({ description: 'Required. Briefly explain this choice in 25 words or fewer.' }),
-                    recommended: Type.Optional(Type.Boolean({ description: 'Whether to show this choice as a visual recommendation; at least one choice per question must be recommended, it is not preselected, and answers use the original label' }))
+                    recommended: Type.Optional(Type.Boolean({ description: 'Whether to show this choice as a visual recommendation; at least one choice per question must be recommended, it is not preselected, and answers use the original label' })),
+                    sketch: Type.Optional(Type.String({ minLength: 1, maxLength: QUESTION_SKETCH_MAX_LENGTH, pattern: QUESTION_SKETCH_PATTERN, description: 'Literal ASCII UI wireframe: 1–24 LF-separated lines, at most 80 printable ASCII characters per line. Include the affected element and neighboring UI using structured table/panel borders with fixed, matching outer-edge columns on every row. Required for every choice when uiSketch is true.' }))
                 }), {
                     minItems: 1,
                     maxItems: MAX_OPTIONS,
@@ -37,26 +41,33 @@ export function askUserTool(run) {
         execute: async (input) => {
             if (!Array.isArray(input.questions) || input.questions.length < 1 || input.questions.length > 5)
                 return 'Ask between one and five questions.';
+            let invalidSketchMode = false;
+            let invalidSketchValue = false;
             const questions = input.questions.map((raw) => {
                 const item = raw;
                 const summary = text(item.summary);
                 const question = text(item.question);
+                if (item.uiSketch !== undefined && item.uiSketch !== true)
+                    invalidSketchMode = true;
                 const options = (Array.isArray(item.options) ? item.options : [])
                     .map((option) => {
                     const choice = option;
+                    if (choice.sketch !== undefined && typeof choice.sketch !== 'string')
+                        invalidSketchValue = true;
                     return {
                         label: text(choice.label),
                         description: text(choice.description),
-                        ...(choice.recommended === true ? { recommended: true } : {})
+                        ...(choice.recommended === true ? { recommended: true } : {}),
+                        ...(typeof choice.sketch === 'string' ? { sketch: choice.sketch } : {})
                     };
                 })
                     .filter((option) => option.label)
                     .slice(0, MAX_OPTIONS);
                 const multiSelect = options.length > 1 && item.multiSelect === true;
-                return { summary, question, options, multiSelect, allowText: true };
+                return { summary, question, options, ...(item.uiSketch === true ? { uiSketch: true } : {}), multiSelect, allowText: true };
             });
-            if (questions.some((question) => !question.summary || question.summary.length > 100))
-                return 'Each question needs a short summary of no more than 100 characters.';
+            if (questions.some((question) => !question.summary || question.summary.length > 100 || question.summary.split(/\s+/u).filter(Boolean).length > 2))
+                return 'Each question needs a concise 1–2 word summary label of no more than 100 characters.';
             if (questions.some((question) => !question.question))
                 return 'Every question needs a question sentence.';
             if (questions.some((question) => question.options.length === 0))
@@ -67,6 +78,13 @@ export function askUserTool(run) {
                 return 'A single-choice question may recommend at most one option.';
             if (questions.some((question) => question.options.some((option) => !option.description)))
                 return 'Every choice needs a short description. Aim for 25 words or fewer.';
+            if (invalidSketchMode)
+                return 'Set uiSketch to true to enable question sketches.';
+            if (invalidSketchValue)
+                return 'Each choice sketch must be text.';
+            const sketchError = questions.map((question) => questionSketchError(question.uiSketch, question.options)).find(Boolean);
+            if (sketchError)
+                return sketchError;
             const answers = await run.requestAnswers(questions);
             return questions.map((question, index) => `${question.summary}: ${describeAnswer(answers[index])}`).join('\n');
         }

package/dist/sdk/tools/checklist.js

@@ -22,9 +22,10 @@ export function checklistTool(run) {
     return {
         name: CHECKLIST_WRITE,
         label: 'Write the checklist',
-        description: 'Keep a checklist of the steps of the current work, so you and the user can see progress. Send the whole list every time; it replaces the previous one. ' +
-            'Use it when the work has three or more distinct steps, or when the user gives several things to do. Do not use it for a single, simple step or for conversation. ' +
+        description: 'Keep a checklist of the steps of the current work. The user watches this list to follow your progress, so write it early and keep it current. Send the whole list every time; it replaces the previous one. ' +
+            'Use it whenever the work has several distinct steps or will take several tool calls, when the user gives several things to do, and when a subagent brief asks for more than one thing. Do not use it for a single, simple step or for conversation. ' +
             'Statuses: pending, in_progress, completed. Keep exactly one step in_progress while you work, mark a step completed as soon as it is done (not in batches), and add steps you discover. ' +
+            'Before your final response, write one final checklist update: mark every fully completed step completed, and leave unfinished or blocked steps in their accurate pending or in_progress status. Never mark unfinished work completed. ' +
             'Only mark a step completed when it is fully done; if something blocks it, keep it in_progress and add a step for the blocker.',
         parameters: (Type) => Type.Object({
             items: Type.Array(Type.Object({

package/dist/sdk/tools/checkpoint.d.ts

@@ -0,0 +1,27 @@
+import { type Checkpoint } from "../sessions/contracts.js";
+import type { ActiveRun } from "../sessions/registry.js";
+import type { RunEvent } from "../sessions/contracts.js";
+import type { ToolSpec } from "./types.js";
+export declare const CHECKPOINT_WRITE = "checkpoint_write";
+/** What the model may send: the record without the numbers the harness fills in. */
+export type CheckpointInput = Omit<Checkpoint, 'slice' | 'reason'> & {
+    reason?: Checkpoint['reason'];
+};
+export type CheckpointParse = {
+    ok: true;
+    value: CheckpointInput;
+} | {
+    ok: false;
+    error: string;
+};
+/** The checkpoint as the model sent it, or one line saying what to fix. */
+export declare function parseCheckpoint(value: unknown): CheckpointParse;
+/** The model's own checkpoint, filled in with this slice and why it was written. */
+export declare function checkpointRecord(input: CheckpointInput, slice: number, fallbackReason: Checkpoint['reason']): Checkpoint;
+/** The latest checkpoint a run recorded, if any. */
+export declare function checkpointOf(events: readonly RunEvent[]): Checkpoint | null;
+/** The checkpoint as the next slice reads it. Bounded by its parts; the caller clips the whole. */
+export declare function describeCheckpoint(checkpoint: Checkpoint): string;
+/** The checkpoint as the model reads it back after writing it. */
+export declare function ackCheckpoint(checkpoint: Checkpoint): string;
+export declare function checkpointTool(run: Pick<ActiveRun, 'emit'>, slice: number | (() => number)): ToolSpec;

package/dist/sdk/tools/checkpoint.js

@@ -0,0 +1,154 @@
+// The reply's handoff when it reaches a work-slice budget (PROP-0041). The model writes it once,
+// the run records it as a `checkpoint` event, and the next slice is told where this one stopped.
+// It only changes run state, so it stays callable in plan mode.
+import { checkpointCheckSchema, checkpointDecisionSchema, checkpointFileSchema, checkpointItemSchema, checkpointReasonSchema, MAX_CHECKPOINT_CHECKS, MAX_CHECKPOINT_DECISIONS, MAX_CHECKPOINT_DONE, MAX_CHECKPOINT_FILES, MAX_CHECKPOINT_SUMMARY, runEventPayloadSchemas } from "../sessions/contracts.js";
+export const CHECKPOINT_WRITE = 'checkpoint_write';
+const text = (value) => (typeof value === 'string' ? value.trim() : '');
+/** Trims and bounds one entry; an unusable entry is dropped rather than failing the whole record. */
+function collect(value, parse, limit) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const entry of value.slice(0, limit)) {
+        const parsed = parse(entry);
+        if (parsed)
+            out.push(parsed);
+    }
+    return out;
+}
+/** The checkpoint as the model sent it, or one line saying what to fix. */
+export function parseCheckpoint(value) {
+    if (!value || typeof value !== 'object')
+        return { ok: false, error: 'Send checkpoint_write an object with summary and next.' };
+    const input = value;
+    const summary = text(input.summary);
+    if (summary.length > MAX_CHECKPOINT_SUMMARY)
+        return { ok: false, error: `Keep summary to ${MAX_CHECKPOINT_SUMMARY} characters.` };
+    if (text(input.next).length > 500)
+        return { ok: false, error: 'Keep next to 500 characters.' };
+    if (text(input.blocked).length > 500)
+        return { ok: false, error: 'Keep blocked to 500 characters.' };
+    const done = collect(input.done, (entry) => {
+        const parsed = checkpointItemSchema.safeParse(entry);
+        return parsed.success ? parsed.data : null;
+    }, MAX_CHECKPOINT_DONE);
+    const files = collect(input.files, (entry) => {
+        const parsed = checkpointFileSchema.safeParse(entry);
+        return parsed.success ? parsed.data : null;
+    }, MAX_CHECKPOINT_FILES);
+    const checks = collect(input.checks, (entry) => {
+        const parsed = checkpointCheckSchema.safeParse(entry);
+        return parsed.success ? parsed.data : null;
+    }, MAX_CHECKPOINT_CHECKS);
+    const decisions = collect(input.decisions, (entry) => {
+        const parsed = checkpointDecisionSchema.safeParse(entry);
+        return parsed.success ? parsed.data : null;
+    }, MAX_CHECKPOINT_DECISIONS);
+    if (!summary && !done.length && !text(input.next) && !files.length) {
+        return { ok: false, error: 'A checkpoint needs a summary, a next step, or what is done; write the handoff the next slice will read.' };
+    }
+    const reason = input.reason === undefined ? undefined : checkpointReasonSchema.safeParse(input.reason);
+    if (reason && !reason.success)
+        return { ok: false, error: 'reason is budget, stuck, compaction-thrash or requested.' };
+    return {
+        ok: true,
+        value: {
+            summary,
+            done,
+            next: text(input.next),
+            ...(text(input.blocked) ? { blocked: text(input.blocked) } : {}),
+            files,
+            checks,
+            decisions,
+            ...(reason && reason.success ? { reason: reason.data } : {})
+        }
+    };
+}
+/** The model's own checkpoint, filled in with this slice and why it was written. */
+export function checkpointRecord(input, slice, fallbackReason) {
+    return { ...input, slice, reason: input.reason ?? fallbackReason };
+}
+/** The latest checkpoint a run recorded, if any. */
+export function checkpointOf(events) {
+    const last = events.filter((event) => event.type === 'checkpoint').at(-1);
+    if (!last)
+        return null;
+    const parsed = runEventPayloadSchemas.checkpoint.safeParse(last.payload);
+    return parsed.success ? parsed.data : null;
+}
+const line = (value) => value.replace(/\s+/gu, ' ').trim();
+/** The checkpoint as the next slice reads it. Bounded by its parts; the caller clips the whole. */
+export function describeCheckpoint(checkpoint) {
+    const parts = [];
+    if (checkpoint.summary)
+        parts.push(`Where the last slice stopped: ${line(checkpoint.summary)}`);
+    if (checkpoint.done.length)
+        parts.push(`Done:\n${checkpoint.done.map((entry) => `- ${line(entry.item)}${entry.evidence.length ? ` (${entry.evidence.map(line).join('; ')})` : ''}`).join('\n')}`);
+    if (checkpoint.files.length)
+        parts.push(`Files touched:\n${checkpoint.files.map((entry) => `- ${line(entry.path)}${entry.why ? `: ${line(entry.why)}` : ''}`).join('\n')}`);
+    if (checkpoint.checks.length) {
+        const failing = checkpoint.checks.filter((entry) => !entry.ok);
+        const passing = checkpoint.checks.filter((entry) => entry.ok);
+        if (passing.length)
+            parts.push(`Checks that passed: ${passing.map((entry) => line(entry.command)).join('; ')}`);
+        if (failing.length)
+            parts.push(`Checks that failed:\n${failing.map((entry) => `- ${line(entry.command)}${entry.detail ? `: ${line(entry.detail)}` : ''}`).join('\n')}`);
+    }
+    if (checkpoint.decisions.length)
+        parts.push(`Decisions:\n${checkpoint.decisions.map((entry) => `- ${line(entry.what)}${entry.why ? `: ${line(entry.why)}` : ''}`).join('\n')}`);
+    if (checkpoint.blocked)
+        parts.push(`Blocked: ${line(checkpoint.blocked)}`);
+    if (checkpoint.next)
+        parts.push(`Next step: ${line(checkpoint.next)}`);
+    return parts.join('\n\n');
+}
+/** The checkpoint as the model reads it back after writing it. */
+export function ackCheckpoint(checkpoint) {
+    const counts = [
+        checkpoint.done.length ? `${checkpoint.done.length} done` : '',
+        checkpoint.files.length ? `${checkpoint.files.length} files` : '',
+        checkpoint.checks.length ? `${checkpoint.checks.length} checks` : ''
+    ].filter(Boolean).join(', ');
+    return `Checkpoint recorded for slice ${checkpoint.slice}${counts ? ` (${counts})` : ''}.${checkpoint.next ? ` Next: ${line(checkpoint.next)}` : ''}`;
+}
+export function checkpointTool(run, slice) {
+    return {
+        name: CHECKPOINT_WRITE,
+        label: 'Write the handoff checkpoint',
+        description: 'Record where this reply stopped and what the next slice must know. Call it when the harness asks for a handoff at the end of a work slice, or before you stop on purpose. ' +
+            'Include what is done (with the file or check that proves it), the single next step, anything blocking, the files you touched, the checks you ran with their outcome, and decisions the next slice must not revisit. ' +
+            'It records run state for the next slice; it does not change files and does not replace your reply to the user.',
+        parameters: (Type) => Type.Object({
+            summary: Type.Optional(Type.String({ description: 'Where this slice stopped, in 1 to 3 sentences (max 1200 characters)' })),
+            done: Type.Optional(Type.Array(Type.Object({
+                item: Type.String({ description: 'One finished step' }),
+                evidence: Type.Optional(Type.Array(Type.String({ description: 'A path, a check command, or a decision that proves it' }), { maxItems: 5 }))
+            }), { maxItems: MAX_CHECKPOINT_DONE })),
+            next: Type.Optional(Type.String({ description: 'The single next step (max 500 characters)' })),
+            blocked: Type.Optional(Type.String({ description: 'What stops progress, if anything (max 500 characters)' })),
+            files: Type.Optional(Type.Array(Type.Object({
+                path: Type.String(),
+                why: Type.Optional(Type.String({ description: 'Why this file matters to the next slice' }))
+            }), { maxItems: MAX_CHECKPOINT_FILES })),
+            checks: Type.Optional(Type.Array(Type.Object({
+                command: Type.String(),
+                ok: Type.Boolean(),
+                detail: Type.Optional(Type.String({ description: 'The failing line, when it failed' }))
+            }), { maxItems: MAX_CHECKPOINT_CHECKS })),
+            decisions: Type.Optional(Type.Array(Type.Object({
+                what: Type.String(),
+                why: Type.Optional(Type.String())
+            }), { maxItems: MAX_CHECKPOINT_DECISIONS }))
+        }),
+        readOnly: true,
+        planModeSafe: () => true,
+        execute: async (input) => {
+            const parsed = parseCheckpoint(input);
+            if (!parsed.ok)
+                return parsed.error;
+            const checkpoint = checkpointRecord(parsed.value, typeof slice === 'function' ? slice() : slice, 'requested');
+            run.emit('checkpoint', checkpoint);
+            return ackCheckpoint(checkpoint);
+        }
+    };
+}