@zergai/ztc 0.4.0-beta.1 → 0.5.0-beta.1

package/dist/mcp/client.js

@@ -1,6 +1,7 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+export const MAX_MCP_IMAGE_BYTES = 4 * 1024 * 1024;
 const CLIENT_INFO = { name: 'ztc', version: '0.1.0' };
 // Connection-independent state and accessors live in registry.ts (so light
 // consumers avoid the SDK import); re-export them to preserve this module's
@@ -71,6 +72,25 @@ function adaptTool(client, serverName, mcpTool) {
             // isError tool result the LLM can see and react to.
             if (result.isError)
                 throw new Error(text || `MCP tool "${mcpTool.name}" failed`);
+            const images = blocks.filter(block => block.type === 'image');
+            if (images.length > 1)
+                throw new Error(`MCP tool "${mcpTool.name}" returned more than one image; request separate image reads`);
+            if (images.length === 1) {
+                const image = images[0];
+                if (!['image/png', 'image/jpeg', 'image/webp', 'image/gif'].includes(image.mimeType ?? ''))
+                    throw new Error(`Unsupported MCP image MIME: ${image.mimeType ?? '(missing)'}`);
+                if (typeof image.data === 'string') {
+                    const padding = image.data.endsWith('==') ? 2 : image.data.endsWith('=') ? 1 : 0;
+                    if (Math.floor(image.data.length / 4) * 3 - padding > MAX_MCP_IMAGE_BYTES) {
+                        throw new Error(`MCP image exceeds ${MAX_MCP_IMAGE_BYTES} bytes; request a smaller raster image`);
+                    }
+                }
+                if (typeof image.data !== 'string' || !image.data.length || image.data.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(image.data) || Buffer.from(image.data, 'base64').toString('base64') !== image.data)
+                    throw new Error('MCP image data must be nonempty canonical base64');
+                // The persisted image envelope is already force-inline and replayed as
+                // actual provider image blocks by the request encoder and session store.
+                return JSON.stringify({ type: 'image', mediaType: image.mimeType, data: image.data, description: text || `Image from MCP tool "${mcpTool.name}"` });
+            }
             return text || '(no output)';
         },
     };

package/dist/modes/builtin/plan.yaml

@@ -83,7 +83,7 @@ system_prompt: |
     - Verification criteria
 
   When your plan is complete, tell the user to run /execute to begin implementation.
-  The plan will be converted to a task list that tracks progress.
+  After approval, implement the plan, run its verification commands, and summarize the result.
 
 artifact:
   enabled: true
@@ -119,4 +119,4 @@ messages:
     - /execute: Approve the plan and begin implementation
 
   on_exit: |
-    Exiting plan mode.
+    Plan mode off.

package/dist/modes/handlers.js

@@ -148,7 +148,7 @@ export const planExecuteHandler = async (args, context) => {
 Plan: ${artifactPath}
 Tasks extracted: ${tasks.length}
 
-${tasks.length > 0 ? 'Tasks have been added to the todo list.' : 'No tasks found in Implementation Steps section.'}
+${tasks.length > 0 ? 'Implementation steps are included in the plan below.' : 'No tasks found in Implementation Steps section.'}
 
 The agent will now implement the plan.`,
     });

package/dist/onboarding/first_run.d.ts

@@ -1,4 +1,5 @@
 import type { GitWorkingTreeStatus } from '../runtime_info.js';
+import { type TaskHandoffSnapshot } from '../session_handoff_contract.js';
 export declare const FIRST_RUN_MESSAGE_METADATA: {
     readonly ephemeral: true;
     readonly onboarding: "first-run";
@@ -68,6 +69,8 @@ export declare function createFirstRunLaunchMessage(content: string): FirstRunLa
 export declare function excludePrintedFirstRunWelcome<T extends FirstRunMessageLike>(messages: readonly T[], printedIds: ReadonlySet<string>): T[];
 export declare function shouldDeferFirstRunScrollback(message: FirstRunMessageLike, messageCount: number): boolean;
 export declare function buildCredentialSetupMessage(): string;
+/** Keep the paste target separate from the historical checkpoint details. */
+export declare function buildSavedSessionNotice(snapshot: TaskHandoffSnapshot, profile: string): string;
 export declare function buildNoCredentialsWelcome(options?: Pick<FirstRunWelcomeOptions, 'mode'>): string;
 export declare function buildReadyWelcome(options?: FirstRunWelcomeOptions): string;
 export declare function buildResumedWelcome(options: ResumedWelcomeOptions): string;

package/dist/onboarding/first_run.js

@@ -1,4 +1,5 @@
 import { displayWidth, sanitizeTerminalText } from '../ui/core/text_width.js';
+import { formatTaskHandoffContext, projectTaskHandoff } from '../session_handoff_contract.js';
 const WELCOME_TITLE = 'Welcome to ZTC - Zerg Terminal Client.';
 const FIRST_RUN_MESSAGE_KIND = 'first-run';
 const READOUT_CONTENT_WIDTH = 76;
@@ -125,8 +126,12 @@ function formatProjectLine(options) {
     return parts.join(' · ');
 }
 function formatRuntimeLine(options) {
+    const providerId = singleLine(options.provider);
+    const modelId = singleLine(options.model);
+    const displayModel = providerId && modelId.startsWith(`${providerId}/`)
+        ? modelId.slice(providerId.length + 1) : modelId;
     const provider = compact(options.provider, 12) || 'not configured';
-    const model = compact(options.model, 24) || 'default';
+    const model = compact(displayModel, 24) || 'default';
     const version = compact(options.version, 12);
     return `Runtime: ${provider}/${model}${version ? ` · ZTC v${version}` : ''}`;
 }
@@ -211,37 +216,39 @@ export function shouldDeferFirstRunScrollback(message, messageCount) {
 export function buildCredentialSetupMessage() {
     return [
         '⚠️  No API credentials configured.',
-        'Authenticate with one of these routes:',
+        'Set up ZTC: /setup',
         '  1. Zerg account: /auth login',
+        '     Complete signup/email verification; then /auth readiness.',
+        '     Fund personal pay-as-you-go with /auth billing; review pricing and caps.',
         '  2. Claude Code: run `claude setup-token`, export CLAUDE_CODE_OAUTH_TOKEN, then /config provider claude_code',
         '  3. Provider API key: /config key <api-key>',
         'You can also set the provider-specific API key environment variable.',
     ].join('\n');
 }
-export function buildNoCredentialsWelcome(options = {}) {
-    if (isPlanMode(options.mode)) {
-        return [
-            WELCOME_TITLE,
-            [
-                '⚠️  No credentials yet. Choose one:',
-                '  1. Zerg account: /auth login',
-                '  2. Claude Code: claude setup-token, then /config provider claude_code',
-                '  3. Provider key: /config key <api-key>',
-            ].join('\n'),
-            'Plan mode is active. Authenticate, then describe what to inspect.',
-        ].join('\n\n');
-    }
+/** Keep the paste target separate from the historical checkpoint details. */
+export function buildSavedSessionNotice(snapshot, profile) {
+    const handoff = projectTaskHandoff(snapshot);
+    const quote = (value) => `'${value.replace(/'/g, "'\\''")}'`;
+    const command = `${handoff.resumeCommand} --cwd ${quote(handoff.snapshot.source.cwd)} --profile ${quote(profile)}`;
     return [
-        WELCOME_TITLE,
-        [
-            '⚠️  No credentials yet. Choose one:',
-            '  1. Zerg account: /auth login',
-            '  2. Claude Code: claude setup-token, then /config provider claude_code',
-            '  3. Provider key: /config key <api-key>',
-        ].join('\n'),
-        formatFirstRunWorkflows(),
-        'Use /help for every command.',
-    ].join('\n\n');
+        'Saved project work is available.',
+        'Paste into your terminal to resume:',
+        command,
+        '',
+        formatTaskHandoffContext(handoff.snapshot),
+    ].join('\n');
+}
+export function buildNoCredentialsWelcome(options = {}) {
+    const credentials = [
+        '⚠️  No credentials yet. Set up ZTC: /setup',
+        '  1. Zerg account: /auth login (finish email verification in the browser)',
+        '     Funding: /auth readiness · Pay-as-you-go and caps: /auth billing',
+        '  2. Claude Code: claude setup-token, then /config provider claude_code',
+        '  3. Provider key: /config key <api-key>',
+    ].join('\n');
+    return [WELCOME_TITLE, credentials, isPlanMode(options.mode)
+            ? 'Plan mode is active. Authenticate, then describe what to inspect.'
+            : formatFirstRunWorkflows(), ...(isPlanMode(options.mode) ? [] : ['Use /help for every command.'])].join('\n\n');
 }
 export function buildReadyWelcome(options = {}) {
     const permissionProfile = compact(options.permissionProfile, 20) || 'trusted';
@@ -289,6 +296,7 @@ export function buildResumedWelcome(options) {
         planMode && context ? `Context: ${context}` : undefined,
         formatRuntimeLine(options),
         formatIdentityLine(options),
+        credentialsReady ? undefined : 'Set up ZTC: /setup',
         credentialsReady
             ? undefined
             : 'Authentication: required · /auth login or /config key <api-key>',

package/dist/onboarding/setup.d.ts

@@ -0,0 +1,32 @@
+import type { ConfigController } from '../agent/commands/types.js';
+import { type SetupAgentProbeResult } from './setup_agent_health.js';
+import { type SetupCheckStatus, type SetupEnvironmentReport, type SetupInstallAttempt } from './setup_environment.js';
+import { type SetupWorkspaceResult } from './setup_workspace.js';
+export interface SetupStepResult {
+    id: 'configuration' | 'workspace' | 'shell' | 'agent';
+    status: SetupCheckStatus;
+    detail: string;
+}
+export interface SetupReport {
+    status: 'ready' | 'needs_auth' | 'blocked' | 'cancelled';
+    environment?: SetupEnvironmentReport;
+    installations: SetupInstallAttempt[];
+    steps: SetupStepResult[];
+    workspace?: SetupWorkspaceResult;
+    agent?: SetupAgentProbeResult;
+}
+export interface CompleteSetupOptions {
+    config: ConfigController;
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+    signal?: AbortSignal;
+    workspaceRoot?: string;
+    agentTimeoutMs?: number;
+    /** Requires an explicit human confirmation in the command UI. May use paid quota. */
+    checkAgent?: boolean;
+    onProgress?: (message: string) => void;
+}
+/** One setup action over existing runtime, accounts and canonical sessions. */
+export declare function completeSetup(options: CompleteSetupOptions): Promise<SetupReport>;
+/** A bounded success/failure readout, including optional tools and next actions. */
+export declare function formatSetupReport(report: SetupReport): string;

package/dist/onboarding/setup.js

@@ -0,0 +1,133 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { profileConfigDir } from '../config/profiles.js';
+import { loadDesktopRuntime } from '../desktop/runtime.js';
+import { probeSetupAgent } from './setup_agent_health.js';
+import { inspectSetupEnvironment, installMissingSetupTools, runSetupShellHealth, } from './setup_environment.js';
+import { ensureSetupWorkspace } from './setup_workspace.js';
+import { sanitizeTerminalText } from '../ui/core/text_width.js';
+/** Existing configuration bytes are kept; a fresh config must survive a real read. */
+async function ensureConfiguration(config) {
+    const path = join(profileConfigDir(), 'config.json');
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        await config.save();
+        // ConfigStore.save logs failures rather than rejecting: do not treat its
+        // return as evidence that defaults were persisted.
+        text = await readFile(path, 'utf8');
+    }
+    const saved = JSON.parse(text);
+    if (typeof saved !== 'object' || saved === null || Array.isArray(saved)) {
+        throw new Error('Saved configuration is not a configuration object.');
+    }
+}
+function cancelled(options) {
+    return options.signal?.aborted === true;
+}
+/** One setup action over existing runtime, accounts and canonical sessions. */
+export async function completeSetup(options) {
+    const report = { status: 'blocked', installations: [], steps: [] };
+    if (cancelled(options))
+        return { ...report, status: 'cancelled' };
+    let runtimeKind;
+    try {
+        runtimeKind = loadDesktopRuntime() ? 'bundled' : 'host';
+    }
+    catch {
+        report.steps.push({ id: 'configuration', status: 'failed', detail: 'The bundled runtime could not be validated. Restart the matching app bundle or reinstall it, then run /setup.' });
+        return report;
+    }
+    const inspection = { cwd: options.cwd, env: options.env, signal: options.signal, runtimeKind };
+    options.onProgress?.('Checking the running Node, shell, tools and GitHub sign-in…');
+    report.environment = await inspectSetupEnvironment(inspection);
+    if (cancelled(options))
+        return { ...report, status: 'cancelled' };
+    const missing = report.environment.checks.filter(check => (check.id === 'git' || check.id === 'rg') && check.status === 'missing')
+        .map(check => check.id);
+    if (missing.length && report.environment.packageManager.status === 'ready') {
+        options.onProgress?.(`Installing missing ${missing.map(tool => tool === 'rg' ? 'ripgrep' : 'Git').join(' and ')} using the detected package manager…`);
+        const installed = await installMissingSetupTools({ ...inspection, tools: missing });
+        report.installations = installed.attempts;
+        report.environment = installed.after;
+    }
+    if (cancelled(options))
+        return { ...report, status: 'cancelled' };
+    if (!report.environment.ready)
+        return report;
+    try {
+        await ensureConfiguration(options.config);
+        report.steps.push({ id: 'configuration', status: 'ready', detail: 'Existing account, model and configuration are preserved; configuration storage is readable.' });
+    }
+    catch {
+        report.steps.push({ id: 'configuration', status: 'failed', detail: 'Configuration could not be persisted or read. Check the active profile’s config.json and storage permissions, preserve existing data, then run /setup.' });
+        return report;
+    }
+    const llm = options.config.resolveLLMBackendConfig();
+    try {
+        report.workspace = await ensureSetupWorkspace({ workspaceRoot: options.workspaceRoot, provider: llm.provider, model: llm.model, signal: options.signal });
+        report.steps.push({ id: 'workspace', status: 'ready', detail: report.workspace.created ? 'Sample workspace and canonical session created.' : 'Existing sample workspace, edits and canonical session preserved.' });
+    }
+    catch {
+        report.steps.push({ id: 'workspace', status: cancelled(options) ? 'cancelled' : 'failed', detail: 'The sample workspace could not be created or verified. Preserve existing files, check the getting-started directory and session-storage permissions, then run /setup.' });
+        if (cancelled(options))
+            report.status = 'cancelled';
+        return report;
+    }
+    const shell = await runSetupShellHealth({ ...inspection, cwd: report.workspace.path });
+    report.steps.push({ id: 'shell', status: shell.status, detail: shell.detail });
+    if (cancelled(options))
+        return { ...report, status: 'cancelled' };
+    if (shell.status !== 'ready')
+        return report;
+    if (!options.checkAgent) {
+        report.status = 'ready';
+        return report;
+    }
+    options.onProgress?.('Checking the selected account and model with one short, isolated agent request…');
+    report.agent = await probeSetupAgent({
+        config: options.config.get(), provider: llm.provider, model: llm.model,
+        cwd: report.workspace.path, signal: options.signal, timeoutMs: options.agentTimeoutMs,
+    });
+    report.steps.push({ id: 'agent', status: report.agent.status, detail: report.agent.detail });
+    report.status = cancelled(options) ? 'cancelled'
+        : report.agent.status === 'ready' ? 'ready'
+            : report.agent.status === 'missing' ? 'needs_auth' : 'blocked';
+    return report;
+}
+function safeLine(value) {
+    return sanitizeTerminalText(value).replace(/\s+/g, ' ').slice(0, 280);
+}
+/** A bounded success/failure readout, including optional tools and next actions. */
+export function formatSetupReport(report) {
+    const title = report.status === 'ready' ? (report.agent ? 'ZTC setup complete — shell and agent are ready.' : 'ZTC environment ready — no model quota used.')
+        : report.status === 'cancelled' ? 'ZTC setup cancelled. Completed steps were preserved; run /setup to resume.'
+            : report.status === 'needs_auth' ? 'ZTC setup needs an account.'
+                : 'ZTC setup incomplete — review the checks below, then run /setup again.';
+    const lines = [title];
+    const env = report.environment;
+    if (env) {
+        lines.push(`OS: ${env.platform}`, `Node (${env.node.runtimeKind}): ${env.node.status} — ${safeLine(env.node.version)}`, `Shell: ${env.shell.status} — ${safeLine(env.shell.detail)}`, `Package manager: ${env.packageManager.status} — ${safeLine(env.packageManager.detail)}`);
+        for (const check of env.checks)
+            lines.push(`${check.label}${check.required ? ' (required)' : ''}: ${check.status} — ${safeLine(check.detail)}`);
+    }
+    for (const attempt of report.installations)
+        lines.push(`Install ${attempt.tool}: ${attempt.status} — ${safeLine(attempt.detail)}`);
+    for (const step of report.steps)
+        lines.push(`${step.id}: ${step.status} — ${safeLine(step.detail)}`);
+    if (report.agent)
+        lines.push(`Selected model: ${safeLine(report.agent.provider)}/${safeLine(report.agent.model)}`);
+    if (report.workspace) {
+        lines.push(`Sample: ${safeLine(report.workspace.path)}`, `Sample session: ${report.workspace.sessionId}`, `Open the sample: /cd ${safeLine(report.workspace.path)}; then /resume ${report.workspace.sessionId}`);
+    }
+    if (report.status === 'needs_auth')
+        lines.push('Next: /auth login for Zerg Router, or /accounts and /config for your existing provider. Then run /setup.');
+    if (!report.agent && report.status === 'ready')
+        lines.push('Next: /auth login, then /auth readiness to check personal funding. Review pay-as-you-go pricing and caps with /auth billing. Optional /setup --check-agent sends one bounded model request after confirmation.');
+    lines.push('Your current project, conversation, shell configuration and PATH are preserved.');
+    return lines.join('\n');
+}

package/dist/onboarding/setup_agent_health.d.ts

@@ -0,0 +1,17 @@
+import type { ZTCConfig } from '../config/types.js';
+export interface SetupAgentProbeOptions {
+    config: ZTCConfig;
+    provider: string;
+    model: string;
+    cwd: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export interface SetupAgentProbeResult {
+    status: 'ready' | 'missing' | 'failed' | 'timeout' | 'cancelled' | 'unsupported';
+    detail: string;
+    provider: string;
+    model: string;
+}
+/** Check an isolated, tool-free turn without borrowing the active conversation. */
+export declare function probeSetupAgent(options: SetupAgentProbeOptions): Promise<SetupAgentProbeResult>;

package/dist/onboarding/setup_agent_health.js

@@ -0,0 +1,79 @@
+import { randomUUID } from 'node:crypto';
+import { Agent } from '../agent/agent.js';
+import { resolveAgentBackendFromConfig } from '../agent/factory.js';
+import { runtimePluginRegistry } from '../plugin/runtime_registry.js';
+/** Check an isolated, tool-free turn without borrowing the active conversation. */
+export async function probeSetupAgent(options) {
+    const result = (status, detail) => ({
+        status, detail, provider: options.provider, model: options.model,
+    });
+    if (options.signal?.aborted)
+        return result('cancelled', 'Health check cancelled.');
+    const timeoutMs = options.timeoutMs ?? 15_000;
+    if (timeoutMs <= 0)
+        return result('timeout', 'Health check deadline expired. Retry when ready.');
+    if (!Number.isFinite(timeoutMs) || timeoutMs > 30_000) {
+        return result('failed', 'Health check deadline must be a finite value of at most 30 seconds.');
+    }
+    if (!options.provider.trim() || !options.model.trim()) {
+        return result('missing', 'Choose a provider and model before checking its connection.');
+    }
+    // Plugin hosts own conversation admission. A local health turn must never
+    // inherit their currently selected cloud conversation or credential broker.
+    if (process.env.ZTC_HOST_RUNTIME !== undefined || runtimePluginRegistry.resolveHostRuntime({ mode: 'normal' })) {
+        return result('unsupported', 'This host owns its conversation. Check the connection through the host, then retry local setup.');
+    }
+    const config = structuredClone(options.config);
+    if (config.accounts) {
+        config.accounts.rotation = { enabled: false, mode: 'failover', defaultCooldownMs: 0,
+            weeklyCooldownMs: 0, subagentInheritance: 'inherit' };
+    }
+    // Native Codex owns subprocess tools independently of Agent's tool list.
+    // Keep this fresh diagnostic thread read-only while retaining its account.
+    config.codexAppServer = { ...config.codexAppServer, sandbox: 'read-only' };
+    const owner = new AbortController();
+    let expired = false;
+    const cancel = () => owner.abort();
+    options.signal?.addEventListener('abort', cancel, { once: true });
+    const timer = setTimeout(() => { expired = true; owner.abort(); }, timeoutMs);
+    let agent;
+    try {
+        const sessionId = `setup-health-${randomUUID()}`;
+        const resolved = resolveAgentBackendFromConfig({ config, provider: options.provider,
+            model: options.model, cwd: options.cwd, sessionId });
+        if (!resolved)
+            return result('missing', 'No usable credentials or endpoint. Sign in or configure this provider, then retry.');
+        agent = new Agent({
+            backend: resolved.backend, apiKey: resolved.apiKey, model: resolved.model,
+            sessionId, cwd: options.cwd, tools: [], ambientDiscovery: false,
+            disableApiKeyFallback: true, runtimeCredentialsAvailable: resolved.provider === 'openai_compatible',
+            autoContinue: false, maxIterations: 1, maxTokens: 64,
+            apiRetry: { maxAttempts: 1, baseDelayMs: 0, recoveryWindowMs: 0 },
+            systemPrompt: 'This is a connection health check. Reply briefly with plain text. Do not call tools or change files.',
+        });
+        const reply = await agent.run([{ id: randomUUID(), role: 'user',
+                content: 'Confirm this connection is responding.', timestamp: new Date() }], owner.signal);
+        if (options.signal?.aborted)
+            return result('cancelled', 'Health check cancelled.');
+        if (expired)
+            return result('timeout', 'Health check timed out. Check the provider connection and retry.');
+        if (reply.stopReason !== 'complete' || reply.toolCalls.length !== 0 || !reply.content.trim()) {
+            return result('failed', 'The provider did not complete a nonempty, tool-free reply. Check its model settings and retry.');
+        }
+        return result('ready', 'The provider completed an isolated connection check.');
+    }
+    catch {
+        if (options.signal?.aborted)
+            return result('cancelled', 'Health check cancelled.');
+        if (expired)
+            return result('timeout', 'Health check timed out. Check the provider connection and retry.');
+        // Provider errors and output can contain credential echoes. Fixed details
+        // stay bounded and never copy those payloads into setup's visible report.
+        return result('failed', 'Health check failed. Check provider credentials, model access and endpoint, then retry.');
+    }
+    finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener('abort', cancel);
+        agent?.dispose();
+    }
+}

package/dist/onboarding/setup_environment.d.ts

@@ -0,0 +1,66 @@
+export type SetupCheckStatus = 'ready' | 'missing' | 'unsupported' | 'timeout' | 'failed' | 'cancelled' | 'output_limit';
+export type SetupRuntimeKind = 'host' | 'bundled';
+export type SetupInstallTool = 'git' | 'rg';
+export type SetupPackageManagerId = 'brew' | 'apt' | 'dnf';
+export type SetupToolId = 'git' | 'rg' | 'gh' | 'gh_auth' | 'python' | 'bun' | 'deno' | 'make' | 'curl' | 'ssh' | 'tar' | 'unzip';
+export interface SetupInspectionOptions {
+    cwd?: string;
+    /** A child-only environment; inspection never changes process.env or PATH. */
+    env?: NodeJS.ProcessEnv;
+    signal?: AbortSignal;
+    /** Supplied by the caller's established desktop-runtime ownership check. */
+    runtimeKind?: SetupRuntimeKind;
+}
+export interface SetupToolCheck {
+    id: SetupToolId;
+    label: string;
+    required: boolean;
+    status: SetupCheckStatus;
+    detail: string;
+    version?: string;
+}
+export interface SetupShellHealth {
+    name: string;
+    path: string;
+    status: SetupCheckStatus;
+    detail: string;
+}
+export interface SetupEnvironmentReport {
+    platform: NodeJS.Platform;
+    shell: SetupShellHealth;
+    node: {
+        version: string;
+        executable: string;
+        runtimeKind: SetupRuntimeKind;
+        status: SetupCheckStatus;
+        detail: string;
+    };
+    packageManager: {
+        id: SetupPackageManagerId | null;
+        status: SetupCheckStatus;
+        detail: string;
+    };
+    checks: SetupToolCheck[];
+    ready: boolean;
+}
+export interface SetupInstallOptions extends SetupInspectionOptions {
+    tools: readonly SetupInstallTool[];
+}
+export interface SetupInstallAttempt {
+    tool: SetupInstallTool;
+    status: SetupCheckStatus;
+    action: 'installed' | 'skipped' | 'not_installed';
+    command?: string;
+    args?: string[];
+    detail: string;
+}
+export interface SetupInstallReport {
+    before: SetupEnvironmentReport;
+    attempts: SetupInstallAttempt[];
+    after: SetupEnvironmentReport;
+}
+/** Health uses only an allowlisted shell name and a fixed, literal sentinel. */
+export declare function runSetupShellHealth(options?: SetupInspectionOptions): Promise<SetupShellHealth>;
+export declare function inspectSetupEnvironment(options?: SetupInspectionOptions): Promise<SetupEnvironmentReport>;
+/** Only fixed package names/argv are supported; no sudo or arbitrary command input. */
+export declare function installMissingSetupTools(options: SetupInstallOptions): Promise<SetupInstallReport>;