@xingular/harness 1.1.1 → 1.2.0

package/dist/sdk/core/workspaceWriteOperations.js

@@ -0,0 +1,206 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { constants as fsConstants, realpathSync, statSync } from 'node:fs';
+import { access, readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { isWithinWorkspace, resolveWritePath, verifyWorkspaceRoot } from "./workspace.js";
+import { workspaceSandboxCommand } from "./workspaceSandbox.js";
+const writeAuthorization = new AsyncLocalStorage();
+const atomicWriteScript = `
+const fs = require('node:fs')
+const path = require('node:path')
+const crypto = require('node:crypto')
+const input = JSON.parse(fs.readFileSync(0, 'utf8'))
+const target = input.path
+const parent = path.dirname(target)
+fs.mkdirSync(parent, { recursive: true })
+let mode = 0o666
+let preserveMode = false
+try {
+  const existing = fs.lstatSync(target)
+  if (existing.isSymbolicLink() || !existing.isFile()) throw new Error('The write target is not a regular file.')
+  fs.accessSync(target, fs.constants.W_OK)
+  if (input.expectedContentHash) {
+    const current = fs.readFileSync(target)
+    if (crypto.createHash('sha256').update(current).digest('hex') !== input.expectedContentHash) {
+      throw new Error('The file changed after the edit tool read it; retry against the current contents.')
+    }
+  }
+  mode = existing.mode & 0o7777
+  preserveMode = true
+} catch (error) {
+  if (error && error.code !== 'ENOENT') throw error
+}
+const temporary = path.join(parent, '.' + path.basename(target) + '.' + process.pid + '.' + crypto.randomBytes(8).toString('hex') + '.tmp')
+let descriptor
+try {
+  descriptor = fs.openSync(temporary, 'wx', mode)
+  fs.writeFileSync(descriptor, input.content, 'utf8')
+  if (preserveMode) fs.fchmodSync(descriptor, mode)
+  fs.fsyncSync(descriptor)
+  fs.closeSync(descriptor)
+  descriptor = undefined
+  fs.renameSync(temporary, target)
+  try {
+    const directory = fs.openSync(parent, 'r')
+    try { fs.fsyncSync(directory) } finally { fs.closeSync(directory) }
+  } catch {}
+} catch (error) {
+  if (descriptor !== undefined) fs.closeSync(descriptor)
+  try { fs.unlinkSync(temporary) } catch {}
+  throw error
+}
+`;
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function nearestExistingDirectory(path) {
+    let current = dirname(path);
+    while (true) {
+        try {
+            const canonical = realpathSync(current);
+            if (!statSync(canonical).isDirectory())
+                throw new Error(`Write scope is not a directory: ${canonical}`);
+            return canonical;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            const parent = dirname(current);
+            if (parent === current)
+                throw new Error(`Could not find a writable parent for ${path}.`);
+            current = parent;
+        }
+    }
+}
+function killProcess(child) {
+    if (child.pid && process.platform !== 'win32') {
+        try {
+            process.kill(-child.pid, 'SIGKILL');
+            return;
+        }
+        catch {
+            // Fall back to the direct child if it has already left its process group.
+        }
+    }
+    child.kill('SIGKILL');
+}
+async function runAtomicWrite(authorization, path, content) {
+    const root = verifyWorkspaceRoot(authorization.workspaceRoot);
+    const canonicalPath = resolveWritePath(path, authorization.cwd);
+    if (canonicalPath !== authorization.path)
+        throw new Error('The write target changed after workspace approval; the write was blocked.');
+    const outside = !isWithinWorkspace(root, canonicalPath);
+    if (outside !== authorization.outside || (outside && !authorization.authorized)) {
+        throw new Error('The write authorization no longer matches the active workspace target.');
+    }
+    const additionalRoots = outside ? [nearestExistingDirectory(canonicalPath)] : [];
+    const command = `exec ${shellQuote(process.execPath)} -e ${shellQuote(atomicWriteScript)}`;
+    const spec = workspaceSandboxCommand(process.platform, root, root, command, additionalRoots);
+    const env = {
+        PATH: '/usr/bin:/bin',
+        ...(process.env.HOME ? { HOME: process.env.HOME } : {})
+    };
+    await new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(spec.executable, spec.args, {
+            cwd: root,
+            detached: process.platform !== 'win32',
+            env,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            windowsHide: true
+        });
+        const output = [];
+        let outputBytes = 0;
+        let settled = false;
+        const timeout = setTimeout(() => {
+            killProcess(child);
+            finish(new Error('Workspace-contained atomic write timed out.'));
+        }, 30_000);
+        const capture = (chunk) => {
+            if (outputBytes >= 8_192)
+                return;
+            const remaining = 8_192 - outputBytes;
+            output.push(chunk.subarray(0, remaining));
+            outputBytes += Math.min(chunk.length, remaining);
+        };
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            authorization.signal?.removeEventListener('abort', abort);
+            if (error)
+                rejectPromise(error);
+            else
+                resolvePromise();
+        };
+        const abort = () => {
+            killProcess(child);
+            finish(new Error('Workspace-contained atomic write was aborted.'));
+        };
+        authorization.signal?.addEventListener('abort', abort, { once: true });
+        if (authorization.signal?.aborted) {
+            abort();
+            return;
+        }
+        child.stdout?.on('data', capture);
+        child.stderr?.on('data', capture);
+        child.once('error', (error) => finish(error));
+        child.once('close', (code) => {
+            if (code === 0) {
+                finish();
+                return;
+            }
+            const detail = Buffer.concat(output).toString('utf8').trim();
+            finish(new Error(`Workspace-contained atomic write failed${detail ? `: ${detail.slice(-2000)}` : ` with exit code ${code ?? 'unknown'}`}.`));
+        });
+        child.stdin?.on('error', () => { });
+        child.stdin?.end(JSON.stringify({
+            path: canonicalPath,
+            content,
+            ...(authorization.expectedContentHash ? { expectedContentHash: authorization.expectedContentHash } : {})
+        }));
+    });
+}
+async function writeWorkspaceFile(path, content) {
+    const authorization = writeAuthorization.getStore();
+    if (!authorization?.authorized)
+        throw new Error('The file write has no current workspace authorization.');
+    await runAtomicWrite(authorization, path, content);
+}
+export const workspaceWriteOperations = {
+    mkdir: async (_directory) => { },
+    writeFile: writeWorkspaceFile
+};
+export const workspaceEditOperations = {
+    access: async (path) => access(path, fsConstants.R_OK | fsConstants.W_OK),
+    readFile: async (path) => {
+        const content = await readFile(path);
+        const authorization = writeAuthorization.getStore();
+        if (authorization && resolve(path) === authorization.path) {
+            authorization.expectedContentHash = createHash('sha256').update(content).digest('hex');
+        }
+        return content;
+    },
+    writeFile: writeWorkspaceFile
+};
+/** Binds one policy-approved path and abort signal to Pi's native write/edit operation. */
+export function withWorkspaceWriteAuthorization(tool, authorizations) {
+    const native = tool;
+    const execute = native.execute.bind(tool);
+    return {
+        ...tool,
+        execute: (...args) => {
+            const toolCallId = String(args[0] ?? '');
+            const authorization = authorizations.get(toolCallId);
+            authorizations.delete(toolCallId);
+            if (!authorization?.authorized)
+                throw new Error('The file write has no current workspace authorization.');
+            const signal = args[2];
+            if (signal && typeof signal === 'object' && 'aborted' in signal)
+                authorization.signal = signal;
+            return writeAuthorization.run(authorization, () => execute(...args));
+        }
+    };
+}

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/index.d.ts

@@ -21,6 +21,10 @@ export type { ApprovalFacts, ApprovalPolicy, AutomaticReason } from "./sessions/
 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";
@@ -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,6 +20,8 @@ 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";
@@ -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

@@ -2,6 +2,8 @@
 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 { 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) => ({
@@ -75,6 +80,7 @@ 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 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: 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);