@oh-my-pi/pi-coding-agent 15.1.1 → 15.1.2

package/dist/types/session/streaming-output.d.ts

@@ -0,0 +1,185 @@
+import type { AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+export declare const DEFAULT_MAX_LINES = 3000;
+export declare const DEFAULT_MAX_BYTES: number;
+export declare const DEFAULT_MAX_COLUMN = 1024;
+export interface OutputSummary {
+    output: string;
+    truncated: boolean;
+    totalLines: number;
+    totalBytes: number;
+    outputLines: number;
+    outputBytes: number;
+    /** Bytes elided from the middle when head-retain mode is active. */
+    elidedBytes?: number;
+    /** Lines elided from the middle when head-retain mode is active. */
+    elidedLines?: number;
+    /** Bytes dropped by the per-line column cap (sum across all lines). */
+    columnDroppedBytes?: number;
+    /** Number of distinct lines that hit the per-line column cap. */
+    columnTruncatedLines?: number;
+    /** Artifact ID for internal URL access (artifact://<id>) when truncated */
+    artifactId?: string;
+}
+export interface OutputSinkOptions {
+    artifactPath?: string;
+    artifactId?: string;
+    /** Tail buffer budget (bytes). Default DEFAULT_MAX_BYTES. */
+    spillThreshold?: number;
+    /**
+     * When > 0, the sink keeps the first `headBytes` of output in addition to
+     * the rolling tail window. Output between the two windows is elided
+     * (middle elision). Default 0 = tail-only behavior.
+     */
+    headBytes?: number;
+    /**
+     * Per-line byte cap. When > 0, lines wider than `maxColumns` bytes are
+     * truncated with an ellipsis at write time; remaining bytes up to the next
+     * `\n` are dropped. Cap state persists across chunks so split-mid-line
+     * writes still respect the budget. Default 0 = no per-line cap.
+     */
+    maxColumns?: number;
+    onChunk?: (chunk: string) => void;
+    /** Minimum ms between onChunk calls. 0 = every chunk (default). */
+    chunkThrottleMs?: number;
+}
+export interface TruncationResult {
+    content: string;
+    truncated?: boolean;
+    truncatedBy?: "lines" | "bytes" | "middle";
+    totalLines: number;
+    totalBytes: number;
+    outputLines?: number;
+    outputBytes?: number;
+    /** Bytes elided from the middle (truncateMiddle only). */
+    elidedBytes?: number;
+    /** Lines elided from the middle (truncateMiddle only). */
+    elidedLines?: number;
+    lastLinePartial?: boolean;
+    firstLineExceedsLimit?: boolean;
+}
+export interface TruncationOptions {
+    /** Maximum number of lines (default: 3000) */
+    maxLines?: number;
+    /** Maximum number of bytes (default: 50KB) */
+    maxBytes?: number;
+    /**
+     * For `truncateMiddle`: bytes reserved for the head window. The tail
+     * window receives `maxBytes - maxHeadBytes`. Default `floor(maxBytes/2)`.
+     */
+    maxHeadBytes?: number;
+    /**
+     * For `truncateMiddle`: lines reserved for the head window. The tail
+     * window receives `maxLines - maxHeadLines`. Default `floor(maxLines/2)`.
+     */
+    maxHeadLines?: number;
+}
+/** Result from byte-level truncation helpers. */
+export interface ByteTruncationResult {
+    text: string;
+    bytes: number;
+}
+export interface TailTruncationNoticeOptions {
+    fullOutputPath?: string;
+    originalContent?: string;
+    suffix?: string;
+}
+export interface HeadTruncationNoticeOptions {
+    startLine?: number;
+    totalFileLines?: number;
+}
+/**
+ * Truncate a string/buffer to fit within a byte limit, keeping the tail.
+ * Handles multi-byte UTF-8 boundaries correctly.
+ */
+export declare function truncateTailBytes(data: string | Uint8Array, maxBytes: number): ByteTruncationResult;
+/**
+ * Truncate a string/buffer to fit within a byte limit, keeping the head.
+ * Handles multi-byte UTF-8 boundaries correctly.
+ */
+export declare function truncateHeadBytes(data: string | Uint8Array, maxBytes: number): ByteTruncationResult;
+/**
+ * Truncate a single line to max characters, appending '…' if truncated.
+ */
+export declare function truncateLine(line: string, maxChars?: number): {
+    text: string;
+    wasTruncated: boolean;
+};
+/** Shared helper to build a no-truncation result. */
+export declare function noTruncResult(content: string, totalLines?: number, totalBytes?: number): TruncationResult;
+/**
+ * Truncate content from the head (keep first N lines/bytes).
+ * Never returns partial lines. If the first line exceeds the byte limit,
+ * returns empty content with firstLineExceedsLimit=true.
+ *
+ * This implementation avoids Buffer.from(content) for the whole input.
+ * It only computes UTF-8 byteLength for candidate lines that can still fit.
+ */
+export declare function truncateHead(content: string, options?: TruncationOptions): TruncationResult;
+/**
+ * Truncate content from the tail (keep last N lines/bytes).
+ * May return a partial first line if the last line exceeds the byte limit.
+ *
+ * Also avoids Buffer.from(content) for the whole input.
+ */
+export declare function truncateTail(content: string, options?: TruncationOptions): TruncationResult;
+/**
+ * Format the inline marker substituted for the elided middle region.
+ * Returned without surrounding newlines so callers can position it freely.
+ */
+export declare function formatMiddleElisionMarker(elidedLines: number, elidedBytes: number): string;
+/**
+ * Truncate content keeping a head window and a tail window, eliding the middle.
+ *
+ * The combined output is `<head>\n<marker>\n<tail>` when truncation is needed.
+ * `maxHeadBytes` defaults to `floor(maxBytes / 2)`; the tail receives the
+ * remainder. Falls back to `truncateTail` / `truncateHead` if either side's
+ * budget is empty or the content already fits.
+ */
+export declare function truncateMiddle(content: string, options?: TruncationOptions): TruncationResult;
+export declare class TailBuffer {
+    #private;
+    readonly maxBytes: number;
+    constructor(maxBytes: number);
+    append(text: string): void;
+    text(): string;
+    bytes(): number;
+}
+export declare class OutputSink {
+    #private;
+    constructor(options?: OutputSinkOptions);
+    /**
+     * Push a chunk of output. The buffer management and onChunk callback run
+     * synchronously. File sink writes are deferred and serialized internally.
+     */
+    push(chunk: string): void;
+    createInput(): WritableStream<Uint8Array | string>;
+    /**
+     * Replace the in-memory buffer with the given text. Used when an upstream
+     * minimizer rewrites the captured output after the raw bytes have already
+     * been streamed.
+     *
+     * After this call the buffer is authoritative: streaming counters realign
+     * to the replacement, the retained head window is cleared, and head
+     * retention is disabled so subsequent `push()` calls append directly to the
+     * tail buffer instead of repopulating the (now meaningless) head window
+     * — which would otherwise reorder content and trip the middle-elision
+     * branch in `dump()` against stale totals.
+     */
+    replace(text: string): void;
+    dump(notice?: string): Promise<OutputSummary>;
+}
+/**
+ * Format a truncation notice for tail-truncated output (bash, python, ssh).
+ * Returns empty string if not truncated.
+ */
+export declare function formatTailTruncationNotice(truncation: TruncationResult, options?: TailTruncationNoticeOptions): string;
+/**
+ * Format a truncation notice for head-truncated output (read tool).
+ * Returns empty string if not truncated.
+ */
+export declare function formatHeadTruncationNotice(truncation: TruncationResult, options?: HeadTruncationNoticeOptions): string;
+/**
+ * Build an onChunk handler that appends to a TailBuffer and emits a streaming
+ * update (when `onUpdate` is defined) with the buffer's current text.
+ */
+export declare function streamTailUpdates<TDetails, TInput = unknown>(tailBuffer: TailBuffer, onUpdate: AgentToolUpdateCallback<TDetails, TInput> | undefined): (chunk: string) => void;

package/dist/types/session/tool-choice-queue.d.ts

@@ -0,0 +1,78 @@
+import type { ToolChoice } from "@oh-my-pi/pi-ai";
+export interface ResolveInfo {
+    /** The ToolChoice that was served to the LLM. */
+    choice: ToolChoice;
+}
+export interface RejectInfo {
+    /** The ToolChoice that was yielded but never (or unsuccessfully) served. */
+    choice: ToolChoice;
+    reason: "aborted" | "error" | "cleared" | "removed";
+}
+/** "requeue" replays the lost yield next turn; "drop" (or void/undefined) discards it. */
+export type RejectOutcome = "requeue" | "drop";
+export interface DirectiveCallbacks {
+    /** Fires when the yield was served (LLM call completed). The directive is consumed. */
+    onResolved?: (info: ResolveInfo) => void;
+    /**
+     * Fires when the yield is being discarded. Return "requeue" to replay the
+     * same value at the head of the queue for the next turn. Default: "drop".
+     */
+    onRejected?: (info: RejectInfo) => RejectOutcome | undefined;
+    /**
+     * Handler invoked when the model actually calls the forced tool. The queue
+     * directive carries the real execution logic; the tool's own execute() is
+     * bypassed. Returns the tool result directly.
+     */
+    onInvoked?: (input: unknown) => Promise<unknown> | unknown;
+}
+export interface ToolChoiceDirective {
+    generator: Iterator<ToolChoice>;
+    /** Stable label for targeted removal and debugging (e.g. "user-force"). */
+    label: string;
+    callbacks: DirectiveCallbacks;
+}
+export interface PushOptions {
+    /** Prepend to head instead of appending to tail. Default: false. */
+    now?: boolean;
+    label?: string;
+    /** Lifecycle callbacks for this directive. */
+    onResolved?: DirectiveCallbacks["onResolved"];
+    onRejected?: DirectiveCallbacks["onRejected"];
+    onInvoked?: DirectiveCallbacks["onInvoked"];
+}
+export declare function onceGen(choice: ToolChoice): Generator<ToolChoice, void, unknown>;
+export declare class ToolChoiceQueue {
+    #private;
+    pushOnce(choice: ToolChoice, options?: PushOptions): void;
+    pushSequence(choices: ToolChoice[], options?: PushOptions): void;
+    push(generator: Iterable<ToolChoice>, options?: PushOptions): void;
+    /**
+     * Advance the head directive and return its next yield. Records the value
+     * as in-flight until resolve() or reject() is called.
+     */
+    nextToolChoice(): ToolChoice | undefined;
+    /**
+     * The in-flight yield was served — the LLM call completed normally.
+     * Fires onResolved, then clears in-flight state. The directive's generator
+     * remains in the queue if it has more values to yield.
+     */
+    resolve(): void;
+    /**
+     * The in-flight yield was not served, or the turn aborted/errored.
+     * Fires onRejected to let the caller decide: "requeue" replays the exact
+     * lost value at the head of the queue; anything else drops it.
+     */
+    reject(reason: RejectInfo["reason"]): void;
+    /** True if there is an in-flight yield that hasn't been resolved or rejected. */
+    get hasInFlight(): boolean;
+    /** Peek the in-flight directive's onInvoked handler, if any. */
+    peekInFlightInvoker(): ((input: unknown) => Promise<unknown> | unknown) | undefined;
+    /** Remove all directives with the given label. Rejects in-flight if it matches. */
+    removeByLabel(label: string): void;
+    /** Empty the queue and reject any in-flight yield. */
+    clear(): void;
+    /** Return the label of the most recently resolved directive, then clear it. */
+    consumeLastServedLabel(): string | undefined;
+    /** For tests/debug: labels of currently queued directives in order. */
+    inspect(): readonly string[];
+}

package/dist/types/slash-commands/acp-builtins.d.ts

@@ -0,0 +1,18 @@
+import type { AvailableCommand } from "@agentclientprotocol/sdk";
+import type { AcpBuiltinCommandRuntime, AcpBuiltinSlashCommandResult } from "./types";
+export type { AcpBuiltinCommandRuntime, AcpBuiltinSlashCommandResult } from "./types";
+/**
+ * Commands advertised to ACP clients. Entries without a text-mode `handle`
+ * (e.g. `/quit`, `/login`, dashboards) are filtered out so the client doesn't
+ * see commands it cannot drive.
+ */
+export declare const ACP_BUILTIN_SLASH_COMMANDS: AvailableCommand[];
+/**
+ * Dispatch a slash command in ACP/text mode. Returns:
+ * - `false` when no builtin matched (or matched a TUI-only entry); the caller
+ *   should forward the input as a prompt.
+ * - `{ consumed: true }` when the command handled the input entirely.
+ * - `{ prompt }` when the command was handled but a residual prompt should be
+ *   sent to the model.
+ */
+export declare function executeAcpBuiltinSlashCommand(text: string, runtime: AcpBuiltinCommandRuntime): Promise<AcpBuiltinSlashCommandResult>;

package/dist/types/slash-commands/builtin-registry.d.ts

@@ -0,0 +1,23 @@
+import type { BuiltinSlashCommand, ParsedSlashCommand, SlashCommandResult, SlashCommandRuntime, SlashCommandSpec, TuiSlashCommandRuntime } from "./types";
+export type { BuiltinSlashCommand, SubcommandDef } from "./types";
+/** TUI-specific runtime accepted by `executeBuiltinSlashCommand`. */
+export type BuiltinSlashCommandRuntime = TuiSlashCommandRuntime;
+/** Builtin command metadata used for slash-command autocomplete and help text. */
+export declare const BUILTIN_SLASH_COMMAND_DEFS: ReadonlyArray<BuiltinSlashCommand>;
+/**
+ * Unified registry exposed for cross-mode tooling. Each spec carries at least
+ * one of `handle` / `handleTui`. The TUI dispatcher prefers `handleTui`; the
+ * ACP dispatcher requires `handle` and skips TUI-only entries.
+ */
+export declare const BUILTIN_SLASH_COMMANDS_INTERNAL: ReadonlyArray<SlashCommandSpec>;
+/**
+ * Execute a builtin slash command in the interactive TUI.
+ *
+ * Returns `false` when no builtin matched. Returns `true` when a command
+ * consumed the input entirely. Returns a `string` when the command was handled
+ * but remaining text should be sent as a prompt.
+ */
+export declare function executeBuiltinSlashCommand(text: string, runtime: BuiltinSlashCommandRuntime): Promise<string | boolean>;
+/** Look up a unified spec by name or alias. Used by the ACP dispatcher. */
+export declare function lookupBuiltinSlashCommand(name: string): SlashCommandSpec | undefined;
+export type { ParsedSlashCommand, SlashCommandResult, SlashCommandRuntime, SlashCommandSpec, TuiSlashCommandRuntime };

package/dist/types/slash-commands/helpers/context-report.d.ts

@@ -0,0 +1,7 @@
+import type { SlashCommandRuntime } from "../types";
+/**
+ * Build the `/context` ACP-mode text. Tries the rich breakdown first
+ * (categories + auto-compact buffer + free slack) and falls back to the
+ * minimal "window/used" lines when the breakdown helper throws.
+ */
+export declare function buildContextReportText(runtime: SlashCommandRuntime): string;

package/dist/types/slash-commands/helpers/format.d.ts

@@ -0,0 +1,7 @@
+/** Format a millisecond duration as a coarse-grained human label. */
+export declare function formatDuration(ms: number): string;
+/**
+ * Render an ASCII progress bar with a trailing percent label.
+ * `fraction` is clamped to `[0, 1]`. `undefined` renders a dotted placeholder.
+ */
+export declare function renderAsciiBar(fraction: number | undefined, width?: number): string;

package/dist/types/slash-commands/helpers/marketplace-manager.d.ts

@@ -0,0 +1,8 @@
+import { MarketplaceManager } from "../../extensibility/plugins/marketplace";
+import type { SlashCommandRuntime } from "../types";
+/**
+ * Build a `MarketplaceManager` wired up with the active project's registry
+ * paths and the shared plugin-root cache invalidator. Reused by both `/plugins`
+ * and `/marketplace` handlers so cache invalidation stays consistent.
+ */
+export declare function createMarketplaceManager(runtime: SlashCommandRuntime): Promise<MarketplaceManager>;

package/dist/types/slash-commands/helpers/mcp.d.ts

@@ -0,0 +1,3 @@
+import type { ParsedSlashCommand, SlashCommandResult, SlashCommandRuntime } from "../types";
+/** ACP/text-mode `/mcp` handler. Shared by both dispatchers via the spec. */
+export declare function handleMcpAcp(command: ParsedSlashCommand, runtime: SlashCommandRuntime): Promise<SlashCommandResult>;

package/dist/types/slash-commands/helpers/parse.d.ts

@@ -0,0 +1,33 @@
+import type { ParsedSlashCommand, SlashCommandResult, SlashCommandRuntime } from "../types";
+export interface ParsedSubcommand {
+    verb: string;
+    rest: string;
+}
+export type ConfigScope = "user" | "project";
+export interface NamedScopeArgs {
+    name?: string;
+    scope: ConfigScope;
+    error?: string;
+}
+/**
+ * Parse a slash-invocation string into `name`/`args`.
+ *
+ * The separator is the earliest whitespace or `:` character so that both
+ * `/foo bar` and `/foo:bar` map to `{ name: "foo", args: "bar" }`.
+ */
+export declare function parseSlashCommand(text: string): ParsedSlashCommand | null;
+/** Mark a command as fully consumed in the ACP shape. */
+export declare function commandConsumed(): {
+    consumed: true;
+};
+/** Emit a usage/error message and consume the command. */
+export declare function usage(text: string, runtime: SlashCommandRuntime): Promise<SlashCommandResult>;
+/** Split `<verb> <rest>` on the first whitespace; lowercases `verb`. */
+export declare function parseSubcommand(input: string): ParsedSubcommand;
+export declare function errorMessage(error: unknown): string;
+/**
+ * Parse `<name?> [--scope project|user]`-style argument strings used by
+ * remove/rm-style subcommands. `name` is optional so callers can surface
+ * "name required" diagnostics with their own messaging.
+ */
+export declare function parseNamedScopeArgs(rest: string, invalidScopeMessage: string): NamedScopeArgs;

package/dist/types/slash-commands/helpers/ssh.d.ts

@@ -0,0 +1,3 @@
+import type { ParsedSlashCommand, SlashCommandResult, SlashCommandRuntime } from "../types";
+/** ACP/text-mode `/ssh` handler. Shared by both dispatchers via the spec. */
+export declare function handleSshAcp(command: ParsedSlashCommand, runtime: SlashCommandRuntime): Promise<SlashCommandResult>;

package/dist/types/slash-commands/helpers/todo.d.ts

@@ -0,0 +1,3 @@
+import type { ParsedSlashCommand, SlashCommandResult, SlashCommandRuntime } from "../types";
+/** ACP/text-mode `/todo` handler. Shared by both dispatchers via the spec. */
+export declare function handleTodoAcp(command: ParsedSlashCommand, runtime: SlashCommandRuntime): Promise<SlashCommandResult>;

package/dist/types/slash-commands/helpers/usage-report.d.ts

@@ -0,0 +1,7 @@
+import type { SlashCommandRuntime } from "../types";
+/**
+ * Build the `/usage` ACP-mode text. Prefers provider-reported limits when the
+ * session exposes `fetchUsageReports`; otherwise falls back to the local
+ * session-manager tallies.
+ */
+export declare function buildUsageReportText(runtime: SlashCommandRuntime): Promise<string>;

package/dist/types/slash-commands/marketplace-install-parser.d.ts

@@ -0,0 +1,33 @@
+export interface MarketplaceInstallArgs {
+    force: boolean;
+    scope: "user" | "project";
+    installSpec: string;
+}
+/**
+ * Parse the argument string following `/marketplace install`.
+ *
+ * Returns either the parsed args or an `{ error }` object whose message is
+ * suitable for direct display to the user via `ctx.showStatus`.
+ *
+ * Accepted flags (any order):
+ *   --force                 Force-reinstall even if already installed
+ *   --scope user|project    Installation scope (default: user)
+ *
+ * Exactly one positional argument is required: `name@marketplace`.
+ */
+export declare function parseMarketplaceInstallArgs(rest: string): MarketplaceInstallArgs | {
+    error: string;
+};
+export interface PluginScopeArgs {
+    pluginId: string;
+    scope?: "user" | "project";
+}
+/**
+ * Parse `[--scope user|project] <name@marketplace>` for commands that accept a
+ * single plugin ID and an optional scope flag.
+ *
+ * Returns parsed args or `{ error }` ready for `ctx.showStatus`.
+ */
+export declare function parsePluginScopeArgs(rest: string, usageHint: string): PluginScopeArgs | {
+    error: string;
+};

package/dist/types/slash-commands/types.d.ts

@@ -0,0 +1,119 @@
+import type { Settings } from "../config/settings";
+import type { InteractiveModeContext } from "../modes/types";
+import type { AgentSession } from "../session/agent-session";
+import type { SessionManager } from "../session/session-manager";
+/** Declarative subcommand definition for commands like /mcp. */
+export interface SubcommandDef {
+    name: string;
+    description: string;
+    /** Usage hint shown as dim ghost text, e.g. "<name> [--scope project|user]". */
+    usage?: string;
+}
+/** Declarative builtin slash command metadata used by autocomplete and help UI. */
+export interface BuiltinSlashCommand {
+    name: string;
+    description: string;
+    /** Subcommands for dropdown completion (e.g. /mcp add, /mcp list). */
+    subcommands?: SubcommandDef[];
+    /** Static inline hint when command takes a simple argument (no subcommands). */
+    inlineHint?: string;
+}
+/** Parsed slash-command text after stripping the leading "/". */
+export interface ParsedSlashCommand {
+    name: string;
+    args: string;
+    text: string;
+}
+/**
+ * Result returned by a slash-command handler.
+ *
+ * - `void` / `undefined` — command was handled and consumed; no further input.
+ * - `{ consumed: true }` — explicit equivalent of the above (ACP shape).
+ * - `{ prompt: string }` — command handled, pass `prompt` through as the new
+ *   user input (e.g. `/force <tool> <prompt>` keeps `<prompt>` as the message).
+ */
+export type SlashCommandResult = undefined | {
+    consumed: true;
+} | {
+    prompt: string;
+};
+/**
+ * Runtime visible to slash-command handlers that run in text/ACP mode.
+ *
+ * Both the TUI dispatcher (when invoking a `handle` via its adapter) and the
+ * ACP dispatcher pass this shape. Implementations MUST NOT depend on TUI-only
+ * state (editor, selectors, status line).
+ */
+export interface SlashCommandRuntime {
+    session: AgentSession;
+    sessionManager: SessionManager;
+    settings: Settings;
+    cwd: string;
+    /** Emit text to the operator. TUI maps to `ctx.showStatus`, ACP to `sessionUpdate`. */
+    output: (text: string) => Promise<void> | void;
+    /** Re-advertise the available command list (no-op outside ACP). */
+    refreshCommands: () => Promise<void> | void;
+    /**
+     * Reload plugin state (caches, slash command registry, project registries)
+     * and re-emit available commands. Used by `/reload-plugins`, `/move`, and
+     * `/marketplace`/`/plugins` mutations so the session sees a consistent view
+     * after plugin or project-scope changes.
+     */
+    reloadPlugins: () => Promise<void>;
+    notifyTitleChanged?: () => Promise<void> | void;
+    notifyConfigChanged?: () => Promise<void> | void;
+}
+/**
+ * Runtime visible to TUI-only handlers (`handleTui`). Carries the interactive
+ * mode context plus the background-detach hook. Intentionally narrower than
+ * `SlashCommandRuntime` so existing callers can keep building it from just
+ * `{ ctx, handleBackgroundCommand }`; when the TUI dispatcher needs to invoke
+ * a `handle` (no `handleTui` override), it synthesizes a `SlashCommandRuntime`
+ * from `ctx`.
+ */
+export interface TuiSlashCommandRuntime {
+    ctx: InteractiveModeContext;
+    handleBackgroundCommand: () => void;
+}
+/** Unified slash-command spec consumed by both TUI and ACP dispatchers. */
+export interface SlashCommandSpec extends BuiltinSlashCommand {
+    aliases?: string[];
+    /** When false, the dispatcher refuses to handle invocations that include arguments. */
+    allowArgs?: boolean;
+    /**
+     * ACP-specific override for `description`. Used by `ACP_BUILTIN_SLASH_COMMANDS`
+     * when building `available_commands_update` payloads so the client receives
+     * mode-appropriate copy (e.g. `/dump` advertises "Return full transcript as
+     * plain text" in ACP rather than the TUI's clipboard-centric copy).
+     */
+    acpDescription?: string;
+    /**
+     * ACP-specific override for the advertised input hint. `subcommands`-only
+     * specs that historically advertised `<subcommand>` / `[on|off|status]` /
+     * `info|delete` to ACP clients carry the hint here so the unification does
+     * not silently drop it from `available_commands_update`.
+     */
+    acpInputHint?: string;
+    /**
+     * Text/ACP-mode handler. The same body is invoked from the ACP dispatcher
+     * and, via the TUI adapter, when no `handleTui` override is provided.
+     */
+    handle?: (command: ParsedSlashCommand, runtime: SlashCommandRuntime) => Promise<SlashCommandResult> | SlashCommandResult;
+    /**
+     * TUI-only handler that supersedes `handle` when both are present. Use for
+     * selectors, wizards, dashboards, and anything else that requires
+     * `InteractiveModeContext`.
+     */
+    handleTui?: (command: ParsedSlashCommand, runtime: TuiSlashCommandRuntime) => Promise<SlashCommandResult> | SlashCommandResult;
+}
+/**
+ * @deprecated Use `SlashCommandRuntime` directly. Retained as an alias so
+ * downstream code that imported the ACP-specific name keeps compiling.
+ */
+export type AcpBuiltinCommandRuntime = SlashCommandRuntime;
+/** Result returned by `executeAcpBuiltinSlashCommand`. */
+export type AcpBuiltinSlashCommandResult = false | {
+    consumed: true;
+} | {
+    prompt: string;
+};

package/dist/types/ssh/config-writer.d.ts

@@ -0,0 +1,49 @@
+export interface SSHHostConfig {
+    host: string;
+    username?: string;
+    port?: number;
+    keyPath?: string;
+    description?: string;
+    compat?: boolean;
+}
+export interface SSHConfigFile {
+    hosts?: Record<string, SSHHostConfig>;
+}
+/**
+ * Read an SSH config file.
+ * Returns empty config if file doesn't exist.
+ */
+export declare function readSSHConfigFile(filePath: string): Promise<SSHConfigFile>;
+/**
+ * Write an SSH config file atomically.
+ * Creates parent directories if they don't exist.
+ */
+export declare function writeSSHConfigFile(filePath: string, config: SSHConfigFile): Promise<void>;
+/**
+ * Validate host name.
+ * @returns Error message if invalid, undefined if valid
+ */
+export declare function validateHostName(name: string): string | undefined;
+/**
+ * Add an SSH host to a config file.
+ *
+ * @throws Error if host name already exists or validation fails
+ */
+export declare function addSSHHost(filePath: string, name: string, hostConfig: SSHHostConfig): Promise<void>;
+/**
+ * Update an existing SSH host in a config file.
+ * If the host doesn't exist, this will add it.
+ *
+ * @throws Error if validation fails
+ */
+export declare function updateSSHHost(filePath: string, name: string, hostConfig: SSHHostConfig): Promise<void>;
+/**
+ * Remove an SSH host from a config file.
+ *
+ * @throws Error if host doesn't exist
+ */
+export declare function removeSSHHost(filePath: string, name: string): Promise<void>;
+/**
+ * List all host names in a config file.
+ */
+export declare function listSSHHosts(filePath: string): Promise<string[]>;

package/dist/types/ssh/connection-manager.d.ts

@@ -0,0 +1,33 @@
+export interface SSHConnectionTarget {
+    name: string;
+    host: string;
+    username?: string;
+    port?: number;
+    keyPath?: string;
+    compat?: boolean;
+}
+export type SSHHostOs = "windows" | "linux" | "macos" | "unknown";
+export type SSHHostShell = "cmd" | "powershell" | "bash" | "zsh" | "sh" | "unknown";
+export type SshPlatform = typeof process.platform;
+export declare function supportsSshControlMaster(platform?: SshPlatform): boolean;
+export interface SSHHostInfo {
+    version: number;
+    os: SSHHostOs;
+    shell: SSHHostShell;
+    compatShell?: "bash" | "sh";
+    compatEnabled: boolean;
+}
+interface SSHArgsOptions {
+    platform?: SshPlatform;
+}
+export declare function getHostInfo(hostName: string): Promise<SSHHostInfo | undefined>;
+export declare function getHostInfoForHost(host: SSHConnectionTarget): Promise<SSHHostInfo | undefined>;
+export declare function ensureHostInfo(host: SSHConnectionTarget): Promise<SSHHostInfo>;
+export declare function buildRemoteCommand(host: SSHConnectionTarget, command: string, options?: SSHArgsOptions): Promise<string[]>;
+export declare function ensureConnection(host: SSHConnectionTarget): Promise<void>;
+export declare function invalidateHostMetadata(hostNames: Iterable<string>): Promise<void>;
+export declare function closeConnection(hostName: string): Promise<void>;
+export declare function closeAllConnections(): Promise<void>;
+export declare function getControlPathTemplate(): string;
+export declare function getControlDir(): string;
+export {};

package/dist/types/ssh/ssh-executor.d.ts

@@ -0,0 +1,37 @@
+import { type SSHConnectionTarget } from "./connection-manager";
+export interface SSHExecutorOptions {
+    /** Timeout in milliseconds */
+    timeout?: number;
+    /** Callback for streaming output chunks (already sanitized) */
+    onChunk?: (chunk: string) => void;
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+    /** Remote path to mount when sshfs is available */
+    remotePath?: string;
+    /** Wrap commands in a POSIX shell for compat mode */
+    compatEnabled?: boolean;
+    /** Artifact path/id for full output storage */
+    artifactPath?: string;
+    artifactId?: string;
+}
+export interface SSHResult {
+    /** Combined stdout + stderr output (sanitized, possibly truncated) */
+    output: string;
+    /** Process exit code (undefined if killed/cancelled) */
+    exitCode: number | undefined;
+    /** Whether the command was cancelled via signal */
+    cancelled: boolean;
+    /** Whether the output was truncated */
+    truncated: boolean;
+    /** Total number of lines in the output stream */
+    totalLines: number;
+    /** Total number of bytes in the output stream */
+    totalBytes: number;
+    /** Number of lines included in the output text */
+    outputLines: number;
+    /** Number of bytes included in the output text */
+    outputBytes: number;
+    /** Artifact ID if full output was saved to artifact storage */
+    artifactId?: string;
+}
+export declare function executeSSH(host: SSHConnectionTarget, command: string, options?: SSHExecutorOptions): Promise<SSHResult>;