@xingular/harness 1.1.1 → 1.3.1-unstable.0

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

@@ -4,6 +4,8 @@ import { isAbsolute, join, relative, resolve, sep } from 'node:path';
 import terminalExtension from "../piExtension.js";
 import { normalModeTools, planModeTools, QUESTION_TOOL_NAMES } from "./planMode.js";
 import { claimTerminalControl, controlCall } from "../control.js";
+import { observeProviderResponses } from "../../usage/limits/capture.js";
+import { limitHeaders } from "../../usage/limits/normalize.js";
 import { loadPiAdapter } from "./piAdapter.js";
 import { loadPi } from "../../pi/runtime.js";
 import { sessionUiContext } from "./sessionUi.js";
@@ -101,8 +103,16 @@ export async function createTerminalRuntime(args, host) {
     const identity = await controlCall('accounts.session').catch(() => null);
     const account = identity && typeof identity.accountId === 'string' && typeof identity.label === 'string'
         ? Object.freeze({ accountId: identity.accountId, label: identity.label }) : null;
-    const adapter = await loadPiAdapter();
+    await loadPiAdapter();
     const modelRuntime = await ModelRuntime.create({ authPath: join(agentDir, 'auth.json'), modelsPath: join(agentDir, 'models.json') });
+    // This process makes the model requests, so it is where response headers are seen. Only the
+    // limit-bearing headers cross the socket, and the parent throttles what it stores.
+    observeProviderResponses(modelRuntime, (provider, response) => {
+        const headers = limitHeaders(response.headers);
+        if (!Object.keys(headers).length)
+            return;
+        void controlCall('terminal.usage.headers', { provider, status: response.status, headers }).catch(() => undefined);
+    });
     const listeners = new Set();
     const changes = new Set();
     const beforeChanges = new Set();
@@ -157,11 +167,21 @@ export async function createTerminalRuntime(args, host) {
             additionalSkillPaths: prepared.skills, additionalPromptTemplatePaths: prepared.prompts,
             additionalThemePaths: prepared.themes,
             extensionFactories: [
-                ...adapter.builtins,
                 { name: 'harness-terminal-bridge', factory: pi => terminalExtension(pi, planRun, () => native.session), hidden: true },
                 // A model picked in the terminal reaches Pi as this event. A restore is not a pick.
                 { name: 'harness-mode-choices', factory: pi => { pi.on('model_select', event => { if (event.source !== 'restore')
-                        void modeChoices.record(recordingMode(), { model: `${event.model.provider}/${event.model.id}` }); }); }, hidden: true }
+                        void modeChoices.record(recordingMode(), { model: `${event.model.provider}/${event.model.id}` }); }); }, hidden: true },
+                // The bridge registers parent capabilities when delegation is available. Runs without
+                // delegation still need the same frozen snapshot, after the bridge has begun the run.
+                { name: 'harness-run-capabilities', factory: pi => {
+                        pi.on('before_agent_start', async () => {
+                            if (!pi.getAllTools().some(tool => tool.name === 'spawn_subagent')) {
+                                const snapshot = await controlCall('terminal.subagents.register', { tools: pi.getActiveTools(), plan: planRun.active });
+                                if (Array.isArray(snapshot.connectors))
+                                    planRun.connectors = snapshot.connectors;
+                            }
+                        });
+                    }, hidden: true }
             ],
             appendSystemPromptOverride: (base) => [...base, ...prepared.appendSystemPrompt]
         });

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

@@ -0,0 +1,40 @@
+import type { SessionInfo, Theme } from '@earendil-works/pi-coding-agent';
+import { type TuiMouseEventResult } from '@earendil-works/pi-tui';
+import type { TerminalPage } from "./page.js";
+import type { TerminalMouseInput } from "./mouse.js";
+export declare function formatSessionRelativeTime(value: Date, now?: number): string;
+export declare function formatSessionSize(bytes: number | undefined): string;
+export interface ResumeSessionsPageOptions {
+    theme: () => Theme;
+    cwd(): string;
+    branch(): string | null;
+    listSessions(signal: AbortSignal): Promise<SessionInfo[]>;
+    select(path: string): void;
+    cancel(): void;
+    changed(): void;
+}
+export declare class ResumeSessionsPage implements TerminalPage {
+    private readonly options;
+    readonly presentation: "fullscreen";
+    private readonly list;
+    private loading;
+    private loaded;
+    private disposed;
+    private error;
+    private abort?;
+    constructor(options: ResumeSessionsPageOptions);
+    get focused(): boolean;
+    set focused(value: boolean);
+    tabs(): {
+        id: string;
+        title: string;
+    }[];
+    activeTab(): string;
+    hint(): string;
+    activate(): void;
+    dispose(): void;
+    private load;
+    handleInput(data: string): boolean;
+    handleMouse(event: TerminalMouseInput): TuiMouseEventResult | undefined;
+    render(width: number, rows: number): string[];
+}

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

@@ -0,0 +1,141 @@
+import { stat } from 'node:fs/promises';
+import { stripTerminalSequences } from '@earendil-works/pi-tui';
+import { displayProjectName, singleLine } from "./status.js";
+import { FilterList } from "./list.js";
+const RELATIVE_TIME = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });
+const TIME_UNITS = [
+    [365 * 24 * 60 * 60 * 1000, 'year'],
+    [30 * 24 * 60 * 60 * 1000, 'month'],
+    [7 * 24 * 60 * 60 * 1000, 'week'],
+    [24 * 60 * 60 * 1000, 'day'],
+    [60 * 60 * 1000, 'hour'],
+    [60 * 1000, 'minute'],
+    [1000, 'second']
+];
+export function formatSessionRelativeTime(value, now = Date.now()) {
+    const delta = value.getTime() - now;
+    if (!Number.isFinite(delta))
+        return 'unknown time';
+    const absolute = Math.abs(delta);
+    const unit = TIME_UNITS.find(([size]) => absolute >= size);
+    return unit ? RELATIVE_TIME.format(Math.round(delta / unit[0]), unit[1]) : RELATIVE_TIME.format(0, 'second');
+}
+export function formatSessionSize(bytes) {
+    if (typeof bytes !== 'number' || !Number.isFinite(bytes) || bytes < 0)
+        return '—';
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    let size = bytes;
+    let unit = 0;
+    while (size >= 1024 && unit < units.length - 1) {
+        size /= 1024;
+        unit += 1;
+    }
+    return `${unit === 0 ? Math.round(size) : size.toFixed(1)}${units[unit]}`;
+}
+function safe(value) {
+    return stripTerminalSequences(value).replace(/[\x00-\x08\x0b-\x1f\x7f]/g, ' ');
+}
+export class ResumeSessionsPage {
+    options;
+    presentation = 'fullscreen';
+    list;
+    loading = false;
+    loaded = false;
+    disposed = false;
+    error;
+    abort;
+    constructor(options) {
+        this.options = options;
+        this.list = new FilterList({
+            theme: options.theme,
+            search: 'always',
+            rowGap: 1,
+            noun: ['session', 'sessions'],
+            empty: 'No saved sessions in this project',
+            onCancel: options.cancel,
+            onActivate: row => { if (row.data)
+                options.select(row.data); }
+        });
+    }
+    get focused() { return this.list.focused; }
+    set focused(value) { this.list.focused = value; }
+    tabs() { return [{ id: 'sessions', title: 'Resume session' }]; }
+    activeTab() { return 'sessions'; }
+    hint() { return '↑/↓ select · type to search · Enter resume'; }
+    activate() {
+        if (this.loaded || this.loading || this.disposed)
+            return;
+        this.abort = new AbortController();
+        void this.load(this.abort.signal);
+    }
+    dispose() {
+        this.disposed = true;
+        this.abort?.abort();
+    }
+    async load(signal) {
+        this.loading = true;
+        this.options.changed();
+        try {
+            const sessions = await this.options.listSessions(signal);
+            const branch = singleLine(this.options.branch() ?? '') || '—';
+            const rows = await Promise.all(sessions.map(async (session) => {
+                let bytes;
+                try {
+                    bytes = (await stat(session.path)).size;
+                }
+                catch { /* A removed or unreadable file remains selectable and shows an unknown size. */ }
+                const title = session.name?.trim() || session.firstMessage.trim() || session.id;
+                const project = displayProjectName(session.cwd || this.options.cwd());
+                const modified = formatSessionRelativeTime(session.modified);
+                const subtitle = `${modified} · ${project}:${branch} · ${formatSessionSize(bytes)}`;
+                return {
+                    id: session.path,
+                    label: singleLine(title),
+                    subtitle,
+                    searchText: `${title} ${session.firstMessage} ${session.id} ${subtitle}`,
+                    data: session.path
+                };
+            }));
+            if (this.disposed || signal.aborted)
+                return;
+            this.list.setRows(rows);
+            this.error = undefined;
+        }
+        catch (error) {
+            if (!this.disposed && !signal.aborted)
+                this.error = error instanceof Error ? error.message : String(error);
+        }
+        finally {
+            this.loaded = true;
+            this.loading = false;
+            if (!this.disposed)
+                this.options.changed();
+        }
+    }
+    handleInput(data) {
+        if (!this.list.handleInput(data))
+            return false;
+        this.options.changed();
+        return true;
+    }
+    handleMouse(event) {
+        if (event.type === 'move')
+            return { handled: true, render: false };
+        if (event.type === 'wheel')
+            return undefined;
+        const result = this.list.handleMouse(event);
+        if (result?.render)
+            this.options.changed();
+        return result;
+    }
+    render(width, rows) {
+        if (width < 1 || rows < 1)
+            return [];
+        const theme = this.options.theme();
+        if (this.error)
+            return [theme.fg('error', `Could not read saved sessions: ${safe(this.error)}`)];
+        if (this.loading || !this.loaded)
+            return [theme.fg('dim', 'Loading saved sessions…')];
+        return this.list.render(width, rows);
+    }
+}

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);
+        }
+    };
+}

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

@@ -0,0 +1,31 @@
+import type { CapabilitySet } from "../capabilities/types.js";
+import type { ToolSpec } from "./types.js";
+export declare const GET_CAPABILITIES = "get_capabilities";
+export declare const CAPABILITY_DISCOVERY: {
+    readonly name: "get_capabilities";
+    readonly label: "Inspect current capabilities";
+    readonly description: "List the tools callable in this run, or inspect one tool and its input schema. Availability is not permission: calls still follow the gate. Disabled, unavailable and unregistered tools are not advertised as callable.";
+    readonly parameters: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly tool: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 200;
+                readonly description: "An exact tool name to inspect. Omit to list callable tools.";
+            };
+        };
+    };
+};
+export interface RegisteredCapabilityTool {
+    name: string;
+    description?: string;
+    parameters?: unknown;
+}
+export declare function describeCapabilities(input: {
+    capabilities: CapabilitySet;
+    active: readonly string[];
+    registered: readonly RegisteredCapabilityTool[];
+}, name?: string): Record<string, unknown>;
+export declare function getCapabilitiesTool(snapshot: () => Parameters<typeof describeCapabilities>[0]): ToolSpec;

package/dist/sdk/tools/getCapabilities.js

@@ -0,0 +1,34 @@
+export const GET_CAPABILITIES = 'get_capabilities';
+export const CAPABILITY_DISCOVERY = {
+    name: GET_CAPABILITIES,
+    label: 'Inspect current capabilities',
+    description: 'List the tools callable in this run, or inspect one tool and its input schema. Availability is not permission: calls still follow the gate. Disabled, unavailable and unregistered tools are not advertised as callable.',
+    parameters: {
+        type: 'object', additionalProperties: false,
+        properties: { tool: { type: 'string', minLength: 1, maxLength: 200, description: 'An exact tool name to inspect. Omit to list callable tools.' } }
+    }
+};
+export function describeCapabilities(input, name) {
+    const allowed = new Set(input.capabilities.tools);
+    const active = new Set(input.active);
+    const tools = input.registered.filter(tool => allowed.has(tool.name) && active.has(tool.name));
+    if (name) {
+        const tool = tools.find(tool => tool.name === name);
+        return tool
+            ? { tool: { name: tool.name, description: tool.description ?? '', ...(tool.parameters !== undefined ? { inputSchema: tool.parameters } : {}), state: 'callable', permission: 'checked per call' } }
+            : { tool: { name, state: 'unavailable', reason: 'This tool is not callable in the current run.' } };
+    }
+    return {
+        tools: tools.map(tool => ({ name: tool.name, description: tool.description ?? '', state: 'callable' })),
+        connectors: [...input.capabilities.connectors],
+        permission: 'Availability does not grant permission. Every call still passes the gate.'
+    };
+}
+export function getCapabilitiesTool(snapshot) {
+    return {
+        ...CAPABILITY_DISCOVERY,
+        readOnly: true,
+        parameters: Type => Type.Unsafe(CAPABILITY_DISCOVERY.parameters),
+        execute: async (input) => JSON.stringify(describeCapabilities(snapshot(), typeof input.tool === 'string' ? input.tool : undefined))
+    };
+}

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

@@ -1,5 +1,7 @@
 import type { ToolSpec } from "./types.js";
 export declare const SESSION_NAME = "session_name";
+/** The trigger the prompt and the tool description share, so naming guidance cannot drift. */
+export declare const SESSION_GUIDANCE: string;
 export interface NamedSession {
     readonly sessionName?: string;
     setSessionName(name: string): void;

package/dist/sdk/tools/sessionName.js

@@ -2,13 +2,15 @@
 // the current native session; it never receives a target session id from the model.
 import { invalid } from "../core/errors.js";
 export const SESSION_NAME = 'session_name';
+/** The trigger the prompt and the tool description share, so naming guidance cannot drift. */
+export const SESSION_GUIDANCE = 'If the request needs tools or changes state — not a greeting, thanks, or a short conversational reply — call session_name once before your first other tool call, naming the work from the request. ' +
+    'Use one short imperative sentence of at most six words. Revise the name only when the overall objective changes; keep the current name when it does not.';
 export function sessionNameTool(current) {
     return {
         name: SESSION_NAME,
         label: 'Name the session',
-        description: 'Set or revise this session’s name. Name meaningful work early, then revise the name when the overall objective changes; greetings alone need no name. ' +
-            'Use one short imperative sentence describing the objective, at most six words, such as "Add web browser integrations". ' +
-            'You may revise a manually assigned name. Keep a useful current name when the objective is unchanged. This only names your own session.',
+        description: `Set or revise this session’s name. ${SESSION_GUIDANCE} ` +
+            'For example, "Add web browser integrations". You may revise a manually assigned name. This only names your own session.',
         parameters: Type => Type.Object({ name: Type.String({ description: 'One short sentence describing the objective, at most six words' }) }),
         planModeSafe: () => true,
         execute: async (input) => {

package/dist/sdk/tools/spawnSubagent.js

@@ -27,19 +27,22 @@ export function subagentTools(service, parentRunId) {
     return [{
             name: SPAWN_SUBAGENT,
             label: 'Start a subagent',
-            description: 'Start a fresh child run for independent work: a copy of yourself, or an agent profile from your Subagents list when you name it in agent (for example worker to make changes, explorer to find and explain). Give a short title, which the user sees in the roster, and a complete brief: the child has no conversation history and no more capabilities than you. Returns its run ID immediately by default so you can continue working. Results arrive automatically before you finish. Use wait_subagents to join selected children, or wait: true for an inline result. Stopping you stops your children.',
+            description: 'Start a fresh child run for independent work. Delegate substantial, bounded tasks that benefit from a separate context, not simple lookups, tiny edits or tightly coupled steps. Prefer a named specialist profile; omit agent only when no profile fits. Plan mode permits only eligible read-only research profiles. Give a short title and a self-contained brief: the child has no conversation history and no more capabilities than you. The optional tools field only narrows the profile and parent intersection; in plan mode, omit it unless you need a stricter subset. Returns its run ID immediately by default so you can continue other useful work. Results arrive automatically before you finish. Use wait_subagents when you need results before proceeding, or wait: true for an inline result. Avoid overlapping write assignments. Stopping you stops your children. To resume a child that stopped before finishing (interrupted or failed), pass continue with its run ID and no title, agent or tools: it reopens that child\'s own conversation with the same profile and tools, and brief becomes an optional extra instruction.',
+            planModeSafe: input => service.planSpawnRefusal(parentRunId, input) === null,
             parameters: (Type) => Type.Object({
-                title: Type.String({ description: `A short imperative title for the roster, at most ${MAX_SUBAGENT_TITLE_WORDS} words, such as "Map the auth flow"` }),
-                brief: Type.String(),
-                agent: Type.Optional(Type.String({ description: 'The name of an agent profile from your Subagents list; omit for a copy of yourself' })),
-                tools: Type.Optional(Type.Array(Type.String())),
+                title: Type.Optional(Type.String({ description: `Required for a new child: a short imperative title for the roster, at most ${MAX_SUBAGENT_TITLE_WORDS} words, such as "Map the auth flow"` })),
+                brief: Type.Optional(Type.String({ description: 'Required for a new child: a self-contained task: goal, relevant context or paths, non-goals, expected result, and acceptance or verification. The child cannot see this conversation. With continue, an optional extra instruction.' })),
+                continue: Type.Optional(Type.String({ description: 'The run ID of one of your subagents that stopped before finishing, to continue it from where it stopped instead of starting a fresh child' })),
+                agent: Type.Optional(Type.String({ description: 'The name of a specialist profile from your Subagents list; omit only when no listed profile fits (omitting starts an unprofiled copy)' })),
+                tools: Type.Optional(Type.Array(Type.String({ description: 'Only request a stricter subset of the profile and parent tools. In plan mode, omit this field to inherit the safe available research intersection.' }))),
                 wait: Type.Optional(Type.Boolean({ description: 'Wait for the child and return its result; default false' }))
             }),
             execute: execute(async (input) => {
-                const title = subagentTitle(input.title);
-                if (!title)
+                const resume = input.continue === undefined ? undefined : input.continue;
+                const title = resume === undefined ? subagentTitle(input.title) : undefined;
+                if (resume === undefined && !title)
                     throw invalid(`Give the subagent a title of at most ${MAX_SUBAGENT_TITLE_WORDS} words, with no control characters.`);
-                const child = await service.spawn({ parentRunId, brief: input.brief, title, agent: input.agent, tools: input.tools, wait: input.wait });
+                const child = await service.spawn({ parentRunId, brief: input.brief, title, agent: input.agent, tools: input.tools, wait: input.wait, ...(resume === undefined ? {} : { continue: resume }) });
                 if (input.wait === true)
                     return reported(parentRunId, service.results({ parentRunId, runIds: [child.runId] }), [child.runId]);
                 return { text: JSON.stringify(child), details: { [SUBAGENT_RECEIPT]: { version: 1, ownerRunId: parentRunId, spawned: [child.runId] } } };

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

@@ -0,0 +1,15 @@
+import { type TodoItem, type RunEvent } from "../sessions/contracts.js";
+import type { ActiveRun } from "../sessions/registry.js";
+import type { ToolSpec } from "./types.js";
+export declare const TODO_WRITE = "todo_write";
+/** The trigger the prompt and the tool description share, so progress guidance cannot drift. */
+export declare const TODO_GUIDANCE: string;
+/** The todo list as the model reads it back. */
+export declare function describeTodo(items: readonly TodoItem[]): string;
+/** The latest todo list a run wrote, or an empty list. Reads the pre-rename event too. */
+export declare function todoOf(events: readonly RunEvent[]): TodoItem[];
+export declare function todoTool(run: Pick<ActiveRun, 'emit'>): ToolSpec;
+/** @deprecated Use `TODO_WRITE`; kept for one release so embedders can migrate. */
+export declare const CHECKLIST_WRITE = "todo_write";
+/** @deprecated Use `todoOf`; kept for one release so embedders can migrate. */
+export declare const checklistOf: typeof todoOf;

package/dist/sdk/tools/todo.js

@@ -0,0 +1,64 @@
+// The run's own todo list: the model writes the whole list each time, and the run records it as
+// a `todo.updated` event. It only changes run state, so it stays callable in plan mode.
+import { todoItemSchema, MAX_TODO_ITEMS } from "../sessions/contracts.js";
+export const TODO_WRITE = 'todo_write';
+/** The trigger the prompt and the tool description share, so progress guidance cannot drift. */
+export const TODO_GUIDANCE = 'If the work has several distinct steps or will take more than one tool call, call todo_write before your first other tool call with the steps you know so far, and keep the list current as steps start and finish. ' +
+    'Before your final reply, write one final update: mark every fully completed step completed and leave unfinished or blocked steps accurate. Never mark unfinished work completed. ' +
+    'The person follows your work from it, and a subagent’s todo list shows as its progress in the person’s list of subagents.';
+/** The event a run writes; `checklist.updated` is the pre-rename name, still read for old runs. */
+const TODO_EVENTS = new Set(['todo.updated', 'checklist.updated']);
+const MARK = { pending: '[ ]', in_progress: '[~]', completed: '[x]' };
+/** The todo list as the model reads it back. */
+export function describeTodo(items) {
+    if (!items.length)
+        return 'The todo list is empty.';
+    return items.map((item) => `${MARK[item.status]} ${item.text}`).join('\n');
+}
+/** The latest todo list a run wrote, or an empty list. Reads the pre-rename event too. */
+export function todoOf(events) {
+    const last = events.filter((event) => TODO_EVENTS.has(event.type)).at(-1);
+    const items = last?.payload?.items;
+    return Array.isArray(items) ? items.flatMap((item) => {
+        const parsed = todoItemSchema.safeParse(item);
+        return parsed.success ? [parsed.data] : [];
+    }) : [];
+}
+export function todoTool(run) {
+    return {
+        name: TODO_WRITE,
+        label: 'Write the todo list',
+        description: `Keep a todo list of the steps of the current work. The user watches this list to follow your progress. ${TODO_GUIDANCE} ` +
+            'Send the whole list every time; it replaces the previous one. 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. ' +
+            '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({
+                text: Type.String({ description: 'One step, as a short imperative line' }),
+                status: Type.Union([Type.Literal('pending'), Type.Literal('in_progress'), Type.Literal('completed')])
+            }), { maxItems: MAX_TODO_ITEMS })
+        }),
+        readOnly: true,
+        planModeSafe: () => true,
+        execute: async (input) => {
+            if (!Array.isArray(input.items))
+                return 'Send items: the whole todo list as an array.';
+            if (input.items.length > MAX_TODO_ITEMS)
+                return `Keep the todo list to ${MAX_TODO_ITEMS} steps or fewer.`;
+            const items = [];
+            for (const raw of input.items) {
+                const entry = raw;
+                const parsed = todoItemSchema.safeParse({ text: typeof entry?.text === 'string' ? entry.text.trim() : entry?.text, status: entry?.status });
+                if (!parsed.success)
+                    return 'Every step needs text of 1 to 500 characters and a status of pending, in_progress or completed.';
+                items.push(parsed.data);
+            }
+            run.emit('todo.updated', { items });
+            return describeTodo(items);
+        }
+    };
+}
+/** @deprecated Use `TODO_WRITE`; kept for one release so embedders can migrate. */
+export const CHECKLIST_WRITE = TODO_WRITE;
+/** @deprecated Use `todoOf`; kept for one release so embedders can migrate. */
+export const checklistOf = todoOf;