@xingular/harness 0.1.7 → 1.1.1

package/dist/sdk/doctor/checks.js

@@ -0,0 +1,208 @@
+import { accessSync, constants, existsSync, readFileSync, statSync } from 'node:fs';
+import { delimiter, isAbsolute, join } from 'node:path';
+import { defaultAssets } from "../terminal/terminals.js";
+import { loadPi, PINNED_PI_VERSION } from "../pi/runtime.js";
+import { list as listPlugins } from "../plugins/api.js";
+import { compile } from "../prompt/compile.js";
+import { materialise } from "../variant/materialise.js";
+import { validate } from "../variant/variant.js";
+import { PI_SURFACE } from "../variant/surface.js";
+import { allowed } from "../mcp/connections.js";
+import { BRAVE, TAVILY, EXA } from "../web/search.js";
+import { KEYLESS_SEARCH, WEB_PLUGIN } from "../web/tools.js";
+const pass = (evidence) => ({ status: 'pass', evidence });
+const fail = (evidence, remedy) => ({ status: 'fail', evidence, remedy });
+function executable(name) {
+    const paths = isAbsolute(name) ? [name] : (process.env.PATH ?? '').split(delimiter).filter(Boolean).map(dir => join(dir, name));
+    return paths.some(path => {
+        try {
+            accessSync(path, constants.X_OK);
+            return statSync(path).isFile();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+export async function builtinChecks(harness, context, secrets, assets = defaultAssets()) {
+    const check = (id, category, title, local) => ({ id, category, title, local });
+    const account = () => context.accountId ? harness.accounts.find(context.accountId) : null;
+    const checks = [
+        check('account', 'account', 'Selected account', async (signal) => {
+            const selected = account();
+            if (!selected)
+                return fail('No account is selected.', 'Choose an account with /accounts.');
+            const saved = harness.accounts.overview().accounts.find(item => item.id === selected.id);
+            const inspected = await harness.accounts.inspect(selected.id, signal);
+            if (!inspected.credentials)
+                return fail('The pinned account has no saved provider credentials.', 'Sign in or add a key in /accounts.');
+            return { status: saved.state.health === 'ok' || saved.state.health === 'unknown' ? 'pass' : 'warning', evidence: `Credentials are configured. Saved health: ${saved.state.health}; checked ${saved.state.lastCheckedAt ?? 'never'}. ${saved.state.limits.map(limit => `${limit.label || limit.id}: ${limit.usedPercent}% used; resets ${limit.resetsAt ?? 'unknown'}`).join('; ')} ${saved.state.lastError ? `Saved issue: ${saved.state.lastError.category}.` : ''} This does not verify authentication with the provider.`, remedy: saved.state.health === 'ok' ? undefined : 'Use the model live probe to verify current provider access.' };
+        }),
+        check('accounts.inventory', 'account', 'Other saved accounts', async () => {
+            const others = harness.accounts.overview().accounts.filter(item => item.id !== context.accountId);
+            return pass(others.length ? others.map(item => `${item.label}: ${item.state.health}; checked ${item.state.lastCheckedAt ?? 'never'}`).join('\n') : 'No other saved accounts.');
+        }),
+        {
+            ...check('model', 'account', 'Selected model', async (signal) => {
+                if (!context.accountId || !context.model)
+                    return fail('No account/model is selected.', 'Choose an account and /model.');
+                const model = (await harness.accounts.inspect(context.accountId, signal)).models.find(item => item.id === context.model);
+                return model ? pass(`${model.id} is available locally; images: ${model.supportsImages}; reasoning: ${model.reasoning}. Provider access is unverified.`) : fail('The selected model is absent from the account model catalogue.', 'Choose an available model with /model.');
+            }),
+            live: {
+                notice: 'One provider request on the selected account/model, up to 64 output tokens; charges may apply. Only synthetic diagnostic content is sent.',
+                run: async ({ signal, run }) => {
+                    const selected = account();
+                    if (!selected || !context.model)
+                        return fail('No account/model is selected.', 'Choose an account and /model.');
+                    const runtime = await harness.accounts.runtime(selected);
+                    const model = (await runtime.getAvailable()).find(item => `${item.provider}/${item.id}` === context.model);
+                    if (!model)
+                        return fail('The selected model is unavailable.', 'Choose an available model with /model.');
+                    signal.throwIfAborted();
+                    const result = await runtime.completeSimple(model, { messages: [{ role: 'user', content: 'Reply with OK.', timestamp: Date.now() }] }, { maxTokens: 64, signal });
+                    const usage = result.usage;
+                    run.emit('usage.updated', {
+                        inputTokens: usage.input, outputTokens: usage.output, cacheReadTokens: usage.cacheRead, cacheWriteTokens: usage.cacheWrite,
+                        costUsd: usage.cost.total, costSource: 'harness', requests: 1, model: result.model, provider: result.provider,
+                        request: { index: 1, model: result.model, provider: result.provider, stopReason: result.stopReason }
+                    });
+                    return result.stopReason === 'error' || result.stopReason === 'aborted'
+                        ? fail(`The provider request ended with ${result.stopReason}.`, 'Review account authentication, limits, and model configuration.')
+                        : pass('The selected provider/model completed a real request. Usage is recorded on the diagnostic run.');
+                }
+            }
+        },
+        check('runtime.pi', 'runtime', 'Pi runtime', async () => { await loadPi(); return pass(`Pi ${PINNED_PI_VERSION} loaded with its required dispatcher.`); }),
+        check('runtime.launcher', 'runtime', 'Terminal launcher', async () => {
+            if (!executable(assets.node))
+                return fail('The configured Node executable cannot be accessed.', 'Check the host launch configuration.');
+            return executable(process.env.XINGULAR_HARNESS_BUN || 'bun')
+                ? pass('Node and Bun executables are accessible. No process was launched for this check.')
+                : { status: 'warning', evidence: 'Bun was not found on the inherited PATH or at XINGULAR_HARNESS_BUN. The terminal launcher may resolve an additional login-shell path.', remedy: 'Verify the terminal Bun launch path.' };
+        }),
+        {
+            ...check('native.files', 'tools', 'Native file tools', async () => {
+                accessSync(context.cwd, constants.R_OK);
+                if (context.tools.some(name => name === 'write' || name === 'edit')) {
+                    try {
+                        accessSync(context.cwd, constants.W_OK);
+                    }
+                    catch {
+                        return { status: 'blocked', evidence: 'The working directory is readable but not writable.', remedy: 'Choose a writable working directory for edits.' };
+                    }
+                }
+                return pass('The working directory is accessible for enabled native file tools. Per-call policy and actual file operations are unverified.');
+            }), tools: ['read', 'grep', 'find', 'ls', 'write', 'edit']
+        },
+        {
+            ...check('native.bash', 'tools', 'Native shell tool', async () => process.platform === 'win32'
+                ? { status: 'unverified', evidence: 'Windows shell resolution is delegated to Pi; no shell was launched.' }
+                : executable('bash') ? pass('Bash is executable on the inherited PATH. No shell command was run.') : fail('Bash was not found on the inherited PATH.', 'Verify the shell executable used by Pi.')),
+            tools: ['bash']
+        },
+        check('runtime.storage', 'runtime', 'State and data storage', async () => {
+            accessSync(harness.stateDir, constants.R_OK | constants.W_OK);
+            if (!harness.dataRoot)
+                return fail('No data root is open.', 'Open a data location before starting runs.');
+            accessSync(harness.dataRoot, constants.R_OK | constants.W_OK);
+            accessSync(context.cwd, constants.R_OK);
+            return pass('State/data directories are accessible and the working directory is readable. Write access is checked without writing files.');
+        }),
+        check('runtime.assets', 'runtime', 'Terminal assets', async () => {
+            const files = [assets.cli, assets.openTui, assets.piExtension];
+            const missing = files.filter(file => !existsSync(file));
+            return missing.length ? { status: 'warning', evidence: `Configured terminal assets are missing: ${missing.join(', ')}.`, remedy: 'Build the Harness or verify the host-supplied assets.' } : pass('Configured terminal assets are present.');
+        }),
+        check('runtime.recovery', 'runtime', 'Startup recovery', async () => harness.recovery.migrationError
+            ? fail('Startup recorded a storage migration error.', 'Review the recovery diagnostics before starting work.')
+            : { status: harness.recovery.interruptedRuns ? 'warning' : 'pass', evidence: `${harness.recovery.interruptedRuns} interrupted runs recovered; no recorded migration error.` }),
+        check('variant', 'variant', 'Pinned variant and prompt', async () => {
+            if (!harness.dataRoot)
+                return { status: 'blocked', evidence: 'Variant and prompt inspection needs an open data root.', remedy: 'Open a data location.' };
+            if (!context.variant) {
+                compile(harness.env, context.caller, {});
+                return pass('No variant is selected; the foundation prompt compiles.');
+            }
+            const variant = materialise(harness.env.root, context.variant, { trust: harness.trust });
+            validate(PI_SURFACE, variant.files);
+            compile(harness.env, context.caller, { tools: [...context.tools] }, variant);
+            return { status: variant.untrustedPlugins.length ? 'warning' : 'pass', evidence: `Variant ${variant.fingerprint} validates and its prompt compiles; ${variant.untrustedPlugins.length} code resources withheld for trust.` };
+        }),
+        check('plugins', 'plugins', 'Plugins, skills and resources', async () => {
+            if (!harness.dataRoot)
+                return { status: 'blocked', evidence: 'Plugin inspection needs an open data root.', remedy: 'Open a data location.' };
+            const plugins = await listPlugins(harness, { ...context.caller, cwd: context.cwd, accountId: context.accountId });
+            const contributions = plugins.flatMap(plugin => plugin.contributions);
+            const problems = [];
+            for (const item of contributions.filter(item => item.state === 'on')) {
+                if (item.problem)
+                    problems.push(`${item.name}: recorded resource error`);
+                if (item.path) {
+                    try {
+                        accessSync(item.path, constants.R_OK);
+                        if (item.kind === 'skill')
+                            readFileSync(item.path, 'utf8');
+                    }
+                    catch {
+                        problems.push(`${item.name}: resource cannot be read`);
+                    }
+                }
+            }
+            const names = contributions.filter(item => item.kind === 'tool' && item.state === 'on').map(item => item.name);
+            const duplicates = [...new Set(names.filter((name, index) => names.indexOf(name) !== index))];
+            if (duplicates.length)
+                problems.push(`Overlapping tool contributions: ${duplicates.join(', ')}`);
+            const withheld = contributions.filter(item => item.state === 'untrusted').length;
+            return problems.length ? fail(problems.join('\n'), 'Review /plugins and the resource configuration.') : { status: withheld ? 'warning' : 'pass', evidence: `${plugins.length} plugins inspected; ${withheld} untrusted resources withheld. No plugin code was executed for diagnostics. Transitive dependencies are unverified until loaded normally.` };
+        })
+    ];
+    const providers = [BRAVE, TAVILY, EXA];
+    checks.push({
+        ...check('web.search', 'web', 'Web search', async () => {
+            const configured = (await Promise.all(providers.map(async (provider) => await secrets.get(provider.key) ? provider.title : null))).filter(Boolean);
+            const keyless = harness.dataRoot !== null && harness.world.setting(WEB_PLUGIN.id, KEYLESS_SEARCH) === 1;
+            return configured.length || keyless ? pass(`Configured: ${[...configured, ...(keyless ? ['DuckDuckGo (keyless)'] : [])].join(', ')}. Keys have not been authenticated.`) : fail('No search provider key is saved and keyless search is disabled.', 'Configure Web in /plugins.');
+        }), tools: ['web_search'],
+        live: { notice: 'Search the public web for “example domain” through configured Brave, Tavily, Exa, or DuckDuckGo endpoints; search API charges may apply.', run: async (probe) => {
+                const result = await probe.call('web_search', { queries: ['example domain'] });
+                const details = typeof result === 'string' ? undefined : result.details;
+                return details?.provider && Array.isArray(details.sources) && details.sources.length ? pass(`Search completed through ${String(details.provider)}.`) : fail('Search did not return verified results.', 'Review configured search providers and limits.');
+            } }
+    });
+    checks.push({
+        ...check('web.fetch', 'web', 'Public web fetch', async () => pass('Checked public HTTP reader is installed; network access is unverified.')),
+        tools: ['web_fetch'], live: { notice: 'Fetch https://example.com/ through the enabled web_fetch tool.', run: async (probe) => {
+                const result = await probe.call('web_fetch', { url: 'https://example.com/' });
+                return typeof result !== 'string' && result.details?.status === 200 ? pass('The public page returned HTTP 200 and readable text.') : fail('The public page could not be read.', 'Check network access and retry.');
+            } }
+    });
+    for (const connection of harness.dataRoot ? harness.apps.connections.list() : []) {
+        const inScope = allowed(connection, context.caller) && (!context.capabilities || context.capabilities.connectors.includes(connection.id));
+        checks.push({
+            ...check(`mcp.${connection.id}`, 'mcp', `MCP: ${connection.name}`, async () => {
+                if (!connection.enabled)
+                    return { status: 'disabled', evidence: 'The connection is disabled.' };
+                if (!inScope)
+                    return { status: 'blocked', evidence: 'The connection is outside this diagnostic scope.' };
+                if (connection.auth === 'oauth' && connection.authState !== 'signed_in')
+                    return { status: 'warning', evidence: `Saved authentication state: ${connection.authState ?? 'unknown'}.`, remedy: 'Check connector authentication in the host.' };
+                return { status: connection.error ? 'warning' : 'pass', evidence: `Configured; last checked ${connection.checkedAt ?? 'never'}; ${connection.tools.length} cached tools. Live connectivity is unverified.` };
+            }),
+            tools: ['mcp_list_tools'],
+            live: { notice: `Connect to configured MCP server “${connection.name}” and list its tools. A configured local server process may start. No connector tools are invoked.`, run: async (probe) => {
+                    if (!connection.enabled || !inScope)
+                        return { status: 'blocked', evidence: 'This connection is disabled or outside the selected scope.' };
+                    const result = await probe.call('mcp_list_tools', { connectionId: connection.id });
+                    const details = typeof result === 'string' ? undefined : result.details;
+                    return details?.doctorOk === true ? pass(`${String(details.toolCount)} tools listed.`) : fail('The MCP server could not list tools.', 'Review its transport, authentication, and scope.');
+                } }
+        });
+    }
+    // A tool without diagnostics is present in the report without claiming its backend works.
+    const supplied = await harness.sessions.diagnostics(context);
+    const covered = new Set([...checks, ...supplied].flatMap(item => item.tools ?? []));
+    for (const tool of context.tools.filter(tool => !covered.has(tool)))
+        checks.push(check(`tool.${tool}`, 'tools', tool, async () => ({ status: 'unverified', evidence: 'Enabled in this session; this provider has no readiness check.', remedy: 'Use the tool normally or add provider diagnostics.' })));
+    return [...checks, ...supplied];
+}

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

@@ -0,0 +1,4 @@
+import type { Harness } from "../harness.js";
+import type { DoctorContext, DoctorProbeContext } from "./types.js";
+/** A real, tool-only diagnostic run. Model requests, if selected, use Pi's account runtime. */
+export declare function diagnosticProbe<T>(harness: Harness, context: DoctorContext, inputSignal: AbortSignal, action: (probe: DoctorProbeContext) => Promise<T>): Promise<T>;

package/dist/sdk/doctor/probe.js

@@ -0,0 +1,92 @@
+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'); 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 refusal = await gate.check(name, input);
+                if (refusal)
+                    throw new HarnessError('doctor_blocked', 'The tool policy refused this diagnostic call.');
+                signal.throwIfAborted();
+                const callId = randomUUID();
+                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.' });
+        throw error;
+    }
+    finally {
+        signal.removeEventListener('abort', abort);
+        run.finish(signal.aborted ? 'interrupted' : 'completed');
+        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";
+        pass: "pass";
+        fail: "fail";
+        blocked: "blocked";
+        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";
+            pass: "pass";
+            fail: "fail";
+            blocked: "blocked";
+            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>;