@xingular/harness 1.0.0 → 1.1.1

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

@@ -0,0 +1,53 @@
+import type { Harness } from "../harness.js";
+import type { Handler } from "../server/rpc.js";
+import type { WorldOptions, WorldPart } from "../world/world.js";
+import type { BrowserEngine } from "../browser/index.js";
+import type { CallerContext } from "../core/caller.js";
+import type { DispatchEnv } from "../tools/dispatch.js";
+import type { ToolSpec } from "../tools/types.js";
+import type { Subagents } from "../sessions/subagentService.js";
+import type { ActiveRun } from "../sessions/registry.js";
+import type { PluginDescriptor } from "./types.js";
+export interface BuiltinPluginCommand {
+    pluginId: string;
+    name: string;
+    description: string;
+    namespace: 'unprefixed' | 'plugin';
+}
+export interface BuiltinWorldContext {
+    options: WorldOptions;
+    setting(pluginId: string, key: string): number;
+    browserEngine: BrowserEngine | null;
+}
+export interface BuiltinToolContext {
+    env: DispatchEnv;
+    caller: CallerContext;
+    variantDir: string | null;
+    run: ActiveRun;
+    runId: string;
+    allowedTools: readonly string[];
+    harnessTools: boolean;
+    subagents: Subagents;
+    sessionName: ToolSpec;
+    connectionTools?: () => ToolSpec[];
+}
+export interface BuiltinPluginModule {
+    descriptor: PluginDescriptor;
+    /** Stable order for model tools, independent of descriptor display order. */
+    toolOrder?: number;
+    tools?: (context: BuiltinToolContext) => ToolSpec[];
+    commands?: readonly Omit<BuiltinPluginCommand, 'pluginId' | 'namespace'>[];
+    createWorldPart?: (context: BuiltinWorldContext) => WorldPart | null;
+    serverMethods?: (harness: Harness) => Record<string, Handler>;
+}
+export interface BuiltinPluginRegistry {
+    readonly modules: readonly BuiltinPluginModule[];
+    descriptors(): PluginDescriptor[];
+    commands(): BuiltinPluginCommand[];
+    command(name: string): BuiltinPluginCommand | undefined;
+    tools(context: BuiltinToolContext): ToolSpec[];
+    worldParts(context: BuiltinWorldContext): WorldPart[];
+    serverMethods(harness: Harness): Record<string, Handler>;
+}
+/** One checked registry for the Harness-owned plugin modules and their surface contributions. */
+export declare function createBuiltinPluginRegistry(modules: readonly BuiltinPluginModule[]): BuiltinPluginRegistry;

package/dist/sdk/plugins/builtinRegistry.js

@@ -0,0 +1,49 @@
+/** 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();
+    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);
+        for (const command of module.commands ?? []) {
+            if (!/^[a-z][a-z0-9-]*$/i.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 commands = modules.flatMap(module => (module.commands ?? []).map(command => ({
+        pluginId: module.descriptor.id,
+        ...command,
+        namespace: module.descriptor.required ? 'unprefixed' : 'plugin'
+    })));
+    const byCommand = new Map(commands.map(command => [command.name, command]));
+    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),
+        tools: context => toolModules.flatMap(({ module }) => module.tools(context)),
+        worldParts: context => modules.flatMap(module => {
+            const part = module.createWorldPart?.(context);
+            return part ? [part] : [];
+        }),
+        serverMethods: harness => {
+            const methods = {};
+            for (const module of modules) {
+                const contributed = module.serverMethods?.(harness) ?? {};
+                for (const [name, handler] of Object.entries(contributed)) {
+                    if (name in methods)
+                        throw new Error(`Duplicate built-in server method: ${name}`);
+                    methods[name] = handler;
+                }
+            }
+            return methods;
+        }
+    };
+}

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

@@ -1,5 +1,5 @@
 import { Harness, type HarnessOptions } from "../harness.js";
-export declare const PLUGINS_USAGE = "Usage: xharness plugins <command> [options]\n\n  list                         Every plugin and whether it is on\n  show <plugin id>             One plugin: what it brings, where it is on, its code\n  install <source>             A folder, an npm name, or a git address. It arrives off and untrusted\n  remove <plugin id>           Remove a plugin you installed\n  update [plugin id]           Fetch a newer version of one installed plugin, or of all\n  attach <id>                  Switch a plugin, or one thing it brings, on\n  detach <id>                  Switch it off\n  trust <plugin id> [--yes]    Show the files of its code, then trust them\n  untrust <plugin id>          Stop trusting its code\n\nOptions:\n  --data <dir>       Data directory (default: ~/.xingular-harness/data)\n  --state <dir>      State directory (default: ~/.xingular-harness/state)\n  --cwd <dir>        Also list what this working folder brings\n  --project <id>     attach/detach for one project instead of everywhere\n  --agent <id>       attach/detach for one agent instead of everywhere\n";
+export declare const PLUGINS_USAGE = "Usage: xagent plugins <command> [options]\n\n  list                         Every plugin and whether it is on\n  show <plugin id>             One plugin: what it brings, where it is on, its code\n  install <source>             A folder, an npm name, or a git address. It arrives off and untrusted\n  remove <plugin id>           Remove a plugin you installed\n  update [plugin id]           Fetch a newer version of one installed plugin, or of all\n  attach <id>                  Switch a plugin, or one thing it brings, on\n  detach <id>                  Switch it off\n  trust <plugin id> [--yes]    Show the files of its code, then trust them\n  untrust <plugin id>          Stop trusting its code\n\nOptions:\n  --data <dir>       Data directory (default: ~/.xingular-harness/data)\n  --state <dir>      State directory (default: ~/.xingular-harness/state)\n  --cwd <dir>        Also list what this working folder brings\n  --project <id>     attach/detach for one project instead of everywhere\n  --agent <id>       attach/detach for one agent instead of everywhere\n";
 export interface PluginsCliDependencies {
     home?: string;
     cwd?: string;

package/dist/sdk/plugins/cli.js

@@ -1,12 +1,13 @@
-// `xharness plugins …`: plugin control for a person using the harness without an
+// `xagent plugins …`: plugin control for a person using the harness without an
 // application. It runs outside any session, as the person who typed it, and acts directly.
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
+import { DEFAULT_PRODUCT_NAME } from "../core/env.js";
 import { Harness } from "../harness.js";
 import * as api from "./api.js";
 import * as install from "./install.js";
-export const PLUGINS_USAGE = `Usage: xharness plugins <command> [options]
+export const PLUGINS_USAGE = `Usage: xagent plugins <command> [options]
 
   list                         Every plugin and whether it is on
   show <plugin id>             One plugin: what it brings, where it is on, its code
@@ -81,7 +82,7 @@ export async function runPluginsCli(argv, dependencies = {}) {
     }
     const base = dependencies.cwd ?? process.cwd();
     const root = join(dependencies.home ?? homedir(), '.xingular-harness');
-    const options = { dataRoot: parsed.values.data ? resolve(base, parsed.values.data) : join(root, 'data'), stateDir: parsed.values.state ? resolve(base, parsed.values.state) : join(root, 'state'), productName: 'Xingular Harness' };
+    const options = { dataRoot: parsed.values.data ? resolve(base, parsed.values.data) : join(root, 'data'), stateDir: parsed.values.state ? resolve(base, parsed.values.state) : join(root, 'state'), productName: DEFAULT_PRODUCT_NAME };
     // Built without opening the data root: a plugin command must not settle runs or migrate a Wiki
     // that another process may be using.
     const harness = dependencies.createHarness ? dependencies.createHarness(options) : new Harness(options);

package/dist/sdk/prompt/compile.d.ts

@@ -4,6 +4,7 @@ import type { Materialised } from "../variant/materialise.js";
 export declare const REFERENCES_BUDGET = 12000;
 /** Where the harness's own sections sit; an application's sections are placed among them by `order`. */
 export declare const SECTION_ORDER: {
+    readonly harnessIdentity: 5;
     readonly system: 25;
     readonly guardrails: 40;
     readonly memory: 45;
@@ -21,7 +22,7 @@ export interface Source {
     revision?: string | null;
 }
 export interface Section {
-    /** `identity`, `role`, `system`, `guardrails`, `memory`, `references`, `subagents`, `scripts`, `wiki`, `tools`, or an application's own. */
+    /** `harness-identity`, `identity`, `role`, `system`, `guardrails`, `memory`, `references`, `subagents`, `scripts`, `wiki`, `tools`, or an application's own. */
     id: string;
     title: string;
     body: string;
@@ -105,6 +106,8 @@ export interface Launch {
     toolGroups?: HostToolGroup[];
     /** Appended to the tools section when it is cut. */
     toolsPointer?: string;
+    /** Suppresses tool guidance for a run that deliberately has no callable tools. */
+    hideToolGuidance?: boolean;
     /** Recorded with the pack: the application's name for who it is for. Defaults to `agent` or `session`. */
     profile?: string;
 }
@@ -129,7 +132,7 @@ export interface OrderedGroup extends ToolGroup {
  * The caller's tools by group, in a fixed order. History and the Wiki are always there; the rest
  * follows the switches in `launch.tools` and what the application provides.
  */
-export declare function toolGroups(context: CallerContext, launch: Launch): OrderedGroup[];
+export declare function toolGroups(context: CallerContext, launch: Launch, dataRoot?: string): OrderedGroup[];
 /** Compiles the pack for a caller. It only reads the data root. */
 export declare function compile(env: HarnessEnv, context: CallerContext, launch?: Launch, variant?: Materialised | null): ContextPack;
 /** The pack as the one string a session receives. */

package/dist/sdk/prompt/compile.js

@@ -4,8 +4,8 @@
 // A pack is an ordered list of sections, each with its own character budget. The harness writes
 // the sections that come from the session's variant (instructions, guardrails, memory, tool
 // guidance, and the indexes of its subagents and scripts), the selected references, the Wiki
-// pointer, and the tools; the embedding application supplies the others (who the model is, its
-// role, what it is working on). Each run's pack is recorded in `runs/<id>/context.json`.
+// pointer, and the tools. The foundation supplies its identity; the embedding application supplies
+// any additional identity, role, and current work. Each run's pack is recorded in `runs/<id>/context.json`.
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { isSession, projectOf, usesCli } from "../core/caller.js";
@@ -13,7 +13,9 @@ import { isDir, now, readJson, safeId, writeJson } from "../core/fs.js";
 import { charCount, compareText, lines, takeChars } from "../core/text.js";
 import * as notes from "../wiki/notes.js";
 import { isWorldTool, WORLD_GUIDANCE } from "../world/untrusted.js";
+import { CHECKLIST_WRITE } from "../tools/checklist.js";
 import { SESSION_NAME } from "../tools/sessionName.js";
+const IDENTITY_BUDGET = 1000;
 const WIKI_BUDGET = 2500;
 const TOOLS_BUDGET = 8000;
 const REPORTING_BUDGET = 2000;
@@ -22,7 +24,7 @@ export const REFERENCES_BUDGET = 12000;
 const VARIANT_BUDGET = 30_000;
 const NOTES_LISTED = 25;
 /** Where the harness's own sections sit; an application's sections are placed among them by `order`. */
-export const SECTION_ORDER = { system: 25, guardrails: 40, memory: 45, references: 50, subagents: 64, scripts: 66, wiki: 80, tools: 90, reporting: 95 };
+export const SECTION_ORDER = { harnessIdentity: 5, system: 25, guardrails: 40, memory: 45, references: 50, subagents: 64, scripts: 66, wiki: 80, tools: 90, reporting: 95 };
 /** How a run's final reply is shaped. Fixed text: it sits in the stable prefix of every pack. */
 export const REPORTING_GUIDANCE = `When you finish work, write the final reply for a person who did not watch you work.
 
@@ -100,12 +102,13 @@ function wiki(root, context) {
  * The caller's tools by group, in a fixed order. History and the Wiki are always there; the rest
  * follows the switches in `launch.tools` and what the application provides.
  */
-export function toolGroups(context, launch) {
+export function toolGroups(context, launch, dataRoot) {
     const enabled = launch.tools ?? [];
     const session = isSession(context);
     const cli = usesCli(context);
     const native = NATIVE_GROUP.filter((name) => enabled.includes(name));
     const wikiTools = WIKI_GROUP.filter((name) => name !== 'wiki_write' || enabled.includes(name));
+    const readGuidance = `Read-only file tools accept absolute paths and paths beginning with ~ anywhere this process has operating-system read access. The working folder is a default location, not a repository boundary.${dataRoot ? ` The Harness data root is ${dataRoot}.` : ''}`;
     const groups = [
         {
             group: 'History',
@@ -127,12 +130,20 @@ export function toolGroups(context, launch) {
             group: 'Native',
             tools: native,
             order: GROUP_ORDER.Native,
-            guidance: session ? "Files and shell: your harness's own tools, within this session's working folder and access level." : `Files (${native.join(', ')}): work in your own folder; edits and commands ask the user first unless already allowed.`
+            guidance: session
+                ? `Files and shell: ${readGuidance} Edits and commands still pass through the Harness gate.`
+                : `Files (${native.join(', ')}): ${readGuidance} Edits and commands still pass through the current gate.`
         },
         // Web, browser and computer tools: the harness's own, and their results are untrusted (world/untrusted.ts).
         { group: 'World', tools: enabled.filter((name) => isWorldTool(name) && !(launch.toolGroups ?? []).some((group) => group.tools.includes(name))), order: GROUP_ORDER.World, guidance: `Web, browser and screen: ${WORLD_GUIDANCE}` },
         ...(launch.toolGroups ?? []).map((group) => ({ group: group.group, tools: group.tools, order: group.order, guidance: group.guidance }))
     ];
+    if (enabled.includes(CHECKLIST_WRITE)) {
+        groups.push({
+            group: 'Progress', tools: [CHECKLIST_WRITE], order: 87,
+            guidance: 'Progress: for work with several steps, write a checklist early with checklist_write and keep it current. The user follows your work from it, and a subagent\'s checklist shows as its progress in the user\'s list of subagents.'
+        });
+    }
     if (enabled.includes(SESSION_NAME)) {
         groups.push({
             group: 'Session', tools: [SESSION_NAME], order: 88,
@@ -145,8 +156,10 @@ export function toolGroups(context, launch) {
     const present = groups.filter((group) => group.tools.length);
     // A session's file and shell tools are Pi's own, whatever the switches say.
     if (session && !present.some((group) => group.group === 'Native')) {
-        present.push({ group: 'Native', tools: ['harness file and shell tools'], order: GROUP_ORDER.placeholder, guidance: "Files and shell: your harness's own tools, within this session's working folder and access level." });
+        present.push({ group: 'Native', tools: ['harness file and shell tools'], order: GROUP_ORDER.placeholder, guidance: `Files and shell: ${readGuidance} Edits and commands still pass through the Harness gate.` });
     }
+    if (launch.hideToolGuidance)
+        return [];
     return present.map((group, index) => ({ group, index })).sort((left, right) => left.group.order - right.group.order || left.index - right.index).map(({ group }) => group);
 }
 /** One paragraph per tool group the caller has, then the harness's own tool guidance. */
@@ -207,13 +220,17 @@ function hostSection(host) {
 /** Compiles the pack for a caller. It only reads the data root. */
 export function compile(env, context, launch = {}, variant = null) {
     const { root } = env;
-    const groups = toolGroups(context, launch);
+    const groups = toolGroups(context, launch, root);
     const variantSource = variant ? [{ id: variant.scope ?? variant.dir, kind: 'variant', revision: variant.fingerprint }] : [];
     const built = [
+        {
+            order: SECTION_ORDER.harnessIdentity,
+            section: section('harness-identity', 'Harness identity', `You are an AI agent running in ${env.productName}.`, IDENTITY_BUDGET, '', [])
+        },
         ...(variant?.sections ?? []).map((entry) => ({ order: entry.order, section: section(entry.id, entry.title, entry.body, VARIANT_BUDGET, '', variantSource) })),
         { order: SECTION_ORDER.references, section: selectedReferences(root, launch) },
         { order: SECTION_ORDER.wiki, section: wiki(root, context) },
-        { order: SECTION_ORDER.tools, section: tools(groups, variant?.toolGuidance ?? '', launch.toolsPointer ?? '') },
+        { order: SECTION_ORDER.tools, section: launch.hideToolGuidance ? null : tools(groups, variant?.toolGuidance ?? '', launch.toolsPointer ?? '') },
         { order: SECTION_ORDER.reporting, section: section('reporting', 'Reporting your work', REPORTING_GUIDANCE, REPORTING_BUDGET, '', []) },
         ...(launch.sections ?? []).map((host) => ({ order: host.order, section: hostSection(host) }))
     ].map((entry, index) => ({ ...entry, index }));

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

@@ -1,4 +1,4 @@
-export declare const REFINE_USAGE = "Usage: xharness refine <demo | run | matrix> [options]\n\n  demo [--k N] [--mode parallel|sequential] [--out <dir>]\n        Run the deterministic demo: no model, no credentials.\n  run --variant <dir> --task <file.md> [--source <dir>] [--scope <id>] [--k N]\n      [--mode parallel|sequential] [--data <dir>] [--state <dir>] [--model <id>]\n      [--executor-model <id>] [--retain-workspaces]\n        Refine a harness on one task with the default account. Costs about\n        4k executions and 3k improver sessions. --model sets the improver's\n        model, --executor-model the executions' model. --retain-workspaces\n        keeps each execution's files for grading afterwards.\n  matrix --suite <file.json> [--data <dir>] [--out <file.json>]\n        Evaluate variants on a task set with the demo executor: no model.\n        Versions come from a variant directory ({ label, dir }) or a committed\n        scope ({ label, scope, version? }); tasks are RefineTask records.\n        Writes <data>/refine/<id>/matrix.json and --out's copy when given.\n";
+export declare const REFINE_USAGE = "Usage: xagent refine <demo | run | matrix> [options]\n\n  demo [--k N] [--mode parallel|sequential] [--out <dir>]\n        Run the deterministic demo: no model, no credentials.\n  run --variant <dir> --task <file.md> [--source <dir>] [--scope <id>] [--k N]\n      [--mode parallel|sequential] [--data <dir>] [--state <dir>] [--model <id>]\n      [--executor-model <id>] [--retain-workspaces]\n        Refine a harness on one task with the default account. Costs about\n        4k executions and 3k improver sessions. --model sets the improver's\n        model, --executor-model the executions' model. --retain-workspaces\n        keeps each execution's files for grading afterwards.\n  matrix --suite <file.json> [--data <dir>] [--out <file.json>]\n        Evaluate variants on a task set with the demo executor: no model.\n        Versions come from a variant directory ({ label, dir }) or a committed\n        scope ({ label, scope, version? }); tasks are RefineTask records.\n        Writes <data>/refine/<id>/matrix.json and --out's copy when given.\n";
 export declare function runRefineCli(argv: string[], io?: {
     write: (text: string) => void;
 }): Promise<number>;

package/dist/sdk/refine/cli.js

@@ -1,4 +1,4 @@
-// `xharness refine`: refinement from a terminal.
+// `xagent refine`: refinement from a terminal.
 //
 //   refine demo [--k N] [--mode parallel|sequential] [--out <dir>]
 //       Runs the deterministic ledger demo end to end with no model and no credentials.
@@ -23,7 +23,7 @@ import { DemoExecutor, DemoImprover, demoBaseVariant, demoTasks } from "./demo.j
 import { Library } from "./library.js";
 import { runRefinement } from "./runner.js";
 import { runMatrix } from "./suite.js";
-export const REFINE_USAGE = `Usage: xharness refine <demo | run | matrix> [options]
+export const REFINE_USAGE = `Usage: xagent refine <demo | run | matrix> [options]
 
   demo [--k N] [--mode parallel|sequential] [--out <dir>]
         Run the deterministic demo: no model, no credentials.

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

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

package/dist/sdk/refine/serverMethods.js

@@ -0,0 +1,20 @@
+import { optional, text } from "../server/params.js";
+import { readSummary } from "./runner.js";
+export function refinementServerMethods(harness) {
+    const root = () => harness.env.root;
+    return {
+        'refine.start': (params) => harness.refine.start({ task: params.task, k: typeof params.k === 'number' ? params.k : 1, mode: params.mode === 'sequential' ? 'sequential' : 'parallel', improver: params.improver ?? {}, executor: params.executor ?? undefined, baseVersion: optional(params, 'baseVersion'), retainWorkspaces: params.retainWorkspaces === true, id: optional(params, 'id') ?? undefined }),
+        'refine.get': (params) => harness.refine.get(text(params, 'id')),
+        'refine.list': (params) => harness.refine.list({ scope: optional(params, 'scope'), limit: typeof params.limit === 'number' ? params.limit : undefined }),
+        'refine.running': () => harness.refine.running(),
+        'refine.cancel': async (params) => {
+            await harness.refine.cancel(text(params, 'id'));
+            return readSummary(root(), text(params, 'id'));
+        },
+        'refine.candidates': (params) => harness.refine.candidates(text(params, 'id')),
+        'refine.adopt': (params) => harness.refine.adopt(text(params, 'id'), { label: optional(params, 'label') }),
+        'library.list': (params) => harness.refine.library(text(params, 'scope')),
+        'library.read': (params) => harness.refine.libraryEntry(text(params, 'scope'), text(params, 'area'), text(params, 'task')),
+        'library.forget': (params) => harness.refine.forget(text(params, 'scope'), text(params, 'area'), Array.isArray(params.tasks) ? params.tasks : [])
+    };
+}

package/dist/sdk/server/methods.js

@@ -7,12 +7,10 @@ import { HarnessError, invalid } from "../core/errors.js";
 import * as capabilities from "../capabilities/api.js";
 import { loadRun as loadCapabilitySnapshot } from "../capabilities/runSnapshot.js";
 import { capabilitySet } from "../capabilities/runSnapshot.js";
-import { validateScopeIds } from "../mcp/connections.js";
-import * as recall from "../history/recall.js";
 import * as plugins from "../plugins/api.js";
+import { BUILTIN_PLUGIN_REGISTRY } from "../plugins/builtin.js";
 import * as install from "../plugins/install.js";
 import { compile, load, render } from "../prompt/compile.js";
-import { readSummary } from "../refine/runner.js";
 import { continuationOf } from "../sessions/continuation.js";
 import { selectHistory } from "../sessions/history.js";
 import { runsSince } from "../sessions/runIndex.js";
@@ -25,14 +23,7 @@ import { seedVariant } from "../variant/seed.js";
 import * as variants from "../variant/store.js";
 import { PI_SURFACE } from "../variant/surface.js";
 import { applyEdit, autotrigger, VariantError, validate } from "../variant/variant.js";
-import * as notes from "../wiki/notes.js";
-const text = (params, name) => {
-    const value = params[name];
-    if (typeof value !== 'string' || !value)
-        throw invalid(`${name} is required.`);
-    return value;
-};
-const optional = (params, name) => (typeof params[name] === 'string' && params[name] ? params[name] : null);
+import { optional, text } from "./params.js";
 const questionAnswer = (value) => {
     const answer = value && typeof value === 'object' && !Array.isArray(value) ? value : {};
     return {
@@ -64,32 +55,16 @@ function check(variant) {
         return { ok: false, problems: error instanceof VariantError ? error.problems : [error instanceof Error ? error.message : String(error)] };
     }
 }
-/** Only the named fields of a parameter object. */
-function pick(params, keys) {
-    return Object.fromEntries(keys.filter((key) => key in params).map((key) => [key, params[key]]));
-}
 export function methods(harness) {
-    const { accounts, approvals, apps, runs, sessions, terminals, env } = harness;
+    const { accounts, approvals, runs, sessions, terminals, env } = harness;
     const root = () => env.root;
     const variantsChanged = (scope) => harness.bus.emit({ type: 'variants.changed', scope });
-    return {
+    const builtins = BUILTIN_PLUGIN_REGISTRY.serverMethods(harness);
+    const foundation = {
         // ---- The harness itself --------------------------------------------------------------------
-        'web.status': () => harness.world.searchStatus(),
-        'web.setKey': (params) => harness.world.setSearchKey(text(params, 'provider'), typeof params.key === 'string' ? params.key : null),
-        'browser.config': () => harness.world.browserConfig(),
-        'browser.configure': (params) => harness.world.configureBrowser(pick(params, ['headed', 'cdpUrl', 'executablePath', 'allowPrivate', 'allowedDomains'])),
         'harness.status': () => ({ dataRoot: harness.dataRoot, productName: env.productName, recovery: harness.recovery, activeRuns: runs.activeRunIds() }),
-        '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')),
         'harness.open': (params) => harness.open(text(params, 'dataRoot'), Array.isArray(params.agentIds) ? params.agentIds : []),
         'harness.rebuildIndex': () => harness.rebuildIndex(),
-        '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')),
         // ---- Accounts --------------------------------------------------------------------------------
         'accounts.list': () => accounts.overview(),
         'accounts.find': (params) => accounts.find(text(params, 'accountId')),
@@ -129,22 +104,6 @@ export function methods(harness) {
         'approvals.remember': (params) => approvals.remember(text(params, 'sessionId'), text(params, 'target')),
         'approvals.forget': (params) => approvals.forget(text(params, 'sessionId'), text(params, 'target')),
         'approvals.forgetSession': (params) => approvals.forgetSession(text(params, 'sessionId')),
-        // ---- Connected apps --------------------------------------------------------------------------
-        '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 : []),
         // ---- Variants: the eight components that shape an agent ---------------------------------
         'variants.surface': () => PI_SURFACE,
         'variants.list': () => variants.scopes(root()).map((scope) => {
@@ -227,45 +186,8 @@ export function methods(harness) {
             const built = materialise(root(), params.variant, { trust: harness.trust });
             return { ...built, files: undefined };
         },
-        // ---- Refinement: improving a harness from evidence -------------------------------------------
-        'refine.start': (params) => harness.refine.start({ task: params.task, k: typeof params.k === 'number' ? params.k : 1, mode: params.mode === 'sequential' ? 'sequential' : 'parallel', improver: params.improver ?? {}, executor: params.executor ?? undefined, baseVersion: optional(params, 'baseVersion'), retainWorkspaces: params.retainWorkspaces === true, id: optional(params, 'id') ?? undefined }),
-        'refine.get': (params) => harness.refine.get(text(params, 'id')),
-        'refine.list': (params) => harness.refine.list({ scope: optional(params, 'scope'), limit: typeof params.limit === 'number' ? params.limit : undefined }),
-        'refine.running': () => harness.refine.running(),
-        'refine.cancel': async (params) => {
-            await harness.refine.cancel(text(params, 'id'));
-            return readSummary(root(), text(params, 'id'));
-        },
-        'refine.candidates': (params) => harness.refine.candidates(text(params, 'id')),
-        'refine.adopt': (params) => harness.refine.adopt(text(params, 'id'), { label: optional(params, 'label') }),
-        'library.list': (params) => harness.refine.library(text(params, 'scope')),
-        'library.read': (params) => harness.refine.libraryEntry(text(params, 'scope'), text(params, 'area'), text(params, 'task')),
-        'library.forget': (params) => harness.refine.forget(text(params, 'scope'), text(params, 'area'), Array.isArray(params.tasks) ? params.tasks : []),
-        // ---- The Wiki: project notes ------------------------------------------------------------------
-        'wiki.list': (params) => notes.list(root(), params.project === undefined ? {} : { project: optional(params, 'project') }),
-        'wiki.read': (params) => notes.read(root(), text(params, 'path')),
-        'wiki.write': (params) => {
-            const note = notes.write(root(), text(params, 'path'), typeof params.text === 'string' ? params.text : '', { expectedUpdatedAt: optional(params, 'expectedUpdatedAt') });
-            harness.bus.emit({ type: 'wiki.changed' });
-            return note;
-        },
-        'wiki.remove': (params) => {
-            notes.remove(root(), text(params, 'path'));
-            harness.bus.emit({ type: 'wiki.changed' });
-        },
-        'wiki.search': (params) => notes.search(root(), typeof params.query === 'string' ? params.query : '', { project: optional(params, 'project'), limit: typeof params.limit === 'number' ? params.limit : undefined }),
-        'wiki.graph': () => notes.graph(root()),
-        'wiki.versions': (params) => notes.versions(root(), text(params, 'path')),
-        'wiki.version': (params) => notes.version(root(), text(params, 'path'), text(params, 'id')),
-        'wiki.ensureProject': () => {
-            notes.ensureLayout(root(), env.productName);
-            harness.bus.emit({ type: 'wiki.changed' });
-        },
         // ---- What a session calls, on behalf of a caller the host names -------------------------------
         'harness.call': (params) => dispatch(env, (params.context ?? {}), text(params, 'call'), params.params ?? {}, { variantDir: optional(params, 'variantDir') }),
-        // ---- Recall ------------------------------------------------------------------------------------
-        'recall.search': (params) => recall.searchAll(env, typeof params.query === 'string' ? params.query : '', params.filter ?? {}),
-        'recall.read': (params) => recall.read(root(), text(params, 'runId')),
         // ---- The compiled prompt -----------------------------------------------------------------------
         'context.compile': (params) => {
             const variant = params.variant ? materialise(root(), params.variant, { trust: harness.trust }) : null;
@@ -354,9 +276,6 @@ export function methods(harness) {
             runs.answerQuestions(text(params, 'runId'), text(params, 'batchId'), params.answers.map((item) => ({ questionId: text(item, 'questionId'), answer: questionAnswer(item.answer) })));
         },
         // ---- Sessions ----------------------------------------------------------------------------------
-        'subagents.spawn': (params) => harness.subagents.spawn(params),
-        'subagents.wait': (params) => harness.subagents.wait(params),
-        'subagents.results': (params) => harness.subagents.results(params),
         'sessions.spawnSubagent': (params) => sessions.spawnSubagent(params),
         'sessions.run': (params) => sessions.run(params),
         'sessions.history': (params) => ({ sessionFile: selectHistory({ sessionDir: text(params, 'sessionDir'), resume: params.resume ?? null }) }),
@@ -367,4 +286,8 @@ export function methods(harness) {
         'terminal.state': (params) => terminals.state(text(params, 'sessionId')),
         'terminal.dispose': (params) => terminals.dispose(text(params, 'sessionId'))
     };
+    const overlap = Object.keys(foundation).find(name => name in builtins);
+    if (overlap)
+        throw new Error(`Server method ${overlap} is owned by both Foundation and a built-in plugin.`);
+    return { ...builtins, ...foundation };
 }

package/dist/sdk/server/params.d.ts

@@ -0,0 +1,4 @@
+export type Params = Record<string, any>;
+export declare const text: (params: Params, name: string) => string;
+export declare const optional: (params: Params, name: string) => string | null;
+export declare function pick<T extends string>(params: Params, keys: readonly T[]): Record<T, unknown>;

package/dist/sdk/server/params.js

@@ -0,0 +1,11 @@
+import { invalid } from "../core/errors.js";
+export const text = (params, name) => {
+    const value = params[name];
+    if (typeof value !== 'string' || !value)
+        throw invalid(`${name} is required.`);
+    return value;
+};
+export const optional = (params, name) => (typeof params[name] === 'string' && params[name] ? params[name] : null);
+export function pick(params, keys) {
+    return Object.fromEntries(keys.filter(key => key in params).map(key => [key, params[key]]));
+}

package/dist/sdk/sessions/contracts.d.ts

@@ -50,10 +50,19 @@ export declare const toolAttachmentRefsSchema: z.ZodArray<z.ZodObject<{
     mimeType: z.ZodString;
 }, z.core.$strict>>;
 export type ToolAttachmentRef = z.infer<typeof toolAttachmentRefSchema>;
+export declare const QUESTION_SKETCH_MAX_LINES = 24;
+export declare const QUESTION_SKETCH_MAX_COLUMNS = 80;
+export declare const QUESTION_SKETCH_MAX_LENGTH: number;
+export declare const QUESTION_SKETCH_PATTERN = "^(?:[\\x20-\\x7e]{0,80})(?:\\n[\\x20-\\x7e]{0,80}){0,23}$";
+export declare const questionSketchSchema: z.ZodString;
+export declare function questionSketchError(uiSketch: unknown, options: readonly {
+    sketch?: unknown;
+}[]): string | undefined;
 export declare const questionOptionSchema: z.ZodObject<{
     label: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
     recommended: z.ZodOptional<z.ZodBoolean>;
+    sketch: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type QuestionOption = z.infer<typeof questionOptionSchema>;
 /** One line of the run's checklist. The list has no ids: every update replaces all of it. */
@@ -277,10 +286,12 @@ export declare const runEventPayloadSchemas: {
         questionId: z.ZodString;
         question: z.ZodString;
         summary: z.ZodOptional<z.ZodString>;
+        uiSketch: z.ZodOptional<z.ZodLiteral<true>>;
         options: z.ZodArray<z.ZodObject<{
             label: z.ZodString;
             description: z.ZodOptional<z.ZodString>;
             recommended: z.ZodOptional<z.ZodBoolean>;
+            sketch: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         multiSelect: z.ZodBoolean;
         allowText: z.ZodBoolean;
@@ -500,6 +511,10 @@ export interface RunRecord {
     /** The variant the run used: its scope and version fingerprint. */
     variantScope?: string | null;
     variantVersion?: string | null;
+    /** The agent profile a subagent started from (PROP-0029); null for a copy of its parent. */
+    profile?: string | null;
+    /** The short name a parent gave a subagent, shown in the roster (PROP-0030). */
+    title?: string | null;
 }
 export declare const runRecordSchema: z.ZodObject<{
     resumedFromRunId: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
@@ -527,6 +542,8 @@ export declare const runRecordSchema: z.ZodObject<{
     trigger: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
     variantScope: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>>;
     variantVersion: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>>;
+    profile: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>>;
+    title: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>>;
 }, z.core.$strip>;
 /** Records written before PROP-0009 name the variant `harnessScope` and `harnessVersion`. */
 export declare function upgradeRunRecord(raw: unknown): unknown;

package/dist/sdk/sessions/contracts.js

@@ -91,7 +91,39 @@ const approvalRequestedPayload = z.object({
     automatic: approvalAutomaticSchema.optional()
 });
 const approvalResolvedPayload = z.object({ approvalId: z.string(), decision: z.enum(['approved', 'denied', 'native']), automatic: approvalAutomaticSchema.optional() });
-export const questionOptionSchema = z.object({ label: z.string().min(1), description: z.string().optional(), recommended: z.boolean().optional() });
+export const QUESTION_SKETCH_MAX_LINES = 24;
+export const QUESTION_SKETCH_MAX_COLUMNS = 80;
+export const QUESTION_SKETCH_MAX_LENGTH = QUESTION_SKETCH_MAX_LINES * QUESTION_SKETCH_MAX_COLUMNS + QUESTION_SKETCH_MAX_LINES - 1;
+export const QUESTION_SKETCH_PATTERN = `^(?:[\\x20-\\x7e]{0,${QUESTION_SKETCH_MAX_COLUMNS}})(?:\\n[\\x20-\\x7e]{0,${QUESTION_SKETCH_MAX_COLUMNS}}){0,${QUESTION_SKETCH_MAX_LINES - 1}}$`;
+export const questionSketchSchema = z.string()
+    .min(1)
+    .max(QUESTION_SKETCH_MAX_LENGTH)
+    .regex(new RegExp(QUESTION_SKETCH_PATTERN), 'Sketches use up to 24 LF-separated lines of at most 80 printable ASCII characters.')
+    .refine((sketch) => {
+    const lines = sketch.split('\n');
+    return lines.length <= QUESTION_SKETCH_MAX_LINES &&
+        lines.every((line) => line.length <= QUESTION_SKETCH_MAX_COLUMNS && /^[\x20-\x7e]*$/u.test(line)) &&
+        /[^ \n]/u.test(sketch);
+}, 'A sketch needs visible content and must use up to 24 LF-separated lines of at most 80 printable ASCII characters.');
+export function questionSketchError(uiSketch, options) {
+    if (uiSketch !== undefined && uiSketch !== true)
+        return 'Set uiSketch to true to enable question sketches.';
+    const sketches = options.map((option) => option.sketch);
+    if (uiSketch === true && sketches.some((sketch) => sketch === undefined))
+        return 'Sketch mode requires a sketch for every choice.';
+    if (uiSketch !== true && sketches.some((sketch) => sketch !== undefined))
+        return 'Choice sketches require uiSketch: true.';
+    if (sketches.some((sketch) => sketch !== undefined && !questionSketchSchema.safeParse(sketch).success)) {
+        return 'Each choice sketch must use 1–24 lines of at most 80 printable ASCII characters and contain a visible character.';
+    }
+    return undefined;
+}
+export const questionOptionSchema = z.object({
+    label: z.string().min(1),
+    description: z.string().optional(),
+    recommended: z.boolean().optional(),
+    sketch: questionSketchSchema.optional()
+});
 const questionBatchFields = {
     batchId: z.string().min(1).optional(),
     batchIndex: z.number().int().min(1).max(5).optional(),
@@ -110,12 +142,17 @@ const questionRequestedPayload = z.object({
     questionId: z.string(),
     question: z.string().min(1),
     summary: z.string().min(1).max(100).optional(),
+    uiSketch: z.literal(true).optional(),
     options: z.array(questionOptionSchema),
     multiSelect: z.boolean(),
     allowText: z.boolean(),
     userOnly: z.boolean().optional(),
     ...questionBatchFields
-}).superRefine(questionBatchRefinement);
+}).superRefine(questionBatchRefinement).superRefine((value, context) => {
+    const error = questionSketchError(value.uiSketch, value.options);
+    if (error)
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ['options'], message: error });
+});
 const questionAnsweredPayload = z.object({
     questionId: z.string(),
     selected: z.array(z.string()),
@@ -281,7 +318,9 @@ export const runRecordSchema = z.object({
     agentId: text,
     trigger: text,
     variantScope: text.optional(),
-    variantVersion: text.optional()
+    variantVersion: text.optional(),
+    profile: text.optional(),
+    title: text.optional()
 });
 /** Records written before PROP-0009 name the variant `harnessScope` and `harnessVersion`. */
 export function upgradeRunRecord(raw) {