@xingular/harness 1.0.0 → 1.1.1

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

@@ -21,7 +21,12 @@ 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 { 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 +65,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 {
@@ -100,6 +107,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 +120,12 @@ export declare class Harness {
     refineHost: RefineHost | null;
     readonly terminals: Terminals;
     readonly doctor: Doctor;
+    /** 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,13 @@ 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 } 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 { AnnotationCapture } from "./annotations/capture.js";
+import { NoteDeliveries } from "./annotations/delivery.js";
 class Env {
     directory;
     productName;
@@ -74,6 +79,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 +92,12 @@ export class Harness {
     refineHost;
     terminals;
     doctor;
+    /** 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 };
@@ -146,7 +159,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,
@@ -157,9 +172,11 @@ export class Harness {
             plugins: this.plugins,
             resolveCapabilities: (caller, tools, cwd) => capabilities.resolve(this, { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null, cwd, tools }),
             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 +186,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, 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 +196,12 @@ 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');
+            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 +270,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));
@@ -274,6 +311,8 @@ export class Harness {
         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,14 @@ 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 { 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";
@@ -60,4 +63,11 @@ export { PROTOCOL_VERSION, RpcPeer, stdioTransport, type Handler, type Transport
 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";

package/dist/sdk/index.js

@@ -20,9 +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 { 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 { 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";
 export { webTools, WEB_PLUGIN, WEB_SEARCH_KEY } from "./web/tools.js";
 export { safeRequest } from "./web/safeRequest.js";
@@ -45,4 +48,8 @@ export { PROTOCOL_VERSION, RpcPeer, stdioTransport } from "./server/rpc.js";
 export { attach, serve } from "./server/serve.js";
 export { DEFAULT_SUBAGENT_DEPTH, MAX_SUBAGENT_DEPTH } from "./sessions/subagents.js";
 export { Subagents } from "./sessions/subagentService.js";
+export { Worktrees } from "./worktrees/service.js";
 export { WAIT_SUBAGENTS } from "./sessions/subagents.js";
+export * as pageNotes from "./annotations/store.js";
+export { PAGE_SCRIPT } from "./annotations/pageScript.js";
+export { NoteDeliveries } from "./annotations/delivery.js";

package/dist/sdk/mcp/connections.js

@@ -449,11 +449,12 @@ export class Connections {
     async launch(connection) {
         if (connection.kind === 'remote') {
             const headers = {};
-            for (const key of connection.headerKeys) {
-                const value = await this.secret(connection.id, headerItem(key));
-                if (value !== null)
-                    headers[key] = value;
-            }
+            if (connection.auth === 'headers')
+                for (const key of connection.headerKeys) {
+                    const value = await this.secret(connection.id, headerItem(key));
+                    if (value !== null)
+                        headers[key] = value;
+                }
             return { id: connection.id, name: connection.name, transport: 'http', url: connection.url ?? '', headers, auth: connection.auth, scopes: connection.oauthScopes };
         }
         let command = findBinary(connection.command) ?? (isAbsolute(connection.command) ? connection.command : null);
@@ -573,7 +574,13 @@ export class Connections {
             throw scopeMigrationError();
         }
         connection.envKeys = [...(existing?.envKeys ?? [])];
-        connection.headerKeys = [...(existing?.headerKeys ?? [])];
+        const keepHeaders = remote && connection.auth === 'headers' && existing?.kind === 'remote'
+            && existing.url === connection.url && existing.auth === 'headers';
+        connection.headerKeys = keepHeaders ? [...existing.headerKeys] : [];
+        if (!keepHeaders) {
+            for (const key of existing?.headerKeys ?? [])
+                await this.deleteSecret(connection.id, headerItem(key));
+        }
         // A sign-in belongs to one server and one client; never carry it to another.
         const sameServer = (existing?.url ?? null) === connection.url && (existing?.auth ?? '') === connection.auth && existing?.oauthClient === connection.oauthClient && existing?.catalogId === connection.catalogId && !oauthCredentials;
         if (!sameServer || connection.auth !== 'oauth')
@@ -588,7 +595,7 @@ export class Connections {
             else
                 await this.deleteSecret(connection.id, OAUTH_CLIENT_SECRET);
         }
-        for (const [key, value] of Object.entries(headers ?? {})) {
+        for (const [key, value] of Object.entries(remote && connection.auth === 'headers' ? headers ?? {} : {})) {
             if (!/^[A-Za-z0-9_-]+$/.test(key) || /[\r\n\0]/.test(value))
                 throw invalid('Invalid header name or value.');
             await this.setSecret(connection.id, headerItem(key), value);

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

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

package/dist/sdk/mcp/serverMethods.js

@@ -0,0 +1,22 @@
+import { validateScopeIds } from "./connections.js";
+import { optional, text } from "../server/params.js";
+export function connectedAppServerMethods(harness) {
+    const apps = harness.apps;
+    return {
+        'connections.list': () => apps.connections.list(),
+        'connections.forScope': (params) => apps.connections.forScope({ agentId: optional(params, 'agentId'), projectId: optional(params, 'projectId') }),
+        'connections.save': (params) => apps.save(params.input),
+        'connections.allowTool': (params) => apps.connections.allowTool(text(params, 'connectionId'), text(params, 'tool')),
+        'connections.remove': (params) => apps.remove(text(params, 'connectionId')),
+        'connections.test': (params) => apps.test(text(params, 'connectionId')),
+        'connections.signIn': (params) => apps.signIn(text(params, 'connectionId')),
+        'connections.signOut': (params) => apps.signOut(text(params, 'connectionId')),
+        'connections.runContext': (params) => apps.runContext(text(params, 'runId')),
+        'connections.refreshSource': (params) => apps.refreshSource(text(params, 'runId'), text(params, 'traceId'), text(params, 'sourceUri')),
+        'connections.setAgentScope': (params) => apps.setAgentScope(params.creator ?? {}, text(params, 'agentId'), Array.isArray(params.ids) ? params.ids : []),
+        'connections.removeAgentScope': (params) => apps.removeAgentScope(text(params, 'agentId')),
+        'connections.revision': () => apps.connections.revision(),
+        'connections.appClients': () => apps.appClients(),
+        'connections.validateScope': (params) => validateScopeIds(apps.connections.list(), { agentId: optional(params, 'agentId'), projectId: optional(params, 'projectId') }, Array.isArray(params.ids) ? params.ids : [])
+    };
+}

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

@@ -3,4 +3,5 @@ import type { PluginDescriptor } from "./types.js";
 export declare const PI_PLUGIN: PluginDescriptor;
 /** The variant: the eight components that shape what an agent is told and can do. */
 export declare const VARIANT_PLUGIN: PluginDescriptor;
+export declare const BUILTIN_PLUGIN_REGISTRY: import("./builtinRegistry.js").BuiltinPluginRegistry;
 export declare const HARNESS_PLUGINS: readonly PluginDescriptor[];

package/dist/sdk/plugins/builtin.js

@@ -1,21 +1,45 @@
-// The harness's own parts, described as plugins. Each is a description of code that already
-// exists; none of it is loaded through Pi's extension system.
+// 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 } from "../tools/askUser.js";
-import { CHECKLIST_WRITE } from "../tools/checklist.js";
+import { ASK_USER, askUserTool } from "../tools/askUser.js";
+import { CHECKLIST_WRITE, checklistTool } from "../tools/checklist.js";
 import { SPAWN_SUBAGENT, WAIT_SUBAGENTS } from "../sessions/subagents.js";
+import { subagentTools } from "../tools/spawnSubagent.js";
+import { SESSION_NAME } from "../tools/sessionName.js";
 import { RECALL_TOOLS, SKILL_TOOLS, TRAJECTORY_TOOLS, WIKI_READ_TOOLS, WIKI_WRITE_TOOLS } from "../tools/definitions.js";
 import { FIRST_PARTY_PLUGINS } from "./firstParty.js";
 import { WEB_PLUGIN } from "../web/tools.js";
-import { BROWSER_PLUGIN } from "../browser/index.js";
+import { KEYLESS_SEARCH, webPart } from "../web/part.js";
+import { BROWSER_PLUGIN, browserPluginPart } from "../browser/index.js";
+import { ANNOTATIONS_PLUGIN } from "../annotations/part.js";
+import { annotationsPart } from "../annotations/part.js";
+import { webServerMethods } from "../web/serverMethods.js";
+import { browserServerMethods } from "../browser/serverMethods.js";
+import { annotationServerMethods } from "../annotations/serverMethods.js";
+import { doctorServerMethods } from "../doctor/serverMethods.js";
+import { worktreeServerMethods } from "../worktrees/serverMethods.js";
+import { hubServerMethods } from "../hub/serverMethods.js";
+import { refinementServerMethods } from "../refine/serverMethods.js";
+import { wikiServerMethods } from "../wiki/serverMethods.js";
+import { historyServerMethods } from "../history/serverMethods.js";
+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 { createBuiltinPluginRegistry } from "./builtinRegistry.js";
 const tools = (definitions) => definitions.map((tool) => ({ name: tool.name, description: tool.label }));
+const toolContribution = (definitions, toolOrder) => ({
+    toolOrder,
+    tools: (context) => context.harnessTools
+        ? harnessTools(context.env, context.caller, { variantDir: context.variantDir, definitions })
+        : []
+});
 /** Pi itself. Its command's built-in extensions are added to it as they are found. */
 export const PI_PLUGIN = {
     id: 'pi',
     title: 'Pi',
     description: 'The engine every session runs on: its base prompt, its file and shell tools, and the extensions built into its command.',
     required: 'Pi runs every session.',
-    tools: NATIVE_GROUP.map((name) => ({ name })),
+    tools: [...NATIVE_GROUP.map((name) => ({ name })), { name: SESSION_NAME }],
     toolGroups: ['Native']
 };
 /** The variant: the eight components that shape what an agent is told and can do. */
@@ -25,6 +49,7 @@ export const VARIANT_PLUGIN = {
     description: 'The agent\'s own variant: system prompt, guardrails, memory and tool guidance in every prompt; skills, scripts and subagents on demand; plugins in the tool loop. Versioned, and refined from evidence.',
     required: 'Every agent runs on a variant.',
     sections: [
+        { id: 'harness-identity', name: 'Harness identity', description: 'Fixed foundation identity; not part of the variant.' },
         { id: 'system', name: 'System prompt', description: 'c1: role and procedure.' },
         { id: 'guardrails', name: 'Guardrails', description: 'c2: standing rules.' },
         { id: 'memory', name: 'Memory', description: 'c3: durable facts about this kind of work.' },
@@ -34,35 +59,105 @@ export const VARIANT_PLUGIN = {
     ],
     tools: tools(SKILL_TOOLS)
 };
-export const HARNESS_PLUGINS = [
-    PI_PLUGIN,
-    { id: 'subagents', title: 'Subagents', description: 'Isolated child runs of the same caller, bounded by parent capabilities and nesting depth.', required: 'Availability is selected by the session host; child runs retain the parent permission boundary.', tools: [{ name: SPAWN_SUBAGENT, description: 'Start a subagent' }, { name: WAIT_SUBAGENTS, description: 'Wait for subagents' }] },
-    VARIANT_PLUGIN,
+const SUBAGENTS_PLUGIN = { id: 'subagents', title: 'Subagents', description: 'Isolated child runs of the same caller, bounded by parent capabilities and nesting depth.', required: 'Availability is selected by the session host; child runs retain the parent permission boundary.', tools: [{ name: SPAWN_SUBAGENT, description: 'Start a subagent' }, { name: WAIT_SUBAGENTS, description: 'Wait for subagents' }] };
+const WIKI_PLUGIN = {
+    id: 'wiki',
+    title: 'Wiki',
+    description: 'Notes about projects, linked to each other, that agents search and read.',
+    required: 'Project notes are reached through it.',
+    tools: tools([...WIKI_READ_TOOLS, ...WIKI_WRITE_TOOLS]),
+    sections: [
+        { id: 'wiki', name: 'Wiki', description: 'The current project\'s notes.' },
+        { id: 'references', name: 'Selected references', description: 'Notes pinned to one request.' }
+    ],
+    toolGroups: ['Wiki']
+};
+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 CONNECTED_APPS_PLUGIN = {
+    id: 'connected-apps',
+    title: 'Connected apps',
+    description: 'Outside services reached over MCP, behind two tools that list and call what is connected.',
+    required: 'Connected apps are reached only through it. Each app is switched on its own.',
+    manage: 'connections',
+    tools: CONNECTION_TOOLS.map((name) => ({ name })),
+    toolGroups: ['Connections']
+};
+const DOCTOR_PLUGIN = { id: 'doctor', title: 'Doctor', description: 'Local readiness checks and explicitly confirmed live probes for accounts, models and tools.', required: 'Every local terminal has readiness diagnostics.' };
+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 SIDE_QUESTIONS_PLUGIN = {
+    id: 'side-questions',
+    title: 'Side questions',
+    description: 'Separate, tool-free answers that use a redacted projection of the main conversation.',
+    required: 'Every host can ask a side question without steering its main run.',
+    sections: [{ id: 'side-question', name: 'Side-question role', description: 'Fixed instructions for an independent, tool-free side run.' }]
+};
+export const BUILTIN_PLUGIN_REGISTRY = createBuiltinPluginRegistry([
     {
-        id: 'wiki',
-        title: 'Wiki',
-        description: 'Notes about projects, linked to each other, that agents search and read.',
-        required: 'Project notes are reached through it.',
-        tools: tools([...WIKI_READ_TOOLS, ...WIKI_WRITE_TOOLS]),
-        sections: [
-            { id: 'wiki', name: 'Wiki', description: 'The current project\'s notes.' },
-            { id: 'references', name: 'Selected references', description: 'Notes pinned to one request.' }
+        descriptor: PI_PLUGIN,
+        toolOrder: 60,
+        tools: context => context.harnessTools ? [context.sessionName] : []
+    },
+    {
+        descriptor: SUBAGENTS_PLUGIN,
+        toolOrder: 70,
+        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) },
+    { descriptor: WIKI_PLUGIN, ...toolContribution([...WIKI_READ_TOOLS, ...WIKI_WRITE_TOOLS], 20), serverMethods: wikiServerMethods },
+    {
+        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: CONNECTED_APPS_PLUGIN,
+        toolOrder: 0,
+        tools: context => context.connectionTools?.() ?? [],
+        serverMethods: connectedAppServerMethods
+    },
+    { descriptor: HUB_PLUGIN, serverMethods: hubServerMethods },
+    { descriptor: REFINEMENT_PLUGIN, serverMethods: refinementServerMethods },
+    { descriptor: SIDE_QUESTIONS_PLUGIN, serverMethods: sideQuestionServerMethods },
+    {
+        descriptor: WEB_PLUGIN,
+        createWorldPart: ({ options, setting }) => webPart({ secrets: options.secrets, request: options.request, keyless: () => setting(WEB_PLUGIN.id, KEYLESS_SEARCH) === 1 }),
+        serverMethods: webServerMethods
+    },
+    {
+        descriptor: BROWSER_PLUGIN,
+        createWorldPart: ({ browserEngine }) => browserEngine ? browserPluginPart(browserEngine) : null,
+        serverMethods: browserServerMethods
+    },
+    {
+        descriptor: ANNOTATIONS_PLUGIN,
+        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]' }
         ],
-        toolGroups: ['Wiki']
+        createWorldPart: ({ options }) => annotationsPart({ root: options.root, changed: options.notesChanged }),
+        serverMethods: annotationServerMethods
+    },
+    {
+        descriptor: DOCTOR_PLUGIN,
+        commands: [{ name: 'doctor', description: 'Check account, model, tools and runtime readiness' }],
+        serverMethods: doctorServerMethods
     },
-    { 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'] },
-    { 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 }] },
-    { 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' }] },
     {
-        id: 'connected-apps',
-        title: 'Connected apps',
-        description: 'Outside services reached over MCP, behind two tools that list and call what is connected.',
-        required: 'Connected apps are reached only through it. Each app is switched on its own.',
-        manage: 'connections',
-        tools: CONNECTION_TOOLS.map((name) => ({ name })),
-        toolGroups: ['Connections']
+        descriptor: WORKTREES_PLUGIN,
+        commands: [{ name: 'worktree', description: 'Work in a managed git worktree: new, switch, hand off, remove' }],
+        serverMethods: worktreeServerMethods
     },
-    WEB_PLUGIN,
-    BROWSER_PLUGIN,
-    ...FIRST_PARTY_PLUGINS
-];
+    ...FIRST_PARTY_PLUGINS.map(descriptor => ({ descriptor }))
+]);
+export const HARNESS_PLUGINS = BUILTIN_PLUGIN_REGISTRY.descriptors();