qlogicagent 0.5.2 → 0.5.3

package/dist/types/skills/tools/plan-mode-tool.d.ts

@@ -0,0 +1,98 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const PLAN_MODE_TOOL_NAME: "plan_mode";
+export type PlanModeAction = "enter" | "exit";
+export interface PlanModeToolParams {
+    /** Action: enter or exit plan mode */
+    action: PlanModeAction;
+    /** Plan text (for exit — the finalized plan to present for approval) */
+    plan?: string;
+    /** File path where plan was saved (optional) */
+    planFilePath?: string;
+    /**
+     * Semantic permissions to request on exit (CC ExitPlanModeV2 parity).
+     * Each entry describes a tool + intent the agent wants permission for.
+     */
+    allowedPrompts?: Array<{
+        tool: string;
+        prompt: string;
+    }>;
+}
+export declare const PLAN_MODE_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly action: {
+            readonly type: "string";
+            readonly enum: readonly ["enter", "exit"];
+            readonly description: string;
+        };
+        readonly plan: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly planFilePath: {
+            readonly type: "string";
+            readonly description: "Optional file path where the plan was saved for reference.";
+        };
+        readonly allowedPrompts: {
+            readonly type: "array";
+            readonly description: string;
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly tool: {
+                        readonly type: "string";
+                        readonly description: "Tool name to pre-approve.";
+                    };
+                    readonly prompt: {
+                        readonly type: "string";
+                        readonly description: "Intent description for this permission.";
+                    };
+                };
+                readonly required: readonly ["tool", "prompt"];
+            };
+        };
+    };
+    readonly required: readonly ["action"];
+};
+/** Tools allowed during plan mode (read-only + reasoning) */
+export declare const PLAN_MODE_ALLOWED_TOOLS: readonly string[];
+export interface PlanModeState {
+    active: boolean;
+    enteredAt?: string;
+    plan?: string;
+    planFilePath?: string;
+}
+export interface PlanModeResult {
+    success: boolean;
+    state: PlanModeState;
+    allowedTools?: readonly string[];
+    error?: string;
+}
+/**
+ * Host-provided plan mode backend.
+ * The host is responsible for filtering tool availability based on mode state.
+ */
+export interface PlanModeToolDeps {
+    /** Get current plan mode state */
+    getState(): PlanModeState;
+    /** Enter plan mode — host should restrict tool availability */
+    enterPlanMode(): Promise<PlanModeResult>;
+    /** Exit plan mode — host restores full tool availability */
+    exitPlanMode(plan?: string, planFilePath?: string): Promise<PlanModeResult>;
+    /** Check if in agent/sub-agent context (plan mode not allowed in sub-agents) */
+    isAgentContext?(): boolean;
+    /**
+     * Request approval for the plan from the user/coordinator.
+     * CC parity: ExitPlanModeV2 triggers an approval dialog on exit.
+     * Returns true if approved, false if rejected.
+     */
+    requestPlanApproval?(plan: string, allowedPrompts?: Array<{
+        tool: string;
+        prompt: string;
+    }>): Promise<boolean>;
+    /**
+     * Persist plan to disk (CC parity: plan is saved to planFilePath).
+     */
+    persistPlan?(plan: string, filePath: string): Promise<void>;
+}
+export declare function createPlanModeTool(deps: PlanModeToolDeps): PortableTool<PlanModeToolParams>;

package/dist/types/skills/tools/read-tool.d.ts

@@ -0,0 +1,51 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const READ_TOOL_NAME: "read";
+export interface ReadToolParams {
+    path: string;
+    offset?: number;
+    limit?: number;
+}
+export declare const READ_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly path: {
+            readonly type: "string";
+            readonly description: "Absolute path to the file to read.";
+        };
+        readonly offset: {
+            readonly type: "number";
+            readonly description: "Line number to start reading from (1-indexed). Default: 1.";
+        };
+        readonly limit: {
+            readonly type: "number";
+            readonly description: "Maximum number of lines to read. Default/max: 2000.";
+        };
+    };
+    readonly required: readonly ["path"];
+};
+export type ReadResultType = "text" | "image" | "binary_rejected";
+/** Deps injected by the host runtime for file reading. */
+export interface ReadToolDeps {
+    /** Read file content. Return string for text, base64 for images, or rejection. */
+    readFile(path: string): Promise<{
+        type: "text";
+        text: string;
+    } | {
+        type: "image";
+        base64: string;
+        mimeType: string;
+    } | {
+        type: "binary";
+        mimeType: string;
+    }>;
+    /** Resolve a relative path to absolute. */
+    resolvePath(input: string): string;
+    /**
+     * Validate read access for the given path.
+     * Returns null if allowed, or an error message if blocked.
+     * Blocks device paths (/dev/zero, /dev/random, etc.) and
+     * paths outside the allowed workspace.
+     */
+    validatePath?(path: string): string | null;
+}
+export declare function createReadTool(deps: ReadToolDeps): PortableTool<ReadToolParams>;

package/dist/types/skills/tools/repl-tool.d.ts

@@ -0,0 +1,70 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const REPL_TOOL_NAME: "repl";
+export interface ReplToolParams {
+    /** JavaScript code to execute in the persistent VM context */
+    code: string;
+}
+export declare const REPL_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly code: {
+            readonly type: "string";
+            readonly description: string;
+        };
+    };
+    readonly required: readonly ["code"];
+};
+export interface ReplExecResult {
+    output: string;
+    error?: string;
+    duration: number;
+}
+/** Primitive operations injected into the VM context. */
+export interface ReplPrimitives {
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    editFile(path: string, edits: Array<{
+        oldText: string;
+        newText: string;
+    }>): Promise<string>;
+    exec(command: string): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+    glob(pattern: string): Promise<string[]>;
+    grep(pattern: string, path?: string): Promise<Array<{
+        file: string;
+        line: number;
+        text: string;
+    }>>;
+}
+/**
+ * Host-provided REPL execution backend.
+ */
+export interface ReplToolDeps {
+    /**
+     * Execute JavaScript code within a persistent VM context.
+     * The VM is pre-initialized with the primitive functions above.
+     * Each tool invocation reuses the same VM (preserving variable state).
+     */
+    executeInVm(code: string): Promise<ReplExecResult>;
+    /**
+     * Reset the VM context (clear state). Optional hook called on errors.
+     */
+    resetVm?(): void;
+    /**
+     * The host-provided primitives injected into the VM.
+     * When provided, the tool validates that the host has set up all required primitives.
+     */
+    primitives?: ReplPrimitives;
+    /**
+     * Permission check for individual primitive operations.
+     * Called before each primitive executes inside the VM.
+     * Returns null if allowed, or an error message if denied.
+     */
+    checkPermission?(operation: string, args: unknown[]): Promise<string | null>;
+}
+/** Tool names that should be hidden from direct LLM access when REPL is active. */
+export declare const REPL_HIDES_TOOLS: readonly string[];
+export declare function createReplTool(deps: ReplToolDeps): PortableTool<ReplToolParams>;

package/dist/types/skills/tools/search-tool.d.ts

@@ -0,0 +1,112 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const SEARCH_TOOL_NAME: "search";
+export type SearchMode = "filename" | "content" | "both";
+export interface SearchToolParams {
+    mode: SearchMode;
+    pattern: string;
+    path?: string;
+    fileGlob?: string;
+    contextLines?: number;
+    caseInsensitive?: boolean;
+    headLimit?: number;
+    offset?: number;
+}
+export declare const SEARCH_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly mode: {
+            readonly type: "string";
+            readonly enum: readonly ["filename", "content", "both"];
+            readonly description: string;
+        };
+        readonly pattern: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly path: {
+            readonly type: "string";
+            readonly description: "Directory to search in. Defaults to workdir/cwd if omitted.";
+        };
+        readonly fileGlob: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly contextLines: {
+            readonly type: "number";
+            readonly description: string;
+        };
+        readonly caseInsensitive: {
+            readonly type: "boolean";
+            readonly description: "Case insensitive search (content/both modes). Default: false.";
+        };
+        readonly headLimit: {
+            readonly type: "number";
+            readonly description: string;
+        };
+        readonly offset: {
+            readonly type: "number";
+            readonly description: "Skip first N results before applying headLimit. Default: 0.";
+        };
+    };
+    readonly required: readonly ["mode", "pattern"];
+};
+export interface SearchFileResult {
+    path: string;
+}
+export interface SearchContentResult {
+    path: string;
+    line: number;
+    text: string;
+    contextBefore?: string[];
+    contextAfter?: string[];
+}
+export interface SearchOutput {
+    mode: SearchMode;
+    totalMatches: number;
+    truncated: boolean;
+    fileResults?: SearchFileResult[];
+    contentResults?: SearchContentResult[];
+}
+/** Host-provided search backend. */
+export interface SearchToolDeps {
+    /**
+     * Find files matching a glob pattern.
+     * Returns array of relative file paths.
+     * The host SHOULD auto-exclude VCS directories (.git, .svn, .hg, .bzr)
+     * unless the user explicitly includes them.
+     */
+    glob(pattern: string, options: {
+        cwd: string;
+        limit: number;
+    }): Promise<{
+        files: string[];
+        truncated: boolean;
+    }>;
+    /**
+     * Search file contents using regex.
+     * The implementation may use ripgrep, native grep, or a custom engine.
+     * Returns match records.
+     * The host SHOULD auto-exclude VCS directories (.git, .svn, .hg, .bzr)
+     * and enforce --max-columns 500 to avoid minified file noise.
+     */
+    grep(pattern: string, options: {
+        cwd: string;
+        fileGlob?: string;
+        caseInsensitive?: boolean;
+        contextLines?: number;
+        headLimit?: number;
+        offset?: number;
+    }): Promise<{
+        matches: Array<{
+            path: string;
+            line: number;
+            text: string;
+            contextBefore?: string[];
+            contextAfter?: string[];
+        }>;
+        truncated: boolean;
+    }>;
+    /** Resolve relative path to absolute. If omitted, cwd is used. */
+    resolvePath?(input: string): string;
+}
+export declare function createSearchTool(deps: SearchToolDeps): PortableTool<SearchToolParams>;

package/dist/types/skills/tools/send-message-tool.d.ts

@@ -0,0 +1,51 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const SEND_MESSAGE_TOOL_NAME: "send_message";
+export interface SendMessageToolParams {
+    /** Target agent name or '*' for broadcast */
+    to: string;
+    /** Message content */
+    message: string;
+    /** Optional short summary for routing/display */
+    summary?: string;
+}
+export declare const SEND_MESSAGE_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly to: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly message: {
+            readonly type: "string";
+            readonly description: "Message content to send to the target agent.";
+        };
+        readonly summary: {
+            readonly type: "string";
+            readonly description: "Optional short summary (for logging/routing).";
+        };
+    };
+    readonly required: readonly ["to", "message"];
+};
+export interface SendMessageResult {
+    success: boolean;
+    recipients?: string[];
+    error?: string;
+}
+/**
+ * Host-provided message routing backend.
+ * Messages are delivered asynchronously via mailbox pattern.
+ */
+export interface SendMessageToolDeps {
+    /** Send message to target agent(s). Returns delivery status. */
+    sendMessage(params: {
+        to: string;
+        message: string;
+        summary?: string;
+        senderId: string;
+    }): Promise<SendMessageResult>;
+    /** Get the current agent's ID */
+    getSenderId(): string;
+    /** List available teammates */
+    listTeammates?(): string[];
+}
+export declare function createSendMessageTool(deps: SendMessageToolDeps): PortableTool<SendMessageToolParams>;

package/dist/types/skills/tools/shell/bash-provider.d.ts

@@ -0,0 +1,26 @@
+import type { ShellProvider } from "./shell-provider.js";
+export interface BashProviderOptions {
+    /**
+     * Absolute path to a pre-saved shell snapshot file.
+     * If provided, will be `source`d before every command
+     * to restore environment (virtualenvs, PATHs, etc.).
+     */
+    snapshotFilePath?: string;
+    /**
+     * Script fragment that sets session-specific env vars.
+     * Injected between snapshot sourcing and command execution.
+     */
+    sessionEnvScript?: string;
+}
+/**
+ * Create a bash ShellProvider.
+ *
+ * @param shellPath Absolute path to bash (e.g. `/bin/bash`, `/usr/bin/bash`)
+ * @param options   Optional snapshot / session env
+ */
+export declare function createBashProvider(shellPath: string, options?: BashProviderOptions): ShellProvider;
+/**
+ * Update the snapshot file path at runtime (e.g. after re-snapshotting).
+ * This is a convenience — in practice the provider is re-created infrequently.
+ */
+export declare function updateSnapshot(provider: ShellProvider, snapshotFilePath: string | undefined): void;

package/dist/types/skills/tools/shell/command-classification.d.ts

@@ -0,0 +1,44 @@
+/** Commands that search/find content (collapsible in UI). */
+export declare const SEARCH_COMMANDS: Set<string>;
+/** Commands that read/display file content (collapsible in UI). */
+export declare const READ_COMMANDS: Set<string>;
+/** Commands that list directory contents. */
+export declare const LIST_COMMANDS: Set<string>;
+/**
+ * Commands that are semantically neutral — they don't interact
+ * with the file system in a meaningful way. Skipped when
+ * classifying piped commands.
+ */
+export declare const SEMANTIC_NEUTRAL_COMMANDS: Set<string>;
+/**
+ * Commands that produce no stdout on success.
+ * For these, the tool shows "Done" instead of "(No output)".
+ */
+export declare const SILENT_COMMANDS: Set<string>;
+export interface CommandClassification {
+    /** First "real" command word (after env vars / wrappers). */
+    firstCommand: string | null;
+    /** Whether the command is search-like (find, grep, etc.). */
+    isSearch: boolean;
+    /** Whether the command only reads (cat, head, stat, etc.). */
+    isRead: boolean;
+    /** Whether the command lists files (ls, tree, du). */
+    isList: boolean;
+    /** Whether the command is expected to produce no stdout. */
+    isSilent: boolean;
+    /** Whether the command is safe to run in parallel with others. */
+    isConcurrencySafe: boolean;
+    /** Whether the command only reads state (never mutates). */
+    isReadOnly: boolean;
+}
+/**
+ * Check whether a command has any `cd` or pushd/popd that changes CWD.
+ * Ported from cc's `commandHasAnyCd()`.
+ */
+export declare function commandHasAnyCd(command: string): boolean;
+/**
+ * Classify a shell command.
+ *
+ * Mirrors cc's `isSearchOrReadBashCommand()` + `isSilentBashCommand()`.
+ */
+export declare function classifyCommand(command: string): CommandClassification;

package/dist/types/skills/tools/shell/command-semantics.d.ts

@@ -0,0 +1,14 @@
+export interface CommandSemanticResult {
+    isError: boolean;
+    message?: string;
+}
+/**
+ * Interpret a command's exit code using semantic rules.
+ *
+ * @param command - The shell command that was executed
+ * @param exitCode - The process exit code
+ * @param stdout - Standard output
+ * @param stderr - Standard error
+ * @returns Semantic interpretation (isError + optional message)
+ */
+export declare function interpretCommandResult(command: string, exitCode: number, stdout: string, stderr: string): CommandSemanticResult;

package/dist/types/skills/tools/shell/destructive-command-warning.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Check a bash/sh command for destructive patterns.
+ * Returns the first matching warning, or null.
+ */
+export declare function getDestructiveCommandWarning(command: string): string | null;
+/**
+ * Check a PowerShell command for destructive patterns.
+ * Returns the first matching warning, or null.
+ */
+export declare function getPowerShellDestructiveCommandWarning(command: string): string | null;

package/dist/types/skills/tools/shell/exec-permissions.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Environment variables that can safely appear as prefixes.
+ * Ported from cc's SAFE_ENV_VARS.
+ *
+ * NEVER add:
+ *   PATH, LD_PRELOAD, LD_LIBRARY_PATH, DYLD_*   (execution/library loading)
+ *   PYTHONPATH, NODE_PATH, CLASSPATH, RUBYLIB     (module loading)
+ *   GOFLAGS, RUSTFLAGS, NODE_OPTIONS              (code execution flags)
+ *   HOME, TMPDIR, SHELL, BASH_ENV                 (system behavior)
+ */
+export declare const SAFE_ENV_VARS: Set<string>;
+/**
+ * Commands that execute their arguments — should not be treated
+ * as "first word" for permission prefix matching.
+ * Ported from cc's BARE_SHELL_PREFIXES.
+ */
+export declare const BARE_SHELL_PREFIXES: Set<string>;
+/**
+ * Strip safe env var prefixes and wrapper commands.
+ * Ported from cc's `stripSafeWrappers()`.
+ *
+ * `NODE_ENV=test timeout 30 grep -r foo .` → `grep -r foo .`
+ */
+export declare function stripSafeWrappers(command: string): string;
+/**
+ * Aggressively strip ALL leading env vars (not just safe ones).
+ * Used for deny-rule matching where the env prefix doesn't change
+ * the dangerousness of the underlying command.
+ * Ported from cc's `stripAllLeadingEnvVars()`.
+ */
+export declare function stripAllLeadingEnvVars(command: string, blocklist?: RegExp): string;
+/**
+ * Extract `<cmd> <subcommand>` prefix for rule matching.
+ * E.g. `git commit -m "foo"` → `git commit`
+ * Ported from cc's `getSimpleCommandPrefix()`.
+ */
+export declare function getSimpleCommandPrefix(command: string): string | null;
+/**
+ * Extract the first command word for prefix-based rule matching.
+ * Ported from cc's `getFirstWordPrefix()`.
+ */
+export declare function getFirstWordPrefix(command: string): string | null;
+/**
+ * Strip argv-level wrapper commands.
+ * Ported from cc's `stripWrappersFromArgv()`.
+ */
+export declare function stripWrappersFromArgv(argv: string[]): string[];
+/**
+ * Detect blocking sleep/wait patterns in commands.
+ * Ported from cc's `detectBlockedSleepPattern()`.
+ */
+export declare function detectBlockedSleepPattern(command: string): string | null;

package/dist/types/skills/tools/shell/index.d.ts

@@ -0,0 +1,17 @@
+export type { ShellType, BuildCommandOpts, BuiltCommand, ShellProvider, } from "./shell-provider.js";
+export { isPowerShellToolEnabled, getDefaultShellType, generateCommandId, } from "./shell-provider.js";
+export { createBashProvider } from "./bash-provider.js";
+export type { BashProviderOptions } from "./bash-provider.js";
+export { createPowerShellProvider, encodePowerShellCommand, } from "./powershell-provider.js";
+export type { CommandClassification } from "./command-classification.js";
+export { SEARCH_COMMANDS, READ_COMMANDS, LIST_COMMANDS, SEMANTIC_NEUTRAL_COMMANDS, SILENT_COMMANDS, classifyCommand, commandHasAnyCd, } from "./command-classification.js";
+export { SAFE_ENV_VARS, BARE_SHELL_PREFIXES, stripSafeWrappers, stripAllLeadingEnvVars, getSimpleCommandPrefix, getFirstWordPrefix, stripWrappersFromArgv, detectBlockedSleepPattern, } from "./exec-permissions.js";
+export { getDestructiveCommandWarning, getPowerShellDestructiveCommandWarning, } from "./destructive-command-warning.js";
+export type { CommandSemanticResult } from "./command-semantics.js";
+export { interpretCommandResult } from "./command-semantics.js";
+export { TaskOutput, generateTaskId, getTaskOutputDir, setTaskOutputDir, getTaskOutputPath, MAX_TASK_OUTPUT_BYTES, } from "./task-output.js";
+export type { ProgressCallback } from "./task-output.js";
+export type { ExecResult, ShellCommand } from "./shell-command.js";
+export { wrapSpawn, createAbortedCommand, createFailedCommand, } from "./shell-command.js";
+export { exec, getCwd, setCwd, initCwd, getOriginalCwd, setShellProvider, getShellProvider, } from "./shell-exec.js";
+export type { ExecOptions } from "./shell-exec.js";

package/dist/types/skills/tools/shell/powershell-provider.d.ts

@@ -0,0 +1,15 @@
+import type { ShellProvider } from "./shell-provider.js";
+/**
+ * Encode a PowerShell command as UTF-16LE Base64 for -EncodedCommand.
+ * This avoids all quoting/escaping issues when passing complex commands
+ * through cmd.exe or other shell wrappers.
+ *
+ * Ported directly from cc's `encodePowerShellCommand()`.
+ */
+export declare function encodePowerShellCommand(psCommand: string): string;
+/**
+ * Create a PowerShell ShellProvider.
+ *
+ * @param shellPath Absolute path to pwsh.exe or powershell.exe
+ */
+export declare function createPowerShellProvider(shellPath: string): ShellProvider;

package/dist/types/skills/tools/shell/shell-command.d.ts

@@ -0,0 +1,54 @@
+import type { ChildProcess } from "node:child_process";
+import { TaskOutput } from "./task-output.js";
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    /** Exit code. 137 = SIGKILL, 143 = SIGTERM, 145 = aborted. */
+    code: number;
+    /** Whether the process was interrupted (killed or timed out). */
+    interrupted: boolean;
+    /** Set when backgrounded. */
+    backgroundTaskId?: string;
+    /** Set when the user explicitly backgrounded. */
+    backgroundedByUser?: boolean;
+    /** Set when assistant mode auto-backgrounded. */
+    assistantAutoBackgrounded?: boolean;
+    /** Path to raw output file for large outputs. */
+    outputFilePath?: string;
+    /** Total output file size in bytes. */
+    outputFileSize?: number;
+    /** Error message when command failed before spawning. */
+    preSpawnError?: string;
+}
+export interface ShellCommand {
+    /** Move the process to background. Returns true if successful. */
+    background(taskId: string): boolean;
+    /** Promise resolving when the process exits. */
+    result: Promise<ExecResult>;
+    /** Kill the process immediately. */
+    kill(): void;
+    /** Current lifecycle status. */
+    status: "running" | "backgrounded" | "completed" | "killed";
+    /** Clean up stream resources and listeners. */
+    cleanup(): void;
+    /** Register timeout callback (for auto-backgrounding). */
+    onTimeout?: (callback: (backgroundFn: (taskId: string) => boolean) => void) => void;
+    /** Output container. */
+    taskOutput: TaskOutput;
+}
+/**
+ * Wrap a child process with lifecycle management.
+ * Ported from cc's wrapSpawn().
+ */
+export declare function wrapSpawn(childProcess: ChildProcess, abortSignal: AbortSignal, timeout: number, taskOutput: TaskOutput, shouldAutoBackground?: boolean, maxOutputBytes?: number): ShellCommand;
+/**
+ * Create a ShellCommand for commands that were aborted before execution.
+ */
+export declare function createAbortedCommand(backgroundTaskId?: string, opts?: {
+    stderr?: string;
+    code?: number;
+}): ShellCommand;
+/**
+ * Create a ShellCommand for commands that failed before spawn.
+ */
+export declare function createFailedCommand(preSpawnError: string): ShellCommand;

package/dist/types/skills/tools/shell/shell-exec.d.ts

@@ -0,0 +1,33 @@
+import type { ShellProvider, ShellType } from "./shell-provider.js";
+import { type ShellCommand } from "./shell-command.js";
+import { type ProgressCallback } from "./task-output.js";
+export type { ExecResult } from "./shell-command.js";
+export declare function getCwd(): string;
+export declare function setCwd(path: string, relativeTo?: string): void;
+export declare function getOriginalCwd(): string;
+export declare function initCwd(cwd: string): void;
+export interface ExecOptions {
+    timeout?: number;
+    onProgress?: ProgressCallback;
+    /** When true, `cd` in the command does NOT update the session CWD. */
+    preventCwdChanges?: boolean;
+    shouldAutoBackground?: boolean;
+    /** When provided, stdout is piped and this callback fires per chunk. */
+    onStdout?: (data: string) => void;
+}
+/**
+ * Set the shell provider for this session.
+ * Must be called once at startup by the host.
+ */
+export declare function setShellProvider(provider: ShellProvider): void;
+/**
+ * Get the current shell provider, or throw if not configured.
+ */
+export declare function getShellProvider(): ShellProvider;
+/**
+ * Execute a shell command using the configured provider.
+ * Creates a new child process for each invocation.
+ *
+ * Ported from cc's Shell.ts — the tool owns process lifecycle.
+ */
+export declare function exec(command: string, abortSignal: AbortSignal, shellType?: ShellType, options?: ExecOptions): Promise<ShellCommand>;