@xingular/harness 0.1.7 → 1.1.1

package/dist/sdk/refine/suite.js

@@ -0,0 +1,174 @@
+// Evaluating variants on a task set: one execution per version × task, recorded as an
+// answer-free matrix of what each variant delivered. No improver, no selection, no adoption —
+// the only executions here are the given Executor's probe runs. Records live beside a
+// refinement's, under `<data root>/refine/<id>/`, so a sweep over variant versions or package
+// commits reads the same record family (`refine/<id>/matrix.json`).
+//
+// Every row carries its comparability keys (task-prompt hash, executor name, package
+// version, variant fingerprint), so two matrices — taken at different commits or versions —
+// are diffable without re-reading the runs that produced them.
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { now, readJson, safeId, writeJson } from "../core/fs.js";
+import * as store from "../variant/store.js";
+import { PI_SURFACE } from "../variant/surface.js";
+import { writeVariant } from "../variant/variant.js";
+import { assertVariantHasNoGraderVerdicts } from "./evidence.js";
+import { mapLimit } from "./recursion.js";
+export function matrixDir(root, id) {
+    return join(root, 'refine', safeId(id));
+}
+export function readMatrix(root, id) {
+    return readJson(join(matrixDir(root, id), 'matrix.json'));
+}
+let packageVersionMemo = null;
+/** This package's release, whatever shape the module took: source, esbuild bundle, or an
+ * installed copy. Walks up from the module's own URL to the nearest package.json. */
+function packageVersion() {
+    if (packageVersionMemo === null) {
+        packageVersionMemo = 'unknown';
+        try {
+            let dir = fileURLToPath(import.meta.url);
+            for (let up = 0; up < 6; up++) {
+                dir = dirname(dir);
+                const manifest = join(dir, 'package.json');
+                if (existsSync(manifest)) {
+                    const json = JSON.parse(readFileSync(manifest, 'utf8'));
+                    if (json.version)
+                        packageVersionMemo = json.version;
+                    break;
+                }
+            }
+        }
+        catch {
+            // A record without a version is still a record.
+        }
+    }
+    return packageVersionMemo;
+}
+function taskHash(task) {
+    return createHash('sha256').update(task.prompt).digest('hex').slice(0, 16);
+}
+const SEGMENT = /^[A-Za-z0-9_-]{1,128}$/;
+function stage(input) {
+    const labels = [];
+    for (const entry of input.versions) {
+        if (!SEGMENT.test(entry.label))
+            throw new Error(`Version label '${entry.label}' must be a usable record name (A-Z a-z 0-9 _ -).`);
+        labels.push(entry.label);
+    }
+    if (new Set(labels).size !== labels.length)
+        throw new Error('Version labels must be unique.');
+    if (input.tasks.some((task) => !SEGMENT.test(task.id)))
+        throw new Error('Task ids must be usable record names (A-Z a-z 0-9 _ -).');
+    if (new Set(input.tasks.map((task) => task.id)).size !== input.tasks.length)
+        throw new Error('Task ids must be unique.');
+    // Staging and the tripwire happen before any execution: a variant carrying grader output
+    // never reaches an execution, the same guard the refinement's evidence folder applies
+    // (INV-REF-1). A variant that cannot be written becomes an error row, never an abort.
+    return input.versions.map((entry) => {
+        try {
+            assertVariantHasNoGraderVerdicts(entry.variant);
+            return { label: entry.label, variant: entry.variant, fingerprint: store.fingerprint(entry.variant), dir: writeVariant(PI_SURFACE, entry.variant, join(matrixDir(input.root, input.id), 'variants', entry.label)), error: '' };
+        }
+        catch (error) {
+            return { label: entry.label, variant: entry.variant, fingerprint: store.fingerprint(entry.variant), dir: '', error: error instanceof Error ? error.message : String(error) };
+        }
+    });
+}
+/** Runs the full version × task matrix. Bad input throws; execution failures become rows. */
+export async function runMatrix(input) {
+    if (!input.versions.length)
+        throw new Error('A matrix needs at least one harness version.');
+    if (!input.tasks.length)
+        throw new Error('A matrix needs at least one task.');
+    if (input.tasks.some((task) => !task.prompt.trim()))
+        throw new Error('Every task needs a non-empty prompt.');
+    const { root, id, tasks, executor } = input;
+    const executorName = input.executorName ?? executor.constructor?.name ?? 'executor';
+    const emit = (event) => input.onEvent?.(event);
+    const staged = stage(input);
+    const summary = {
+        id,
+        status: 'running',
+        startedAt: now(),
+        endedAt: null,
+        versions: staged.map((entry) => entry.label),
+        tasks: tasks.map((task) => task.id),
+        rows: [],
+        usd: 0,
+        errors: []
+    };
+    const save = () => {
+        summary.usd = Math.round(summary.rows.reduce((sum, row) => sum + row.costUsd, 0) * 1e6) / 1e6;
+        writeJson(join(matrixDir(root, id), 'matrix.json'), summary);
+        emit({ type: 'summary', summary: structuredClone(summary) });
+    };
+    writeJson(join(matrixDir(root, id), 'suite.json'), { id, versions: staged.map(({ label, fingerprint }) => ({ label, fingerprint })), tasks });
+    save();
+    const pairs = staged.flatMap((version) => tasks.map((task) => ({ version, task })));
+    await mapLimit(pairs, input.rolloutWidth ?? 4, async ({ version, task }) => {
+        const runId = `${id}-${version.label}-${task.id}`;
+        let row;
+        if (input.signal?.aborted)
+            row = failedRow(version, task, runId, executorName, 'The matrix was cancelled.');
+        else if (version.error)
+            row = failedRow(version, task, runId, executorName, `the variant could not be staged: ${version.error}`);
+        else {
+            let validation = null;
+            if (executor.validateVariant) {
+                try {
+                    executor.validateVariant(task, version.variant);
+                }
+                catch (error) {
+                    validation = `invalid variant for this task: ${error instanceof Error ? error.message : String(error)}`;
+                }
+            }
+            if (validation)
+                row = failedRow(version, task, runId, executorName, validation);
+            else {
+                emit({ type: 'execution.started', version: version.label, task: task.id, label: runId });
+                let rollout;
+                try {
+                    rollout = await executor.execute(task, version.dir, runId, runId);
+                }
+                catch (error) {
+                    // The Executor contract says execute never throws; this keeps the record honest if one does.
+                    rollout = { label: runId, runId, dir: join(matrixDir(root, id), 'missing', version.label, task.id), ok: false, delivered: false, costUsd: 0, wallMs: 0, error: error instanceof Error ? error.message : String(error) };
+                }
+                emit({ type: 'execution.finished', version: version.label, task: task.id, ok: rollout.ok, delivered: rollout.delivered, error: rollout.error });
+                row = rowOf(version, task, runId, executorName, rollout);
+            }
+        }
+        summary.rows.push(row);
+        save();
+    });
+    for (const error of staged.filter((entry) => entry.error).map((entry) => `${entry.label}: ${entry.error}`))
+        summary.errors.push(error);
+    summary.status = input.signal?.aborted ? 'cancelled' : summary.rows.some((row) => row.ok) ? 'ok' : summary.rows.length ? 'partial' : 'failed';
+    summary.endedAt = now();
+    save();
+    return summary;
+}
+function rowOf(version, task, runId, executorName, rollout) {
+    return {
+        version: version.label,
+        fingerprint: version.fingerprint,
+        task: task.id,
+        runId,
+        dir: rollout.dir,
+        ok: rollout.ok,
+        delivered: rollout.delivered,
+        costUsd: rollout.costUsd,
+        wallMs: rollout.wallMs,
+        error: rollout.error,
+        taskHash: taskHash(task),
+        executor: executorName,
+        packageVersion: packageVersion()
+    };
+}
+function failedRow(version, task, runId, executorName, error) {
+    return rowOf(version, task, runId, executorName, { label: runId, runId, dir: '', ok: false, delivered: false, costUsd: 0, wallMs: 0, error });
+}

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

@@ -0,0 +1,9 @@
+import type { RunEvent } from "../sessions/contracts.js";
+export declare function renderEvents(events: readonly RunEvent[], options: {
+    obsTrunc: number;
+    argsTrunc?: number;
+}): string;
+/** The last assistant message of a run. */
+export declare function finalText(events: readonly RunEvent[]): string;
+/** The run's cost so far, from its last usage report. */
+export declare function costOf(events: readonly RunEvent[]): number;

package/dist/sdk/refine/trajectory.js

@@ -0,0 +1,68 @@
+const TRUNC = (n) => `…(+${n} chars — render truncation)`;
+function clip(text, limit) {
+    const clean = text.replace(/\0/g, '');
+    return limit > 0 && clean.length > limit ? `${clean.slice(0, limit)}${TRUNC(clean.length - limit)}` : clean;
+}
+export function renderEvents(events, options) {
+    const out = [];
+    const argsTrunc = options.argsTrunc ?? 2000;
+    for (const event of events) {
+        const payload = (event.payload ?? {});
+        switch (event.type) {
+            case 'message.completed':
+                if (typeof payload.text === 'string' && payload.text.trim())
+                    out.push(`[${payload.role === 'user' ? 'USER' : 'ASSISTANT'}]\n${clip(payload.text, options.obsTrunc)}`);
+                break;
+            case 'tool.started':
+                out.push(`[ACTION] ${String(payload.name ?? 'tool')}${typeof payload.input === 'string' && payload.input ? ` ${clip(payload.input, argsTrunc)}` : ''}`);
+                break;
+            case 'tool.completed': {
+                const text = typeof payload.output === 'string' ? payload.output : '';
+                out.push(`${payload.ok === false ? '[ERROR]' : '[OBSERVATION]'} ${String(payload.name ?? 'tool')}${typeof payload.durationMs === 'number' ? ` (${Math.round(payload.durationMs)} ms)` : ''}\n${clip(text, options.obsTrunc)}${payload.outputTruncated ? '\n(the tool output was already bounded when it was recorded)' : ''}`);
+                break;
+            }
+            case 'retry.started':
+                out.push(`[ERROR] model request failed, retrying (${String(payload.attempt)}/${String(payload.maxAttempts)}): ${String(payload.error ?? '')}`);
+                break;
+            case 'compaction.ended':
+                out.push(`[ACTION] context compacted (${String(payload.reason ?? '')})${typeof payload.tokensBefore === 'number' ? `: ${payload.tokensBefore} → ${String(payload.tokensAfter ?? '?')} tokens` : ''}`);
+                break;
+            case 'approval.resolved':
+                if (payload.decision === 'denied')
+                    out.push('[ERROR] a tool call was refused');
+                break;
+            case 'extension.notice':
+                if (typeof payload.text === 'string')
+                    out.push(`[OBSERVATION] notice: ${clip(payload.text, 2000)}`);
+                break;
+            case 'failed':
+                out.push(`[ERROR] run failed: ${String(payload.message ?? payload.code ?? '')}`);
+                break;
+            case 'status.changed':
+                if (payload.status === 'interrupted')
+                    out.push('[ERROR] run interrupted');
+                break;
+            default:
+                break;
+        }
+    }
+    return out.length ? out.join('\n\n') : '(no trajectory: the run recorded no messages or tool use)';
+}
+/** The last assistant message of a run. */
+export function finalText(events) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const payload = events[i].payload;
+        if (events[i].type === 'message.completed' && payload?.role === 'assistant' && typeof payload.text === 'string' && payload.text.trim())
+            return payload.text;
+    }
+    return '';
+}
+/** The run's cost so far, from its last usage report. */
+export function costOf(events) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const payload = events[i].payload;
+        if (events[i].type === 'usage.updated' && typeof payload?.costUsd === 'number')
+            return payload.costUsd;
+    }
+    return 0;
+}

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

@@ -0,0 +1,77 @@
+import type { Variant } from "../variant/surface.js";
+import type { WorkPrompts } from "./prompts.js";
+export type RecursionMode = 'parallel' | 'sequential';
+/** One piece of work to refine on. */
+export interface RefineTask {
+    /** Stable id of the task; names its folder and its library entry. */
+    id: string;
+    /** The request, as the agent received it, with any expected answer stripped. */
+    prompt: string;
+    /** The harness scope: whose variant this is and whose library it reads and grows. */
+    scope: string;
+    /** A grouping inside the scope's library. Defaults to the scope. */
+    domain?: string;
+    /** Material the work was done from, served to improvers and the selector as `source/`. */
+    sourceDir?: string | null;
+    /** Paths that must never reach a model (answer keys and the like), as globs. */
+    leakGlobs?: string[];
+    /** The text about the work the prompts interpolate. */
+    prompts?: WorkPrompts;
+    /** Whether a harness here may carry subagents. Default true. */
+    allowSubagents?: boolean;
+}
+/** What the method knows about one finished execution. Never carries a score. */
+export interface Rollout {
+    label: string;
+    runId: string;
+    /** A folder that holds this execution's evidence. */
+    dir: string;
+    ok: boolean;
+    delivered: boolean;
+    costUsd: number;
+    wallMs: number;
+    error: string;
+}
+export interface Executor {
+    /**
+     * Runs one execution of `task` with the harness in `variantDir` (null: the base harness) and
+     * returns what it produced. A failure is returned as `ok: false`, never thrown.
+     */
+    execute(task: RefineTask, variantDir: string | null, label: string, runId: string): Promise<Rollout>;
+    /** The execution in the shared `[ACTION]/[OBSERVATION]/[ERROR]` grammar. */
+    trajectory(rollout: Rollout, options: {
+        obsTrunc: number;
+    }): string;
+    /** filename → readable text, one entry per artifact produced. */
+    deliverableFiles(rollout: Rollout): Record<string, string>;
+    /** Extra validation of a proposed variant for this task; throw with every problem listed. */
+    validateVariant?(task: RefineTask, variant: Variant): void;
+}
+export interface ImproverReply {
+    label: string;
+    text: string;
+    costUsd: number;
+    attempts: number;
+    cached: boolean;
+    /** The harvested folder, when the call asked for one; null when it did not come back. */
+    workspace: string | null;
+}
+export declare class ImproverError extends Error {
+    readonly attempts: number;
+    readonly costUsd: number;
+    constructor(message: string, attempts?: number, costUsd?: number);
+}
+export interface ImproverCall {
+    /** The instruction; evidence stays on disk under `context/`. */
+    mission: string;
+    /** The folder copied into the session as `context/`. */
+    contextDir: string;
+    /** A unique label for the audit trail and cache. */
+    label: string;
+    /** A path inside the session's folder to copy out before it is removed, e.g. `context/harness`. */
+    harvest?: string;
+    signal?: AbortSignal;
+}
+export interface Improver {
+    call(input: ImproverCall): Promise<ImproverReply>;
+}

package/dist/sdk/refine/types.js

@@ -0,0 +1,10 @@
+export class ImproverError extends Error {
+    attempts;
+    costUsd;
+    constructor(message, attempts = 0, costUsd = 0) {
+        super(message);
+        this.attempts = attempts;
+        this.costUsd = costUsd;
+        this.name = 'ImproverError';
+    }
+}

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

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

package/dist/sdk/server/methods.js

@@ -0,0 +1,293 @@
+// 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 * 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 { 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 { 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 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, 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 };
+        },
+        // ---- 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')),
+        // ---- 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 ----------------------------------------------------------------------------------
+        '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'))
+    };
+    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>;