@xingular/harness 1.0.0 → 1.2.0

package/dist/sdk/server/methods.js

@@ -7,13 +7,13 @@ 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 * as control from "../sessions/control.js";
+import { listCommands } from "../commands/list.js";
 import { selectHistory } from "../sessions/history.js";
 import { runsSince } from "../sessions/runIndex.js";
 import { findRun, listRuns, loadRun, pendingDecisions, readEvents, runFamily, snapshot } from "../sessions/runStore.js";
@@ -25,14 +25,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 {
@@ -43,6 +36,7 @@ const questionAnswer = (value) => {
             : {})
     };
 };
+const sessionRef = (params) => ({ sessionDir: text(params, 'sessionDir'), sessionFile: optional(params, 'sessionFile'), cwd: optional(params, 'cwd') });
 const pluginScope = (params) => ({ cwd: optional(params, 'cwd'), accountId: optional(params, 'accountId'), agentId: optional(params, 'agentId'), projectId: optional(params, 'projectId') });
 const variantOf = (value) => {
     if (!value || typeof value !== 'object' || Array.isArray(value))
@@ -64,32 +58,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 +107,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 +189,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,12 +279,24 @@ 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 }) }),
+        // The commands that need no model act on the saved history; see sessions/control.ts.
+        'sessions.tree': (params) => control.tree(sessionRef(params)),
+        'sessions.navigate': (params) => control.navigate({ ...sessionRef(params), entryId: text(params, 'entryId') }),
+        'sessions.fork': (params) => control.fork({ ...sessionRef(params), entryId: text(params, 'entryId'), targetDir: text(params, 'targetDir') }),
+        'sessions.clone': (params) => control.clone({ ...sessionRef(params), targetDir: text(params, 'targetDir') }),
+        'sessions.rename': (params) => control.rename({ ...sessionRef(params), name: text(params, 'name') }),
+        'sessions.lastReply': (params) => control.lastReply(sessionRef(params)),
+        'sessions.export': (params) => control.exportJsonl({ ...sessionRef(params), path: text(params, 'path') }),
+        // Each structured turn loads its resources fresh; this reloads what lives between turns.
+        'sessions.reload': async () => {
+            await harness.hooks.reload();
+            return { reloaded: true };
+        },
+        // ---- Commands ----------------------------------------------------------------------------------
+        'commands.list': async (params) => listCommands(await plugins.list(harness, pluginScope(params))),
         // ---- Terminal sessions -------------------------------------------------------------------------
         'terminal.prepare': (params) => terminals.prepare(params),
         'terminal.send': (params) => terminals.send({ sessionId: text(params, 'sessionId'), runId: optional(params, 'runId'), text: text(params, 'text') }),
@@ -367,4 +304,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/server/remote.js

@@ -3,6 +3,8 @@
 // host; the harness works without any of them.
 import { z } from 'zod';
 import { findingSchema } from "../doctor/types.js";
+import { browserBackendTools } from "../browser/backend.js";
+import { BROWSER_TOOLS } from "../browser/contracts.js";
 /** `secrets.get`, `secrets.set`, `secrets.delete` on the host. */
 export function remoteSecrets(peer) {
     return {
@@ -52,18 +54,41 @@ export function remoteTools(peer) {
         registered = Array.isArray(params.tools) ? params.tools : [];
         return { registered: registered.map((tool) => tool.name) };
     });
-    const provider = (session) => registered
-        .filter((tool) => session.allow.includes(tool.name))
-        .map((tool) => ({
-        name: tool.name,
-        label: tool.label ?? tool.name,
-        description: tool.description,
-        parameters: (Type) => Type.Unsafe(tool.parameters),
-        execute: async (input) => {
-            const result = await peer.callHost('tools.call', { name: tool.name, input, runId: session.run.runId, sessionId: session.run.sessionId, caller: session.caller, depth: session.depth, cwd: session.cwd }, 1_230_000);
-            return typeof result === 'string' ? result : JSON.stringify(result);
+    const provider = (session) => {
+        const unique = [];
+        const names = new Set();
+        for (const tool of registered) {
+            if (!session.allow.includes(tool.name) || names.has(tool.name))
+                continue;
+            names.add(tool.name);
+            unique.push(tool);
         }
-    }));
+        const browserNames = unique.filter(tool => BROWSER_TOOLS.some(definition => definition.name === tool.name)).map(tool => tool.name);
+        const browser = new Map(browserBackendTools({
+            id: 'remote host',
+            // Registering a canonical browser tool means the host implements it; the backend contract
+            // documents the freshness, tab isolation and approval rules that implementation must keep.
+            unsupported: () => null,
+            execute: async (name, input) => {
+                const result = await peer.callHost('tools.call', { name, input, runId: session.run.runId, sessionId: session.run.sessionId, caller: session.caller, depth: session.depth, cwd: session.cwd }, 1_230_000);
+                if (typeof result === 'string')
+                    return result;
+                if (result && typeof result === 'object' && !Array.isArray(result) && typeof result.text === 'string')
+                    return result;
+                return JSON.stringify(result) ?? String(result);
+            }
+        }, browserNames).map(tool => [tool.name, tool]));
+        return unique.map((tool) => browser.get(tool.name) ?? ({
+            name: tool.name,
+            label: tool.label ?? tool.name,
+            description: tool.description,
+            parameters: (Type) => Type.Unsafe(tool.parameters),
+            execute: async (input) => {
+                const result = await peer.callHost('tools.call', { name: tool.name, input, runId: session.run.runId, sessionId: session.run.sessionId, caller: session.caller, depth: session.depth, cwd: session.cwd }, 1_230_000);
+                return typeof result === 'string' ? result : JSON.stringify(result);
+            }
+        }));
+    };
     provider.diagnostics = context => diagnostics.map(check => ({
         id: `host.${check.id}`, category: check.category, title: check.title, tools: check.tools,
         local: async (signal) => {

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

@@ -0,0 +1,11 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { type ChecklistItem } from "./contracts.js";
+export declare const COMPACTION_CHECKPOINT_EXTENSION = "compaction-checkpoint";
+export interface CompactionCheckpointOptions {
+    /** A stopped run's persisted checklist, when the active run is a continuation. */
+    initialChecklist?: readonly ChecklistItem[];
+    /** The current dynamic plan instructions, if this request is in plan mode. */
+    planInstructions?: () => string | null;
+}
+/** Adds only the active run's explicit state to requests made after a compaction. */
+export declare function compactionCheckpoint(options?: CompactionCheckpointOptions): (pi: ExtensionAPI) => void;

package/dist/sdk/sessions/compactionCheckpoint.js

@@ -0,0 +1,79 @@
+import { renderCompactionCheckpoint } from "../prompt/compile.js";
+import { CHECKLIST_WRITE } from "../tools/checklist.js";
+import { checklistItemSchema, MAX_CHECKLIST_ITEMS } from "./contracts.js";
+export const COMPACTION_CHECKPOINT_EXTENSION = 'compaction-checkpoint';
+function validatedChecklist(value) {
+    if (!Array.isArray(value) || value.length > MAX_CHECKLIST_ITEMS)
+        return null;
+    const items = [];
+    for (const valueItem of value) {
+        const item = valueItem;
+        const parsed = checklistItemSchema.safeParse({
+            text: typeof item?.text === 'string' ? item.text.trim() : item?.text,
+            status: item?.status
+        });
+        if (!parsed.success)
+            return null;
+        items.push(parsed.data);
+    }
+    return items;
+}
+/** Adds only the active run's explicit state to requests made after a compaction. */
+export function compactionCheckpoint(options = {}) {
+    return (pi) => {
+        let goal = '';
+        let checklist = validatedChecklist(options.initialChecklist ?? []) ?? [];
+        let lastCompactionKey = null;
+        let compacted = false;
+        const reset = () => {
+            goal = '';
+            checklist = validatedChecklist(options.initialChecklist ?? []) ?? [];
+            lastCompactionKey = null;
+            compacted = false;
+        };
+        pi.on('before_agent_start', (event) => {
+            if (event.messageType !== 'user')
+                return;
+            goal = event.prompt;
+            checklist = validatedChecklist(options.initialChecklist ?? []) ?? [];
+            lastCompactionKey = null;
+            compacted = false;
+        });
+        pi.on('tool_result', (event) => {
+            if (event.toolName !== CHECKLIST_WRITE || event.isError)
+                return;
+            const items = validatedChecklist(event.input.items);
+            if (items)
+                checklist = items;
+        });
+        pi.on('context', (event) => {
+            const summary = event.messages.findLast((message) => message.role === 'compactionSummary');
+            const compactionKey = summary ? `${summary.timestamp}:${summary.tokensBefore}` : null;
+            const planInstructions = options.planInstructions?.() ?? null;
+            if (compactionKey && compactionKey !== lastCompactionKey) {
+                lastCompactionKey = compactionKey;
+                compacted = true;
+            }
+            else if (!compactionKey) {
+                lastCompactionKey = null;
+                compacted = false;
+            }
+            if (!compacted)
+                return;
+            const content = renderCompactionCheckpoint({ goal, checklist, planInstructions });
+            if (!content)
+                return;
+            return {
+                messages: [...event.messages, {
+                        role: 'custom',
+                        customType: COMPACTION_CHECKPOINT_EXTENSION,
+                        content,
+                        display: false,
+                        timestamp: Date.now()
+                    }]
+            };
+        });
+        pi.on('agent_settled', reset);
+        pi.on('session_tree', reset);
+    };
+}

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

@@ -1,5 +1,6 @@
 import type { CapabilitySet } from "../capabilities/types.js";
 import type { HostSection } from "../prompt/compile.js";
+import type { Checkpoint } from "./contracts.js";
 import { type ChecklistItem } from "./contracts.js";
 import { type PendingDecision } from "./runStore.js";
 export declare const CONTINUATION_SECTION_ID = "continuation";
@@ -28,6 +29,8 @@ export interface Continuation {
     stoppedAt: string | null;
     terminalReason: string | null;
     checklist: ChecklistItem[];
+    /** The last work-slice handoff, when the run wrote one (PROP-0041). */
+    checkpoint: Checkpoint | null;
     pending: PendingDecision[];
     /** The last tool the run started, and whether it finished. */
     lastTool: {

package/dist/sdk/sessions/continuation.js

@@ -3,6 +3,7 @@
 // run with `continueFrom`, tells the model where the earlier one stopped.
 import { loadRun as loadCapabilities } from "../capabilities/runSnapshot.js";
 import { checklistOf, describeChecklist } from "../tools/checklist.js";
+import { checkpointOf, describeCheckpoint } from "../tools/checkpoint.js";
 import { isActiveStatus } from "./contracts.js";
 import { findHistory } from "./history.js";
 import { findRun, pendingDecisions, readEvents, recordedSubagents } from "./runStore.js";
@@ -17,7 +18,7 @@ const CONTINUATION_BUDGET = 2000;
 export function continuationOf(root, runId, sessionDir) {
     const record = findRun(root, runId);
     if (!record) {
-        return { runId, sessionId: '', status: 'missing', resumable: false, reason: 'not_found', resume: null, accountId: null, variant: null, capabilities: null, stoppedAt: null, terminalReason: null, checklist: [], pending: [], lastTool: null, unfinishedSubagents: [] };
+        return { runId, sessionId: '', status: 'missing', resumable: false, reason: 'not_found', resume: null, accountId: null, variant: null, capabilities: null, stoppedAt: null, terminalReason: null, checklist: [], checkpoint: null, pending: [], lastTool: null, unfinishedSubagents: [] };
     }
     const events = readEvents(root, runId);
     const started = events.filter((event) => event.type === 'tool.started').at(-1);
@@ -46,6 +47,7 @@ export function continuationOf(root, runId, sessionDir) {
         stoppedAt: record.endedAt,
         terminalReason: record.terminalReason,
         checklist: checklistOf(events),
+        checkpoint: checkpointOf(events),
         pending: pendingDecisions(events),
         lastTool,
         unfinishedSubagents: recordedSubagents(root, runId).filter((id) => {
@@ -69,6 +71,8 @@ export function continuationBody(continuation) {
     ];
     if (continuation.lastTool)
         lines.push(continuation.lastTool.finished ? `Its last tool call, ${continuation.lastTool.name}, finished.` : `Its last tool call, ${continuation.lastTool.name}, did not finish; its effect is unknown.`);
+    if (continuation.checkpoint)
+        lines.push('', 'The handoff it wrote when it stopped:', describeCheckpoint(continuation.checkpoint));
     if (continuation.checklist.length)
         lines.push('', 'Its checklist when it stopped:', describeChecklist(continuation.checklist));
     if (continuation.pending.length)