@xingular/harness 1.0.0 → 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/serverMethods.d.ts

@@ -0,0 +1,3 @@
+import type { Harness } from "../harness.js";
+import type { Handler } from "../server/rpc.js";
+export declare function doctorServerMethods(harness: Harness): Record<string, Handler>;

package/dist/sdk/doctor/serverMethods.js

@@ -0,0 +1,8 @@
+import { text } from "../server/params.js";
+export function doctorServerMethods(harness) {
+    return {
+        'doctor.start': (params) => harness.doctor.start(params),
+        'doctor.read': (params) => harness.doctor.read(text(params, 'id')),
+        'doctor.cancel': (params) => harness.doctor.cancel(text(params, 'id'))
+    };
+}

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

@@ -21,7 +21,14 @@ import type { ToolPolicy } from "./sessions/policy.js";
 import { RunRegistry } from "./sessions/registry.js";
 import type { SessionFactory } from "./sessions/runner.js";
 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";
 export interface HarnessOptions {
     /** Disable the generic backend when a host supplies its own browser tools. */
     browser?: boolean;
@@ -60,6 +67,8 @@ export interface HarnessOptions {
     oauthClients?: AppOAuthClients;
     /** Replaces how a plugin's hooks file is read as a module, for tests. */
     hookImporter?: (address: string) => Promise<unknown>;
+    /** Where managed worktrees are made, the prefix of branches they get, and how many `prune` keeps. */
+    worktrees?: WorktreesOptions;
 }
 /** What starting on a data root found and repaired. */
 export interface Recovery {
@@ -82,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;
@@ -100,6 +111,8 @@ export declare class Harness {
     applicationPlugins: ReadonlySet<string>;
     readonly subagents: Subagents;
     readonly sessions: Sessions;
+    /** Tool-free, run-backed questions over a redacted projection of the main conversation. */
+    readonly sideQuestions: SideQuestions;
     /** Web, browser and computer tools (page 13). */
     readonly world: World;
     /** Which plugin code in variants a person trusted. */
@@ -111,6 +124,15 @@ 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). */
+    readonly noteCapture: AnnotationCapture;
+    /** Page notes on their way to a session (PROP-0018). */
+    readonly pageNotes: NoteDeliveries;
     /** Resolves when what was loaded in the background at construction is in place. */
     readonly ready: Promise<void>;
     recovery: Recovery;

package/dist/sdk/harness.js

@@ -25,6 +25,7 @@ import { migrateVariantLayout } from "./variant/migrate.js";
 import { VariantTrust } from "./variant/trust.js";
 import * as notes from "./wiki/notes.js";
 import * as pluginApi from "./plugins/api.js";
+import * as pluginInstall from "./plugins/install.js";
 import * as attachments from "./plugins/attachments.js";
 import { HARNESS_PLUGINS } from "./plugins/builtin.js";
 import { World } from "./world/world.js";
@@ -35,9 +36,16 @@ 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 { 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 {
     directory;
     productName;
@@ -56,6 +64,8 @@ class Env {
     }
 }
 export class Harness {
+    /** The periodic liveness check, started once with recovery (PROP-0041). */
+    staleRuns;
     browserEnabled;
     hub;
     bus = new Bus();
@@ -74,6 +84,8 @@ export class Harness {
     applicationPlugins = new Set();
     subagents;
     sessions;
+    /** Tool-free, run-backed questions over a redacted projection of the main conversation. */
+    sideQuestions;
     /** Web, browser and computer tools (page 13). */
     world;
     /** Which plugin code in variants a person trusted. */
@@ -85,6 +97,15 @@ 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). */
+    noteCapture;
+    /** Page notes on their way to a session (PROP-0018). */
+    pageNotes;
     /** Resolves when what was loaded in the background at construction is in place. */
     ready;
     recovery = { interruptedRuns: 0, interruptedRunIds: [], reindexedPages: 0, migrationError: null };
@@ -103,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) => {
@@ -146,7 +171,9 @@ export class Harness {
             reloadTimer.unref?.();
         });
         this.describe(options.plugins ?? []);
-        this.subagents = new Subagents(this.env, this.runs, (input) => this.sessions.run(input));
+        this.worktrees = new Worktrees(this.stateDir, options.worktrees);
+        this.noteCapture = new AnnotationCapture({ stateDir: this.stateDir });
+        this.subagents = new Subagents(this.env, this.runs, (input) => this.sessions.run(input), { descriptors: () => HARNESS_PLUGINS });
         this.sessions = new Sessions({
             subagents: this.subagents,
             env: this.env,
@@ -156,10 +183,13 @@ 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
+            trust: this.trust,
+            worktrees: this.worktrees
         });
-        this.world = new World({ root: () => this.env.root, stateDir: this.stateDir, secrets, browser: this.browserEnabled ? undefined : false });
+        this.sideQuestions = new SideQuestions({ env: this.env, sessions: this.sessions, runs: this.runs });
+        this.world = new World({ root: () => this.env.root, stateDir: this.stateDir, secrets, browser: this.browserEnabled ? undefined : false, notesChanged: (sessionId, ids) => this.bus.emit({ type: 'annotations.changed', sessionId, ids }) });
         // The harness's own world tools come first; a tool an application provides under the same name is not added again.
         this.sessions.provide(this.world.provider());
         this.doctor = new Doctor({
@@ -169,7 +199,8 @@ export class Harness {
         const refineRuntime = { root: () => this.env.root, runs: this.runs, run: (input) => this.sessions.run(input) };
         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.terminals = new Terminals({ trust: this.trust, subagents: this.subagents, 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) }, assets: options.assets, hub: this.hub, world: this.world, doctor: this.doctor });
+        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, 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);
@@ -178,6 +209,16 @@ export class Harness {
                 recall.indexRun(this.env.root, event.runId);
             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.
+                setTimeout(() => void this.pageNotes.runEnded(run.sessionId).catch((error) => log('page notes', error instanceof Error ? error.message : String(error))), 250).unref?.();
+            }
             if ((event.type === 'completed' || event.type === 'failed') && run) {
                 if (event.type === 'completed')
                     this.lessons.consider(run);
@@ -246,6 +287,19 @@ export class Harness {
         let interruptedRunIds = [];
         try {
             interruptedRunIds = markInterruptedRuns(root, `${this.env.productName} stopped before the run settled.`);
+            const recoveredSessions = new Set();
+            for (const runId of interruptedRunIds) {
+                try {
+                    const sessionId = loadRun(root, runId).sessionId;
+                    if (!sessionId || recoveredSessions.has(sessionId))
+                        continue;
+                    recoveredSessions.add(sessionId);
+                    setTimeout(() => void this.pageNotes.runEnded(sessionId).catch((error) => log('page notes', error instanceof Error ? error.message : String(error))), 250).unref?.();
+                }
+                catch {
+                    // A malformed run record does not prevent the rest of recovery.
+                }
+            }
         }
         catch (error) {
             log('run recovery', error instanceof Error ? error.message : String(error));
@@ -257,23 +311,48 @@ 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();
         await this.lessons.close();
         await this.terminals.close();
+        await this.noteCapture.close();
+        await this.sideQuestions.close();
         await this.runs.interruptAll();
         await this.world.close();
         await this.hooks.settled().catch(() => undefined);

package/dist/sdk/history/recall.js

@@ -32,11 +32,11 @@ export function passages(run, events) {
     return found;
 }
 function writeRun(database, run, found) {
-    execute(database, 'DELETE FROM recall_fts WHERE run_id = ?1', run.id);
+    execute(database, 'DELETE FROM recall_fts WHERE run_id = ?', run.id);
     found.forEach((passage, seq) => {
-        execute(database, 'INSERT INTO recall_fts (run_id, seq, role, at, mode, session_id, project_id, text) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)', run.id, seq, passage.role, passage.at, run.mode, run.sessionId, run.projectId, passage.text);
+        execute(database, 'INSERT INTO recall_fts (run_id, seq, role, at, mode, session_id, project_id, text) VALUES (?, ?, ?, ?, ?, ?, ?, ?)', run.id, seq, passage.role, passage.at, run.mode, run.sessionId, run.projectId, passage.text);
     });
-    execute(database, 'INSERT OR REPLACE INTO recall_runs (run_id, passages, status) VALUES (?1, ?2, ?3)', run.id, found.length, run.status);
+    execute(database, 'INSERT OR REPLACE INTO recall_runs (run_id, passages, status) VALUES (?, ?, ?)', run.id, found.length, run.status);
 }
 function eventsOf(root, runId) {
     try {
@@ -93,13 +93,13 @@ export function search(root, query, scope, limit) {
     if (!fts)
         return [];
     return withIndex(root, (database) => all(database, `SELECT run_id, seq, role, at, mode, session_id, project_id, snippet(recall_fts, 7, '', '', '…', 40) AS snippet
-       FROM recall_fts WHERE recall_fts MATCH ?1
-         AND (?2 IS NULL OR session_id = ?2) AND (?3 IS NULL OR mode = ?3)
-         AND (?4 IS NULL OR project_id = ?4) AND (?5 IS NULL OR at >= ?5)
-       ORDER BY bm25(recall_fts), at DESC LIMIT ?6`, fts, scope.sessionId ?? null, scope.mode ?? null, scope.projectId ?? null, scope.since ?? null, Math.min(Math.max(limit, 1), SEARCH_MAX)).map((row) => ({ runId: row.run_id, seq: Number(row.seq), role: row.role, at: row.at ?? '', mode: row.mode ?? '', sessionId: row.session_id ?? '', projectId: row.project_id, snippet: row.snippet })));
+       FROM recall_fts WHERE recall_fts MATCH ?
+         AND (? IS NULL OR session_id = ?) AND (? IS NULL OR mode = ?)
+         AND (? IS NULL OR project_id = ?) AND (? IS NULL OR at >= ?)
+       ORDER BY bm25(recall_fts), at DESC LIMIT ?`, fts, scope.sessionId ?? null, scope.sessionId ?? null, scope.mode ?? null, scope.mode ?? null, scope.projectId ?? null, scope.projectId ?? null, scope.since ?? null, scope.since ?? null, Math.min(Math.max(limit, 1), SEARCH_MAX)).map((row) => ({ runId: row.run_id, seq: Number(row.seq), role: row.role, at: row.at ?? '', mode: row.mode ?? '', sessionId: row.session_id ?? '', projectId: row.project_id, snippet: row.snippet })));
 }
 export function read(root, runId) {
-    return withIndex(root, (database) => all(database, 'SELECT seq, role, at, text FROM recall_fts WHERE run_id = ?1 ORDER BY CAST(seq AS INTEGER)', runId).map((row) => ({ seq: Number(row.seq), role: row.role, at: row.at ?? '', text: row.text })));
+    return withIndex(root, (database) => all(database, 'SELECT seq, role, at, text FROM recall_fts WHERE run_id = ? ORDER BY CAST(seq AS INTEGER)', runId).map((row) => ({ seq: Number(row.seq), role: row.role, at: row.at ?? '', text: row.text })));
 }
 function textParam(params, key) {
     const value = params?.[key];

package/dist/sdk/history/serverMethods.d.ts

@@ -0,0 +1,3 @@
+import type { Harness } from "../harness.js";
+import type { Handler } from "../server/rpc.js";
+export declare function historyServerMethods(harness: Harness): Record<string, Handler>;

package/dist/sdk/history/serverMethods.js

@@ -0,0 +1,8 @@
+import * as recall from "./recall.js";
+import { text } from "../server/params.js";
+export function historyServerMethods(harness) {
+    return {
+        'recall.search': (params) => recall.searchAll(harness.env, typeof params.query === 'string' ? params.query : '', params.filter ?? {}),
+        'recall.read': (params) => recall.read(harness.env.root, text(params, 'runId'))
+    };
+}

package/dist/sdk/hub/cli.d.ts

@@ -1,5 +1,5 @@
 import { Harness, type HarnessOptions } from "../harness.js";
-export declare const HUB_USAGE = "Usage: xharness hub <list | show | install> [id@version] [options]\n\n  list [--refresh]             Browse the curated catalog and locally installed versions\n  show <id@version>            Show publisher, license, source, and delivery details\n  install <id@version>         Install the exact reviewed version, disabled and untrusted\n\n  --data <dir>                 Target data library (default: ~/.xingular-harness/data)\n  --state <dir>                Target device state (default: ~/.xingular-harness/state)\n  --refresh                    Refresh the public catalog; cached items remain usable offline\n";
+export declare const HUB_USAGE = "Usage: xagent hub <list | show | install> [id@version] [options]\n\n  list [--refresh]             Browse the curated catalog and locally installed versions\n  show <id@version>            Show publisher, license, source, and delivery details\n  install <id@version>         Install the exact reviewed version, disabled and untrusted\n\n  --data <dir>                 Target data library (default: ~/.xingular-harness/data)\n  --state <dir>                Target device state (default: ~/.xingular-harness/state)\n  --refresh                    Refresh the public catalog; cached items remain usable offline\n";
 export declare function runHubCli(argv: string[], dependencies?: {
     home?: string;
     write?: (text: string) => void;

package/dist/sdk/hub/cli.js

@@ -1,7 +1,7 @@
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { Harness } from "../harness.js";
-export const HUB_USAGE = `Usage: xharness hub <list | show | install> [id@version] [options]
+export const HUB_USAGE = `Usage: xagent hub <list | show | install> [id@version] [options]
 
   list [--refresh]             Browse the curated catalog and locally installed versions
   show <id@version>            Show publisher, license, source, and delivery details

package/dist/sdk/hub/schema.d.ts

@@ -263,9 +263,9 @@ export declare const hubOverviewSchema: z.ZodObject<{
         }>>;
     }, z.core.$strict>>;
     origin: z.ZodEnum<{
-        remote: "remote";
         bundled: "bundled";
         cached: "cached";
+        remote: "remote";
     }>;
     refreshedAt: z.ZodNullable<z.ZodString>;
     error: z.ZodNullable<z.ZodString>;

package/dist/sdk/hub/serverMethods.d.ts

@@ -0,0 +1,3 @@
+import type { Harness } from "../harness.js";
+import type { Handler } from "../server/rpc.js";
+export declare function hubServerMethods(harness: Harness): Record<string, Handler>;

package/dist/sdk/hub/serverMethods.js

@@ -0,0 +1,11 @@
+import { text } from "../server/params.js";
+export function hubServerMethods(harness) {
+    return {
+        'hub.list': (params) => harness.hub.list(params.refresh === true),
+        'hub.get': (params) => harness.hub.get(text(params, 'id'), text(params, 'version'), params.preview === true),
+        'hub.install': (params) => harness.hub.install(text(params, 'id'), text(params, 'version')),
+        'hub.preview': (params) => harness.hub.preview(text(params, 'id'), text(params, 'version'), typeof params.offset === 'number' ? params.offset : 0),
+        'hub.uninstall': (params) => harness.hub.uninstall(text(params, 'id'), text(params, 'version')),
+        'hub.readDocument': (params) => harness.hub.readDocument(text(params, 'id'), text(params, 'version'))
+    };
+}

package/dist/sdk/index.d.ts

@@ -21,11 +21,18 @@ 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";
 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 { 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";
 export { webTools, WEB_PLUGIN, WEB_SEARCH_KEY, type WebToolOptions } from "./web/tools.js";
 export { safeRequest, type WebRequest, type WebResponse } from "./web/safeRequest.js";
@@ -53,11 +60,19 @@ 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";
 export { attach, serve, type Served } from "./server/serve.js";
 export { DEFAULT_SUBAGENT_DEPTH, MAX_SUBAGENT_DEPTH, type SubagentOptions, type SubagentInput } from "./sessions/subagents.js";
 export { Subagents } from "./sessions/subagentService.js";
+export { Worktrees } from "./worktrees/service.js";
+export type { CreateWorktreeInput, CreateWorktreeResult, HandoffResult, WorktreeRecord, WorktreeStatus, WorktreesOptions, WorktreeKind } from "./worktrees/types.js";
 export { WAIT_SUBAGENTS, type SubagentResult, type SubagentSelection } from "./sessions/subagents.js";
+export * as pageNotes from "./annotations/store.js";
+export type { Note as PageNote, NoteApp as PageNoteApp, NoteDelivery as PageNoteDelivery, NoteInput as PageNoteInput, NoteSource as PageNoteSource, NoteTarget as PageNoteTarget } from "./annotations/store.js";
+export { PAGE_SCRIPT } from "./annotations/pageScript.js";
+export { NoteDeliveries, type SendResult } from "./annotations/delivery.js";
+export type { CaptureTargetSpec, CaptureWindow, InspectState } from "./annotations/capture.js";