@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/server/methods.js

@@ -0,0 +1,365 @@
+// 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 { openLinkTarget } from "../core/links.js";
+import * as capabilities from "../capabilities/api.js";
+import { loadRun as loadCapabilitySnapshot } from "../capabilities/runSnapshot.js";
+import { capabilitySet } from "../capabilities/runSnapshot.js";
+import * as plugins from "../plugins/api.js";
+import { BUILTIN_PLUGIN_REGISTRY } from "../plugins/builtin.js";
+import * as install from "../plugins/install.js";
+import * as proposals from "../plugins/proposals.js";
+import { attribution } from "../context/attribution.js";
+import { runDetails } from "../context/runDetails.js";
+import { compile, load, render } from "../prompt/compile.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";
+import { todoOf } from "../tools/todo.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 { optional, text } from "./params.js";
+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 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))
+        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)] };
+    }
+}
+export function methods(harness) {
+    const { accounts, approvals, runs, sessions, terminals, env } = harness;
+    const root = () => env.root;
+    const variantsChanged = (scope) => harness.bus.emit({ type: 'variants.changed', scope });
+    const builtins = BUILTIN_PLUGIN_REGISTRY.serverMethods(harness);
+    const foundation = {
+        // ---- The harness itself --------------------------------------------------------------------
+        'harness.status': () => ({ dataRoot: harness.dataRoot, productName: env.productName, recovery: harness.recovery, activeRuns: runs.activeRunIds() }),
+        'harness.open': (params) => harness.open(text(params, 'dataRoot'), Array.isArray(params.agentIds) ? params.agentIds : []),
+        'harness.rebuildIndex': () => harness.rebuildIndex(),
+        // ---- 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')),
+        // ---- 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, variants.resolveRef(root(), scope, text(params, 'version')), optional(params, 'note') ?? undefined);
+            variantsChanged(scope);
+            return head;
+        },
+        // Names a version (a fingerprint, a short prefix or another tag); a tag already in use moves.
+        'variants.tag': (params) => {
+            const scope = text(params, 'scope');
+            const tags = variants.tag(root(), scope, text(params, 'name'), variants.resolveRef(root(), scope, text(params, 'version')));
+            variantsChanged(scope);
+            return tags;
+        },
+        'variants.untag': (params) => {
+            const scope = text(params, 'scope');
+            const tags = variants.untag(root(), scope, text(params, 'name'));
+            variantsChanged(scope);
+            return tags;
+        },
+        'variants.tags': (params) => variants.tags(root(), text(params, 'scope')),
+        'variants.resolve': (params) => {
+            const scope = text(params, 'scope');
+            const fp = variants.resolveRef(root(), scope, text(params, 'ref'));
+            return { fingerprint: fp, version: variants.versionRecord(root(), scope, fp) };
+        },
+        // A new head built from the current one with some components taken from an earlier version.
+        'variants.revert': (params) => {
+            const scope = text(params, 'scope');
+            const from = variants.resolveRef(root(), scope, text(params, 'from'));
+            const selectors = Array.isArray(params.components) ? params.components.filter((entry) => typeof entry === 'string' && entry.trim().length > 0) : [];
+            const record = variants.revertComponents(root(), scope, from, selectors, optional(params, 'note') ?? undefined);
+            variantsChanged(scope);
+            return record;
+        },
+        // 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 };
+        },
+        // ---- 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') }),
+        // ---- 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')),
+        'context.runDetails': (params) => runDetails(root(), text(params, 'runId')),
+        // What the request was made of: one row per contributor, reconciled to the provider's figure.
+        'context.attribution': (params) => attribution(env, 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.proposals.create': (params) => proposals.create(root(), params.name, params.description, params.files),
+        'plugins.proposals.list': () => proposals.list(root()),
+        'plugins.proposals.preview': (params) => proposals.preview(root(), text(params, 'id')),
+        'plugins.proposals.reject': (params) => proposals.reject(root(), text(params, 'id'), text(params, 'hash')),
+        'plugins.proposals.accept': (params) => proposals.accept(harness, text(params, 'id'), text(params, 'hash')),
+        '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') : []),
+        // ---- Links: what a person's click opens, and with which system handler ---------------------------
+        // A person's action, not a model tool: nothing here is in `HARNESS_TOOLS`, so the gate is untouched.
+        'links.open': (params) => openLinkTarget(text(params, 'target'), { base: optional(params, 'base'), opener: harness.linkOpener }),
+        // ---- 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.todo': (params) => todoOf(readEvents(root(), text(params, 'runId'))),
+        // Pre-rename name; kept for one release so existing hosts keep working.
+        'runs.checklist': (params) => todoOf(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 ----------------------------------------------------------------------------------
+        'sessions.spawnSubagent': (params) => sessions.spawnSubagent(params),
+        'sessions.run': (params) => sessions.run(params),
+        // Live sessions (ADR-0083): Pi sessions kept open between the runs of a conversation.
+        'sessions.live': () => ({ sessions: sessions.liveSessions() }),
+        'sessions.close': (params) => sessions.closeLive(text(params, 'sessionId')),
+        'sessions.followUp': (params) => sessions.followUp(text(params, 'sessionId'), text(params, 'text')),
+        'sessions.followUp.clear': (params) => ({ removed: sessions.live.clearQueue(text(params, 'sessionId')) }),
+        '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) => { sessions.live.yieldHistory({ sessionDir: sessionRef(params).sessionDir }); return 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) => { sessions.live.yieldHistory({ sessionDir: sessionRef(params).sessionDir }); return 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') }),
+        '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')),
+        // ADR-0083 phase 3: a client terminal's reply may outlive its window.
+        'terminal.detach': (params) => terminals.detach(text(params, 'sessionId')),
+        'terminal.detached': () => ({ sessions: terminals.detached() }),
+        'terminal.takeRelaunch': (params) => terminals.takeRelaunch(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.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,109 @@
+// 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";
+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 {
+        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) => {
+        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) => {
+            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);
+            }
+        }
+    }
+}