@xingular/harness 0.1.7 → 1.0.0

package/dist/sdk/server/methods.js

@@ -0,0 +1,370 @@
+// Everything a host process can ask of the harness, by name. Each method takes one JSON object
+// and returns JSON; the in-process API these call is the same one a Node application uses
+// directly. Methods are grouped by the part of the harness they belong to.
+import { ensureSharedDir, nativeConfig } from "../accounts/env.js";
+import { audit, readAudit, summaryAuthentication } from "../accounts/store.js";
+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 * 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";
+import { findRun, listRuns, loadRun, pendingDecisions, readEvents, runFamily, snapshot } from "../sessions/runStore.js";
+import { checklistOf } from "../tools/checklist.js";
+import { dispatch } from "../tools/dispatch.js";
+import * as components from "../variant/components.js";
+import { materialise } from "../variant/materialise.js";
+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);
+const questionAnswer = (value) => {
+    const answer = value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+    return {
+        selected: Array.isArray(answer.selected) ? answer.selected.filter((label) => typeof label === 'string') : [],
+        ...(typeof answer.text === 'string' && answer.text ? { text: answer.text } : {}),
+        ...(answer.notes && typeof answer.notes === 'object' && !Array.isArray(answer.notes)
+            ? { notes: Object.fromEntries(Object.entries(answer.notes).filter((entry) => typeof entry[1] === 'string')) }
+            : {})
+    };
+};
+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))
+        throw invalid('variant must be an object of path → text.');
+    const out = {};
+    for (const [path, body] of Object.entries(value)) {
+        if (typeof body !== 'string')
+            throw invalid(`${path} must be text.`);
+        out[path] = body;
+    }
+    return out;
+};
+/** Validates a variant without throwing: its census, or every problem. */
+function check(variant) {
+    try {
+        return { ok: true, census: validate(PI_SURFACE, variant) };
+    }
+    catch (error) {
+        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 root = () => env.root;
+    const variantsChanged = (scope) => harness.bus.emit({ type: 'variants.changed', scope });
+    return {
+        // ---- 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')),
+        'accounts.resolve': (params) => accounts.resolve(optional(params, 'accountId'), optional(params, 'poolId')),
+        'accounts.create': (params) => accounts.create(text(params, 'label'), optional(params, 'authKind') ?? 'subscription'),
+        'accounts.rename': (params) => accounts.rename(text(params, 'accountId'), text(params, 'label')),
+        'accounts.setDefault': (params) => accounts.setDefault(text(params, 'accountId')),
+        'accounts.remove': (params) => accounts.remove(text(params, 'accountId')),
+        'accounts.savePool': (params) => accounts.savePool(params.pool),
+        'accounts.removePool': (params) => accounts.removePool(text(params, 'poolId')),
+        'accounts.audit': (params) => readAudit(accounts.dir, optional(params, 'accountId'), typeof params.limit === 'number' ? params.limit : 100),
+        // A line in the account audit log for something the application did with the account (pinning a session to it).
+        'accounts.record': (params) => audit(accounts.dir, optional(params, 'accountId'), text(params, 'action'), typeof params.detail === 'string' ? params.detail : ''),
+        'accounts.nativeConfig': () => nativeConfig(accounts.dir),
+        // The folder every account shares, created if no account has linked it yet.
+        'accounts.sharedDir': () => ensureSharedDir(accounts.dir),
+        'accounts.refresh': (params) => accounts.refresh(optional(params, 'accountId')),
+        'accounts.loginStart': (params) => accounts.loginStart(text(params, 'accountId'), text(params, 'provider'), optional(params, 'method')),
+        'accounts.loginStatus': (params) => accounts.loginStatus(text(params, 'accountId')),
+        'accounts.loginRespond': (params) => accounts.loginRespond(text(params, 'loginId'), text(params, 'promptId'), typeof params.value === 'string' ? params.value : null),
+        'accounts.loginCancel': (params) => accounts.loginCancel(text(params, 'accountId'), optional(params, 'loginId')),
+        'accounts.setApiKey': (params) => accounts.setApiKey(text(params, 'accountId'), text(params, 'key'), text(params, 'provider')),
+        'accounts.removeProvider': (params) => accounts.removeProvider(text(params, 'accountId'), text(params, 'provider')),
+        'accounts.signOut': (params) => accounts.signOut(text(params, 'accountId')),
+        'accounts.providers': () => accounts.providers(),
+        'accounts.models': (params) => accounts.models(optional(params, 'accountId')),
+        'accounts.choices': (params) => accounts.choices(text(params, 'accountId')),
+        'accounts.choose': (params) => accounts.choose(text(params, 'accountId'), text(params, 'mode'), {
+            ...(typeof params.model === 'string' ? { model: params.model } : {}),
+            ...(typeof params.effort === 'string' ? { effort: params.effort } : {})
+        }),
+        'accounts.authentication': () => summaryAuthentication(accounts.dir),
+        'accounts.status': (params) => accounts.status(optional(params, 'accountId')),
+        // ---- Standing approvals ----------------------------------------------------------------------
+        'approvals.get': () => approvals.read(),
+        'approvals.setAuto': (params) => approvals.setAuto(text(params, 'key'), params.on === true),
+        '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) => {
+            const head = variants.head(root(), scope);
+            return { scope, head, version: head ? variants.versionRecord(root(), scope, head.fingerprint) : null };
+        }),
+        'variants.get': (params) => {
+            const scope = text(params, 'scope');
+            const head = variants.head(root(), scope);
+            const fp = optional(params, 'version') ?? head?.fingerprint ?? null;
+            if (!fp)
+                return { scope, head: null, version: null, variant: null, plugins: [] };
+            const variant = variants.readVersion(root(), scope, fp);
+            return { scope, head, version: variants.versionRecord(root(), scope, fp), variant, plugins: harness.trust.review(variant), probeCode: harness.trust.probeCode(scope) };
+        },
+        'variants.lineage': (params) => variants.lineage(root(), text(params, 'scope')),
+        'variants.compare': (params) => variants.compare(root(), text(params, 'scope'), text(params, 'from'), text(params, 'to')),
+        'variants.validate': (params) => {
+            const variant = variantOf(params.variant);
+            const repaired = params.repair === true ? autotrigger(PI_SURFACE, variant) : [];
+            return { ...check(variant), repaired, variant };
+        },
+        // A whole variant, or an edit of the head that names only the files it changes (null removes one).
+        'variants.save': (params) => {
+            const scope = text(params, 'scope');
+            const base = variants.headVariant(root(), scope)?.variant ?? {};
+            const variant = params.variant !== undefined ? variantOf(params.variant) : applyEdit(base, (params.edit ?? {}));
+            if (params.repair === true)
+                autotrigger(PI_SURFACE, variant);
+            const record = variants.commit(root(), scope, variant, { kind: params.source === 'import' ? 'import' : 'edit', note: optional(params, 'note') ?? undefined, components: Array.isArray(params.components) ? params.components : undefined });
+            variantsChanged(scope);
+            return record;
+        },
+        'variants.restore': (params) => {
+            const scope = text(params, 'scope');
+            const head = variants.restore(root(), scope, text(params, 'version'), optional(params, 'note') ?? undefined);
+            variantsChanged(scope);
+            return head;
+        },
+        // A first version: the variant given, or one built from what shaped the caller before variants.
+        'variants.seed': (params) => {
+            const scope = text(params, 'scope');
+            const variant = params.variant !== undefined ? variantOf(params.variant) : seedVariant(root(), { agentId: optional(params, 'agentId') ?? scope, projectId: optional(params, 'projectId'), instructions: typeof params.instructions === 'string' ? params.instructions : '' });
+            const head = variants.seed(root(), scope, variant, optional(params, 'note') ?? undefined);
+            variantsChanged(scope);
+            return head;
+        },
+        'variants.legacy': (params) => seedVariant(root(), { agentId: optional(params, 'agentId'), projectId: optional(params, 'projectId'), instructions: typeof params.instructions === 'string' ? params.instructions : '' }),
+        'variants.trusted': () => harness.trust.list(),
+        'variants.trust': (params) => {
+            const scope = text(params, 'scope');
+            const variant = variants.headVariant(root(), scope)?.variant ?? {};
+            const path = text(params, 'path');
+            const body = typeof params.text === 'string' ? params.text : variant[path];
+            if (typeof body !== 'string')
+                throw invalid('That plugin file is not in the harness.');
+            const entry = harness.trust.grant(body, path, scope);
+            variantsChanged(scope);
+            return entry;
+        },
+        'variants.untrust': (params) => {
+            harness.trust.revoke(text(params, 'hash'));
+            harness.bus.emit({ type: 'variants.changed' });
+        },
+        'variants.setProbeCode': (params) => {
+            const scope = text(params, 'scope');
+            harness.trust.setProbeCode(scope, params.on === true);
+            variantsChanged(scope);
+        },
+        // The component library (skills, rules and prompts kept as files), and adding one to a variant.
+        'variants.components': () => components.list(root()),
+        'variants.importComponents': (params) => components.importItems(root(), (optional(params, 'kind') ?? 'skills'), Array.isArray(params.items) ? params.items : []),
+        'variants.addComponent': (params) => {
+            const scope = text(params, 'scope');
+            const base = params.variant !== undefined ? variantOf(params.variant) : variants.headVariant(root(), scope)?.variant ?? {};
+            const variant = components.addToVariant(root(), base, text(params, 'id'));
+            return { variant, ...check(variant) };
+        },
+        'variants.materialise': (params) => {
+            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;
+            const pack = compile(env, (params.context ?? {}), (params.launch ?? {}), variant);
+            return params.render ? { pack, text: render(env, pack) } : pack;
+        },
+        'context.runPack': (params) => load(root(), text(params, 'runId')),
+        // ---- Plugins: everything that shapes a session, and the trust a working folder's code needs ---
+        // A host that is not a Node program describes its own parts here instead of in the options.
+        'plugins.describe': (params) => {
+            harness.describe(Array.isArray(params.plugins) ? params.plugins : []);
+            harness.bus.emit({ type: 'plugins.changed' });
+            return { described: [...harness.applicationPlugins] };
+        },
+        'plugins.list': (params) => plugins.list(harness, pluginScope(params)),
+        'plugins.get': async (params) => (await plugins.list(harness, pluginScope(params))).find((plugin) => plugin.id === text(params, 'pluginId')) ?? null,
+        'plugins.attach': (params) => plugins.attach(harness, { ...pluginScope(params), id: text(params, 'id'), scope: params.scope ?? null }, true),
+        'plugins.detach': (params) => plugins.attach(harness, { ...pluginScope(params), id: text(params, 'id'), scope: params.scope ?? null }, false),
+        'plugins.install': (params) => install.install(harness, { ...pluginScope(params), source: text(params, 'source') }),
+        'plugins.remove': (params) => install.remove(harness, { ...pluginScope(params), pluginId: text(params, 'pluginId') }),
+        'plugins.update': (params) => install.update(harness, { ...pluginScope(params), pluginId: optional(params, 'pluginId') }),
+        'plugins.configure': (params) => plugins.configure(harness, { ...pluginScope(params), pluginId: text(params, 'pluginId'), settings: (params.settings && typeof params.settings === 'object' ? params.settings : {}) }),
+        'plugins.forgetAgent': (params) => plugins.forgetAgent(harness, text(params, 'agentId')),
+        'plugins.inventory': (params) => plugins.inventoryFor(harness, { ...pluginScope(params), context: (params.context ?? {}), launch: (params.launch ?? {}), tools: params.tools, connections: params.connections, variant: (params.variant ?? null) }),
+        'plugins.trust': (params) => plugins.trust(harness, { cwd: optional(params, 'cwd'), accountId: optional(params, 'accountId'), hash: text(params, 'hash') }),
+        'plugins.untrust': (params) => plugins.untrust(harness, { cwd: optional(params, 'cwd'), accountId: optional(params, 'accountId'), hash: text(params, 'hash') }),
+        // ---- Capabilities: the caller-facing view over the existing stores -------------------------
+        'capabilities.list': (params) => capabilities.list(harness, pluginScope(params)),
+        'capabilities.inventory': (params) => capabilities.inventory(harness, { ...pluginScope(params), context: (params.context ?? {}), launch: (params.launch ?? {}), tools: Array.isArray(params.tools) ? params.tools : [], connections: params.connections }),
+        'capabilities.attach': (params) => capabilities.switchCapability(harness, { ...pluginScope(params), id: text(params, 'id'), scope: params.scope ?? null }, true),
+        'capabilities.detach': (params) => capabilities.switchCapability(harness, { ...pluginScope(params), id: text(params, 'id'), scope: params.scope ?? null }, false),
+        'capabilities.resolve': (params) => capabilities.resolve(harness, { ...pluginScope(params), tools: Array.isArray(params.tools) ? params.tools.filter((item) => typeof item === 'string') : [] }),
+        'capabilities.run': (params) => loadCapabilitySnapshot(root(), text(params, 'runId')),
+        'capabilities.intersect': (params) => capabilities.toolIntersection(capabilitySet(params.parent), capabilitySet(params.assignee), params.tools === undefined ? undefined : Array.isArray(params.tools) ? params.tools.filter((item) => typeof item === 'string') : []),
+        // ---- Runs --------------------------------------------------------------------------------------
+        'runs.load': (params) => snapshot(root(), text(params, 'runId')),
+        'runs.family': (params) => runFamily(root(), text(params, 'runId')),
+        'runs.find': (params) => findRun(root(), text(params, 'runId')),
+        'runs.list': (params) => listRuns(root(), params.filter ?? {}),
+        // Ids of the runs one session, agent, or account made since an instant, oldest first.
+        'runs.since': (params) => runsSince(root(), { session: optional(params.filter ?? {}, 'session'), agent: optional(params.filter ?? {}, 'agent'), account: optional(params.filter ?? {}, 'account') }, optional(params, 'since')),
+        'runs.events': (params) => readEvents(root(), text(params, 'runId')),
+        'runs.pending': (params) => pendingDecisions(readEvents(root(), text(params, 'runId'))),
+        'runs.checklist': (params) => checklistOf(readEvents(root(), text(params, 'runId'))),
+        'runs.continuation': (params) => continuationOf(root(), text(params, 'runId'), optional(params, 'sessionDir')),
+        'runs.active': () => runs.activeRunIds(),
+        'runs.interrupt': async (params) => {
+            const runId = text(params, 'runId');
+            loadRun(root(), runId);
+            await runs.interrupt(runId);
+            return loadRun(root(), runId);
+        },
+        // A message the person sends into a live reply. It reaches the model after the current step;
+        // `message.steered` marks the moment, and a message the run never takes is reported by its end.
+        'runs.steer': async (params) => {
+            const runId = text(params, 'runId');
+            await runs.steer(runId, text(params, 'text'));
+            return { runId };
+        },
+        // What the application reports into a live run, and an approval it asks a person for.
+        'runs.emit': (params) => {
+            const run = runs.active(text(params, 'runId'));
+            if (!run)
+                throw new HarnessError('run_not_active', 'This run is not active.');
+            run.emit(params.type, params.payload ?? {});
+        },
+        'runs.requestApproval': async (params) => {
+            const run = runs.active(text(params, 'runId'));
+            if (!run)
+                throw new HarnessError('run_not_active', 'The requesting run has ended.');
+            const decision = await run.requestApproval({
+                target: text(params, 'target'),
+                action: typeof params.action === 'string' ? params.action : '',
+                ...(typeof params.screenshotRef === 'string' ? { screenshotRef: params.screenshotRef } : {}),
+                ...(params.operation ? { operation: params.operation } : {}),
+                standing: params.standing === 'none' || params.standing === 'switch' ? params.standing : 'full',
+                ...(typeof params.timeoutMs === 'number' ? { timeoutMs: params.timeoutMs } : {})
+            });
+            return { decision };
+        },
+        'runs.resolveApproval': (params) => runs.resolveApproval(text(params, 'runId'), text(params, 'approvalId'), params.decision),
+        'runs.answerQuestion': (params) => runs.answerQuestion(text(params, 'runId'), text(params, 'questionId'), questionAnswer(params.answer)),
+        'runs.answerQuestions': (params) => {
+            if (!Array.isArray(params.answers))
+                throw invalid('answers must be an array.');
+            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 }) }),
+        // ---- 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') }),
+        'terminal.input': (params) => terminals.input(text(params, 'sessionId'), typeof params.data === 'string' ? params.data : ''),
+        'terminal.state': (params) => terminals.state(text(params, 'sessionId')),
+        'terminal.dispose': (params) => terminals.dispose(text(params, 'sessionId'))
+    };
+}

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

@@ -0,0 +1,19 @@
+import type { SecretStore } from "../accounts/secrets.js";
+import type { Directory } from "../core/env.js";
+import type { ToolPolicy } from "../sessions/policy.js";
+import type { ToolProvider } from "../tools/types.js";
+import type { RpcPeer } from "./rpc.js";
+/** `secrets.get`, `secrets.set`, `secrets.delete` on the host. */
+export declare function remoteSecrets(peer: RpcPeer): SecretStore;
+/** `policy.scope`, `policy.authorize`, `policy.approval`, `policy.connections` on the host. */
+export declare function remotePolicy(peer: RpcPeer): ToolPolicy;
+/**
+ * Names the host knows and the harness shows in what it writes. The host pushes them with the
+ * `directory.set` method, because the lookups are synchronous.
+ */
+export declare function remoteDirectory(peer: RpcPeer): Directory;
+/**
+ * Tools the host registers with `tools.register` and runs when the harness calls `tools.call`
+ * back. A session is given those its `allow` list names.
+ */
+export declare function remoteTools(peer: RpcPeer): ToolProvider;

package/dist/sdk/server/remote.js

@@ -0,0 +1,84 @@
+// What a host that is not a Node program supplies over the protocol instead of in-process:
+// its secret store, its policy, its names for agents, and its own tools. Each is a call to the
+// host; the harness works without any of them.
+import { z } from 'zod';
+import { findingSchema } from "../doctor/types.js";
+/** `secrets.get`, `secrets.set`, `secrets.delete` on the host. */
+export function remoteSecrets(peer) {
+    return {
+        get: (key) => peer.callHost('secrets.get', { key }),
+        set: async (key, value) => void (await peer.callHost('secrets.set', { key, value })),
+        delete: async (key) => void (await peer.callHost('secrets.delete', { key }))
+    };
+}
+/** `policy.scope`, `policy.authorize`, `policy.approval`, `policy.connections` on the host. */
+export function remotePolicy(peer) {
+    const identify = (call) => ({ runId: call.run.id, sessionId: call.run.sessionId, caller: call.caller, tool: call.tool, args: call.args });
+    return {
+        scope: (call) => peer.callHost('policy.scope', identify(call), 90_000),
+        authorize: async (call) => void (await peer.callHost('policy.authorize', identify(call), 90_000)),
+        approval: (input) => peer.callHost('policy.approval', { runId: input.run.id, sessionId: input.run.sessionId, target: input.target, operation: input.operation ?? null }),
+        connections: (input) => peer.callHost('policy.connections', input)
+    };
+}
+/**
+ * Names the host knows and the harness shows in what it writes. The host pushes them with the
+ * `directory.set` method, because the lookups are synchronous.
+ */
+export function remoteDirectory(peer) {
+    let agents = {};
+    let sessions = {};
+    peer.handle('directory.set', (params) => {
+        if (params.agents)
+            agents = params.agents;
+        if (params.sessions)
+            sessions = { ...sessions, ...params.sessions };
+    });
+    return { agentName: (id) => agents[id] ?? null, sessionAgent: (id) => sessions[id] ?? null };
+}
+/**
+ * Tools the host registers with `tools.register` and runs when the harness calls `tools.call`
+ * back. A session is given those its `allow` list names.
+ */
+export function remoteTools(peer) {
+    let registered = [];
+    const descriptor = z.object({
+        id: z.string().min(1), category: z.string(), title: z.string(), tools: z.array(z.string()),
+        probe: z.object({ notice: z.string(), tool: z.string(), input: z.record(z.string(), z.unknown()), contains: z.string().min(1) }).optional()
+    });
+    let diagnostics = [];
+    peer.handle('tools.register', (params) => {
+        diagnostics = z.array(descriptor).parse(params.diagnostics ?? []);
+        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);
+        }
+    }));
+    provider.diagnostics = context => diagnostics.map(check => ({
+        id: `host.${check.id}`, category: check.category, title: check.title, tools: check.tools,
+        local: async (signal) => {
+            signal.throwIfAborted();
+            const result = await peer.callHost('tools.diagnose', { id: check.id, context }, 8000);
+            return findingSchema.pick({ status: true, evidence: true, remedy: true }).parse(result);
+        },
+        live: check.probe ? {
+            notice: check.probe.notice,
+            run: async (probe) => {
+                const result = await probe.call(check.probe.tool, check.probe.input);
+                const text = typeof result === 'string' ? result : result.text;
+                return { status: text.includes(check.probe.contains) ? 'pass' : 'fail', evidence: 'The registered host tool probe completed; the expected response marker was checked.' };
+            }
+        } : undefined
+    }));
+    return provider;
+}

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

@@ -0,0 +1,20 @@
+export declare const PROTOCOL_VERSION = 1;
+export type Handler = (params: any) => Promise<unknown> | unknown;
+export interface Transport {
+    write(line: string): void;
+    onLine(listener: (line: string) => void): void;
+}
+export declare function stdioTransport(): Transport;
+export declare class RpcPeer {
+    private readonly transport;
+    private readonly handlers;
+    private readonly pendingCalls;
+    private nextCallId;
+    constructor(transport: Transport);
+    handle(method: string, handler: Handler): void;
+    methods(): string[];
+    send(message: Record<string, unknown>): void;
+    /** Asks the host to perform a named operation. */
+    callHost<T = unknown>(call: string, params: unknown, timeoutMs?: number): Promise<T>;
+    private receive;
+}

package/dist/sdk/server/rpc.js

@@ -0,0 +1,102 @@
+// Newline-delimited JSON between the harness and a host process that embeds it.
+//
+//   host → harness  { v, id, method, params }        request
+//   harness → host  { v, id, result } | { v, id, error }
+//   harness → host  { v, event }                     run event (validated before sending)
+//   harness → host  { v, notice }                    some state changed and should be read again
+//   harness → host  { v, id, call, params }          the harness asks the host for a named operation
+//   host → harness  { v, id, result } | { v, id, error }  reply to a call
+//
+// stdout carries only protocol lines; diagnostics go to stderr.
+import { createInterface } from 'node:readline';
+import { log } from "../core/bus.js";
+import { HarnessError, toErrorShape } from "../core/errors.js";
+export const PROTOCOL_VERSION = 1;
+export function stdioTransport() {
+    const reader = createInterface({ input: process.stdin, crlfDelay: Infinity });
+    return {
+        write: (line) => void process.stdout.write(`${line}\n`),
+        onLine: (listener) => void reader.on('line', listener)
+    };
+}
+export class RpcPeer {
+    transport;
+    handlers = new Map();
+    pendingCalls = new Map();
+    nextCallId = 0;
+    constructor(transport) {
+        this.transport = transport;
+        transport.onLine((line) => void this.receive(line));
+    }
+    handle(method, handler) {
+        this.handlers.set(method, handler);
+    }
+    methods() {
+        return [...this.handlers.keys()].sort();
+    }
+    send(message) {
+        this.transport.write(JSON.stringify({ v: PROTOCOL_VERSION, ...message }));
+    }
+    /** Asks the host to perform a named operation. */
+    callHost(call, params, timeoutMs = 30_000) {
+        const id = `s${++this.nextCallId}`;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingCalls.delete(id);
+                reject(new HarnessError('host_timeout', `The host did not answer ${call}.`));
+            }, timeoutMs);
+            this.pendingCalls.set(id, {
+                resolve: (value) => {
+                    clearTimeout(timer);
+                    resolve(value);
+                },
+                reject: (error) => {
+                    clearTimeout(timer);
+                    reject(error);
+                }
+            });
+            this.send({ id, call, params });
+        });
+    }
+    async receive(line) {
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            log('ignored a non-JSON line');
+            return;
+        }
+        if (message.v !== PROTOCOL_VERSION || typeof message.id !== 'string') {
+            log('ignored a message with an unknown version or no id');
+            return;
+        }
+        const id = message.id;
+        if (typeof message.method === 'string') {
+            const handler = this.handlers.get(message.method);
+            if (!handler) {
+                this.send({ id, error: { code: 'unknown_method', message: `Unknown method ${message.method}.` } });
+                return;
+            }
+            try {
+                const result = await handler(message.params ?? {});
+                this.send({ id, result: result ?? null });
+            }
+            catch (error) {
+                this.send({ id, error: toErrorShape(error) });
+            }
+            return;
+        }
+        const pending = this.pendingCalls.get(id);
+        if (pending) {
+            this.pendingCalls.delete(id);
+            if (message.error) {
+                const shape = message.error;
+                pending.reject(new HarnessError(shape.code, shape.message, shape.retryHint ?? null));
+            }
+            else {
+                pending.resolve(message.result);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,10 @@
+import type { Harness } from "../harness.js";
+import { RpcPeer, type Transport } from "./rpc.js";
+export interface Served {
+    peer: RpcPeer;
+    /** Stops live work and releases what the harness holds. */
+    shutdown(): Promise<void>;
+}
+/** Registers the method table on `peer` and forwards events and notices to it. */
+export declare function attach(harness: Harness, peer: RpcPeer): void;
+export declare function serve(harness: Harness, transport: Transport): Served;

package/dist/sdk/server/serve.js

@@ -0,0 +1,18 @@
+import { methods } from "./methods.js";
+import { RpcPeer } from "./rpc.js";
+/** Registers the method table on `peer` and forwards events and notices to it. */
+export function attach(harness, peer) {
+    for (const [name, handler] of Object.entries(methods(harness)))
+        peer.handle(name, handler);
+    peer.handle('harness.methods', () => peer.methods());
+    harness.runs.listen((event) => peer.send({ event }));
+    harness.bus.on((notice) => peer.send({ notice }));
+}
+export function serve(harness, transport) {
+    const peer = new RpcPeer(transport);
+    attach(harness, peer);
+    let closing = null;
+    const shutdown = () => (closing ??= harness.close());
+    peer.handle('harness.shutdown', () => shutdown());
+    return { peer, shutdown };
+}