@astralyn/pi 0.87.6 → 1.0.0

package/dist/core/{background → tasks}/types.d.ts

@@ -1,71 +1,42 @@
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { Usage } from "@earendil-works/pi-ai/compat";
-export type BackgroundKind = "bash" | "subagent";
-export type BackgroundMode = "foreground" | "background";
-export type BackgroundTerminalStatus = "completed" | "partial" | "failed" | "cancelled" | "timeout";
-export type BackgroundStatus = "queued" | "running" | "stopping" | BackgroundTerminalStatus;
+/** An executor-owned source label, never a dispatch key for the runtime. */
+export type TaskKind = string;
+export type TaskMode = "foreground" | "background";
+export type TaskTerminalStatus = "completed" | "partial" | "failed" | "cancelled" | "timeout";
+export type TaskStatus = "queued" | "running" | "stopping" | TaskTerminalStatus;
 /** A bounded snapshot; truncation is recorded at the source, never inferred from text. */
-export interface BackgroundText {
+export interface TaskText {
     text: string;
     truncated: boolean;
 }
-export interface BackgroundWorkerReport {
-    id: string;
-    label: string;
-    profile: string;
-    description: string;
-    status: string;
-    report: BackgroundText;
-    error?: string;
-}
-/** A serializable, domain-owned projection. No extension-private renderer imports. */
-export interface BackgroundWorker extends BackgroundWorkerReport {
-    prompt: string;
-    activity: string;
-    model?: string;
-    usage?: string;
-}
-export interface BackgroundProjection {
-    text?: string;
-    shell?: {
-        name: string;
-        output: BackgroundText;
-    };
-    workers?: BackgroundWorker[];
-}
-interface BackgroundCompletionBase {
-    version: 1;
+/** Self-contained completion-message details. No live handles, tool-private details or accounting. */
+export interface TaskCompletionSnapshot {
+    version: 2;
+    kind: string;
     taskId: string;
     title: string;
-    status: BackgroundTerminalStatus;
+    status: TaskTerminalStatus;
     startedAt: number;
     endedAt: number;
     error?: string;
-}
-/** Self-contained completion-message details. No live handles, tool-private details or accounting. */
-export type BackgroundCompletionSnapshot = BackgroundCompletionBase & ({
-    kind: "bash";
-    shell?: string;
-    command?: BackgroundText;
+    command?: TaskText;
     cwd?: string;
     outputPath?: string;
     /** Process exit code: a number, or null when signal-reaped. */
     exitCode?: number | null;
-    output: BackgroundText;
-} | {
-    kind: "subagent";
-    workers: BackgroundWorkerReport[];
-    /** Plain fallback when an executor has no worker projection. */
-    output?: BackgroundText;
-});
-export interface BackgroundTask {
+    /** The tail of the final result text. */
+    output: TaskText;
+}
+/** A read-only view of one task; the runtime returns frozen snapshots. */
+export interface TaskSnapshot {
     id: string;
-    kind: BackgroundKind;
+    kind: TaskKind;
     title: string;
     toolCallId: string;
     anchorId: string | null;
-    mode: BackgroundMode;
-    status: BackgroundStatus;
+    mode: TaskMode;
+    status: TaskStatus;
     startedAt: number;
     endedAt?: number;
     command?: string;
@@ -74,14 +45,13 @@ export interface BackgroundTask {
     /** Process exit code (bash): a number, or null when signal-reaped. Absent while running or unreported. */
     exitCode?: number | null;
     outputPath?: string;
-    projection?: BackgroundProjection;
     result?: AgentToolResult<unknown>;
     resultTruncated?: boolean;
     error?: string;
 }
-export interface BackgroundCompletion<T> {
+export interface TaskCompletion<T> {
     result: AgentToolResult<T>;
-    status?: BackgroundTerminalStatus;
+    status?: TaskTerminalStatus;
     /** Terminal diagnostic, stored independently of log slices and bounded to 4096 bytes. */
     error?: string;
     /** Process exit code (bash): a number, or null when signal-reaped. */
@@ -89,10 +59,12 @@ export interface BackgroundCompletion<T> {
     /** Authoritative cumulative usage; overrides result.usage and any published snapshot. */
     usage?: Usage;
 }
-export interface BackgroundControl<T> {
+export interface TaskControl<T> {
     readonly id: string;
     readonly signal: AbortSignal;
-    readonly mode: BackgroundMode;
+    readonly mode: TaskMode;
+    onModeChange(listener: (mode: TaskMode) => void): () => void;
+    requestCancel(): boolean;
     /** Accept only after whole-invocation preflight; required before returning a handoff. */
     accept(): void;
     /**
@@ -100,12 +72,12 @@ export interface BackgroundControl<T> {
      * published usage is settled once on rejection (never inferred from details).
      * Final completion.usage, then completion.result.usage, override that snapshot.
      */
-    publish(result: AgentToolResult<T>, projection?: BackgroundProjection): void;
+    publish(result: AgentToolResult<T>): void;
     /** Register once; cleanup must own only this exclusively-created file and close its writer first. */
     setOutputPath(path: string, cleanup?: () => void | Promise<void>): void;
 }
-export interface BackgroundExecution<T> {
-    kind: BackgroundKind;
+export interface TaskExecution<T> {
+    kind: TaskKind;
     title: string;
     toolCallId: string;
     command?: string;
@@ -113,19 +85,19 @@ export interface BackgroundExecution<T> {
     background?: boolean;
     signal?: AbortSignal;
     onUpdate?: (result: AgentToolResult<T>) => void;
-    run(control: BackgroundControl<T>): Promise<BackgroundCompletion<T>>;
+    run(control: TaskControl<T>): Promise<TaskCompletion<T>>;
 }
-export type BackgroundToolOutcome<T> = {
+export type TaskToolOutcome<T> = {
     kind: "result";
     result: AgentToolResult<T>;
-    status?: BackgroundTerminalStatus;
+    status?: TaskTerminalStatus;
     error?: string;
 } | {
     kind: "background";
-    task: BackgroundTask;
+    task: TaskSnapshot;
 };
-export interface BackgroundRead {
-    task: BackgroundTask;
+export interface TaskRead {
+    task: TaskSnapshot;
     text: string;
     /** Bounded log-read/expiry diagnostic, independent of text slicing and byte offsets. */
     readError?: string;
@@ -134,45 +106,52 @@ export interface BackgroundRead {
     fromByte?: number;
 }
 /** Session-bound public capability. Captured instances close on runtime replacement. */
-export interface BackgroundContext {
+export interface TasksContext {
     readonly enabled: boolean;
     readonly closed?: boolean;
-    execute<T>(execution: BackgroundExecution<T>): Promise<BackgroundToolOutcome<T>>;
-    list(): BackgroundTask[];
-    get(id: string): BackgroundTask;
+    execute<T>(execution: TaskExecution<T>): Promise<TaskToolOutcome<T>>;
+    list(): TaskSnapshot[];
+    get(id: string): TaskSnapshot;
     read(id: string, options?: {
         mode?: "head" | "tail";
         bytes?: number;
         sinceBytes?: number;
-    }): Promise<BackgroundRead>;
+    }): Promise<TaskRead>;
     /** Observation only: terminal delivery is acknowledged by the host via markDelivered after result persistence. */
-    wait(id: string, timeoutMs?: number, signal?: AbortSignal): Promise<BackgroundTask>;
+    wait(id: string, timeoutMs?: number, signal?: AbortSignal): Promise<TaskSnapshot>;
     kill(id: string): boolean;
-    /** Move every running foreground execution to the background; returns how many moved. */
+    /**
+     * Move running foreground executions to the background while background slots remain;
+     * returns how many moved. Throws when eligible work exists but every slot is taken.
+     */
     detachForeground(): number;
+    /** Returns false when the task cannot move; throws when every background slot is taken. */
+    detach(id: string): boolean;
     subscribe(listener: () => void): () => void;
-    pin(id: string): () => void;
+    /** Keep retained output available without delaying completion delivery. */
+    retain(id: string): () => void;
+    /** Hold automatic delivery while preparing a result for the host to persist. */
+    holdDelivery(id: string): () => void;
 }
-export interface BackgroundServiceOptions {
+export interface TaskRuntimeOptions {
     enabled?: boolean;
-    role?: "main" | "subagent";
+    backgroundAllowed?: boolean;
     anchor?: () => string | null;
+    /** Concurrent background executions. Foreground work is bounded by its caller instead. */
     maxActive?: number;
-    /** Per-history limit: foreground shells and background tasks/all subagents each get this allowance. */
+    /** Per-history limit: foreground and background tasks each get this allowance. */
     maxHistory?: number;
     /** Best-effort cleanup errors, bounded to 4096 bytes; no retries or execution failure. */
     onCleanupError?: (message: string) => void;
     /** Synchronous persistence before terminal observers or notifications. */
-    onSettled?: (task: BackgroundTask, usage: Usage | undefined) => void;
+    onSettled?: (task: TaskSnapshot, usage: Usage | undefined) => void;
 }
-export declare const SUBAGENT_BACKGROUND_REJECTION = "Background execution is not available inside subagents. Run this command with background: false (or omit background). Only the parent agent or the user can background the entire subagent invocation. No command was started.";
-export declare function isBackgroundTerminal(status: BackgroundStatus): boolean;
-/** Foreground shell logs have their own history; subagent groups remain inspectable in either mode. */
-export declare function isForegroundShellTask(task: Pick<BackgroundTask, "kind" | "mode">): boolean;
+export declare const TASK_BACKGROUND_REJECTION = "Background execution is not permitted in this host. Run with background: false or omit background. No work was started.";
+export declare function isTaskTerminal(status: TaskStatus): boolean;
 /** Preserve the foreground throwing contract without guessing status from output text. */
-export declare class BackgroundExecutionError extends Error {
-    readonly status: BackgroundTerminalStatus;
-    constructor(message: string, status: BackgroundTerminalStatus);
+export declare class TaskExecutionError extends Error {
+    readonly status: TaskTerminalStatus;
+    constructor(message: string, status: TaskTerminalStatus);
 }
 /**
  * A failed id lookup, typed so hosts can enrich the message without matching
@@ -180,10 +159,9 @@ export declare class BackgroundExecutionError extends Error {
  * resolved against — including records outside the current branch, which
  * list() hides but prefix matching still collides with.
  */
-export declare class BackgroundLookupError extends Error {
+export declare class TaskLookupError extends Error {
     readonly kind: "unknown" | "ambiguous";
-    readonly matches: BackgroundTask[];
-    constructor(kind: "unknown" | "ambiguous", matches: BackgroundTask[]);
+    readonly matches: TaskSnapshot[];
+    constructor(kind: "unknown" | "ambiguous", matches: TaskSnapshot[]);
 }
-export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/core/tasks/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/tasks/types.ts"],"names":[],"mappings":"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"}

package/dist/core/tasks/types.js

@@ -0,0 +1,27 @@
+export const TASK_BACKGROUND_REJECTION = "Background execution is not permitted in this host. Run with background: false or omit background. No work was started.";
+export function isTaskTerminal(status) {
+    return status !== "queued" && status !== "running" && status !== "stopping";
+}
+/** Preserve the foreground throwing contract without guessing status from output text. */
+export class TaskExecutionError extends Error {
+    constructor(message, status) {
+        super(message);
+        this.name = "TaskExecutionError";
+        this.status = status;
+    }
+}
+/**
+ * A failed id lookup, typed so hosts can enrich the message without matching
+ * on message text. `matches` snapshots exactly the records the id or prefix
+ * resolved against — including records outside the current branch, which
+ * list() hides but prefix matching still collides with.
+ */
+export class TaskLookupError extends Error {
+    constructor(kind, matches) {
+        super(kind === "ambiguous" ? "Ambiguous task ID" : "Unknown task ID");
+        this.name = "TaskLookupError";
+        this.kind = kind;
+        this.matches = matches;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/core/tasks/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/tasks/types.ts"],"names":[],"mappings":"AAsJA,MAAM,CAAC,MAAM,yBAAyB,GACrC,yHAAyH,CAAC;AAE3H,MAAM,UAAU,cAAc,CAAC,MAAkB;IAChD,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,UAAU,CAAC;AAC7E,CAAC;AAED,0FAA0F;AAC1F,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAE5C,YAAY,OAAe,EAAE,MAA0B;QACtD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACtB,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAGzC,YAAY,IAA6B,EAAE,OAAuB;QACjE,KAAK,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC;QACtE,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACxB,CAAC;CACD","sourcesContent":["import type { AgentToolResult } from \"@earendil-works/pi-agent-core\";\nimport type { Usage } from \"@earendil-works/pi-ai/compat\";\n\n/** An executor-owned source label, never a dispatch key for the runtime. */\nexport type TaskKind = string;\nexport type TaskMode = \"foreground\" | \"background\";\nexport type TaskTerminalStatus = \"completed\" | \"partial\" | \"failed\" | \"cancelled\" | \"timeout\";\nexport type TaskStatus = \"queued\" | \"running\" | \"stopping\" | TaskTerminalStatus;\n\n/** A bounded snapshot; truncation is recorded at the source, never inferred from text. */\nexport interface TaskText {\n\ttext: string;\n\ttruncated: boolean;\n}\n\n/** Self-contained completion-message details. No live handles, tool-private details or accounting. */\nexport interface TaskCompletionSnapshot {\n\tversion: 2;\n\tkind: string;\n\ttaskId: string;\n\ttitle: string;\n\tstatus: TaskTerminalStatus;\n\tstartedAt: number;\n\tendedAt: number;\n\terror?: string;\n\tcommand?: TaskText;\n\tcwd?: string;\n\toutputPath?: string;\n\t/** Process exit code: a number, or null when signal-reaped. */\n\texitCode?: number | null;\n\t/** The tail of the final result text. */\n\toutput: TaskText;\n}\n\n/** A read-only view of one task; the runtime returns frozen snapshots. */\nexport interface TaskSnapshot {\n\tid: string;\n\tkind: TaskKind;\n\ttitle: string;\n\ttoolCallId: string;\n\tanchorId: string | null;\n\tmode: TaskMode;\n\tstatus: TaskStatus;\n\tstartedAt: number;\n\tendedAt?: number;\n\tcommand?: string;\n\tcommandTruncated?: boolean;\n\tcwd?: string;\n\t/** Process exit code (bash): a number, or null when signal-reaped. Absent while running or unreported. */\n\texitCode?: number | null;\n\toutputPath?: string;\n\tresult?: AgentToolResult<unknown>;\n\tresultTruncated?: boolean;\n\terror?: string;\n}\n\nexport interface TaskCompletion<T> {\n\tresult: AgentToolResult<T>;\n\tstatus?: TaskTerminalStatus;\n\t/** Terminal diagnostic, stored independently of log slices and bounded to 4096 bytes. */\n\terror?: string;\n\t/** Process exit code (bash): a number, or null when signal-reaped. */\n\texitCode?: number | null;\n\t/** Authoritative cumulative usage; overrides result.usage and any published snapshot. */\n\tusage?: Usage;\n}\n\nexport interface TaskControl<T> {\n\treadonly id: string;\n\treadonly signal: AbortSignal;\n\treadonly mode: TaskMode;\n\tonModeChange(listener: (mode: TaskMode) => void): () => void;\n\trequestCancel(): boolean;\n\t/** Accept only after whole-invocation preflight; required before returning a handoff. */\n\taccept(): void;\n\t/**\n\t * result.usage is a cumulative snapshot, never a delta. The most recent explicitly\n\t * published usage is settled once on rejection (never inferred from details).\n\t * Final completion.usage, then completion.result.usage, override that snapshot.\n\t */\n\tpublish(result: AgentToolResult<T>): void;\n\t/** Register once; cleanup must own only this exclusively-created file and close its writer first. */\n\tsetOutputPath(path: string, cleanup?: () => void | Promise<void>): void;\n}\n\nexport interface TaskExecution<T> {\n\tkind: TaskKind;\n\ttitle: string;\n\ttoolCallId: string;\n\tcommand?: string;\n\tcwd?: string;\n\tbackground?: boolean;\n\tsignal?: AbortSignal;\n\tonUpdate?: (result: AgentToolResult<T>) => void;\n\trun(control: TaskControl<T>): Promise<TaskCompletion<T>>;\n}\n\nexport type TaskToolOutcome<T> =\n\t| { kind: \"result\"; result: AgentToolResult<T>; status?: TaskTerminalStatus; error?: string }\n\t| { kind: \"background\"; task: TaskSnapshot };\n\nexport interface TaskRead {\n\ttask: TaskSnapshot;\n\ttext: string;\n\t/** Bounded log-read/expiry diagnostic, independent of text slicing and byte offsets. */\n\treadError?: string;\n\ttotalBytes: number;\n\ttruncated: boolean;\n\tfromByte?: number;\n}\n\n/** Session-bound public capability. Captured instances close on runtime replacement. */\nexport interface TasksContext {\n\treadonly enabled: boolean;\n\treadonly closed?: boolean;\n\texecute<T>(execution: TaskExecution<T>): Promise<TaskToolOutcome<T>>;\n\tlist(): TaskSnapshot[];\n\tget(id: string): TaskSnapshot;\n\tread(id: string, options?: { mode?: \"head\" | \"tail\"; bytes?: number; sinceBytes?: number }): Promise<TaskRead>;\n\t/** Observation only: terminal delivery is acknowledged by the host via markDelivered after result persistence. */\n\twait(id: string, timeoutMs?: number, signal?: AbortSignal): Promise<TaskSnapshot>;\n\tkill(id: string): boolean;\n\t/**\n\t * Move running foreground executions to the background while background slots remain;\n\t * returns how many moved. Throws when eligible work exists but every slot is taken.\n\t */\n\tdetachForeground(): number;\n\t/** Returns false when the task cannot move; throws when every background slot is taken. */\n\tdetach(id: string): boolean;\n\tsubscribe(listener: () => void): () => void;\n\t/** Keep retained output available without delaying completion delivery. */\n\tretain(id: string): () => void;\n\t/** Hold automatic delivery while preparing a result for the host to persist. */\n\tholdDelivery(id: string): () => void;\n}\n\nexport interface TaskRuntimeOptions {\n\tenabled?: boolean;\n\tbackgroundAllowed?: boolean;\n\tanchor?: () => string | null;\n\t/** Concurrent background executions. Foreground work is bounded by its caller instead. */\n\tmaxActive?: number;\n\t/** Per-history limit: foreground and background tasks each get this allowance. */\n\tmaxHistory?: number;\n\t/** Best-effort cleanup errors, bounded to 4096 bytes; no retries or execution failure. */\n\tonCleanupError?: (message: string) => void;\n\t/** Synchronous persistence before terminal observers or notifications. */\n\tonSettled?: (task: TaskSnapshot, usage: Usage | undefined) => void;\n}\n\nexport const TASK_BACKGROUND_REJECTION =\n\t\"Background execution is not permitted in this host. Run with background: false or omit background. No work was started.\";\n\nexport function isTaskTerminal(status: TaskStatus): boolean {\n\treturn status !== \"queued\" && status !== \"running\" && status !== \"stopping\";\n}\n\n/** Preserve the foreground throwing contract without guessing status from output text. */\nexport class TaskExecutionError extends Error {\n\treadonly status: TaskTerminalStatus;\n\tconstructor(message: string, status: TaskTerminalStatus) {\n\t\tsuper(message);\n\t\tthis.name = \"TaskExecutionError\";\n\t\tthis.status = status;\n\t}\n}\n\n/**\n * A failed id lookup, typed so hosts can enrich the message without matching\n * on message text. `matches` snapshots exactly the records the id or prefix\n * resolved against — including records outside the current branch, which\n * list() hides but prefix matching still collides with.\n */\nexport class TaskLookupError extends Error {\n\treadonly kind: \"unknown\" | \"ambiguous\";\n\treadonly matches: TaskSnapshot[];\n\tconstructor(kind: \"unknown\" | \"ambiguous\", matches: TaskSnapshot[]) {\n\t\tsuper(kind === \"ambiguous\" ? \"Ambiguous task ID\" : \"Unknown task ID\");\n\t\tthis.name = \"TaskLookupError\";\n\t\tthis.kind = kind;\n\t\tthis.matches = matches;\n\t}\n}\n"]}

package/dist/core/tools/bash.d.ts

@@ -1,98 +1,13 @@
-import type { AgentTool } from "@earendil-works/pi-agent-core";
-import { type Static, Type } from "typebox";
-import { type ShellConfig } from "../../utils/shell.ts";
-import type { ExtensionContext, ToolDefinition } from "../extensions/types.ts";
-import { type TruncationResult } from "./truncate.ts";
-declare const bashSchema: Type.TObject<{
-    command: Type.TString;
-    timeout: Type.TOptional<Type.TNumber>;
-    background: Type.TOptional<Type.TBoolean>;
-}>;
-export declare const bashToolSystemPromptContribution: {
-    readonly snippet: "Execute bash commands, foreground or background";
-    readonly guidelines: readonly ["You can inspect PI_* environment variables for current model and session details."];
-};
-export type BashToolInput = Static<typeof bashSchema>;
-export interface BashToolDetails {
-    truncation?: TruncationResult;
-    fullOutputPath?: string;
-    /** Settled handoff snapshot, not a command completion or exit code. */
-    background?: {
-        kind: "background";
-        taskId: string;
-    };
-}
-/**
- * Pluggable operations for the bash tool.
- * Override these to delegate command execution to remote systems (for example SSH).
- */
-export interface BashOperations {
-    /**
-     * Execute a command and stream output.
-     * @param command The command to execute
-     * @param cwd Working directory
-     * @param options Execution options
-     * @returns Promise resolving to the exit code. Report signal terminations as 128 + signal number;
-     * a null exit code is treated as a failed command.
-     *
-     * Error contract: reject with `new Error("aborted")` when aborted via `signal`,
-     * and `new Error("timeout:<seconds>")` on timeout expiry. The shared shell
-     * execution pipeline classifies outcomes from these exact markers.
-     */
-    exec: (command: string, cwd: string, options: {
-        onData: (data: Buffer) => void;
-        signal?: AbortSignal;
-        timeout?: number;
-        env?: NodeJS.ProcessEnv;
-    }) => Promise<{
-        exitCode: number | null;
-    }>;
-}
-/** Shared process execution used by the built-in shell tools. */
-export declare function createLocalShellOperations(shellName: string, resolveShellConfig: () => ShellConfig, normalizeCommand?: (command: string) => string): BashOperations;
-/**
- * Create bash operations using pi's built-in local shell execution backend.
- *
- * This is useful for extensions that intercept user_bash and still want pi's
- * standard local shell behavior while wrapping or rewriting commands.
- */
+import { type BashOperations, type BashToolOptions, createShellToolDefinition } from "./shell-tool.ts";
+export { type BashOperations, type BashRenderState, type BashSpawnContext, type BashSpawnHook, type BashToolDetails, type BashToolInput, type BashToolOptions, bashToolSystemPromptContribution, } from "./shell-tool.ts";
 export declare function normalizeLocalBashCommand(command: string, platform?: NodeJS.Platform): string;
 export declare function createLocalBashOperations(options?: {
     shellPath?: string;
 }): BashOperations;
-export interface BashSpawnContext {
-    command: string;
-    cwd: string;
-    env: NodeJS.ProcessEnv;
-}
-export type BashSpawnHook = (context: BashSpawnContext) => BashSpawnContext;
-export declare function resolveSpawnContext(command: string, cwd: string, spawnHook: BashSpawnHook | undefined, exposeSessionEnvironment: boolean, ctx: ExtensionContext | undefined): BashSpawnContext;
-export interface BashToolOptions {
-    /** Custom operations for command execution. Default: local shell */
-    operations?: BashOperations;
-    /** Command prefix prepended to every command (for example shell setup commands) */
-    commandPrefix?: string;
-    /** Optional explicit shell path from settings */
-    shellPath?: string;
-    /** Expose current Pi session metadata as PI_* environment variables. Default: true */
-    exposeSessionEnvironment?: boolean;
-    /** Hook to adjust command, cwd, or env before execution */
-    spawnHook?: BashSpawnHook;
-}
-export type BashRenderState = {
-    dispose?: () => void;
-};
-export interface ShellToolConfig {
-    name: string;
-    label: string;
-    shellName: string;
-    prompt: string;
-    promptSnippet: string;
-    promptGuidelines?: readonly string[];
-    tempFilePrefix: string;
-}
-export declare function createShellToolDefinition(cwd: string, config: ShellToolConfig, options?: BashToolOptions): ToolDefinition<typeof bashSchema, BashToolDetails | undefined, BashRenderState>;
-export declare function createBashToolDefinition(cwd: string, options?: BashToolOptions): ToolDefinition<typeof bashSchema, BashToolDetails | undefined, BashRenderState>;
-export declare function createBashTool(cwd: string, options?: BashToolOptions): AgentTool<typeof bashSchema>;
-export {};
+export declare function createBashToolDefinition(cwd: string, options?: BashToolOptions): ReturnType<typeof createShellToolDefinition>;
+export declare function createBashTool(cwd: string, options?: BashToolOptions): import("@earendil-works/pi-agent-core").AgentTool<import("typebox").TObject<{
+    command: import("typebox").TString;
+    timeout: import("typebox").TOptional<import("typebox").TNumber>;
+    background: import("typebox").TOptional<import("typebox").TBoolean>;
+}>, import("./shell-tool.ts").BashToolDetails | undefined>;
 //# sourceMappingURL=bash.d.ts.map

package/dist/core/tools/bash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bash.d.ts","sourceRoot":"","sources":["../../../src/core/tools/bash.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bash.d.ts","sourceRoot":"","sources":["../../../src/core/tools/bash.ts"],"names":[],"mappings":"AAEA,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,eAAe,EAGpB,yBAAyB,EAEzB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,gCAAgC,GAChC,MAAM,iBAAiB,CAAC;AACzB,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,MAAM,CAE/G;AAED,wBAAgB,yBAAyB,CAAC,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,cAAc,CAE1F;AAYD,wBAAgB,wBAAwB,CACvC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,eAAe,GACvB,UAAU,CAAC,OAAO,yBAAyB,CAAC,CAK9C;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe;;;;2DAQpE"}