@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/doctor/probe.js

@@ -0,0 +1,94 @@
+import { randomUUID } from 'node:crypto';
+import { resolve } from "../capabilities/api.js";
+import { freezeRun } from "../capabilities/runSnapshot.js";
+import { runRecordSchema } from "../sessions/contracts.js";
+import { saveRun } from "../sessions/runStore.js";
+import { HarnessError } from "../core/errors.js";
+import { materialise } from "../variant/materialise.js";
+/** A real, tool-only diagnostic run. Model requests, if selected, use Pi's account runtime. */
+export async function diagnosticProbe(harness, context, inputSignal, action) {
+    const interrupt = new AbortController();
+    const signal = AbortSignal.any([inputSignal, interrupt.signal]);
+    signal.throwIfAborted();
+    const root = harness.env.root;
+    const id = randomUUID();
+    const caller = { ...context.caller, runId: id, sessionId: id, surface: 'doctor' };
+    const available = await resolve(harness, { ...context.caller, cwd: context.cwd, tools: context.tools });
+    const capabilities = {
+        version: 1,
+        tools: available.tools.filter(tool => context.tools.includes(tool) && (!context.capabilities || context.capabilities.tools.includes(tool))),
+        connectors: available.connectors.filter(connector => !context.capabilities || context.capabilities.connectors.includes(connector)),
+        contributions: available.contributions.filter(item => !context.capabilities || context.capabilities.contributions.includes(item))
+    };
+    signal.throwIfAborted();
+    if (context.accountId)
+        harness.accounts.find(context.accountId);
+    const variant = context.variant ? materialise(root, context.variant, { trust: harness.trust }) : null;
+    saveRun(root, runRecordSchema.parse({
+        id, sessionId: id, mode: 'doctor', harness: 'pi', sessionType: 'structured', workingDirectory: context.cwd,
+        startedAt: new Date().toISOString(), status: 'running', goal: 'User-approved diagnostic probe',
+        accountId: context.accountId, agentId: caller.agentId ?? null, projectId: caller.projectId ?? null, trigger: 'doctor',
+        variantScope: variant?.scope ?? null, variantVersion: variant?.fingerprint ?? null
+    }));
+    freezeRun(root, id, caller, capabilities);
+    const run = harness.runs.start(id, id);
+    run.onInterrupt(() => interrupt.abort());
+    const abort = () => { run.finish('interrupted', undefined, undefined, 'user_abort'); void harness.world.release(id); };
+    signal.addEventListener('abort', abort, { once: true });
+    const gate = harness.sessions.diagnosticGate(run, caller);
+    try {
+        signal.throwIfAborted();
+        const result = await action({
+            signal, context, run,
+            call: async (name, input) => {
+                signal.throwIfAborted();
+                if (run.finished || !capabilities.tools.includes(name))
+                    throw new HarnessError('doctor_blocked', 'This tool is outside the diagnostic capability set.');
+                const callId = randomUUID();
+                const refusal = await gate.checkDetailed?.(name, input);
+                if (refusal) {
+                    run.emit('tool.refused', { toolCallId: callId, name, code: refusal.code, reason: 'The tool policy refused this diagnostic call.' });
+                    throw new HarnessError('doctor_blocked', 'The tool policy refused this diagnostic call.');
+                }
+                signal.throwIfAborted();
+                run.emit('tool.started', { toolCallId: callId, name, summary: 'Synthetic diagnostic input' });
+                try {
+                    let result;
+                    if (name === 'mcp_list_tools') {
+                        if (typeof input.connectionId !== 'string')
+                            throw new HarnessError('doctor_blocked', 'A connection must be selected.');
+                        const broker = harness.apps.grant({ sessionId: id, runId: id, caller, readOnly: true, depth: 0, capabilities: { ...capabilities, connectors: capabilities.connectors.filter(connector => connector === input.connectionId) } });
+                        const count = await harness.apps.diagnosticList(broker, input.connectionId, signal);
+                        result = { text: `${count} tools listed.`, details: { doctorOk: true, toolCount: count } };
+                    }
+                    else {
+                        const tools = await harness.sessions.diagnosticTools({ run, caller, allow: capabilities.tools, depth: 0, cwd: context.cwd, capabilities });
+                        const tool = tools.find(tool => tool.name === name);
+                        if (!tool)
+                            throw new HarnessError('doctor_blocked', 'No provider supplies this diagnostic tool.');
+                        signal.throwIfAborted();
+                        result = await tool.execute(input);
+                    }
+                    signal.throwIfAborted();
+                    run.emit('tool.completed', { toolCallId: callId, name, ok: true });
+                    return result;
+                }
+                catch (error) {
+                    run.emit('tool.completed', { toolCallId: callId, name, ok: false });
+                    throw error;
+                }
+            }
+        });
+        return result;
+    }
+    catch (error) {
+        run.finish(signal.aborted ? 'interrupted' : 'failed', { code: 'doctor_failed', message: 'The diagnostic probe failed.' }, undefined, signal.aborted ? 'user_abort' : undefined);
+        throw error;
+    }
+    finally {
+        signal.removeEventListener('abort', abort);
+        run.finish(signal.aborted ? 'interrupted' : 'completed', undefined, undefined, signal.aborted ? 'user_abort' : undefined);
+        harness.apps.revokeRun(id, id);
+        await harness.world.release(id);
+    }
+}

package/dist/sdk/doctor/serverMethods.d.ts

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

package/dist/sdk/doctor/serverMethods.js

@@ -0,0 +1,8 @@
+import { text } from "../server/params.js";
+export function doctorServerMethods(harness) {
+    return {
+        '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'))
+    };
+}

package/dist/sdk/doctor/service.d.ts

@@ -0,0 +1,23 @@
+import { type DoctorCheck, type DoctorContext, type DoctorInput, type DoctorProbeContext, type DoctorReport } from "./types.js";
+export interface DoctorOptions {
+    checks(context: DoctorContext): Promise<DoctorCheck[]>;
+    probe<T>(context: DoctorContext, signal: AbortSignal, action: (probe: DoctorProbeContext) => Promise<T>): Promise<T>;
+    timeout?: {
+        local: number;
+        live: number;
+        model: number;
+    };
+}
+export declare class Doctor {
+    private readonly options;
+    private readonly jobs;
+    private closed;
+    constructor(options: DoctorOptions);
+    start(input: DoctorInput): DoctorReport;
+    read(id: string): DoctorReport;
+    cancel(id: string): DoctorReport;
+    close(): Promise<void>;
+    private job;
+    private run;
+    private bounded;
+}

package/dist/sdk/doctor/service.js

@@ -0,0 +1,144 @@
+import { randomUUID } from 'node:crypto';
+import { redactLogText } from "../core/bus.js";
+import { invalid, notFound } from "../core/errors.js";
+import { doctorInputSchema, findingSchema } from "./types.js";
+const safe = (text) => redactLogText(text).replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '').replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, ' ').slice(0, 4000);
+export class Doctor {
+    options;
+    jobs = new Map();
+    closed = false;
+    constructor(options) {
+        this.options = options;
+    }
+    start(input) {
+        if (this.closed)
+            throw invalid('Diagnostics are closed.');
+        const parsed = doctorInputSchema.parse(input);
+        if (parsed.mode === 'live' && (!parsed.confirmed || !parsed.checks.length))
+            throw invalid('Select live checks and confirm their costs and isolated resources first.');
+        const context = structuredClone(parsed.context);
+        const report = {
+            id: randomUUID(), state: 'running', startedAt: new Date().toISOString(), endedAt: null,
+            mode: parsed.mode, context: { accountId: context.accountId, model: context.model },
+            completed: 0, total: 0, findings: [], liveChecks: []
+        };
+        const job = { report, abort: new AbortController(), settled: Promise.resolve() };
+        this.jobs.set(report.id, job);
+        job.settled = this.run(job, context, parsed.checks);
+        return this.read(report.id);
+    }
+    read(id) { return structuredClone(this.job(id).report); }
+    cancel(id) {
+        const job = this.job(id);
+        if (job.report.state === 'running') {
+            job.report.state = 'cancelled';
+            job.report.endedAt = new Date().toISOString();
+            job.abort.abort();
+        }
+        return this.read(id);
+    }
+    async close() {
+        this.closed = true;
+        for (const id of this.jobs.keys())
+            this.cancel(id);
+        await Promise.all([...this.jobs.values()].map(job => job.settled));
+        this.jobs.clear();
+    }
+    job(id) {
+        const job = this.jobs.get(id);
+        if (!job)
+            throw notFound('Diagnostic job');
+        return job;
+    }
+    async run(job, context, selected) {
+        const { report, abort } = job;
+        try {
+            const checks = await this.bounded(abort.signal, 10_000, () => this.options.checks(context));
+            const ids = new Set();
+            for (const check of checks) {
+                if (ids.has(check.id))
+                    throw invalid(`Duplicate diagnostic check: ${check.id}`);
+                ids.add(check.id);
+            }
+            const enabled = (check) => !check.tools?.length || check.tools.some(tool => context.tools.includes(tool));
+            report.liveChecks = checks.filter(check => check.live && enabled(check)).map(check => ({ id: check.id, title: safe(check.title), notice: safe(check.live.notice) }));
+            if (selected.some(id => !ids.has(id)))
+                throw invalid('An unknown diagnostic check was selected.');
+            const wanted = selected.length ? checks.filter(check => selected.includes(check.id)) : checks;
+            report.total = wanted.length;
+            const execute = async (check) => {
+                if (abort.signal.aborted)
+                    return;
+                const mode = report.mode;
+                const limits = this.options.timeout ?? { local: 10_000, live: 30_000, model: 60_000 };
+                let result;
+                try {
+                    result = !enabled(check)
+                        ? { status: 'disabled', evidence: 'This capability is disabled in the selected session.' }
+                        : await this.bounded(abort.signal, mode === 'local' ? limits.local : check.id === 'model' ? limits.model : limits.live, signal => {
+                            if (mode === 'local')
+                                return check.local(signal);
+                            if (!check.live)
+                                return Promise.resolve({ status: 'unverified', evidence: 'This check has no live probe.' });
+                            return this.options.probe(context, signal, probe => check.live.run(probe));
+                        });
+                }
+                catch (error) {
+                    const blocked = error && typeof error === 'object' && 'code' in error && error.code === 'doctor_blocked';
+                    result = { status: blocked ? 'blocked' : 'fail', evidence: blocked ? 'The capability or tool policy refused this diagnostic call.' : 'The check failed or exceeded its time limit.', remedy: blocked ? 'Review the selected scope and tool permissions.' : 'Review the backend configuration and retry this check.' };
+                }
+                if (abort.signal.aborted)
+                    return;
+                const parsed = findingSchema.safeParse({ ...result, id: check.id, category: safe(check.category), title: safe(check.title), verification: mode, checkedAt: new Date().toISOString() });
+                const finding = parsed.success ? parsed.data : {
+                    id: check.id, category: safe(check.category), title: safe(check.title), verification: mode,
+                    checkedAt: new Date().toISOString(), status: 'fail',
+                    evidence: 'The diagnostic provider returned an invalid finding.', remedy: 'Review the provider implementation.'
+                };
+                finding.evidence = safe(finding.evidence);
+                if (finding.remedy)
+                    finding.remedy = safe(finding.remedy);
+                report.findings.push(finding);
+                report.completed++;
+            };
+            // Interaction probes are serial, so only one isolated surface can own input at a time.
+            if (report.mode === 'live') {
+                for (const check of wanted)
+                    await execute(check);
+            }
+            else {
+                let index = 0;
+                await Promise.all(Array.from({ length: Math.min(4, wanted.length) }, async () => {
+                    while (!abort.signal.aborted && index < wanted.length)
+                        await execute(wanted[index++]);
+                }));
+            }
+        }
+        catch {
+            if (!abort.signal.aborted)
+                report.findings.push({ id: 'doctor', title: 'Diagnostic setup', category: 'runtime', status: 'fail', verification: 'local', evidence: 'Diagnostic checks could not be prepared.', remedy: 'Check the selected scope, account, and data location.', checkedAt: new Date().toISOString() });
+        }
+        finally {
+            if (report.state === 'running')
+                report.state = 'completed';
+            report.endedAt ??= new Date().toISOString();
+        }
+    }
+    async bounded(parent, ms, action) {
+        parent.throwIfAborted();
+        const controller = new AbortController();
+        const abort = () => controller.abort();
+        parent.addEventListener('abort', abort, { once: true });
+        const timer = setTimeout(abort, ms);
+        try {
+            return await Promise.race([
+                Promise.resolve().then(() => { controller.signal.throwIfAborted(); return action(controller.signal); }),
+                new Promise((_, reject) => controller.signal.addEventListener('abort', () => reject(new Error('Diagnostic cancelled or timed out.')), { once: true }))
+            ]);
+        }
+        finally {
+            clearTimeout(timer);
+            parent.removeEventListener('abort', abort);
+        }
+    }
+}

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

@@ -0,0 +1,141 @@
+import { z } from 'zod';
+import type { CallerContext } from "../core/caller.js";
+import type { CapabilitySet } from "../capabilities/types.js";
+import type { VariantChoice } from "../variant/materialise.js";
+import type { ToolResult } from "../tools/types.js";
+import type { ActiveRun } from "../sessions/registry.js";
+export declare const findingSchema: z.ZodObject<{
+    id: z.ZodString;
+    category: z.ZodString;
+    title: z.ZodString;
+    status: z.ZodEnum<{
+        disabled: "disabled";
+        warning: "warning";
+        blocked: "blocked";
+        pass: "pass";
+        fail: "fail";
+        unverified: "unverified";
+    }>;
+    verification: z.ZodEnum<{
+        local: "local";
+        live: "live";
+    }>;
+    evidence: z.ZodString;
+    remedy: z.ZodOptional<z.ZodString>;
+    checkedAt: z.ZodString;
+}, z.core.$strip>;
+export type DoctorFinding = z.infer<typeof findingSchema>;
+export type CheckResult = Pick<DoctorFinding, 'status' | 'evidence' | 'remedy'>;
+export interface DoctorContext {
+    caller: CallerContext;
+    cwd: string;
+    accountId: string | null;
+    model: string | null;
+    tools: readonly string[];
+    capabilities?: CapabilitySet;
+    variant?: VariantChoice | null;
+}
+export interface DoctorCheck {
+    id: string;
+    category: string;
+    title: string;
+    tools?: readonly string[];
+    /** Readiness inspection only: no network, authentication or world actions. */
+    local(signal: AbortSignal): Promise<CheckResult>;
+    live?: {
+        /** Shown to the person before confirmation. Include destinations, costs and isolation. */
+        notice: string;
+        run(context: DoctorProbeContext): Promise<CheckResult>;
+    };
+}
+export interface DoctorProbeContext {
+    run: ActiveRun;
+    signal: AbortSignal;
+    context: DoctorContext;
+    /** Executes an enabled tool through the existing per-call gate. */
+    call(tool: string, input: Record<string, unknown>): Promise<string | ToolResult>;
+}
+/** Optional metadata on a callable tool provider; no new Harness extension point. */
+export interface ProviderDiagnostics {
+    diagnostics?(context: DoctorContext): DoctorCheck[] | Promise<DoctorCheck[]>;
+}
+export declare const doctorInputSchema: z.ZodObject<{
+    context: z.ZodObject<{
+        caller: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        cwd: z.ZodString;
+        accountId: z.ZodNullable<z.ZodString>;
+        model: z.ZodNullable<z.ZodString>;
+        tools: z.ZodArray<z.ZodString>;
+        variant: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodObject<{
+            scope: z.ZodString;
+            version: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>, z.ZodObject<{
+            dir: z.ZodString;
+            scope: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>]>>>;
+        capabilities: z.ZodOptional<z.ZodObject<{
+            version: z.ZodLiteral<1>;
+            tools: z.ZodArray<z.ZodString>;
+            connectors: z.ZodArray<z.ZodString>;
+            contributions: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    mode: z.ZodDefault<z.ZodEnum<{
+        local: "local";
+        live: "live";
+    }>>;
+    checks: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    confirmed: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export interface DoctorInput {
+    context: DoctorContext;
+    mode?: 'local' | 'live';
+    checks?: string[];
+    confirmed?: boolean;
+}
+export declare const doctorReportSchema: z.ZodObject<{
+    id: z.ZodString;
+    state: z.ZodEnum<{
+        running: "running";
+        completed: "completed";
+        cancelled: "cancelled";
+    }>;
+    startedAt: z.ZodString;
+    endedAt: z.ZodNullable<z.ZodString>;
+    mode: z.ZodEnum<{
+        local: "local";
+        live: "live";
+    }>;
+    context: z.ZodObject<{
+        accountId: z.ZodNullable<z.ZodString>;
+        model: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    completed: z.ZodNumber;
+    total: z.ZodNumber;
+    findings: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        category: z.ZodString;
+        title: z.ZodString;
+        status: z.ZodEnum<{
+            disabled: "disabled";
+            warning: "warning";
+            blocked: "blocked";
+            pass: "pass";
+            fail: "fail";
+            unverified: "unverified";
+        }>;
+        verification: z.ZodEnum<{
+            local: "local";
+            live: "live";
+        }>;
+        evidence: z.ZodString;
+        remedy: z.ZodOptional<z.ZodString>;
+        checkedAt: z.ZodString;
+    }, z.core.$strip>>;
+    liveChecks: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        notice: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type DoctorReport = z.infer<typeof doctorReportSchema>;

package/dist/sdk/doctor/types.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+export const findingSchema = z.object({
+    id: z.string(), category: z.string(), title: z.string(),
+    status: z.enum(['pass', 'warning', 'fail', 'disabled', 'blocked', 'unverified']),
+    verification: z.enum(['local', 'live']), evidence: z.string(), remedy: z.string().optional(),
+    checkedAt: z.string()
+});
+export const doctorInputSchema = z.object({
+    context: z.object({
+        caller: z.record(z.string(), z.unknown()).default({}), cwd: z.string().min(1),
+        accountId: z.string().nullable(), model: z.string().nullable(), tools: z.array(z.string()),
+        variant: z.union([
+            z.object({ scope: z.string(), version: z.string().nullable().optional() }),
+            z.object({ dir: z.string(), scope: z.string().nullable().optional() })
+        ]).nullable().optional(),
+        capabilities: z.object({ version: z.literal(1), tools: z.array(z.string()), connectors: z.array(z.string()), contributions: z.array(z.string()) }).optional()
+    }),
+    mode: z.enum(['local', 'live']).default('local'),
+    checks: z.array(z.string()).default([]),
+    /** A trusted host attests that the person approved these exact checks. */
+    confirmed: z.boolean().default(false)
+});
+export const doctorReportSchema = z.object({
+    id: z.string(), state: z.enum(['running', 'completed', 'cancelled']),
+    startedAt: z.string(), endedAt: z.string().nullable(), mode: z.enum(['local', 'live']),
+    context: z.object({ accountId: z.string().nullable(), model: z.string().nullable() }),
+    completed: z.number(), total: z.number(), findings: z.array(findingSchema),
+    liveChecks: z.array(z.object({ id: z.string(), title: z.string(), notice: z.string() }))
+});

package/dist/sdk/harness.d.ts

@@ -0,0 +1,172 @@
+import { Subagents } from "./sessions/subagentService.js";
+import { Accounts } from "./accounts/accounts.js";
+import { Hub, type HubOptions } from "./hub/hub.js";
+import { type SecretStore } from "./accounts/secrets.js";
+import { Bus } from "./core/bus.js";
+import { type Directory, type HarnessEnv } from "./core/env.js";
+import { type LinkOpener } from "./core/links.js";
+import { ConnectedApps } from "./mcp/service.js";
+import type { AppOAuthClients } from "./mcp/types.js";
+import { Lessons } from "./history/lessons.js";
+import type { RefineHost } from "./refine/host.js";
+import { Refinements } from "./refine/service.js";
+import { VariantTrust } from "./variant/trust.js";
+import { World } from "./world/world.js";
+import { Doctor } from "./doctor/service.js";
+import type { Resolver } from "./plugins/discover.js";
+import { Hooks } from "./plugins/hooks.js";
+import { Plugins } from "./plugins/plugins.js";
+import type { PluginDescriptor } from "./plugins/types.js";
+import { Approvals } from "./sessions/approvals.js";
+import type { ToolPolicy } from "./sessions/policy.js";
+import { RunRegistry } from "./sessions/registry.js";
+import type { SessionFactory } from "./sessions/runner.js";
+import { Sessions } from "./sessions/sessions.js";
+import { SideQuestions } from "./sessions/sideQuestions.js";
+import { Terminals, type TerminalAssets } from "./terminal/terminals.js";
+import { Worktrees } from "./worktrees/service.js";
+import { Usage } from "./usage/service.js";
+import { UsageLimits } from "./usage/limits/service.js";
+import { AnnotationCapture } from "./annotations/capture.js";
+import { NoteDeliveries } from "./annotations/delivery.js";
+import type { WorktreesOptions } from "./worktrees/types.js";
+export interface HarnessOptions {
+    /** Disable the generic backend when a host supplies its own browser tools. */
+    browser?: boolean;
+    /** Enables the Brave extension bridge when a host supplies its own isolated browser. */
+    browserExtension?: {
+        port?: number;
+    };
+    hub?: HubOptions;
+    /** Where knowledge and history live. May be set later with `open`. */
+    dataRoot?: string | null;
+    /** Device-local state that never belongs in the data root: accounts, approvals, connections, sockets. */
+    stateDir: string;
+    /**
+     * Where account identity lives: the registry, each account's Pi folder, and the shared settings.
+     * Defaults to `<state dir>/accounts`. A launch that points it at another state's folder signs in
+     * as that state's accounts, so it must pair it with that state's secret store.
+     */
+    accountsDir?: string;
+    /** Where credentials are kept. Defaults to an owner-only file in the state directory. */
+    secrets?: SecretStore;
+    /** How the harness names itself to a model. */
+    productName?: string;
+    directory?: Directory;
+    policy?: ToolPolicy;
+    /** Replaces Pi, for tests. */
+    sessionFactory?: SessionFactory;
+    /** Where refinement executions work and with what; without it, a temporary copy of the task's source and Pi's own tools. */
+    refineHost?: RefineHost;
+    /** Where the built commands a terminal session runs are, when they are not beside this package. */
+    assets?: TerminalAssets;
+    /** @deprecated Ignored. The Harness-owned OpenTUI frontend is the only terminal. */
+    piProgram?: () => string | null;
+    /** Folders of built-in skills, prompts, and rules for the component library, each laid out like `registry/`. */
+    builtins?: string[];
+    /**
+     * The application's own parts, described as plugins: which tools, prompt sections and tool
+     * groups each one provides. Data only; it changes what is listed, never what runs.
+     */
+    plugins?: PluginDescriptor[];
+    /** Replaces Pi's own search for extensions, skills, prompts and themes, for tests. */
+    resolver?: Resolver;
+    /**
+     * The application's own registered OAuth clients, so a connector it publishes needs no client
+     * from the person. Only a catalog entry listed in `ids` can use one, and nothing is stored.
+     */
+    oauthClients?: AppOAuthClients;
+    /** Replaces how a plugin's hooks file is read as a module, for tests. */
+    hookImporter?: (address: string) => Promise<unknown>;
+    /** Where managed worktrees are made, the prefix of branches they get, and how many `prune` keeps. */
+    worktrees?: WorktreesOptions;
+    /** How a link a person clicked reaches the operating system. Defaults to the system's own opener. */
+    linkOpener?: LinkOpener;
+}
+/** What starting on a data root found and repaired. */
+export interface Recovery {
+    interruptedRuns: number;
+    /** The runs marked interrupted, which the application may continue with `continueFrom`. */
+    interruptedRunIds: string[];
+    /** Notes in the Wiki. */
+    reindexedPages: number;
+    /** Where an earlier Wiki's memory, facts and revisions were moved, when they were. */
+    legacyWiki?: string | null;
+    /** Set when the storage migration failed; the old data is left as it was. */
+    migrationError: string | null;
+}
+declare class Env implements HarnessEnv {
+    readonly directory: Directory;
+    readonly productName: string;
+    dataRoot: string | null;
+    readonly bus: Bus;
+    constructor(dataRoot: string | null, directory: Directory, productName: string, bus: Bus);
+    get root(): string;
+}
+export declare class Harness {
+    /** The periodic liveness check, started once with recovery (PROP-0041). */
+    private staleRuns?;
+    private readonly browserEnabled;
+    readonly hub: Hub;
+    readonly bus: Bus;
+    readonly env: Env;
+    readonly stateDir: string;
+    /** The account registry, account Pi folders and their shared settings; usually `<state dir>/accounts`. */
+    readonly accountsDir: string;
+    readonly policy: ToolPolicy;
+    /** How a link a person clicked reaches the operating system (page 10, `links.open`). */
+    readonly linkOpener: LinkOpener;
+    readonly accounts: Accounts;
+    readonly approvals: Approvals;
+    readonly runs: RunRegistry;
+    readonly apps: ConnectedApps;
+    readonly plugins: Plugins;
+    /** Code plugins gave the harness to run after memory, the Wiki or history changed. */
+    readonly hooks: Hooks;
+    /** Every part described as a plugin: the harness's own, then the application's. */
+    descriptors: readonly PluginDescriptor[];
+    applicationPlugins: ReadonlySet<string>;
+    readonly subagents: Subagents;
+    readonly sessions: Sessions;
+    /** Tool-free, run-backed questions over a redacted projection of the main conversation. */
+    readonly sideQuestions: SideQuestions;
+    /** Web, browser and computer tools (page 13). */
+    readonly world: World;
+    /** Which plugin code in variants a person trusted. */
+    readonly trust: VariantTrust;
+    /** Refinement: improving a variant from evidence of how it ran. */
+    readonly refine: Refinements;
+    /** Reflection on finished runs, when the `lessons` plugin is on (page 08). */
+    readonly lessons: Lessons;
+    refineHost: RefineHost | null;
+    readonly terminals: Terminals;
+    readonly doctor: Doctor;
+    /** Usage analytics over the derived ledger, and the provider limits last reported. */
+    readonly usage: Usage;
+    readonly usageLimits: UsageLimits;
+    /** Managed git worktrees sessions can work in (PROP-0016). */
+    readonly worktrees: Worktrees;
+    /** The terminal's visible browser for capturing page notes (PROP-0017). */
+    readonly noteCapture: AnnotationCapture;
+    /** Page notes on their way to a session (PROP-0018). */
+    readonly pageNotes: NoteDeliveries;
+    /** Resolves when what was loaded in the background at construction is in place. */
+    readonly ready: Promise<void>;
+    recovery: Recovery;
+    constructor(options: HarnessOptions);
+    get dataRoot(): string | null;
+    /** Sets the application's own parts, described as plugins. One with a harness plugin's id is ignored. */
+    describe(plugins: readonly PluginDescriptor[]): void;
+    /**
+     * Opens a data root: moves an earlier Wiki's memory and facts aside (once), lays out the Wiki,
+     * settles runs that never ended, and refreshes the history index. `agentIds` is accepted for
+     * hosts written against earlier versions and is not used.
+     */
+    open(dataRoot: string, _agentIds?: readonly string[]): Recovery;
+    /** Rebuilds the history index from the run records. Returns the notes in the Wiki. */
+    rebuildIndex(): number;
+    /** Stops live runs and refinements and releases the index. */
+    close(): Promise<void>;
+}
+export declare function createHarness(options: HarnessOptions): Harness;
+export {};