@xingular/harness 1.2.0 → 1.3.1-unstable.0

package/dist/sdk/terminal/tui/pages/pluginsPage.js

@@ -6,13 +6,16 @@
 import { describePlugin, surfaceBadge } from "../../../plugins/surfaces.js";
 import { matchesKey, truncateToWidth, wrapTextWithAnsi } from '@earendil-works/pi-tui';
 import { BACK, applyPluginAction, menuRows, rowActions } from "../../pluginMenu.js";
-import { safeText } from "../chrome.js";
+import { inspectorListWidth, safeText, splitColumns } from "../chrome.js";
 import { FilterList } from "../list.js";
 const SECTIONS = [
     { id: 'plugins', title: 'Plugins' },
-    { id: 'trust', title: 'Trust' }
+    { id: 'trust', title: 'Trust' },
+    { id: 'packages', title: 'Packages' }
 ];
 const SETTINGS_ROW = 'settings:';
+const PACKAGE_ROW = 'package:';
+const INSTALL_PACKAGE = 'action:install-package';
 const isSwitch = (setting) => setting.min === 0 && setting.max === 1;
 const settingValueText = (setting) => isSwitch(setting)
     ? setting.value === 1 ? 'on' : 'off'
@@ -20,14 +23,17 @@ const settingValueText = (setting) => isSwitch(setting)
 const settingsOf = (plugin) => plugin.settings ?? [];
 export class PluginsPage {
     options;
+    presentation = 'fullscreen';
     plugins;
     section = 'plugins';
     projectId = null;
+    hubManagedIds = new Set();
     error;
     restart = false;
     busy = false;
     disposed = false;
     list;
+    pointerLayout;
     /** The plugin whose settings are open, or null on the list. */
     settingsFor = null;
     saved = false;
@@ -70,6 +76,12 @@ export class PluginsPage {
             this.projectId = (await call('plugins.session').catch(() => ({ projectId: null }))).projectId;
             this.plugins = await call('plugins.list');
             this.error = undefined;
+            this.hubManagedIds = new Set();
+            try {
+                const overview = await call('hub.list');
+                this.hubManagedIds = new Set(overview.installed.filter(receipt => receipt.entry.delivery.kind === 'pi-package').flatMap(receipt => receipt.resourceIds));
+            }
+            catch { /* Package actions still go through the receipt-aware Harness service. */ }
         }
         catch (error) {
             this.error = error instanceof Error ? error.message : String(error);
@@ -91,8 +103,17 @@ export class PluginsPage {
                 searchText: `${setting.label} ${setting.description}`
             })));
     }
-    /** The menu rows, with a Settings row after the last row of each plugin that has settings. */
+    /** Switch, trust, settings and package actions stay grouped under their owning plugin. */
     rows() {
+        if (this.section === 'packages')
+            return [
+                ...(this.plugins ?? []).filter(plugin => plugin.install).map(plugin => {
+                    const source = plugin.install.kind === 'folder' ? 'local folder' : 'package';
+                    const hub = this.hubManagedIds.has(plugin.id);
+                    return { id: `${PACKAGE_ROW}${plugin.id}`, group: safeText(plugin.title), label: 'Manage package', detail: `${source} · ${hub ? 'Hub' : 'local'} · ${plugin.version ?? plugin.install.source}`, tone: 'muted', searchText: `${plugin.title} ${plugin.install.source} ${plugin.version ?? ''} package ${hub ? 'Hub' : 'local'}` };
+                }),
+                { id: INSTALL_PACKAGE, group: 'Packages', label: 'Install package…', detail: 'Folder, npm or Git', tone: 'accent', searchText: 'install add package plugin npm Git folder' }
+            ];
         const menu = this.menu();
         const out = [];
         const placed = new Set();
@@ -107,18 +128,19 @@ export class PluginsPage {
             if (this.section === 'plugins' && last && settingsOf(row.plugin).length)
                 out.push(settingsRow(row.plugin));
         });
-        if (this.section === 'plugins') {
+        if (this.section === 'plugins')
             for (const plugin of this.plugins ?? [])
                 if (settingsOf(plugin).length && !placed.has(plugin.id))
                     out.push(settingsRow(plugin));
-        }
         return out;
     }
     menu() {
         const rows = menuRows(this.plugins ?? [], this.projectId);
-        return this.section === 'trust'
-            ? rows.filter(row => row.whole && Boolean(row.plugin.code))
-            : rows.filter(row => rowActions(row, this.projectId).some(action => action.startsWith('Switch ')));
+        if (this.section === 'trust')
+            return rows.filter(row => row.whole && Boolean(row.plugin.code));
+        if (this.section === 'packages')
+            return [];
+        return rows.filter(row => rowActions(row, this.projectId).some(action => action.startsWith('Switch ')));
     }
     key(row) { return `${row.whole ? 'plugin' : 'item'}:${row.id}`; }
     toRow(row) {
@@ -137,6 +159,16 @@ export class PluginsPage {
             this.options.changed();
             return;
         }
+        if (id === INSTALL_PACKAGE) {
+            await this.installPackage();
+            return;
+        }
+        if (id.startsWith(PACKAGE_ROW)) {
+            const plugin = this.plugins?.find(candidate => candidate.id === id.slice(PACKAGE_ROW.length));
+            if (plugin?.install)
+                await this.managePackage(plugin);
+            return;
+        }
         const row = this.menu().find(candidate => this.key(candidate) === id);
         if (!row || this.busy)
             return;
@@ -151,6 +183,74 @@ export class PluginsPage {
         }
         await this.reload();
     }
+    async installPackage() {
+        if (this.busy)
+            return;
+        this.busy = true;
+        try {
+            const source = await this.options.ui.input('Install local plugin package', 'npm:package@version, Git address, or absolute folder path');
+            if (!source?.trim())
+                return;
+            const confirmed = await this.options.ui.confirm('Install package?', `${source.trim()} will be installed without running package code. It arrives switched off and code remains untrusted until reviewed.`);
+            if (!confirmed)
+                return;
+            await this.options.call('plugins.install', { source: source.trim() });
+            this.restart = true;
+            this.options.ui.notify('Installed switched off. Changes apply when this session restarts.', 'info');
+            await this.reload();
+        }
+        catch (error) {
+            this.options.ui.notify(error instanceof Error ? error.message : String(error), 'error');
+        }
+        finally {
+            this.busy = false;
+            if (!this.disposed)
+                this.options.changed();
+        }
+    }
+    async managePackage(plugin) {
+        if (this.busy || !plugin.install)
+            return;
+        const hubManaged = this.hubManagedIds.has(plugin.id);
+        const actions = [
+            ...(hubManaged || plugin.install.kind === 'folder' ? [] : ['Update package']),
+            hubManaged ? 'Uninstall Hub version' : 'Remove package',
+            BACK
+        ];
+        this.busy = true;
+        try {
+            const action = await this.options.ui.select(`${plugin.title}: ${plugin.install.source}`, actions);
+            if (!action || action === BACK)
+                return;
+            if (action === 'Update package') {
+                const confirmed = await this.options.ui.confirm(`Update ${plugin.title}?`, 'Fetches a newer package version without running its scripts. Changed code remains subject to trust review.');
+                if (!confirmed)
+                    return;
+                await this.options.call('plugins.update', { pluginId: plugin.id });
+                this.options.ui.notify('Updated. Changes apply when this session restarts.', 'info');
+            }
+            else {
+                const title = hubManaged ? `Uninstall ${plugin.title} from Hub?` : `Remove ${plugin.title}?`;
+                const message = hubManaged
+                    ? 'This removes the exact Hub receipt and only its recorded package resources.'
+                    : 'This removes the installed package. A local folder is moved to the Harness trash.';
+                if (!await this.options.ui.confirm(title, message))
+                    return;
+                await this.options.call('plugins.remove', { pluginId: plugin.id });
+                this.options.ui.notify(hubManaged ? 'Hub package uninstalled.' : 'Package removed.', 'info');
+            }
+            this.restart = true;
+            await this.reload();
+        }
+        catch (error) {
+            this.options.ui.notify(error instanceof Error ? error.message : String(error), 'error');
+        }
+        finally {
+            this.busy = false;
+            if (!this.disposed)
+                this.options.changed();
+        }
+    }
     back() {
         this.settingsFor = null;
         this.saved = false;
@@ -196,7 +296,12 @@ export class PluginsPage {
         }
     }
     handleMouse(event) {
-        return this.settingsPlugin() ? this.settingsList.handleMouse(event) : this.list.handleMouse(event);
+        const layout = this.pointerLayout;
+        if (!layout)
+            return undefined;
+        if (event.x < 0 || event.x >= layout.width || event.y < layout.top || event.y >= layout.top + layout.rows)
+            return { handled: true, render: false };
+        return layout.list.handleMouse({ ...event, y: event.y - layout.top });
     }
     handleInput(data) {
         if (this.settingsPlugin()) {
@@ -206,44 +311,111 @@ export class PluginsPage {
         }
         if (matchesKey(data, 'tab') || matchesKey(data, 'shift+tab')) {
             if (!this.list.query) {
-                this.section = this.section === 'plugins' ? 'trust' : 'plugins';
+                const direction = matchesKey(data, 'shift+tab') ? -1 : 1;
+                const current = SECTIONS.findIndex(section => section.id === this.section);
+                this.section = SECTIONS[(current + direction + SECTIONS.length) % SECTIONS.length].id;
                 this.fill();
             }
             return true;
         }
         return this.list.handleInput(data);
     }
+    selectedPlugin() {
+        const selectedId = this.list.selected?.id;
+        return selectedId?.startsWith(SETTINGS_ROW)
+            ? this.plugins?.find(candidate => `${SETTINGS_ROW}${candidate.id}` === selectedId)
+            : selectedId?.startsWith(PACKAGE_ROW)
+                ? this.plugins?.find(candidate => `${PACKAGE_ROW}${candidate.id}` === selectedId)
+                : this.menu().find(candidate => this.key(candidate) === selectedId)?.plugin;
+    }
+    pluginInspector(plugin, width, rows) {
+        const theme = this.options.theme();
+        if (width < 1 || rows < 1)
+            return [];
+        if (!plugin) {
+            const action = this.list.selected?.id === INSTALL_PACKAGE;
+            return [theme.fg('muted', action ? 'Add a package from npm, Git, or a local folder.' : 'Select a plugin to inspect it.')].slice(0, rows).map(line => truncateToWidth(line, width, ''));
+        }
+        const selectedId = this.list.selected?.id;
+        const row = this.menu().find(candidate => this.key(candidate) === selectedId);
+        const title = row ? row.whole ? row.plugin.title : row.name : plugin.title;
+        const lines = [theme.bold(safeText(title))];
+        if (title !== plugin.title)
+            lines.push(theme.fg('dim', `Part of ${safeText(plugin.title)}`));
+        lines.push('', ...wrapTextWithAnsi(safeText(describePlugin(plugin)), width));
+        if (row) {
+            const status = this.section === 'trust' && row.whole
+                ? plugin.trust === 'trusted' ? 'Code trusted' : 'Code not trusted'
+                : row.on ? 'Enabled' : 'Disabled';
+            lines.push('', theme.fg(row.on ? 'success' : 'dim', status));
+        }
+        if (plugin.code) {
+            lines.push(theme.fg('muted', `Code trust: ${plugin.trust === 'trusted' ? 'trusted' : 'not trusted'}`));
+            lines.push(theme.fg('muted', `Fingerprint: ${plugin.code.hash.slice(0, 12)}`));
+        }
+        if (plugin.install) {
+            lines.push('', theme.fg('muted', `Package: ${this.hubManagedIds.has(plugin.id) ? 'Hub receipt' : 'local'}`));
+            lines.push(...wrapTextWithAnsi(theme.fg('dim', safeText(plugin.install.source)), width));
+        }
+        if (settingsOf(plugin).length)
+            lines.push('', theme.fg('muted', `${settingsOf(plugin).length} settings`));
+        return lines.slice(0, rows).map(line => truncateToWidth(line, width, ''));
+    }
     render(width, rows) {
         const theme = this.options.theme();
         if (width < 1 || rows < 1)
             return [];
-        if (!this.plugins)
+        if (!this.plugins) {
+            this.pointerLayout = undefined;
             return [theme.fg(this.error ? 'error' : 'dim', this.error ? `Could not read plugins: ${this.error}` : 'Reading plugins…')];
+        }
         const plugin = this.settingsPlugin();
         if (plugin)
             return this.renderSettings(plugin, width, rows);
-        const selectedId = this.list.selected?.id;
-        const selected = selectedId?.startsWith(SETTINGS_ROW)
-            ? this.plugins.find(candidate => `${SETTINGS_ROW}${candidate.id}` === selectedId)
-            : this.menu().find(candidate => this.key(candidate) === selectedId)?.plugin;
+        const note = this.restart ? [theme.fg('warning', 'Saved. Changes apply when this session restarts.')] : [];
+        const paneWidth = inspectorListWidth(width);
+        if (paneWidth !== undefined) {
+            const bodyRows = Math.max(0, rows - note.length);
+            const rightWidth = Math.max(0, width - paneWidth - 3);
+            const listLines = this.list.render(paneWidth, bodyRows);
+            this.pointerLayout = { list: this.list, width: paneWidth, top: note.length, rows: listLines.length };
+            return [...note, ...splitColumns(listLines, this.pluginInspector(this.selectedPlugin(), rightWidth, bodyRows), paneWidth, width, bodyRows, theme)]
+                .slice(0, rows).map(line => truncateToWidth(line, width, ''));
+        }
+        const selected = this.selectedPlugin();
         const detail = selected && rows >= 8 ? wrapTextWithAnsi(safeText(describePlugin(selected)), width).slice(0, 3) : [];
-        const note = this.restart ? ['Saved. Changes apply when this session restarts.'] : [];
-        const extra = detail.length + note.length;
-        const lines = this.list.render(width, Math.max(2, rows - (extra ? extra + 1 : 0)));
-        if (extra)
-            lines.push('', ...detail.map(line => theme.fg('muted', line)), ...note.map(line => theme.fg('warning', line)));
+        const listRows = Math.max(2, rows - note.length - (detail.length ? detail.length + 1 : 0));
+        const listLines = this.list.render(width, listRows);
+        this.pointerLayout = { list: this.list, width, top: note.length, rows: Math.min(listLines.length, Math.max(0, rows - note.length)) };
+        const lines = [...note, ...listLines];
+        if (detail.length)
+            lines.push('', ...detail.map(line => theme.fg('muted', line)));
         return lines.slice(0, rows).map(line => truncateToWidth(line, width, ''));
     }
     renderSettings(plugin, width, rows) {
         const theme = this.options.theme();
         const setting = settingsOf(plugin).find(candidate => candidate.key === this.settingsList.selected?.id);
         const range = setting && !isSwitch(setting) ? [`From ${setting.min.toLocaleString('en-US')} to ${setting.max.toLocaleString('en-US')} · default ${setting.default.toLocaleString('en-US')}`] : [];
+        const note = this.saved ? [theme.fg('success', 'Saved.')] : [];
+        const paneWidth = inspectorListWidth(width);
+        if (paneWidth !== undefined) {
+            const bodyRows = Math.max(0, rows - note.length);
+            const rightWidth = Math.max(0, width - paneWidth - 3);
+            const listLines = this.settingsList.render(paneWidth, bodyRows);
+            const details = setting
+                ? [theme.bold(safeText(setting.label)), '', ...wrapTextWithAnsi(safeText(setting.description), rightWidth), '', ...range.map(line => theme.fg('muted', line)), theme.fg('dim', `Current value: ${settingValueText(setting)}`)]
+                : [theme.fg('muted', 'Select a setting to review its value and description.')];
+            this.pointerLayout = { list: this.settingsList, width: paneWidth, top: note.length, rows: listLines.length };
+            return [...note, ...splitColumns(listLines, details, paneWidth, width, bodyRows, theme)]
+                .slice(0, rows).map(line => truncateToWidth(line, width, ''));
+        }
         const detail = setting && rows >= 8 ? [...wrapTextWithAnsi(safeText(setting.description), width).slice(0, 3), ...range] : [];
-        const note = this.saved ? ['Saved.'] : [];
-        const extra = detail.length + note.length;
-        const lines = this.settingsList.render(width, Math.max(2, rows - (extra ? extra + 1 : 0)));
-        if (extra)
-            lines.push('', ...detail.map(line => theme.fg('muted', line)), ...note.map(line => theme.fg('success', line)));
+        const listRows = Math.max(2, rows - note.length - (detail.length ? detail.length + 1 : 0));
+        const listLines = this.settingsList.render(width, listRows);
+        this.pointerLayout = { list: this.settingsList, width, top: note.length, rows: Math.min(listLines.length, Math.max(0, rows - note.length)) };
+        const lines = [...note, ...listLines];
+        if (detail.length)
+            lines.push('', ...detail.map(line => theme.fg('muted', line)));
         return lines.slice(0, rows).map(line => truncateToWidth(line, width, ''));
     }
 }

package/dist/sdk/terminal/tui/pages/subagentsPage.js

@@ -88,9 +88,11 @@ export class SubagentsPage {
     activeTab() { return 'subagents'; }
     hint() { return '↑↓ select · type to search'; }
     rows(width = 80, now = this.options.now?.() ?? Date.now()) {
+        // The main agent is pinned first so its children read against it.
         const ordered = [...this.options.snapshot()].sort((left, right) => {
+            const main = Number(right.relation === 'main') - Number(left.relation === 'main');
             const active = Number(ACTIVE_SUBAGENT_STATUSES.has(right.status)) - Number(ACTIVE_SUBAGENT_STATUSES.has(left.status));
-            return active || left.startedAt.localeCompare(right.startedAt) || left.id.localeCompare(right.id);
+            return main || active || left.startedAt.localeCompare(right.startedAt) || left.id.localeCompare(right.id);
         });
         return ordered.map(item => {
             const profile = clean(item.profile?.name ?? '') || 'subagent';
@@ -115,9 +117,10 @@ export class SubagentsPage {
     render(width, rows) {
         const items = this.rows(width, this.options.now?.() ?? Date.now());
         this.list.setRows(items);
-        const active = items.filter(item => item.data && ACTIVE_SUBAGENT_STATUSES.has(item.data.status)).length;
+        const children = items.filter(item => item.data?.relation !== 'main');
+        const active = children.filter(item => item.data && ACTIVE_SUBAGENT_STATUSES.has(item.data.status)).length;
         const selected = this.list.selected?.data;
-        const header = headerRow('Subagents', `${active} active · ${items.length} total`, width, this.options.theme());
+        const header = headerRow('Subagents', `${active} active · ${children.length} total`, width, this.options.theme());
         const bodyRows = Math.max(0, rows - 7);
         const listRows = Math.max(1, Math.min(this.list.height, Math.floor(bodyRows * 0.6)));
         const output = [header, '', ...this.list.render(width, listRows), ''];
@@ -129,8 +132,8 @@ export class SubagentsPage {
             output.push(neutralRule(width, theme));
             output.push(padded(theme.fg('muted', `Profile: ${clean(selected.profile?.name ?? '') || 'copy of the parent'}`), width));
             output.push(padded(theme.fg('accent', 'Task'), width));
-            output.push(...detailLines(selected.goal || 'Subagent'));
-            output.push(padded(theme.fg('muted', `Status: ${[selected.status.replaceAll('_', ' '), subagentTasks(selected.checklist), terminalSubagentDuration(selected)].filter(Boolean).join(' · ')}`), width));
+            output.push(...detailLines(selected.goal || (selected.relation === 'main' ? 'Main agent' : 'Subagent')));
+            output.push(padded(theme.fg('muted', `Status: ${[selected.status.replaceAll('_', ' '), subagentTasks(selected.todo), terminalSubagentDuration(selected)].filter(Boolean).join(' · ')}`), width));
             output.push(padded(theme.fg('accent', 'Current activity'), width));
             output.push(...detailLines(selected.activity));
         }

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,20 +27,22 @@ export function subagentTools(service, parentRunId) {
     return [{
             name: SPAWN_SUBAGENT,
             label: 'Start a subagent',
-            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. 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.',
+            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({ description: 'A self-contained task: goal, relevant context or paths, non-goals, expected result, and acceptance or verification. The child cannot see this conversation.' }),
+                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())),
+                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;