@zpi-dev/agent-sdk 0.0.0-stage → 0.1.61

package/dist/types/coding-agent/src/core/session-manager.d.ts

@@ -0,0 +1,138 @@
+import type { ThinkingLevel } from "../../../agent/src/index.js";
+import type { JsonValue, Message, SystemMessage, Usage } from "../../../ai/src/index.js";
+import type { SessionCurrentState, TranscriptSnapshot, TranscriptState, TranscriptStore } from "./transcript-store.js";
+export interface SessionHeader {
+    type: "session";
+    version: 1 | 2;
+    format: "zpi";
+    id: string;
+    timestamp: string;
+    cwd: string;
+}
+interface EntryBase {
+    id: string;
+    parentId: string | null;
+    timestamp: string;
+}
+export type SessionEntry = EntryBase & ({
+    type: "message";
+    message: Message;
+} | {
+    type: "model_change";
+    provider: string;
+    modelId: string;
+} | {
+    type: "thinking_level_change";
+    thinkingLevel: ThinkingLevel;
+} | {
+    type: "session_info";
+    name: string;
+} | {
+    type: "custom";
+    customType: string;
+    data?: JsonValue;
+} | {
+    type: "microcompact";
+    data: import("./microcompact.js").MicrocompactBoundary;
+} | {
+    type: "compaction";
+    summary: string;
+    firstKeptEntryId: string;
+    tokensBefore?: number;
+    details?: {
+        readFiles: string[];
+        modifiedFiles: string[];
+    };
+    usage?: Usage;
+    systemMessage?: SystemMessage;
+    contextMessage?: SystemMessage;
+});
+export interface SessionContext {
+    messages: Message[];
+    thinkingLevel: ThinkingLevel;
+    model: {
+        provider: string;
+        modelId: string;
+    } | null;
+    lastThinkingLevel: ThinkingLevel;
+}
+export type SessionEntryInput = SessionEntry extends infer Entry ? Entry extends SessionEntry ? Omit<Entry, keyof EntryBase> : never : never;
+export declare class SessionManager {
+    private header;
+    private store?;
+    private currentState?;
+    private contextCache?;
+    private entries;
+    private file?;
+    private storageError?;
+    private appendQueue;
+    private lastEntry?;
+    private appendListeners;
+    subscribeEntries(listener: (entry: SessionEntry) => void): () => void;
+    private constructor();
+    /** Open an already validated indexed store without reading historical message bodies. */
+    static fromStore(store: TranscriptStore, currentState?: SessionCurrentState): SessionManager;
+    static openAsync(store: TranscriptStore, currentState?: SessionCurrentState): Promise<SessionManager>;
+    hasCurrentState(): boolean;
+    getCurrentState(): Pick<TranscriptState, "model" | "thinkingLevel" | "lastThinkingLevel" | "name">;
+    getStateAt(snapshot?: TranscriptSnapshot): TranscriptState;
+    iterateEntries(): Iterable<SessionEntry>;
+    readEntryById(id: string): SessionEntry | undefined;
+    unresolvedToolJournals(): Iterable<SessionEntry[]>;
+    /** Only effective retained entries, suitable for compaction and current usage. */
+    getContextEntries(): SessionEntry[];
+    precedesCompaction(message: Message): boolean;
+    materializeContext(snapshot?: TranscriptSnapshot): Promise<SessionContext>;
+    static create(cwd: string, sessionDir?: string, options?: {
+        id?: string;
+    }): SessionManager;
+    static inMemory(cwd?: string, options?: {
+        id?: string;
+    }, entries?: SessionEntry[]): SessionManager;
+    static open(path: string, _sessionDir?: string, cwdOverride?: string): SessionManager;
+    getSessionId(): string;
+    getSessionFile(): string | undefined;
+    getCwd(): string;
+    /** Move a draft into its worktree before any model messages are committed. */
+    setCwd(cwd: string): void;
+    getEntries(): SessionEntry[];
+    getLastEntry(): SessionEntry | undefined;
+    /** Serialize durable appends, including concurrently finishing tools, before notifying readers. */
+    appendEntryAsync(fields: SessionEntryInput): Promise<string>;
+    private enqueueWrite;
+    private persistEntry;
+    flushAsync(): Promise<void>;
+    appendMessageAsync(message: Message): Promise<string>;
+    appendCustomEntryAsync(customType: string, data?: JsonValue): Promise<string>;
+    setCwdAsync(cwd: string): Promise<void>;
+    replaceEntriesAsync(source: Iterable<SessionEntry>): Promise<void>;
+    /** Atomically replace a transcript after a stable fork or conversation rewind. */
+    replaceEntries(source: Iterable<SessionEntry>): void;
+    private writeTranscript;
+    getMicrocompactClearedIds(): string[];
+    buildSessionContext(snapshot?: TranscriptSnapshot): SessionContext;
+    appendMessage(message: Message): string;
+    appendModelChange(provider: string, modelId: string): string;
+    appendThinkingLevelChange(thinkingLevel: ThinkingLevel): string;
+    appendSessionInfo(name: string): string;
+    appendMicrocompact(data: import("./microcompact.js").MicrocompactBoundary): string;
+    appendCustomEntry(customType: string, data?: JsonValue): string;
+    appendCompaction(summary: string, firstKeptEntryId: string, tokensBefore?: number, details?: {
+        readFiles: string[];
+        modifiedFiles: string[];
+    }, usage?: Usage): string;
+    appendCompactionAsync(...args: Parameters<SessionManager["appendCompaction"]>): Promise<string>;
+    private compactionInput;
+    private createEntry;
+    private publishEntry;
+    private append;
+}
+export type CompactionEntry = Extract<SessionEntry, {
+    type: "compaction";
+}>;
+/** Entries are append-only. Like Pi, context projection shares immutable message records. */
+export declare function sessionEntryToContextMessages(entry: SessionEntry): Message[];
+export declare function buildSessionContext(entries: SessionEntry[]): SessionContext;
+/** Stream ID remapping without retaining the whole transcript. */
+export declare function remapSessionEntries(source: Iterable<SessionEntry>): Iterable<SessionEntry>;
+export {};

package/dist/types/coding-agent/src/core/session-state.d.ts

@@ -0,0 +1,14 @@
+import type { ThinkingLevel } from "../../../agent/src/index.js";
+import type { ContextBreakdownItem, Model } from "../../../ai/src/index.js";
+import type { SessionEntry } from "./session-manager.js";
+export interface ContextUsage {
+    contextWindow: number;
+    inputTokens: number | null;
+    percent: number | null;
+    timestamp: number | null;
+    source: "server usage" | "unknown";
+    breakdown?: ContextBreakdownItem[];
+    averageCacheHitRate?: number | null;
+}
+export declare function contextUsage(entries: SessionEntry[], model: Model): ContextUsage;
+export declare function supportedThinkingLevels(model: Model): ThinkingLevel[];

package/dist/types/coding-agent/src/core/settings-manager.d.ts

@@ -0,0 +1,41 @@
+import type { ThinkingLevel } from "../../../agent/src/index.js";
+import { type Model, type RetryPolicy } from "../../../ai/src/index.js";
+import { type CompactionOptions, type CompactionSettings } from "./compaction.js";
+export interface ProviderRetrySettings {
+    timeoutMs?: number;
+    maxRetries?: number;
+    maxRetryDelayMs?: number;
+}
+export interface RetrySettings extends Partial<RetryPolicy> {
+    provider?: ProviderRetrySettings;
+}
+export interface Settings {
+    defaultThinkingLevel?: ThinkingLevel;
+    modelThinkingLevels?: Record<string, ThinkingLevel>;
+    compaction?: CompactionOptions;
+    retry?: RetrySettings;
+    httpIdleTimeoutMs?: number | string;
+    streamIdleTimeoutMs?: number;
+    streamFirstResponseTimeoutMs?: number;
+}
+export declare class SettingsManager {
+    private settings;
+    private errors;
+    constructor(settings?: Settings);
+    static inMemory(settings?: Settings): SettingsManager;
+    static create(cwd?: string, agentDir?: string): SettingsManager;
+    getErrors(): {
+        path: string;
+        error: Error;
+    }[];
+    applyOverrides(overrides: Settings): void;
+    getDefaultThinkingLevel(): ThinkingLevel | undefined;
+    getModelThinkingLevel(provider: string, id: string): ThinkingLevel | undefined;
+    getCompactionSettings(model?: Pick<Model, "provider" | "id">): CompactionSettings;
+    getMicrocompactSettings(): import("./microcompact.js").MicrocompactConfig;
+    getRetrySettings(): RetryPolicy;
+    getProviderRetrySettings(): ProviderRetrySettings;
+    getStreamIdleTimeoutMs(): number;
+    getStreamFirstResponseTimeoutMs(): number;
+    getHttpIdleTimeoutMs(): number;
+}

package/dist/types/coding-agent/src/core/streaming-tool-journal.d.ts

@@ -0,0 +1,17 @@
+import type { AgentEvent } from "../../../agent/src/index.js";
+import type { Message } from "../../../ai/src/index.js";
+import type { SessionEntry, SessionManager } from "./session-manager.js";
+/** Calls are durable before execute; results are durable before the batch settles. */
+export declare class StreamingToolJournal {
+    private partial?;
+    private journal?;
+    private manager;
+    private notify;
+    constructor(manager: SessionManager, notify: () => void);
+    private save;
+    observe(event: AgentEvent): Promise<void>;
+}
+export declare function recoverStreamedToolJournal(manager: SessionManager): void;
+/** History rendering also works before the writable SDK session is opened. */
+export declare function projectStreamedToolJournal(entries: SessionEntry[]): SessionEntry[];
+export declare function recoverCanonicalToolCallsAsync(manager: SessionManager, messages: Message[]): Promise<void>;

package/dist/types/coding-agent/src/core/system-prompt.d.ts

@@ -0,0 +1,32 @@
+import type { AgentTool } from "../../../agent/src/index.js";
+import { type ResourceLoader } from "./types.js";
+export interface PromptTemplate {
+    id: string;
+    name: string;
+    preamble: string;
+    rules: string;
+}
+export declare const piTemplate: PromptTemplate;
+export declare function validateTemplate(template: PromptTemplate): void;
+export declare function renderTemplate(text: string, context: {
+    cwd: string;
+    project_name: string;
+    platform: string;
+}): string;
+export interface SystemContext {
+    base: string;
+    sections: Record<string, string>;
+}
+export declare function buildSystemContext(options: {
+    cwd: string;
+    projectName?: string;
+    platform?: string;
+    template?: PromptTemplate;
+    tools: readonly Pick<AgentTool, "name" | "description" | "promptSnippet" | "promptGuidelines">[];
+    loader?: ResourceLoader;
+    /** Literal instructions appended after resources, before the skill catalog and working directory. */
+    customInstructions?: readonly string[];
+    baseInstructions?: string;
+}): SystemContext;
+/** Human-readable preview; model requests use the independently managed blocks. */
+export declare function buildSystemPrompt(options: Parameters<typeof buildSystemContext>[0]): string;

package/dist/types/coding-agent/src/core/tools/file-change.d.ts

@@ -0,0 +1,21 @@
+export interface FileChange {
+    path: string;
+    operation: "created" | "modified";
+    toolCallId: string;
+    beforeHash: string | null;
+    afterHash: string;
+    patch?: string;
+    patchFile?: string;
+    beforeFile?: string;
+    afterFile?: string;
+    reason?: string;
+    failed?: boolean;
+    additions?: number;
+    deletions?: number;
+}
+export declare function beforeFile(path: string): Promise<Buffer | null>;
+export declare function recordFileChange(path: string, toolCallId: string, before: Buffer | null, outputDir?: string, failed?: boolean): Promise<FileChange | undefined>;
+export declare function patchLineCounts(patch: string): {
+    additions: number;
+    deletions: number;
+};

package/dist/types/coding-agent/src/core/tools/index.d.ts

@@ -0,0 +1,20 @@
+import type { AgentTool } from "../../../../agent/src/index.js";
+import type { Model } from "../../../../ai/src/index.js";
+import type { ToolContext } from "../types.js";
+import { type BashToolOptions } from "./pi/bash.js";
+import { type EditToolOptions } from "./pi/edit.js";
+import { FileReadState } from "./pi/file-read-state.js";
+import { type ReadToolOptions } from "./pi/read.js";
+import { type WriteToolOptions } from "./pi/write.js";
+export { createBashToolDefinition, createLocalBashOperations } from "./pi/bash.js";
+export { createEditToolDefinition } from "./pi/edit.js";
+export { FileReadState } from "./pi/file-read-state.js";
+export { createReadToolDefinition } from "./pi/read.js";
+export { createWriteToolDefinition } from "./pi/write.js";
+export type { BashToolOptions, EditToolOptions, ReadToolOptions, WriteToolOptions };
+export type ToolContextFactory = () => Partial<ToolContext> | undefined;
+export declare function createReadTool(cwd: string, options?: ReadToolOptions | (() => Model), context?: ToolContextFactory): AgentTool;
+export declare function createBashTool(cwd: string, options?: BashToolOptions, context?: ToolContextFactory): AgentTool;
+export declare function createWriteTool(cwd: string, options?: WriteToolOptions | string, context?: ToolContextFactory): AgentTool;
+export declare function createEditTool(cwd: string, options?: EditToolOptions | string, context?: ToolContextFactory): AgentTool;
+export declare function createCodingTools(cwd: string, outputDir?: string, getModel?: () => Model, context?: ToolContextFactory, fileReadState?: FileReadState): AgentTool[];

package/dist/types/coding-agent/src/core/tools/pi/bash.d.ts

@@ -0,0 +1,185 @@
+import { type Static, Type } from "typebox";
+import type { ToolContext } from "../../types.js";
+import { type TruncationResult } from "./truncate.js";
+import { type ShellConfig } from "./utils/shell.js";
+export declare const bashToolSystemPromptContribution: {
+    readonly snippet: "Execute bash commands (ls, grep, find, etc.)";
+    readonly guidelines: readonly ["You can inspect ZPI_* environment variables for current model and session details."];
+};
+/**
+ * Result for programmatic callers such as codemode scripts. A non-zero exit code is an error result for the model, but scripts still resolve to this value.
+ * `output` is not limited like the model-facing output: callers decide how much of it reaches the model.
+ */
+declare const bashOutputSchema: Type.TObject<{
+    output: Type.TString;
+    truncated: Type.TBoolean;
+    full_output_path: Type.TOptional<Type.TString>;
+    exit_code: Type.TNumber;
+    wall_time_seconds: Type.TNumber;
+}>;
+export type BashToolOutput = Static<typeof bashOutputSchema>;
+export interface BashToolDetails {
+    truncation?: TruncationResult;
+    fullOutputPath?: 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.
+     */
+    exec: (command: string, cwd: string, options: {
+        /**
+         * Await returned promises before delivering another chunk to bound pending output writes.
+         * Other return values are ignored, as with the original synchronous callback.
+         */
+        onData: (data: Buffer, stream?: "stdout" | "stderr") => unknown;
+        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): BashOperations;
+/**
+ * Create bash operations using the local shell execution backend.
+ */
+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 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 ZPI session metadata as ZPI_* environment variables. Default: true */
+    exposeSessionEnvironment?: boolean;
+    /** Hook to adjust command, cwd, or env before execution */
+    spawnHook?: BashSpawnHook;
+}
+export interface ShellToolConfig {
+    name: string;
+    label: string;
+    shellName: string;
+    promptSnippet: string;
+    promptGuidelines?: readonly string[];
+    tempFilePrefix: string;
+}
+export declare function createShellToolDefinition(cwd: string, config: ShellToolConfig, options?: BashToolOptions): {
+    name: string;
+    label: string;
+    description: string;
+    promptSnippet: string;
+    promptGuidelines: string[] | undefined;
+    parameters: Type.TObject<{
+        command: Type.TString;
+        timeout: Type.TOptional<Type.TNumber>;
+    }>;
+    outputSchema: Type.TObject<{
+        output: Type.TString;
+        truncated: Type.TBoolean;
+        full_output_path: Type.TOptional<Type.TString>;
+        exit_code: Type.TNumber;
+        wall_time_seconds: Type.TNumber;
+    }>;
+    execute(_toolCallId: string, { command, timeout }: {
+        command: string;
+        timeout?: number;
+    }, signal?: AbortSignal, onUpdate?: import("../../../../../agent/src/index.js").AgentToolUpdateCallback<BashToolDetails | undefined> | undefined, ctx?: Partial<ToolContext>): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: BashToolDetails | undefined;
+        structuredContent: {
+            output: string;
+            truncated: boolean;
+            full_output_path?: string | undefined;
+            exit_code: number;
+            wall_time_seconds: number;
+        };
+        isError: true;
+    } | {
+        isError?: undefined;
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: BashToolDetails | undefined;
+        structuredContent: {
+            output: string;
+            truncated: boolean;
+            full_output_path?: string | undefined;
+            exit_code: number;
+            wall_time_seconds: number;
+        };
+    }>;
+};
+export declare function createBashToolDefinition(cwd: string, options?: BashToolOptions): {
+    name: string;
+    label: string;
+    description: string;
+    promptSnippet: string;
+    promptGuidelines: string[] | undefined;
+    parameters: Type.TObject<{
+        command: Type.TString;
+        timeout: Type.TOptional<Type.TNumber>;
+    }>;
+    outputSchema: Type.TObject<{
+        output: Type.TString;
+        truncated: Type.TBoolean;
+        full_output_path: Type.TOptional<Type.TString>;
+        exit_code: Type.TNumber;
+        wall_time_seconds: Type.TNumber;
+    }>;
+    execute(_toolCallId: string, { command, timeout }: {
+        command: string;
+        timeout?: number;
+    }, signal?: AbortSignal, onUpdate?: import("../../../../../agent/src/index.js").AgentToolUpdateCallback<BashToolDetails | undefined> | undefined, ctx?: Partial<ToolContext>): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: BashToolDetails | undefined;
+        structuredContent: {
+            output: string;
+            truncated: boolean;
+            full_output_path?: string | undefined;
+            exit_code: number;
+            wall_time_seconds: number;
+        };
+        isError: true;
+    } | {
+        isError?: undefined;
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: BashToolDetails | undefined;
+        structuredContent: {
+            output: string;
+            truncated: boolean;
+            full_output_path?: string | undefined;
+            exit_code: number;
+            wall_time_seconds: number;
+        };
+    }>;
+};
+export {};

package/dist/types/coding-agent/src/core/tools/pi/edit-diff.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Shared diff computation utilities for the edit and similar tools.
+ */
+export declare function detectLineEnding(content: string): "\r\n" | "\r" | "\n";
+export declare function normalizeToLF(text: string): string;
+export declare function restoreLineEndings(text: string, ending: "\r\n" | "\r" | "\n"): string;
+/**
+ * Normalize text for fuzzy matching. Applies progressive transformations:
+ * - Strip trailing whitespace from each line
+ * - Normalize smart quotes to ASCII equivalents
+ * - Normalize Unicode dashes/hyphens to ASCII hyphen
+ * - Normalize special Unicode spaces to regular space
+ */
+export declare function normalizeForFuzzyMatch(text: string): string;
+interface MatchedEdit {
+    editIndex: number;
+    matchIndex: number;
+    matchLength: number;
+    newText: string;
+}
+type TextReplacement = Pick<MatchedEdit, "matchIndex" | "matchLength" | "newText">;
+/**
+ * Apply replacements matched against `baseContent` to `originalContent` while
+ * preserving unchanged line blocks from the original.
+ *
+ * This is useful when `baseContent` is a normalized view of the original. Each
+ * replacement is widened to the lines it actually touches, those touched lines
+ * are rewritten from the normalized base, and all other lines are copied back
+ * from `originalContent`. The actual replacement ranges drive preservation so
+ * duplicate normalized lines cannot be aligned to the wrong occurrence.
+ */
+export declare function applyReplacementsPreservingUnchangedLines(originalContent: string, baseContent: string, replacements: TextReplacement[]): string;
+export interface FuzzyMatchResult {
+    /** Whether a match was found */
+    found: boolean;
+    /** The index where the match starts (in the content that should be used for replacement) */
+    index: number;
+    /** Length of the matched text */
+    matchLength: number;
+    /** Whether fuzzy matching was used (false = exact match) */
+    usedFuzzyMatch: boolean;
+    /**
+     * The content to use for replacement operations.
+     * When exact match: original content. When fuzzy match: normalized content.
+     */
+    contentForReplacement: string;
+}
+export interface Edit {
+    oldText: string;
+    newText: string;
+}
+export interface AppliedEditsResult {
+    baseContent: string;
+    newContent: string;
+}
+/**
+ * Find oldText in content, trying exact match first, then fuzzy match.
+ * When fuzzy matching is used, the returned contentForReplacement is the
+ * fuzzy-normalized version of the content (trailing whitespace stripped,
+ * Unicode quotes/dashes normalized to ASCII).
+ */
+export declare function fuzzyFindText(content: string, oldText: string): FuzzyMatchResult;
+/**
+ * Apply one or more exact-text replacements to LF-normalized content.
+ *
+ * All edits are matched against the same original content. Replacements are
+ * then applied in reverse order so offsets remain stable. If any edit needs
+ * fuzzy matching, the operation runs in fuzzy-normalized content space and then
+ * overlays those line-level changes onto the original content so unchanged line
+ * blocks keep their original bytes. Supply originalContent to also preserve its
+ * line endings; changed blocks use the ending of their first original line.
+ */
+export declare function applyEditsToNormalizedContent(normalizedContent: string, edits: Edit[], path: string, originalContent?: string): AppliedEditsResult;
+/** Generate a standard unified patch, or omit it when the computation budget is exceeded. */
+export declare function generateUnifiedPatch(path: string, oldContent: string, newContent: string, contextLines?: number): string | undefined;
+/**
+ * Generate a display-oriented diff string with line numbers and context.
+ * Returns both the diff string and the first changed line number (in the new file).
+ */
+export declare function generateDiffString(oldContent: string, newContent: string, contextLines?: number): {
+    diff: string | undefined;
+    firstChangedLine: number | undefined;
+};
+export {};

package/dist/types/coding-agent/src/core/tools/pi/edit.d.ts

@@ -0,0 +1,69 @@
+import { type Static, Type } from "typebox";
+import type { ToolContext } from "../../types.js";
+import type { FileReadState } from "./file-read-state.js";
+declare const editSchema: Type.TObject<{
+    path: Type.TString;
+    edits: Type.TArray<Type.TObject<{
+        oldText: Type.TString;
+        newText: Type.TString;
+    }>>;
+}>;
+export declare const editToolSystemPromptContribution: {
+    readonly snippet: "Make precise file edits with exact text replacement, including multiple disjoint edits in one call";
+    readonly guidelines: readonly ["Use edit for precise changes (edits[].oldText must match exactly)", "When changing multiple separate locations in one file, use one edit call with multiple entries in edits[] instead of multiple edit calls", "Each edits[].oldText is matched against the original file, not after earlier edits are applied. Do not emit overlapping or nested edits. Merge nearby changes into one edit.", "Keep edits[].oldText as small as possible while still being unique in the file. Do not pad with large unchanged regions."];
+};
+export type EditToolInput = Static<typeof editSchema>;
+export interface EditToolDetails {
+    /** Display-oriented diff of the changes made */
+    diff: string;
+    /** Standard unified patch of the changes made */
+    patch: string;
+    /** Line number of the first change in the new file (for editor navigation) */
+    firstChangedLine?: number;
+}
+/**
+ * Pluggable operations for the edit tool.
+ * Override these to delegate file editing to remote systems (for example SSH).
+ */
+export interface EditOperations {
+    /** Read file contents as a Buffer */
+    readFile: (absolutePath: string) => Promise<Buffer>;
+    /** Write content to a file */
+    writeFile: (absolutePath: string, content: string) => Promise<void>;
+    /** Check if file is readable and writable (throw if not) */
+    access: (absolutePath: string) => Promise<void>;
+}
+export interface EditToolOptions {
+    /** Shared knowledge of file contents in the current model context. */
+    fileReadState?: FileReadState;
+    /** Custom operations for file editing. Default: local filesystem */
+    operations?: EditOperations;
+}
+declare function prepareEditArguments(input: unknown): EditToolInput;
+export declare function createEditToolDefinition(cwd: string, options?: EditToolOptions): {
+    name: string;
+    label: string;
+    description: string;
+    promptSnippet: "Make precise file edits with exact text replacement, including multiple disjoint edits in one call";
+    promptGuidelines: ("Each edits[].oldText is matched against the original file, not after earlier edits are applied. Do not emit overlapping or nested edits. Merge nearby changes into one edit." | "Keep edits[].oldText as small as possible while still being unique in the file. Do not pad with large unchanged regions." | "Use edit for precise changes (edits[].oldText must match exactly)" | "When changing multiple separate locations in one file, use one edit call with multiple entries in edits[] instead of multiple edit calls")[];
+    parameters: Type.TObject<{
+        path: Type.TString;
+        edits: Type.TArray<Type.TObject<{
+            oldText: Type.TString;
+            newText: Type.TString;
+        }>>;
+    }>;
+    prepareArguments: typeof prepareEditArguments;
+    execute(_toolCallId: string, input: EditToolInput, signal?: AbortSignal, _onUpdate?: import("../../../../../agent/src/index.js").AgentToolUpdateCallback<EditToolDetails | undefined> | undefined, ctx?: Partial<ToolContext>): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: {
+            diff: string;
+            patch: string;
+            firstChangedLine: number | undefined;
+        };
+    }>;
+};
+export {};

package/dist/types/coding-agent/src/core/tools/pi/file-mutation-queue.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Serialize file mutation operations targeting the same file.
+ * Operations for different files still run in parallel.
+ */
+export declare function withFileMutationQueue<T>(filePath: string, fn: () => Promise<T>): Promise<T>;

package/dist/types/coding-agent/src/core/tools/pi/file-read-state.d.ts

@@ -0,0 +1,12 @@
+/** File contents known to the model in one live context; no transcript or disk cache. */
+export declare class FileReadState {
+    private files;
+    clear(): void;
+    isUnchanged(path: string, content: string, offset?: number, limit?: number): boolean;
+    /** Reuse an incremental decoded-text hash without retaining the full file. */
+    isHashUnchanged(path: string, hash: string, offset?: number, limit?: number): boolean;
+    recordRead(path: string, content: string, offset?: number, limit?: number, truncated?: boolean): void;
+    recordReadHash(path: string, hash: string, offset?: number, limit?: number, truncated?: boolean): void;
+    recordWrite(path: string, content: string): void;
+    recordEdit(path: string, before: string, after: string): void;
+}