@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/core/workspaceWriteOperations.d.ts

@@ -0,0 +1,57 @@
+export interface WorkspaceWriteAuthorization {
+    workspaceRoot: string;
+    cwd: string;
+    path: string;
+    outside: boolean;
+    authorized: boolean;
+    expectedContentHash?: string;
+    signal?: AbortSignal;
+}
+export interface AtomicWriteLaunch {
+    executable: string;
+    args: string[];
+    env: NodeJS.ProcessEnv;
+}
+/**
+ * How the atomic write helper starts. macOS and Linux run it inside the write-boundary sandbox.
+ * Windows has none, so Node runs the helper directly; the target was still canonicalized and
+ * authorized, and the rename replaces the directory entry rather than writing through an alias.
+ */
+export declare function atomicWriteLaunch(platform: NodeJS.Platform, root: string, additionalRoots: readonly string[]): AtomicWriteLaunch;
+declare function writeWorkspaceFile(path: string, content: string): Promise<void>;
+export declare const workspaceWriteOperations: {
+    mkdir: (_directory: string) => Promise<void>;
+    writeFile: typeof writeWorkspaceFile;
+};
+export declare const workspaceEditOperations: {
+    access: (path: string) => Promise<void>;
+    readFile: (path: string) => Promise<Buffer>;
+    writeFile: typeof writeWorkspaceFile;
+};
+/** Binds one policy-approved path and abort signal to Pi's native write/edit operation. */
+export declare function withWorkspaceWriteAuthorization<T>(tool: T, authorizations: Map<string, WorkspaceWriteAuthorization>): T;
+interface PromptMetadata {
+    promptSnippet?: string;
+    promptGuidelines?: string[];
+}
+/** The part of Pi's tool factories the workspace file tools use. Structural, so this module needs no Pi import. */
+export interface FileToolFactories<W, E> {
+    createWriteTool(cwd: string, options: {
+        operations: typeof workspaceWriteOperations;
+    }): W;
+    createWriteToolDefinition(cwd: string, options: {
+        operations: typeof workspaceWriteOperations;
+    }): PromptMetadata;
+    createEditTool(cwd: string, options: {
+        operations: typeof workspaceEditOperations;
+    }): E;
+    createEditToolDefinition(cwd: string, options: {
+        operations: typeof workspaceEditOperations;
+    }): PromptMetadata;
+}
+/** Pi's native `write` and `edit`, routed through the workspace operations and per-call authorization. */
+export declare function createWorkspaceFileTools<W, E>(pi: FileToolFactories<W, E>, cwd: string, authorizations: Map<string, WorkspaceWriteAuthorization>): {
+    write: W;
+    edit: E;
+};
+export {};

package/dist/sdk/core/workspaceWriteOperations.js

@@ -0,0 +1,245 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { constants as fsConstants, realpathSync, statSync } from 'node:fs';
+import { access, readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { isWithinWorkspace, resolveWritePath, verifyWorkspaceRoot } from "./workspace.js";
+import { workspaceSandboxCommand } from "./workspaceSandbox.js";
+const writeAuthorization = new AsyncLocalStorage();
+const atomicWriteScript = `
+const fs = require('node:fs')
+const path = require('node:path')
+const crypto = require('node:crypto')
+const input = JSON.parse(fs.readFileSync(0, 'utf8'))
+const target = input.path
+const parent = path.dirname(target)
+fs.mkdirSync(parent, { recursive: true })
+let mode = 0o666
+let preserveMode = false
+try {
+  const existing = fs.lstatSync(target)
+  if (existing.isSymbolicLink() || !existing.isFile()) throw new Error('The write target is not a regular file.')
+  fs.accessSync(target, fs.constants.W_OK)
+  if (input.expectedContentHash) {
+    const current = fs.readFileSync(target)
+    if (crypto.createHash('sha256').update(current).digest('hex') !== input.expectedContentHash) {
+      throw new Error('The file changed after the edit tool read it; retry against the current contents.')
+    }
+  }
+  mode = existing.mode & 0o7777
+  preserveMode = true
+} catch (error) {
+  if (error && error.code !== 'ENOENT') throw error
+}
+const temporary = path.join(parent, '.' + path.basename(target) + '.' + process.pid + '.' + crypto.randomBytes(8).toString('hex') + '.tmp')
+let descriptor
+try {
+  descriptor = fs.openSync(temporary, 'wx', mode)
+  fs.writeFileSync(descriptor, input.content, 'utf8')
+  if (preserveMode) fs.fchmodSync(descriptor, mode)
+  fs.fsyncSync(descriptor)
+  fs.closeSync(descriptor)
+  descriptor = undefined
+  fs.renameSync(temporary, target)
+  try {
+    const directory = fs.openSync(parent, 'r')
+    try { fs.fsyncSync(directory) } finally { fs.closeSync(directory) }
+  } catch {}
+} catch (error) {
+  if (descriptor !== undefined) fs.closeSync(descriptor)
+  try { fs.unlinkSync(temporary) } catch {}
+  throw error
+}
+`;
+/**
+ * How the atomic write helper starts. macOS and Linux run it inside the write-boundary sandbox.
+ * Windows has none, so Node runs the helper directly; the target was still canonicalized and
+ * authorized, and the rename replaces the directory entry rather than writing through an alias.
+ */
+export function atomicWriteLaunch(platform, root, additionalRoots) {
+    if (platform === 'win32') {
+        // Node needs SystemRoot to start on Windows; keep only what the helper requires.
+        const env = {};
+        for (const name of ['SystemRoot', 'windir', 'TEMP', 'TMP', 'USERPROFILE']) {
+            if (process.env[name])
+                env[name] = process.env[name];
+        }
+        return { executable: process.execPath, args: ['-e', atomicWriteScript], env };
+    }
+    const command = `exec ${shellQuote(process.execPath)} -e ${shellQuote(atomicWriteScript)}`;
+    const spec = workspaceSandboxCommand(platform, root, root, command, additionalRoots);
+    return {
+        executable: spec.executable,
+        args: spec.args,
+        env: { PATH: '/usr/bin:/bin', ...(process.env.HOME ? { HOME: process.env.HOME } : {}) }
+    };
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function nearestExistingDirectory(path) {
+    let current = dirname(path);
+    while (true) {
+        try {
+            const canonical = realpathSync(current);
+            if (!statSync(canonical).isDirectory())
+                throw new Error(`Write scope is not a directory: ${canonical}`);
+            return canonical;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            const parent = dirname(current);
+            if (parent === current)
+                throw new Error(`Could not find a writable parent for ${path}.`);
+            current = parent;
+        }
+    }
+}
+function killProcess(child) {
+    if (child.pid && process.platform !== 'win32') {
+        try {
+            process.kill(-child.pid, 'SIGKILL');
+            return;
+        }
+        catch {
+            // Fall back to the direct child if it has already left its process group.
+        }
+    }
+    child.kill('SIGKILL');
+}
+async function runAtomicWrite(authorization, path, content) {
+    const root = verifyWorkspaceRoot(authorization.workspaceRoot);
+    const canonicalPath = resolveWritePath(path, authorization.cwd);
+    if (canonicalPath !== authorization.path)
+        throw new Error('The write target changed after workspace approval; the write was blocked.');
+    const outside = !isWithinWorkspace(root, canonicalPath);
+    if (outside !== authorization.outside || (outside && !authorization.authorized)) {
+        throw new Error('The write authorization no longer matches the active workspace target.');
+    }
+    const additionalRoots = outside ? [nearestExistingDirectory(canonicalPath)] : [];
+    const launch = atomicWriteLaunch(process.platform, root, additionalRoots);
+    await new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(launch.executable, launch.args, {
+            cwd: root,
+            detached: process.platform !== 'win32',
+            env: launch.env,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            windowsHide: true
+        });
+        const output = [];
+        let outputBytes = 0;
+        let settled = false;
+        const timeout = setTimeout(() => {
+            killProcess(child);
+            finish(new Error('Workspace-contained atomic write timed out.'));
+        }, 30_000);
+        const capture = (chunk) => {
+            if (outputBytes >= 8_192)
+                return;
+            const remaining = 8_192 - outputBytes;
+            output.push(chunk.subarray(0, remaining));
+            outputBytes += Math.min(chunk.length, remaining);
+        };
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            authorization.signal?.removeEventListener('abort', abort);
+            if (error)
+                rejectPromise(error);
+            else
+                resolvePromise();
+        };
+        const abort = () => {
+            killProcess(child);
+            finish(new Error('Workspace-contained atomic write was aborted.'));
+        };
+        authorization.signal?.addEventListener('abort', abort, { once: true });
+        if (authorization.signal?.aborted) {
+            abort();
+            return;
+        }
+        child.stdout?.on('data', capture);
+        child.stderr?.on('data', capture);
+        child.once('error', (error) => finish(error));
+        child.once('close', (code) => {
+            if (code === 0) {
+                finish();
+                return;
+            }
+            const detail = Buffer.concat(output).toString('utf8').trim();
+            finish(new Error(`Workspace-contained atomic write failed${detail ? `: ${detail.slice(-2000)}` : ` with exit code ${code ?? 'unknown'}`}.`));
+        });
+        child.stdin?.on('error', () => { });
+        child.stdin?.end(JSON.stringify({
+            path: canonicalPath,
+            content,
+            ...(authorization.expectedContentHash ? { expectedContentHash: authorization.expectedContentHash } : {})
+        }));
+    });
+}
+async function writeWorkspaceFile(path, content) {
+    const authorization = writeAuthorization.getStore();
+    if (!authorization?.authorized)
+        throw new Error('The file write has no current workspace authorization.');
+    await runAtomicWrite(authorization, path, content);
+}
+export const workspaceWriteOperations = {
+    mkdir: async (_directory) => { },
+    writeFile: writeWorkspaceFile
+};
+export const workspaceEditOperations = {
+    access: async (path) => access(path, fsConstants.R_OK | fsConstants.W_OK),
+    readFile: async (path) => {
+        const content = await readFile(path);
+        const authorization = writeAuthorization.getStore();
+        if (authorization && resolve(path) === authorization.path) {
+            authorization.expectedContentHash = createHash('sha256').update(content).digest('hex');
+        }
+        return content;
+    },
+    writeFile: writeWorkspaceFile
+};
+/** Binds one policy-approved path and abort signal to Pi's native write/edit operation. */
+export function withWorkspaceWriteAuthorization(tool, authorizations) {
+    const native = tool;
+    const execute = native.execute.bind(tool);
+    return {
+        ...tool,
+        execute: (...args) => {
+            const toolCallId = String(args[0] ?? '');
+            const authorization = authorizations.get(toolCallId);
+            authorizations.delete(toolCallId);
+            if (!authorization?.authorized)
+                throw new Error('The file write has no current workspace authorization.');
+            const signal = args[2];
+            if (signal && typeof signal === 'object' && 'aborted' in signal)
+                authorization.signal = signal;
+            return writeAuthorization.run(authorization, () => execute(...args));
+        }
+    };
+}
+/**
+ * Pi's `createWriteTool` and `createEditTool` drop the definition's prompt line and guidelines, and Pi
+ * lists only tools with a prompt line in the system prompt. Without them the model is told it has
+ * only `read` and `bash`, and edits files through shell scripts. Pi's `createBashTool` restores them
+ * the same way.
+ */
+function withPromptMetadata(tool, definition) {
+    return Object.assign(tool, {
+        promptSnippet: definition.promptSnippet,
+        promptGuidelines: definition.promptGuidelines
+    });
+}
+/** Pi's native `write` and `edit`, routed through the workspace operations and per-call authorization. */
+export function createWorkspaceFileTools(pi, cwd, authorizations) {
+    const writeOptions = { operations: workspaceWriteOperations };
+    const editOptions = { operations: workspaceEditOperations };
+    return {
+        write: withWorkspaceWriteAuthorization(withPromptMetadata(pi.createWriteTool(cwd, writeOptions), pi.createWriteToolDefinition(cwd, writeOptions)), authorizations),
+        edit: withWorkspaceWriteAuthorization(withPromptMetadata(pi.createEditTool(cwd, editOptions), pi.createEditToolDefinition(cwd, editOptions)), authorizations)
+    };
+}

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

@@ -0,0 +1,5 @@
+import type { Harness } from "../harness.js";
+import { type TerminalAssets } from "../terminal/terminals.js";
+import type { SecretStore } from "../accounts/secrets.js";
+import type { DoctorCheck, DoctorContext } from "./types.js";
+export declare function builtinChecks(harness: Harness, context: DoctorContext, secrets: SecretStore, assets?: TerminalAssets): Promise<DoctorCheck[]>;

package/dist/sdk/doctor/checks.js

@@ -0,0 +1,270 @@
+import { randomUUID } from 'node:crypto';
+import { accessSync, constants, existsSync, readFileSync, statSync } from 'node:fs';
+import { basename, delimiter, isAbsolute, join } from 'node:path';
+import { hostShell, shellLabel } from "../core/shell.js";
+import { createWorkspaceBashOperations, workspaceSandboxBackend } from "../core/workspaceSandbox.js";
+import { resolveWorkspaceRoot } from "../core/workspace.js";
+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 resolvedExecutable(name) {
+    const paths = isAbsolute(name) ? [name] : (process.env.PATH ?? '').split(delimiter).filter(Boolean).map(dir => join(dir, name));
+    for (const path of paths) {
+        try {
+            accessSync(path, constants.X_OK);
+            if (statSync(path).isFile())
+                return path;
+        }
+        catch { /* try the next PATH entry */ }
+    }
+    return null;
+}
+function executable(name) {
+    return resolvedExecutable(name) !== null;
+}
+/** One command written by the harness, not the model: it prints a fixed word and touches nothing. */
+const BASH_PROBE_COMMAND = `printf '%s\\n' harness-doctor`;
+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('computer.capture', 'tools', 'Application window capture', async () => context.tools.includes('computer_screenshot')
+            ? { status: 'unverified', evidence: 'A computer screenshot tool is listed for this session; its backend and window isolation were not tested.', remedy: 'Check the provider and approve an application window before capture.' }
+            : { status: 'blocked', evidence: 'No computer screenshot tool is listed for this session. An application window cannot be read through this capability.', remedy: 'Use a host with an approved-window capture backend.' }),
+        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 () => {
+                if (process.platform === 'win32') {
+                    const shell = hostShell();
+                    if (!shell)
+                        return fail('Neither Git Bash nor PowerShell was found.', 'Install Git for Windows, or restore Windows PowerShell.');
+                    return { status: 'warning', evidence: `Commands run in ${shellLabel(shell)} at ${shell.executable}. Windows has no workspace write-boundary sandbox, so each command asks for approval unless Full Permission is on, and plan mode cannot run commands. No shell command was run.`, remedy: 'Approve each command when asked, or turn on Full Permission for this session.' };
+                }
+                const shell = resolvedExecutable('bash');
+                if (!shell)
+                    return fail('Bash was not found on the inherited PATH.', 'Verify the shell executable used by Pi.');
+                // Bash runs inside the platform's write-boundary sandbox; without that backend every call
+                // fails before the command starts, so presence of bash alone is not readiness.
+                const backend = workspaceSandboxBackend(process.platform);
+                return backend
+                    ? pass(`Bash is executable at ${shell}, and the ${basename(backend)} workspace write-boundary sandbox it runs inside is present. No shell command was run.`)
+                    : fail(`Bash is executable at ${shell}, but the workspace write-boundary sandbox this platform needs is missing, so every Bash call fails before it runs.`, process.platform === 'linux' ? 'Install bubblewrap (bwrap) so Bash can run inside the workspace boundary.' : 'Restore the platform sandbox executable so Bash can run inside the workspace boundary.');
+            }),
+            tools: ['bash'],
+            live: {
+                notice: 'Run one fixed command written by the harness (printf) in the working folder, inside the same workspace write-boundary sandbox as a normal Bash call. No model input, no network request, no file written; only the exit status is reported.',
+                run: async (probe) => {
+                    if (process.platform === 'win32')
+                        return { status: 'unverified', evidence: 'On Windows every command needs a person to approve it, so the diagnostic does not run one.' };
+                    const refusal = await harness.sessions.diagnosticGate(probe.run, context.caller).check('bash', { command: BASH_PROBE_COMMAND });
+                    if (refusal)
+                        return { status: 'blocked', evidence: `The tool policy refused the diagnostic command: ${refusal}`, remedy: 'Review what the policy allows Bash to do in this session.' };
+                    const toolCallId = randomUUID();
+                    probe.run.emit('tool.started', { toolCallId, name: 'bash', summary: 'Synthetic diagnostic command' });
+                    let output = '';
+                    try {
+                        // The same root, boundary, hard-link scan and sandbox a real Bash call takes. A
+                        // diagnostic never widens that boundary, so Full Permission cannot change this result.
+                        const workspaceRoot = resolveWorkspaceRoot(context.cwd);
+                        const { exitCode } = await createWorkspaceBashOperations(workspaceRoot).exec(BASH_PROBE_COMMAND, workspaceRoot, {
+                            onData: chunk => { if (output.length < 400)
+                                output += chunk.toString('utf8'); },
+                            signal: probe.signal,
+                            timeout: 20
+                        });
+                        probe.run.emit('tool.completed', { toolCallId, name: 'bash', ok: exitCode === 0 });
+                        return exitCode === 0 && output.includes('harness-doctor')
+                            ? pass('A real command ran in the working folder through the workspace sandbox and returned exit status 0 with the expected output.')
+                            : fail(`The shell returned exit status ${exitCode ?? 'unknown'} for the diagnostic command.`, 'Review the shell executable, the workspace write-boundary sandbox and the working folder permissions.');
+                    }
+                    catch (error) {
+                        probe.run.emit('tool.completed', { toolCallId, name: 'bash', ok: false });
+                        return {
+                            status: 'blocked',
+                            evidence: `The command could not start in this working folder, so the shell itself was not exercised: ${error instanceof Error ? error.message : String(error)}`,
+                            remedy: 'Resolve what stops Bash before it runs (a hard-link alias in the workspace, a missing sandbox backend, or a redirected workspace root), or choose another working folder.'
+                        };
+                    }
+                }
+            }
+        },
+        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>;