@xingular/harness 1.0.0 → 1.2.0

package/dist/sdk/index.js

@@ -20,9 +20,14 @@ export { fileSecretStore, memorySecretStore, secretKey } from "./accounts/secret
 export { dispatch as harnessCall } from "./tools/dispatch.js";
 export { compile, render, SECTION_ORDER, CONTEXT_MESSAGE_TYPE, CONTEXT_SNAPSHOT_KEY } from "./prompt/compile.js";
 export { runEventSchema, runRecordSchema, isActiveStatus } from "./sessions/contracts.js";
+export { CORE_COMMANDS, coreCommand } from "./commands/registry.js";
+export { STANDARD_CONNECTIONS } from "./prompt/standard.js";
+export { SideQuestions, SIDE_QUESTION_INSTRUCTION, buildSideQuestionText } from "./sessions/sideQuestions.js";
 export { describeTool, HARNESS_TOOLS, DEFAULT_TOOL_NAMES, WIKI_WRITE } from "./tools/definitions.js";
 export { SPAWN_SUBAGENT, SUBAGENT_RELATION } from "./tools/spawnSubagent.js";
 export { CHECKLIST_WRITE, checklistOf } from "./tools/checklist.js";
+export { 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";
@@ -39,10 +44,15 @@ export { attach as attachPlugin, inventoryFor as pluginInventory, list as listPl
 export { HARNESS_PLUGINS } from "./plugins/builtin.js";
 export { FIRST_PARTY_PLUGINS } from "./plugins/firstParty.js";
 export { CONTRIBUTION_KINDS, PLUGIN_SOURCES } from "./plugins/types.js";
+export { describePlugin, surfaceBadge } from "./plugins/surfaces.js";
 export { methods } from "./server/methods.js";
 export { remoteDirectory, remotePolicy, remoteSecrets, remoteTools } from "./server/remote.js";
 export { PROTOCOL_VERSION, RpcPeer, stdioTransport } from "./server/rpc.js";
 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/pi/runtime.d.ts

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

package/dist/sdk/pi/runtime.js

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

package/dist/sdk/plugins/builtin.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,50 @@
-// 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 { CHECKPOINT_WRITE, checkpointTool } from "../tools/checkpoint.js";
+import { sliceOf } from "../sessions/workSlice.js";
 import { SPAWN_SUBAGENT, WAIT_SUBAGENTS } from "../sessions/subagents.js";
+import { subagentTools } from "../tools/spawnSubagent.js";
+import { SESSION_NAME } from "../tools/sessionName.js";
 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 { GET_CAPABILITIES } from "../tools/getCapabilities.js";
+import { USAGE_SETTINGS } from "../usage/settings.js";
+import { usageServerMethods } from "../usage/serverMethods.js";
+import { createBuiltinPluginRegistry } from "./builtinRegistry.js";
 const tools = (definitions) => definitions.map((tool) => ({ name: tool.name, description: tool.label }));
+const toolContribution = (definitions, toolOrder) => ({
+    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 +54,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 +64,117 @@ 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 CHECKPOINT_PLUGIN = { id: 'checkpoint', title: 'Checkpoint', description: 'Lets a bounded reply record a handoff at a work-slice boundary so the next slice starts from it.', required: 'A reply that stops at its budget leaves the state the next one resumes from.', tools: [{ name: CHECKPOINT_WRITE, description: 'Write the handoff checkpoint' }] };
+const CONNECTED_APPS_PLUGIN = {
+    id: 'connected-apps',
+    title: 'Connected apps',
+    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 CAPABILITIES_PLUGIN = { id: 'capabilities', title: 'Capability discovery', description: 'Inspect the callable tools of the current run, including their input schemas. Discovery never grants access.', required: 'Every interactive session can inspect its own registered capabilities.', tools: [{ name: GET_CAPABILITIES, description: 'Inspect current capabilities' }] };
+const USAGE_PLUGIN = {
+    id: 'usage',
+    title: 'Usage',
+    description: 'Token, cost and latency totals from recorded runs, and the plan windows, balances or rate limits each provider reports.',
+    settings: [...USAGE_SETTINGS]
+};
+const SIDE_QUESTIONS_PLUGIN = {
+    id: 'side-questions',
+    title: 'Side questions',
+    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([
+    {
+        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))
+            : [],
+        serverMethods: subagentServerMethods
+    },
+    { descriptor: VARIANT_PLUGIN, ...toolContribution(SKILL_TOOLS, 30) },
+    { descriptor: WIKI_PLUGIN, ...toolContribution([...WIKI_READ_TOOLS, ...WIKI_WRITE_TOOLS], 20), serverMethods: wikiServerMethods },
     {
-        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: HISTORY_PLUGIN,
+        ...toolContribution([...RECALL_TOOLS, ...TRAJECTORY_TOOLS], 10),
+        serverMethods: historyServerMethods
+    },
+    { descriptor: ASK_USER_PLUGIN, toolOrder: 40, tools: context => context.harnessTools && context.allowedTools.includes(ASK_USER) ? [askUserTool(context.run)] : [] },
+    { descriptor: CHECKLIST_PLUGIN, toolOrder: 50, tools: context => context.harnessTools ? [checklistTool(context.run)] : [] },
+    { descriptor: CHECKPOINT_PLUGIN, toolOrder: 51, tools: context => context.harnessTools && context.allowedTools.includes(CHECKPOINT_WRITE) ? [checkpointTool(context.run, () => sliceOf(context.env.root, context.runId))] : [] },
+    {
+        descriptor: CONNECTED_APPS_PLUGIN,
+        toolOrder: 0,
+        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,
+        commandPrefix: 'annotate',
+        defaultCommand: 'annotate',
+        commands: [
+            { name: 'notes', description: 'Review web annotations saved from pages and apps' },
+            { name: 'annotate', description: 'Inspect a page or app, comment on components, and send fixes: /annotate:annotate [url | --app <devtools address> | --bridge]' }
         ],
-        toolGroups: ['Wiki']
+        createWorldPart: ({ options }) => annotationsPart({ root: options.root, changed: options.notesChanged }),
+        serverMethods: annotationServerMethods
     },
-    { 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' }] },
+    { descriptor: CAPABILITIES_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']
+        descriptor: USAGE_PLUGIN,
+        commandPrefix: 'usage',
+        defaultCommand: 'analysis',
+        commands: [
+            { name: 'analysis', description: 'Token, cost and latency totals: /usage:analysis [today | 7d | 30d | all]' },
+            { name: 'limit', description: 'Provider plan windows, balances and rate limits: /usage:limit' }
+        ],
+        serverMethods: usageServerMethods
     },
-    WEB_PLUGIN,
-    BROWSER_PLUGIN,
-    ...FIRST_PARTY_PLUGINS
-];
+    { descriptor: DOCTOR_PLUGIN, serverMethods: doctorServerMethods },
+    { descriptor: WORKTREES_PLUGIN, serverMethods: worktreeServerMethods },
+    ...FIRST_PARTY_PLUGINS.map(descriptor => ({ descriptor }))
+]);
+export const HARNESS_PLUGINS = BUILTIN_PLUGIN_REGISTRY.descriptors();

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

@@ -0,0 +1,60 @@
+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;
+    prefix: string;
+    name: string;
+    description: string;
+    legacyBare: boolean;
+}
+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 terminal command namespace; defaults to the plugin id. */
+    commandPrefix?: string;
+    /** Command invoked by the namespace root, such as `/annotate:`. */
+    defaultCommand?: string;
+    /** Stable order for model tools, independent of descriptor display order. */
+    toolOrder?: number;
+    tools?: (context: BuiltinToolContext) => ToolSpec[];
+    commands?: readonly Omit<BuiltinPluginCommand, 'pluginId' | 'prefix' | 'legacyBare'>[];
+    createWorldPart?: (context: BuiltinWorldContext) => WorldPart | null;
+    serverMethods?: (harness: Harness) => Record<string, Handler>;
+}
+export interface BuiltinPluginRegistry {
+    readonly modules: readonly BuiltinPluginModule[];
+    descriptors(): PluginDescriptor[];
+    commands(): BuiltinPluginCommand[];
+    command(prefix: string, name: string): BuiltinPluginCommand | undefined;
+    commandsNamed(name: string): BuiltinPluginCommand[];
+    defaultCommand(prefix: string): BuiltinPluginCommand | undefined;
+    tools(context: BuiltinToolContext): ToolSpec[];
+    worldParts(context: BuiltinWorldContext): WorldPart[];
+    serverMethods(harness: Harness): Record<string, Handler>;
+}
+/** 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,71 @@
+/** One checked registry for the Harness-owned plugin modules and their surface contributions. */
+export function createBuiltinPluginRegistry(modules) {
+    const pluginIds = new Set();
+    const prefixOwners = new Map();
+    const routeKeys = new Set();
+    for (const module of modules) {
+        const id = module.descriptor.id;
+        if (pluginIds.has(id))
+            throw new Error(`Duplicate built-in plugin id: ${id}`);
+        pluginIds.add(id);
+        const prefix = module.commandPrefix ?? id;
+        if (!/^[a-z][a-z0-9-]*$/.test(prefix) || prefix === 'plugin' || prefix === 'skill')
+            throw new Error(`Invalid built-in plugin command prefix: ${prefix}`);
+        if ((module.commands?.length || module.defaultCommand) && prefixOwners.has(prefix)) {
+            throw new Error(`Duplicate built-in plugin command prefix: ${prefix}`);
+        }
+        if (module.commands?.length || module.defaultCommand)
+            prefixOwners.set(prefix, id);
+        for (const command of module.commands ?? []) {
+            if (!/^[a-z][a-z0-9-]*$/.test(command.name))
+                throw new Error(`Invalid built-in plugin command: ${command.name}`);
+            const key = `${prefix}:${command.name}`;
+            if (routeKeys.has(key))
+                throw new Error(`Duplicate built-in plugin command: ${key}`);
+            routeKeys.add(key);
+        }
+        if (module.defaultCommand && !module.commands?.some(command => command.name === module.defaultCommand)) {
+            throw new Error(`Unknown default command for built-in plugin ${id}: ${module.defaultCommand}`);
+        }
+    }
+    const commands = modules.flatMap(module => (module.commands ?? []).map(command => ({
+        pluginId: module.descriptor.id,
+        prefix: module.commandPrefix ?? module.descriptor.id,
+        ...command,
+        legacyBare: !!module.descriptor.required
+    })));
+    const byRoute = new Map(commands.map(command => [`${command.prefix}:${command.name}`, command]));
+    const byName = new Map();
+    for (const command of commands)
+        byName.set(command.name, [...(byName.get(command.name) ?? []), command]);
+    const defaults = new Map(modules.flatMap(module => module.defaultCommand
+        ? [[module.commandPrefix ?? module.descriptor.id, byRoute.get(`${module.commandPrefix ?? module.descriptor.id}:${module.defaultCommand}`)]]
+        : []));
+    const toolModules = modules.map((module, index) => ({ module, index })).filter(({ module }) => module.tools)
+        .sort((left, right) => (left.module.toolOrder ?? left.index) - (right.module.toolOrder ?? right.index));
+    return {
+        modules,
+        descriptors: () => modules.map(module => module.descriptor),
+        commands: () => [...commands],
+        command: (prefix, name) => byRoute.get(`${prefix}:${name}`),
+        commandsNamed: name => [...(byName.get(name) ?? [])],
+        defaultCommand: prefix => defaults.get(prefix),
+        tools: context => toolModules.flatMap(({ module }) => module.tools(context)),
+        worldParts: context => modules.flatMap(module => {
+            const part = module.createWorldPart?.(context);
+            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/catalogue.js

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

package/dist/sdk/plugins/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/plugins/commandPrefix.d.ts

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

package/dist/sdk/plugins/commandPrefix.js

@@ -0,0 +1,21 @@
+import { basename, dirname, extname } from 'node:path';
+import { packageManifest } from "./manifest.js";
+const slug = (value) => {
+    const normalized = value.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
+    const prefix = /^[a-z]/.test(normalized) ? normalized : `plugin-${normalized || 'command'}`;
+    return prefix === 'plugin' || prefix === 'skill' ? `extension-${prefix}` : prefix;
+};
+/** Stable command namespace for a Pi extension's owning package or loose extension file. */
+export function pluginCommandPrefix(source) {
+    if (source.origin === 'package' && source.baseDir) {
+        const manifest = packageManifest(source.baseDir);
+        return manifest.commandPrefix ?? slug(manifest.name);
+    }
+    if (source.path.startsWith('builtin:'))
+        return slug(source.path.slice('builtin:'.length));
+    const synthetic = /^<[^:>]+:([^>]+)>$/.exec(source.path);
+    if (synthetic)
+        return slug(synthetic[1]);
+    const file = basename(source.path, extname(source.path));
+    return slug(file === 'index' ? basename(dirname(source.path)) : file);
+}

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

@@ -5,7 +5,7 @@ interface Api {
     on(event: 'tool_call', handler: (event: {
         toolName: string;
     }) => unknown): void;
-    on(event: 'turn_start', handler: () => unknown): void;
+    on(event: 'turn_start' | 'agent_start', handler: () => unknown): void;
     on(event: 'message_end', handler: (event: {
         message: {
             role: string;

package/dist/sdk/plugins/firstParty.js

@@ -21,7 +21,7 @@ export const FIRST_PARTY_PLUGINS = [
         description: 'Cuts a very long tool result to its beginning and its end before the model reads it, and says how much was cut.',
         switchable: { on: false },
         settings: OUTPUT_TRIM_SETTINGS,
-        code: [{ name: 'Trim long tool results', description: 'Runs after every tool call, in conversations, task threads and unattended work. Not in terminal sessions yet.' }]
+        code: [{ name: 'Trim long tool results', description: 'Runs after every tool call, in conversations, terminal sessions, task threads and unattended work.' }]
     },
     {
         id: BUDGET_GUARD,
@@ -29,7 +29,7 @@ export const FIRST_PARTY_PLUGINS = [
         description: 'Stops a reply that keeps going: past a limit of model requests or tokens, further tool calls are refused and the agent is told to wrap up.',
         switchable: { on: false },
         settings: BUDGET_GUARD_SETTINGS,
-        code: [{ name: 'Refuse tool calls past the limit', description: 'Counts model requests and tokens in one reply, in conversations, task threads and unattended work. Not in terminal sessions yet.' }]
+        code: [{ name: 'Refuse tool calls past the limit', description: 'Counts model requests and tokens in one reply, in conversations, terminal sessions, task threads and unattended work.' }]
     },
     {
         id: LESSONS,
@@ -75,6 +75,12 @@ export function budgetGuard(saved) {
         let requests = 0;
         let tokens = 0;
         let refusedInRequest = 0;
+        // A terminal session keeps one Pi session for many replies; each reply starts its own count.
+        pi.on('agent_start', () => {
+            requests = 0;
+            tokens = 0;
+            refusedInRequest = 0;
+        });
         pi.on('turn_start', () => {
             requests += 1;
         });