@xingular/harness 1.1.1 → 1.3.1-unstable.0

package/dist/sdk/doctor/checks.js

@@ -1,5 +1,9 @@
+import { randomUUID } from 'node:crypto';
 import { accessSync, constants, existsSync, readFileSync, statSync } from 'node:fs';
-import { delimiter, isAbsolute, join } from 'node:path';
+import { basename, delimiter, isAbsolute, join } from 'node:path';
+import { hostShell, shellLabel } from "../core/shell.js";
+import { createWorkspaceBashOperations, workspaceSandboxBackend } from "../core/workspaceSandbox.js";
+import { resolveWorkspaceRoot } from "../core/workspace.js";
 import { defaultAssets } from "../terminal/terminals.js";
 import { loadPi, PINNED_PI_VERSION } from "../pi/runtime.js";
 import { list as listPlugins } from "../plugins/api.js";
@@ -12,18 +16,23 @@ import { BRAVE, TAVILY, EXA } from "../web/search.js";
 import { KEYLESS_SEARCH, WEB_PLUGIN } from "../web/tools.js";
 const pass = (evidence) => ({ status: 'pass', evidence });
 const fail = (evidence, remedy) => ({ status: 'fail', evidence, remedy });
-function executable(name) {
+function resolvedExecutable(name) {
     const paths = isAbsolute(name) ? [name] : (process.env.PATH ?? '').split(delimiter).filter(Boolean).map(dir => join(dir, name));
-    return paths.some(path => {
+    for (const path of paths) {
         try {
             accessSync(path, constants.X_OK);
-            return statSync(path).isFile();
-        }
-        catch {
-            return false;
+            if (statSync(path).isFile())
+                return path;
         }
-    });
+        catch { /* try the next PATH entry */ }
+    }
+    return null;
 }
+function executable(name) {
+    return resolvedExecutable(name) !== null;
+}
+/** One command written by the harness, not the model: it prints a fixed word and touches nothing. */
+const BASH_PROBE_COMMAND = `printf '%s\\n' harness-doctor`;
 export async function builtinChecks(harness, context, secrets, assets = defaultAssets()) {
     const check = (id, category, title, local) => ({ id, category, title, local });
     const account = () => context.accountId ? harness.accounts.find(context.accountId) : null;
@@ -96,10 +105,60 @@ export async function builtinChecks(harness, context, secrets, assets = defaultA
             }), tools: ['read', 'grep', 'find', 'ls', 'write', 'edit']
         },
         {
-            ...check('native.bash', 'tools', 'Native shell tool', async () => process.platform === 'win32'
-                ? { status: 'unverified', evidence: 'Windows shell resolution is delegated to Pi; no shell was launched.' }
-                : executable('bash') ? pass('Bash is executable on the inherited PATH. No shell command was run.') : fail('Bash was not found on the inherited PATH.', 'Verify the shell executable used by Pi.')),
-            tools: ['bash']
+            ...check('native.bash', 'tools', 'Native shell tool', async () => {
+                if (process.platform === 'win32') {
+                    const shell = hostShell();
+                    if (!shell)
+                        return fail('Neither Git Bash nor PowerShell was found.', 'Install Git for Windows, or restore Windows PowerShell.');
+                    return { status: 'warning', evidence: `Commands run in ${shellLabel(shell)} at ${shell.executable}. Windows has no workspace write-boundary sandbox, so each command asks for approval unless Full Permission is on, and plan mode cannot run commands. No shell command was run.`, remedy: 'Approve each command when asked, or turn on Full Permission for this session.' };
+                }
+                const shell = resolvedExecutable('bash');
+                if (!shell)
+                    return fail('Bash was not found on the inherited PATH.', 'Verify the shell executable used by Pi.');
+                // Bash runs inside the platform's write-boundary sandbox; without that backend every call
+                // fails before the command starts, so presence of bash alone is not readiness.
+                const backend = workspaceSandboxBackend(process.platform);
+                return backend
+                    ? pass(`Bash is executable at ${shell}, and the ${basename(backend)} workspace write-boundary sandbox it runs inside is present. No shell command was run.`)
+                    : fail(`Bash is executable at ${shell}, but the workspace write-boundary sandbox this platform needs is missing, so every Bash call fails before it runs.`, process.platform === 'linux' ? 'Install bubblewrap (bwrap) so Bash can run inside the workspace boundary.' : 'Restore the platform sandbox executable so Bash can run inside the workspace boundary.');
+            }),
+            tools: ['bash'],
+            live: {
+                notice: 'Run one fixed command written by the harness (printf) in the working folder, inside the same workspace write-boundary sandbox as a normal Bash call. No model input, no network request, no file written; only the exit status is reported.',
+                run: async (probe) => {
+                    if (process.platform === 'win32')
+                        return { status: 'unverified', evidence: 'On Windows every command needs a person to approve it, so the diagnostic does not run one.' };
+                    const refusal = await harness.sessions.diagnosticGate(probe.run, context.caller).check('bash', { command: BASH_PROBE_COMMAND });
+                    if (refusal)
+                        return { status: 'blocked', evidence: `The tool policy refused the diagnostic command: ${refusal}`, remedy: 'Review what the policy allows Bash to do in this session.' };
+                    const toolCallId = randomUUID();
+                    probe.run.emit('tool.started', { toolCallId, name: 'bash', summary: 'Synthetic diagnostic command' });
+                    let output = '';
+                    try {
+                        // The same root, boundary, hard-link scan and sandbox a real Bash call takes. A
+                        // diagnostic never widens that boundary, so Full Permission cannot change this result.
+                        const workspaceRoot = resolveWorkspaceRoot(context.cwd);
+                        const { exitCode } = await createWorkspaceBashOperations(workspaceRoot).exec(BASH_PROBE_COMMAND, workspaceRoot, {
+                            onData: chunk => { if (output.length < 400)
+                                output += chunk.toString('utf8'); },
+                            signal: probe.signal,
+                            timeout: 20
+                        });
+                        probe.run.emit('tool.completed', { toolCallId, name: 'bash', ok: exitCode === 0 });
+                        return exitCode === 0 && output.includes('harness-doctor')
+                            ? pass('A real command ran in the working folder through the workspace sandbox and returned exit status 0 with the expected output.')
+                            : fail(`The shell returned exit status ${exitCode ?? 'unknown'} for the diagnostic command.`, 'Review the shell executable, the workspace write-boundary sandbox and the working folder permissions.');
+                    }
+                    catch (error) {
+                        probe.run.emit('tool.completed', { toolCallId, name: 'bash', ok: false });
+                        return {
+                            status: 'blocked',
+                            evidence: `The command could not start in this working folder, so the shell itself was not exercised: ${error instanceof Error ? error.message : String(error)}`,
+                            remedy: 'Resolve what stops Bash before it runs (a hard-link alias in the workspace, a missing sandbox backend, or a redirected workspace root), or choose another working folder.'
+                        };
+                    }
+                }
+            }
         },
         check('runtime.storage', 'runtime', 'State and data storage', async () => {
             accessSync(harness.stateDir, constants.R_OK | constants.W_OK);

package/dist/sdk/doctor/types.d.ts

@@ -11,9 +11,9 @@ export declare const findingSchema: z.ZodObject<{
     status: z.ZodEnum<{
         disabled: "disabled";
         warning: "warning";
+        blocked: "blocked";
         pass: "pass";
         fail: "fail";
-        blocked: "blocked";
         unverified: "unverified";
     }>;
     verification: z.ZodEnum<{
@@ -119,9 +119,9 @@ export declare const doctorReportSchema: z.ZodObject<{
         status: z.ZodEnum<{
             disabled: "disabled";
             warning: "warning";
+            blocked: "blocked";
             pass: "pass";
             fail: "fail";
-            blocked: "blocked";
             unverified: "unverified";
         }>;
         verification: z.ZodEnum<{

package/dist/sdk/harness.d.ts

@@ -24,6 +24,8 @@ import { Sessions } from "./sessions/sessions.js";
 import { SideQuestions } from "./sessions/sideQuestions.js";
 import { Terminals, type TerminalAssets } from "./terminal/terminals.js";
 import { Worktrees } from "./worktrees/service.js";
+import { Usage } from "./usage/service.js";
+import { UsageLimits } from "./usage/limits/service.js";
 import { AnnotationCapture } from "./annotations/capture.js";
 import { NoteDeliveries } from "./annotations/delivery.js";
 import type { WorktreesOptions } from "./worktrees/types.js";
@@ -89,6 +91,8 @@ declare class Env implements HarnessEnv {
     get root(): string;
 }
 export declare class Harness {
+    /** The periodic liveness check, started once with recovery (PROP-0041). */
+    private staleRuns?;
     private readonly browserEnabled;
     readonly hub: Hub;
     readonly bus: Bus;
@@ -120,6 +124,9 @@ export declare class Harness {
     refineHost: RefineHost | null;
     readonly terminals: Terminals;
     readonly doctor: Doctor;
+    /** Usage analytics over the derived ledger, and the provider limits last reported. */
+    readonly usage: Usage;
+    readonly usageLimits: UsageLimits;
     /** Managed git worktrees sessions can work in (PROP-0016). */
     readonly worktrees: Worktrees;
     /** The terminal's visible browser for capturing page notes (PROP-0017). */

package/dist/sdk/harness.js

@@ -36,11 +36,14 @@ import { Hooks } from "./plugins/hooks.js";
 import { packageFolders, Plugins } from "./plugins/plugins.js";
 import { approvalKey, Approvals } from "./sessions/approvals.js";
 import { RunRegistry } from "./sessions/registry.js";
-import { loadRun, markInterruptedRuns } from "./sessions/runStore.js";
+import { loadRun, markInterruptedRuns, reconcileStaleRuns } from "./sessions/runStore.js";
 import { Sessions } from "./sessions/sessions.js";
 import { SideQuestions } from "./sessions/sideQuestions.js";
 import { Terminals } from "./terminal/terminals.js";
 import { Worktrees } from "./worktrees/service.js";
+import { Usage } from "./usage/service.js";
+import { UsageLimits } from "./usage/limits/service.js";
+import { indexRunUsage, syncUsage } from "./usage/ledger.js";
 import { AnnotationCapture } from "./annotations/capture.js";
 import { NoteDeliveries } from "./annotations/delivery.js";
 class Env {
@@ -61,6 +64,8 @@ class Env {
     }
 }
 export class Harness {
+    /** The periodic liveness check, started once with recovery (PROP-0041). */
+    staleRuns;
     browserEnabled;
     hub;
     bus = new Bus();
@@ -92,6 +97,9 @@ export class Harness {
     refineHost;
     terminals;
     doctor;
+    /** Usage analytics over the derived ledger, and the provider limits last reported. */
+    usage;
+    usageLimits;
     /** Managed git worktrees sessions can work in (PROP-0016). */
     worktrees;
     /** The terminal's visible browser for capturing page notes (PROP-0017). */
@@ -116,6 +124,10 @@ export class Harness {
         const secrets = options.secrets ?? fileSecretStore(join(this.stateDir, 'secrets.json'));
         this.accounts = new Accounts({ dir: join(this.stateDir, 'accounts'), secrets, bus: this.bus });
         this.approvals = new Approvals(this.stateDir, this.bus);
+        this.usageLimits = new UsageLimits({ accounts: this.accounts, root: () => this.env.dataRoot });
+        // Response headers are the free, always-fresh limit signal; the account runtime reports them here.
+        this.accounts.observeModels = (models, accountId) => this.usageLimits.observeModels(models, accountId);
+        this.usage = new Usage({ root: () => this.env.root, accounts: this.accounts });
         this.runs = new RunRegistry({
             root: () => this.env.root,
             automatic: async (run, target, operation, standing) => {
@@ -171,6 +183,7 @@ export class Harness {
             broker: this.apps,
             plugins: this.plugins,
             resolveCapabilities: (caller, tools, cwd) => capabilities.resolve(this, { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null, cwd, tools }),
+            fullPermission: (run) => this.approvals.isAuto(approvalKey(run)),
             factory: options.sessionFactory,
             trust: this.trust,
             worktrees: this.worktrees
@@ -187,7 +200,7 @@ export class Harness {
         this.refine = new Refinements({ root: () => this.env.root, bus: this.bus, trust: this.trust, host: () => this.refineHost, runtime: refineRuntime });
         this.lessons = new Lessons({ root: () => this.env.root, runtime: refineRuntime });
         this.pageNotes = new NoteDeliveries({ root: () => this.env.root, bus: this.bus, terminals: () => this.terminals ?? null });
-        this.terminals = new Terminals({ trust: this.trust, subagents: this.subagents, sideQuestions: this.sideQuestions, resolveCapabilities: (caller, tools, cwd) => capabilities.resolve(this, { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null, cwd, tools }), env: this.env, stateDir: this.stateDir, accounts: this.accounts, runs: this.runs, approvals: this.approvals, apps: this.apps, policy: this.policy, bus: this.bus, plugins: this.plugins, pluginControl: { list: (scope) => pluginApi.list(this, scope), attach: (params, on) => pluginApi.attach(this, params, on), trust: (scope) => pluginApi.trust(this, scope), untrust: (scope) => pluginApi.untrust(this, scope), configure: (params) => pluginApi.configure(this, params), install: params => pluginInstall.install(this, params), remove: params => pluginInstall.remove(this, params) }, assets: options.assets, hub: this.hub, world: this.world, doctor: this.doctor, worktrees: this.worktrees, noteCapture: this.noteCapture, pageNotes: this.pageNotes });
+        this.terminals = new Terminals({ trust: this.trust, subagents: this.subagents, sideQuestions: this.sideQuestions, resolveCapabilities: (caller, tools, cwd) => capabilities.resolve(this, { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null, cwd, tools }), env: this.env, stateDir: this.stateDir, accounts: this.accounts, runs: this.runs, approvals: this.approvals, apps: this.apps, policy: this.policy, bus: this.bus, plugins: this.plugins, usage: this.usage, usageLimits: this.usageLimits, pluginControl: { list: (scope) => pluginApi.list(this, scope), attach: (params, on) => pluginApi.attach(this, params, on), trust: (scope) => pluginApi.trust(this, scope), untrust: (scope) => pluginApi.untrust(this, scope), configure: (params) => pluginApi.configure(this, params), install: params => pluginInstall.install(this, params), remove: params => pluginInstall.remove(this, params) }, assets: options.assets, hub: this.hub, world: this.world, doctor: this.doctor, worktrees: this.worktrees, noteCapture: this.noteCapture, pageNotes: this.pageNotes });
         this.ready = this.apps.start().catch((error) => log('connected apps', error instanceof Error ? error.message : String(error)));
         this.runs.listen((event, run) => {
             this.accounts.onRunEvent(event, run);
@@ -197,6 +210,10 @@ export class Harness {
             if (run?.trigger === 'doctor')
                 return;
             const runEnded = event.type === 'completed' || event.type === 'failed' || (event.type === 'status.changed' && event.payload.status === 'interrupted');
+            // The usage ledger is derived from the same recorded events; a failure never blocks the run.
+            // An interrupted run is indexed too, so its spent tokens are not lost until the next start.
+            if (runEnded)
+                indexRunUsage(this.env.root, event.runId);
             if (runEnded && run?.sessionId) {
                 // Notes sent with "Proceed now" while this session was working go out now; the terminal
                 // needs a moment to see its run as ended.
@@ -294,18 +311,41 @@ export class Harness {
         catch (error) {
             log('recall', error instanceof Error ? error.message : String(error));
         }
+        try {
+            // Usage rows come from the same run events; the ledger can always be rebuilt from them.
+            syncUsage(root);
+        }
+        catch (error) {
+            log('usage ledger', error instanceof Error ? error.message : String(error));
+        }
         this.recovery = { interruptedRuns: interruptedRunIds.length, interruptedRunIds, reindexedPages: safeCount(root), migrationError, legacyWiki };
+        if (!this.staleRuns) {
+            // A reply that stops emitting heartbeats while its process lives is settled here, not left
+            // `running` for the next restart (PROP-0041).
+            this.staleRuns = setInterval(() => {
+                try {
+                    reconcileStaleRuns(root);
+                }
+                catch (error) {
+                    log('stale run check', error instanceof Error ? error.message : String(error));
+                }
+            }, 60_000);
+            this.staleRuns.unref?.();
+        }
         return this.recovery;
     }
     /** Rebuilds the history index from the run records. Returns the notes in the Wiki. */
     rebuildIndex() {
         recall.sync(this.env.root);
+        syncUsage(this.env.root);
         const count = safeCount(this.env.root);
         this.recovery = { ...this.recovery, reindexedPages: count };
         return count;
     }
     /** Stops live runs and refinements and releases the index. */
     async close() {
+        if (this.staleRuns)
+            clearInterval(this.staleRuns);
         await this.doctor.close();
         this.hub.close();
         await this.refine.close();

package/dist/sdk/hub/hub.js

@@ -316,7 +316,7 @@ export class Hub {
                     attachments.save(root, choicesBefore);
                 if (entry.delivery.kind === 'pi-package')
                     for (const pluginId of receipt.resourceIds)
-                        await packages.remove(this.harness, { pluginId });
+                        await packages.removeDirect(this.harness, { pluginId });
                 throw error;
             }
             this.harness.bus.emit({ type: 'hub.changed' });
@@ -404,8 +404,10 @@ export class Hub {
                     }
                 }
                 if (receipt.entry.delivery.kind === 'pi-package')
-                    for (const pluginId of receipt.resourceIds)
-                        await packages.remove(this.harness, { pluginId });
+                    for (const pluginId of receipt.resourceIds) {
+                        if ((await pluginApi.list(this.harness, {})).some((plugin) => plugin.id === pluginId && plugin.install))
+                            await packages.removeDirect(this.harness, { pluginId });
+                    }
                 writeJson(join(root, 'hub', 'installed.json'), records.filter((item) => item !== receipt));
                 committed = true;
                 try {

package/dist/sdk/index.d.ts

@@ -16,17 +16,21 @@ export type { RunCapabilitySnapshot } from "./capabilities/runSnapshot.js";
 export type { CallerContext } from "./core/caller.js";
 export { dispatch as harnessCall } from "./tools/dispatch.js";
 export { compile, render, SECTION_ORDER, CONTEXT_MESSAGE_TYPE, CONTEXT_SNAPSHOT_KEY, type ContextPack, type HostSection, type HostToolGroup, type Launch, type Reference, type Section } from "./prompt/compile.js";
-export { runEventSchema, runRecordSchema, isActiveStatus, type ChecklistItem, type RunEvent, type RunEventType, type RunRecord } from "./sessions/contracts.js";
+export { runEventSchema, runRecordSchema, isActiveStatus, type TodoItem, type RunEvent, type RunEventType, type RunRecord } from "./sessions/contracts.js";
 export type { ApprovalFacts, ApprovalPolicy, AutomaticReason } from "./sessions/approvals.js";
 export type { ScopeDecision, ToolCall, ToolPolicy } from "./sessions/policy.js";
 export type { ActiveRun, ApprovalDecision, ApprovalInput, QuestionAnswer, QuestionInput } from "./sessions/registry.js";
 export type { RunFields, SessionRunInput } from "./sessions/sessions.js";
+export type { SessionCommand } from "./sessions/runner.js";
+export type { SessionRef, SessionTree, SessionTreeEntry } from "./sessions/control.js";
+export { CORE_COMMANDS, coreCommand, type CoreCommand, type CoreCommandGroup, type CoreCommandKind, type CoreCommandName, type ListedCommand } from "./commands/registry.js";
+export { STANDARD_CONNECTIONS, type StandardSession } from "./prompt/standard.js";
 export { SideQuestions, SIDE_QUESTION_INSTRUCTION, buildSideQuestionText, type SideQuestionContext, type SideQuestionRead, type SideQuestionStartInput } from "./sessions/sideQuestions.js";
 export type { Effort } from "./sessions/runner.js";
 export { describeTool, HARNESS_TOOLS, DEFAULT_TOOL_NAMES, WIKI_WRITE, type HarnessCall, type HarnessToolDefinition } from "./tools/definitions.js";
 export type { ToolProvider, ToolResult, ToolSession, ToolSpec } from "./tools/types.js";
 export { SPAWN_SUBAGENT, SUBAGENT_RELATION } from "./tools/spawnSubagent.js";
-export { CHECKLIST_WRITE, checklistOf } from "./tools/checklist.js";
+export { TODO_WRITE, todoOf, CHECKLIST_WRITE, checklistOf } from "./tools/todo.js";
 export { BUILTIN_PROFILES } from "./agents/builtin.js";
 export { PROFILE_COLORS, createProfile, listProfiles, parseProfile, profileDirs, removeProfile, resolveProfile, type AgentProfile, type ProfileColor, type ProfileListing, type ProfileProblem, type ProfileScope, type ProfileSource, type ProfileVariant } from "./agents/profiles.js";
 export { continuationOf, type Continuation, type ContinuationBlock } from "./sessions/continuation.js";
@@ -56,7 +60,8 @@ export { HARNESS_PLUGINS } from "./plugins/builtin.js";
 export { FIRST_PARTY_PLUGINS } from "./plugins/firstParty.js";
 export type { Found, Resolver } from "./plugins/discover.js";
 export type { Loading, Registered } from "./plugins/plugins.js";
-export { CONTRIBUTION_KINDS, PLUGIN_SOURCES, type ConnectorTemplate, type Contribution, type ContributionKind, type ContributionState, type Delivery, type Inventory, type InventoryItem, type Plugin, type PluginDescriptor, type PluginManage, type PluginSetting, type PluginSource } from "./plugins/types.js";
+export { CONTRIBUTION_KINDS, PLUGIN_SOURCES, type ConnectorTemplate, type Contribution, type ContributionKind, type ContributionState, type Delivery, type Inventory, type InventoryItem, type Plugin, type PluginDescriptor, type PluginManage, type PluginSetting, type PluginSource, type PluginSurfaces } from "./plugins/types.js";
+export { describePlugin, surfaceBadge } from "./plugins/surfaces.js";
 export { methods } from "./server/methods.js";
 export { remoteDirectory, remotePolicy, remoteSecrets, remoteTools } from "./server/remote.js";
 export { PROTOCOL_VERSION, RpcPeer, stdioTransport, type Handler, type Transport } from "./server/rpc.js";

package/dist/sdk/index.js

@@ -20,10 +20,12 @@ export { fileSecretStore, memorySecretStore, secretKey } from "./accounts/secret
 export { dispatch as harnessCall } from "./tools/dispatch.js";
 export { compile, render, SECTION_ORDER, CONTEXT_MESSAGE_TYPE, CONTEXT_SNAPSHOT_KEY } from "./prompt/compile.js";
 export { runEventSchema, runRecordSchema, isActiveStatus } from "./sessions/contracts.js";
+export { CORE_COMMANDS, coreCommand } from "./commands/registry.js";
+export { STANDARD_CONNECTIONS } from "./prompt/standard.js";
 export { SideQuestions, SIDE_QUESTION_INSTRUCTION, buildSideQuestionText } from "./sessions/sideQuestions.js";
 export { describeTool, HARNESS_TOOLS, DEFAULT_TOOL_NAMES, WIKI_WRITE } from "./tools/definitions.js";
 export { SPAWN_SUBAGENT, SUBAGENT_RELATION } from "./tools/spawnSubagent.js";
-export { CHECKLIST_WRITE, checklistOf } from "./tools/checklist.js";
+export { TODO_WRITE, todoOf, CHECKLIST_WRITE, checklistOf } from "./tools/todo.js";
 export { BUILTIN_PROFILES } from "./agents/builtin.js";
 export { PROFILE_COLORS, createProfile, listProfiles, parseProfile, profileDirs, removeProfile, resolveProfile } from "./agents/profiles.js";
 export { continuationOf } from "./sessions/continuation.js";
@@ -42,6 +44,7 @@ export { attach as attachPlugin, inventoryFor as pluginInventory, list as listPl
 export { HARNESS_PLUGINS } from "./plugins/builtin.js";
 export { FIRST_PARTY_PLUGINS } from "./plugins/firstParty.js";
 export { CONTRIBUTION_KINDS, PLUGIN_SOURCES } from "./plugins/types.js";
+export { describePlugin, surfaceBadge } from "./plugins/surfaces.js";
 export { methods } from "./server/methods.js";
 export { remoteDirectory, remotePolicy, remoteSecrets, remoteTools } from "./server/remote.js";
 export { PROTOCOL_VERSION, RpcPeer, stdioTransport } from "./server/rpc.js";

package/dist/sdk/pi/runtime.d.ts

@@ -1,4 +1,5 @@
-export declare const PINNED_PI_VERSION = "1.2.0";
+export declare const PINNED_PI_VERSION = "1.4.0";
+export declare const HTTP_DISPATCHER_CHUNK = "dist/bundle/chunks/chunk-MM3LKT73.js";
 type PiRuntimeModule = {
     VERSION: string;
     getPackageDir(): string;

package/dist/sdk/pi/runtime.js

@@ -1,7 +1,7 @@
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
-export const PINNED_PI_VERSION = '1.2.0';
-const HTTP_DISPATCHER_CHUNK = 'dist/bundle/chunks/chunk-TJXZSVTD.js';
+export const PINNED_PI_VERSION = '1.4.0';
+export const HTTP_DISPATCHER_CHUNK = 'dist/bundle/chunks/chunk-MM3LKT73.js';
 export function assertPiRuntimeVersion(version) {
     if (version !== PINNED_PI_VERSION)
         throw new Error(`The Harness Pi runtime requires Pi ${PINNED_PI_VERSION}; found ${version}. Install the Harness package's pinned dependencies.`);

package/dist/sdk/plugins/builtin.js

@@ -1,7 +1,9 @@
 // Built-in feature modules register their contributions here; this registry never loads Pi code.
 import { CONNECTION_TOOLS, NATIVE_GROUP } from "../prompt/compile.js";
 import { ASK_USER, askUserTool } from "../tools/askUser.js";
-import { CHECKLIST_WRITE, checklistTool } from "../tools/checklist.js";
+import { TODO_WRITE, todoTool } from "../tools/todo.js";
+import { CHECKPOINT_WRITE, checkpointTool } from "../tools/checkpoint.js";
+import { sliceOf } from "../sessions/workSlice.js";
 import { SPAWN_SUBAGENT, WAIT_SUBAGENTS } from "../sessions/subagents.js";
 import { subagentTools } from "../tools/spawnSubagent.js";
 import { SESSION_NAME } from "../tools/sessionName.js";
@@ -25,6 +27,9 @@ import { subagentServerMethods } from "../sessions/subagentServerMethods.js";
 import { sideQuestionServerMethods } from "../sessions/sideQuestionServerMethods.js";
 import { connectedAppServerMethods } from "../mcp/serverMethods.js";
 import { harnessTools } from "../tools/harnessTools.js";
+import { GET_CAPABILITIES } from "../tools/getCapabilities.js";
+import { USAGE_SETTINGS } from "../usage/settings.js";
+import { usageServerMethods } from "../usage/serverMethods.js";
 import { createBuiltinPluginRegistry } from "./builtinRegistry.js";
 const tools = (definitions) => definitions.map((tool) => ({ name: tool.name, description: tool.label }));
 const toolContribution = (definitions, toolOrder) => ({
@@ -74,7 +79,8 @@ const WIKI_PLUGIN = {
 };
 const HISTORY_PLUGIN = { id: 'history', title: 'History', description: 'Search earlier conversations and inspect recorded run trajectories.', required: 'Earlier runs are how an agent picks up where work stopped.', tools: tools([...RECALL_TOOLS, ...TRAJECTORY_TOOLS]), toolGroups: ['History'] };
 const ASK_USER_PLUGIN = { id: 'ask-user', title: 'Ask the user', description: 'Lets the agent stop and ask a question with choices.', required: 'An agent must be able to stop and ask you.', tools: [{ name: ASK_USER }] };
-const CHECKLIST_PLUGIN = { id: 'checklist', title: 'Checklist', description: 'Lets the agent keep a checklist of the steps of its work, recorded with the run so progress can be shown and picked up again.', required: 'Progress of longer work is kept through it.', tools: [{ name: CHECKLIST_WRITE, description: 'Write the checklist' }] };
+const TODO_PLUGIN = { id: 'todo', title: 'Todo', description: 'Lets the agent keep a todo list of the steps of its work, recorded with the run so progress can be shown and picked up again.', required: 'Progress of longer work is kept through it.', tools: [{ name: TODO_WRITE, description: 'Write the todo list' }] };
+const CHECKPOINT_PLUGIN = { id: 'checkpoint', title: 'Checkpoint', description: 'Lets a bounded reply record a handoff at a work-slice boundary so the next slice starts from it.', required: 'A reply that stops at its budget leaves the state the next one resumes from.', tools: [{ name: CHECKPOINT_WRITE, description: 'Write the handoff checkpoint' }] };
 const CONNECTED_APPS_PLUGIN = {
     id: 'connected-apps',
     title: 'Connected apps',
@@ -88,6 +94,13 @@ const DOCTOR_PLUGIN = { id: 'doctor', title: 'Doctor', description: 'Local readi
 const WORKTREES_PLUGIN = { id: 'worktrees', title: 'Worktrees', description: 'Create and manage isolated git worktrees, move changes between them, and restore removed worktrees.', required: 'Managed worktrees are available to every local terminal.' };
 const HUB_PLUGIN = { id: 'hub', title: 'Hub', description: 'Browse and install reviewed skills, plugins and documents from configured registries.', required: 'Reviewed Harness resources are available to every host.' };
 const REFINEMENT_PLUGIN = { id: 'refinement', title: 'Refinement', description: 'Improve variants from recorded evidence through isolated refinement runs and reviewed candidates.', required: 'Variant refinement is available to every host.' };
+const CAPABILITIES_PLUGIN = { id: 'capabilities', title: 'Capability discovery', description: 'Inspect the callable tools of the current run, including their input schemas. Discovery never grants access.', required: 'Every interactive session can inspect its own registered capabilities.', tools: [{ name: GET_CAPABILITIES, description: 'Inspect current capabilities' }] };
+const USAGE_PLUGIN = {
+    id: 'usage',
+    title: 'Usage',
+    description: 'Token, cost and latency totals from recorded runs, and the plan windows, balances or rate limits each provider reports.',
+    settings: [...USAGE_SETTINGS]
+};
 const SIDE_QUESTIONS_PLUGIN = {
     id: 'side-questions',
     title: 'Side questions',
@@ -107,7 +120,6 @@ export const BUILTIN_PLUGIN_REGISTRY = createBuiltinPluginRegistry([
         tools: context => context.allowedTools.includes(SPAWN_SUBAGENT)
             ? subagentTools(context.subagents, context.runId).filter(tool => context.allowedTools.includes(tool.name))
             : [],
-        commands: [{ name: 'subagents', description: 'Watch current subagent tasks and activity' }, { name: 'agents', description: 'Browse and edit agent profiles' }],
         serverMethods: subagentServerMethods
     },
     { descriptor: VARIANT_PLUGIN, ...toolContribution(SKILL_TOOLS, 30) },
@@ -115,11 +127,11 @@ export const BUILTIN_PLUGIN_REGISTRY = createBuiltinPluginRegistry([
     {
         descriptor: HISTORY_PLUGIN,
         ...toolContribution([...RECALL_TOOLS, ...TRAJECTORY_TOOLS], 10),
-        commands: [{ name: 'trajectory', description: 'Inspect the recorded runs of this session' }],
         serverMethods: historyServerMethods
     },
     { descriptor: ASK_USER_PLUGIN, toolOrder: 40, tools: context => context.harnessTools && context.allowedTools.includes(ASK_USER) ? [askUserTool(context.run)] : [] },
-    { descriptor: CHECKLIST_PLUGIN, toolOrder: 50, tools: context => context.harnessTools ? [checklistTool(context.run)] : [] },
+    { descriptor: TODO_PLUGIN, toolOrder: 50, tools: context => context.harnessTools ? [todoTool(context.run)] : [] },
+    { descriptor: CHECKPOINT_PLUGIN, toolOrder: 51, tools: context => context.harnessTools && context.allowedTools.includes(CHECKPOINT_WRITE) ? [checkpointTool(context.run, () => sliceOf(context.env.root, context.runId))] : [] },
     {
         descriptor: CONNECTED_APPS_PLUGIN,
         toolOrder: 0,
@@ -141,23 +153,28 @@ export const BUILTIN_PLUGIN_REGISTRY = createBuiltinPluginRegistry([
     },
     {
         descriptor: ANNOTATIONS_PLUGIN,
+        commandPrefix: 'annotate',
+        defaultCommand: 'annotate',
         commands: [
-            { name: 'notes', description: 'Page notes: keep notes on web pages and share them with this session' },
-            { name: 'annotate', description: 'Inspect a page or app, comment on components, send fixes to the agent: /plugin:annotate [url | --app <devtools address> | --bridge]' }
+            { name: 'notes', description: 'Review web annotations saved from pages and apps' },
+            { name: 'annotate', description: 'Inspect a page or app, comment on components, and send fixes: /annotate:annotate [url | --app <devtools address> | --bridge]' }
         ],
         createWorldPart: ({ options }) => annotationsPart({ root: options.root, changed: options.notesChanged }),
         serverMethods: annotationServerMethods
     },
+    { descriptor: CAPABILITIES_PLUGIN },
     {
-        descriptor: DOCTOR_PLUGIN,
-        commands: [{ name: 'doctor', description: 'Check account, model, tools and runtime readiness' }],
-        serverMethods: doctorServerMethods
-    },
-    {
-        descriptor: WORKTREES_PLUGIN,
-        commands: [{ name: 'worktree', description: 'Work in a managed git worktree: new, switch, hand off, remove' }],
-        serverMethods: worktreeServerMethods
+        descriptor: USAGE_PLUGIN,
+        commandPrefix: 'usage',
+        defaultCommand: 'analysis',
+        commands: [
+            { name: 'analysis', description: 'Token, cost and latency totals: /usage:analysis [today | 7d | 30d | all]' },
+            { name: 'limit', description: 'Provider plan windows, balances and rate limits: /usage:limit' }
+        ],
+        serverMethods: usageServerMethods
     },
+    { descriptor: DOCTOR_PLUGIN, serverMethods: doctorServerMethods },
+    { descriptor: WORKTREES_PLUGIN, serverMethods: worktreeServerMethods },
     ...FIRST_PARTY_PLUGINS.map(descriptor => ({ descriptor }))
 ]);
 export const HARNESS_PLUGINS = BUILTIN_PLUGIN_REGISTRY.descriptors();

package/dist/sdk/plugins/builtinRegistry.d.ts

@@ -10,9 +10,10 @@ import type { ActiveRun } from "../sessions/registry.js";
 import type { PluginDescriptor } from "./types.js";
 export interface BuiltinPluginCommand {
     pluginId: string;
+    prefix: string;
     name: string;
     description: string;
-    namespace: 'unprefixed' | 'plugin';
+    legacyBare: boolean;
 }
 export interface BuiltinWorldContext {
     options: WorldOptions;
@@ -33,10 +34,14 @@ export interface BuiltinToolContext {
 }
 export interface BuiltinPluginModule {
     descriptor: PluginDescriptor;
+    /** Stable terminal command namespace; defaults to the plugin id. */
+    commandPrefix?: string;
+    /** Command invoked by the namespace root, such as `/annotate:`. */
+    defaultCommand?: string;
     /** Stable order for model tools, independent of descriptor display order. */
     toolOrder?: number;
     tools?: (context: BuiltinToolContext) => ToolSpec[];
-    commands?: readonly Omit<BuiltinPluginCommand, 'pluginId' | 'namespace'>[];
+    commands?: readonly Omit<BuiltinPluginCommand, 'pluginId' | 'prefix' | 'legacyBare'>[];
     createWorldPart?: (context: BuiltinWorldContext) => WorldPart | null;
     serverMethods?: (harness: Harness) => Record<string, Handler>;
 }
@@ -44,7 +49,9 @@ export interface BuiltinPluginRegistry {
     readonly modules: readonly BuiltinPluginModule[];
     descriptors(): PluginDescriptor[];
     commands(): BuiltinPluginCommand[];
-    command(name: string): BuiltinPluginCommand | undefined;
+    command(prefix: string, name: string): BuiltinPluginCommand | undefined;
+    commandsNamed(name: string): BuiltinPluginCommand[];
+    defaultCommand(prefix: string): BuiltinPluginCommand | undefined;
     tools(context: BuiltinToolContext): ToolSpec[];
     worldParts(context: BuiltinWorldContext): WorldPart[];
     serverMethods(harness: Harness): Record<string, Handler>;

package/dist/sdk/plugins/builtinRegistry.js

@@ -1,33 +1,55 @@
 /** One checked registry for the Harness-owned plugin modules and their surface contributions. */
 export function createBuiltinPluginRegistry(modules) {
     const pluginIds = new Set();
-    const commandNames = new Set();
+    const prefixOwners = new Map();
+    const routeKeys = new Set();
     for (const module of modules) {
         const id = module.descriptor.id;
         if (pluginIds.has(id))
             throw new Error(`Duplicate built-in plugin id: ${id}`);
         pluginIds.add(id);
+        const prefix = module.commandPrefix ?? id;
+        if (!/^[a-z][a-z0-9-]*$/.test(prefix) || prefix === 'plugin' || prefix === 'skill')
+            throw new Error(`Invalid built-in plugin command prefix: ${prefix}`);
+        if ((module.commands?.length || module.defaultCommand) && prefixOwners.has(prefix)) {
+            throw new Error(`Duplicate built-in plugin command prefix: ${prefix}`);
+        }
+        if (module.commands?.length || module.defaultCommand)
+            prefixOwners.set(prefix, id);
         for (const command of module.commands ?? []) {
-            if (!/^[a-z][a-z0-9-]*$/i.test(command.name))
+            if (!/^[a-z][a-z0-9-]*$/.test(command.name))
                 throw new Error(`Invalid built-in plugin command: ${command.name}`);
-            if (commandNames.has(command.name))
-                throw new Error(`Duplicate built-in plugin command: ${command.name}`);
-            commandNames.add(command.name);
+            const key = `${prefix}:${command.name}`;
+            if (routeKeys.has(key))
+                throw new Error(`Duplicate built-in plugin command: ${key}`);
+            routeKeys.add(key);
+        }
+        if (module.defaultCommand && !module.commands?.some(command => command.name === module.defaultCommand)) {
+            throw new Error(`Unknown default command for built-in plugin ${id}: ${module.defaultCommand}`);
         }
     }
     const commands = modules.flatMap(module => (module.commands ?? []).map(command => ({
         pluginId: module.descriptor.id,
+        prefix: module.commandPrefix ?? module.descriptor.id,
         ...command,
-        namespace: module.descriptor.required ? 'unprefixed' : 'plugin'
+        legacyBare: !!module.descriptor.required
     })));
-    const byCommand = new Map(commands.map(command => [command.name, command]));
+    const byRoute = new Map(commands.map(command => [`${command.prefix}:${command.name}`, command]));
+    const byName = new Map();
+    for (const command of commands)
+        byName.set(command.name, [...(byName.get(command.name) ?? []), command]);
+    const defaults = new Map(modules.flatMap(module => module.defaultCommand
+        ? [[module.commandPrefix ?? module.descriptor.id, byRoute.get(`${module.commandPrefix ?? module.descriptor.id}:${module.defaultCommand}`)]]
+        : []));
     const toolModules = modules.map((module, index) => ({ module, index })).filter(({ module }) => module.tools)
         .sort((left, right) => (left.module.toolOrder ?? left.index) - (right.module.toolOrder ?? right.index));
     return {
         modules,
         descriptors: () => modules.map(module => module.descriptor),
         commands: () => [...commands],
-        command: name => byCommand.get(name),
+        command: (prefix, name) => byRoute.get(`${prefix}:${name}`),
+        commandsNamed: name => [...(byName.get(name) ?? [])],
+        defaultCommand: prefix => defaults.get(prefix),
         tools: context => toolModules.flatMap(({ module }) => module.tools(context)),
         worldParts: context => modules.flatMap(module => {
             const part = module.createWorldPart?.(context);

package/dist/sdk/plugins/catalogue.js

@@ -43,6 +43,7 @@ function fromDescriptor(descriptor, source, attachments = null, caller = {}) {
         settings: (descriptor.settings ?? []).map((setting) => ({ ...setting, value: settingValue(setting, attachments?.settings[descriptor.id]) })),
         connectorTemplates: descriptor.connectorTemplates ?? [],
         attachment: switchable ? describe(attachments, descriptor.id, switchable.on) : null,
+        surfaces: descriptor.surfaces ?? null,
         contributions: [
             ...(descriptor.code ?? []).map((code) => contribution(descriptor.id, 'code', code.name, { description: code.description, state: on ? 'on' : 'off' })),
             ...(descriptor.sections ?? []).map((section) => contribution(descriptor.id, 'instruction', section.name, { description: section.description ?? '' })),
@@ -102,7 +103,7 @@ function foundContribution(plugin, item, trusted, input, projects) {
     const state = !item.enabled || !on ? 'off' : loads(item, trusted) ? 'on' : 'untrusted';
     const rest = { state, attachment, scope: attachment ? scopeWords(attachment, projects) : null };
     if (item.path.startsWith(BUILTIN_PREFIX))
-        return contribution(plugin, kind, name, { ...rest, description: 'Built into the pi command. A terminal session loads it; other sessions do not have it.' });
+        return contribution(plugin, kind, name, { ...rest, description: 'Built into the pi command. Xingular sessions do not load it, in the terminal or in a host, so both offer the same tools.' });
     if (item.kind === 'extension') {
         const observed = input.registered[item.path];
         const hash = input.loading ? registrationHash(input.loading, item.path) : null;

package/dist/sdk/plugins/commandPrefix.d.ts

@@ -0,0 +1,8 @@
+export interface CommandSourceInfo {
+    path: string;
+    source?: string;
+    origin?: 'package' | 'top-level';
+    baseDir?: string;
+}
+/** Stable command namespace for a Pi extension's owning package or loose extension file. */
+export declare function pluginCommandPrefix(source: CommandSourceInfo): string;