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

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

@@ -0,0 +1,68 @@
+import { type TruncationResult } from "./truncate.js";
+export interface OutputAccumulatorOptions {
+    maxLines?: number;
+    maxBytes?: number;
+    tempFilePrefix?: string;
+}
+export interface OutputSnapshot {
+    content: string;
+    truncation: TruncationResult;
+    fullOutputPath?: string;
+}
+export interface FullOutput {
+    content: string;
+    /** Whether `content` omits part of the output. */
+    truncated: boolean;
+}
+/** Keep recent output available to read, and prune expired logs on the next bash invocation. */
+export declare function cleanupOutputFiles(prefix: string, directory?: string): Promise<void>;
+/**
+ * Incrementally tracks streaming output with bounded memory when producers await `append`.
+ *
+ * Appends decode chunks with a streaming UTF-8 decoder, keeps only a decoded
+ * tail for display snapshots, and opens a temp file when the full output needs
+ * to be preserved.
+ */
+export declare class OutputAccumulator {
+    private readonly maxLines;
+    private readonly maxBytes;
+    private readonly maxRollingBytes;
+    private readonly tempFilePrefix;
+    private readonly decoder;
+    private rawChunks;
+    private tailText;
+    private tailBytes;
+    private tailStartsAtLineBoundary;
+    private totalRawBytes;
+    private totalDecodedBytes;
+    private completedLines;
+    private totalLines;
+    private currentLineBytes;
+    private hasOpenLine;
+    private finished;
+    private tempFilePath;
+    private tempFileStream;
+    private tempFileError;
+    private tempFileDrain;
+    constructor(options?: OutputAccumulatorOptions);
+    /** Await the returned promise, when present, before appending another chunk. */
+    append(data: Buffer): void | Promise<void>;
+    finish(): void;
+    snapshot(options?: {
+        persistIfTruncated?: boolean;
+    }): OutputSnapshot;
+    closeTempFile(): Promise<void>;
+    /**
+     * The complete output, for callers that can take more than the display snapshot. Call after
+     * `finish()` and `closeTempFile()`. Output longer than `maxBytes` raw bytes keeps its first and
+     * last `maxBytes / 2` bytes around an omission marker.
+     */
+    readFullOutput(maxBytes: number): Promise<FullOutput>;
+    getLastLineBytes(): number;
+    private appendDecodedText;
+    private trimTail;
+    private getSnapshotText;
+    private shouldUseTempFile;
+    private waitForTempFileDrain;
+    private ensureTempFile;
+}

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

@@ -0,0 +1,7 @@
+export declare function pathExists(filePath: string): Promise<boolean>;
+/**
+ * Resolve a path relative to the given cwd.
+ * Handles ~ expansion and absolute paths.
+ */
+export declare function resolveToCwd(filePath: string, cwd: string): string;
+export declare function resolveReadPathAsync(filePath: string, cwd: string): Promise<string>;

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

@@ -0,0 +1,63 @@
+import type { ImageContent, TextContent } from "../../../../../ai/src/index.js";
+import { Type } from "typebox";
+import type { ToolContext } from "../../types.js";
+import { FileReadState } from "./file-read-state.js";
+import { type TruncationResult } from "./truncate.js";
+import type { ImageResizeOptions as ModelImageResizeOptions } from "./utils/image-resize-core.js";
+export declare const readToolSystemPromptContribution: {
+    readonly snippet: "Read file contents";
+    readonly guidelines: readonly ["Use read to examine files instead of cat or sed."];
+};
+export interface ReadToolDetails {
+    truncation?: TruncationResult;
+}
+/**
+ * Pluggable operations for the read tool.
+ * Override these to delegate file reading to remote systems (for example SSH).
+ */
+export interface ReadOperations {
+    /** Read file contents as a Buffer. Bound source I/O to maxBytes + 1 when a limit is supplied. */
+    readFile: (absolutePath: string, maxBytes?: number) => Promise<Buffer>;
+    /** Check if file is readable (throw if not) */
+    access: (absolutePath: string) => Promise<void>;
+    /** Detect image MIME type, return null or undefined for non-images */
+    detectImageMimeType?: (absolutePath: string) => Promise<string | null | undefined>;
+}
+export interface ReadToolOptions {
+    /** Shared knowledge of file contents in the current model context. */
+    fileReadState?: FileReadState;
+    /** Whether to auto-resize images. Default: true */
+    autoResizeImages?: boolean;
+    /** Fallback resize profile when the execution context has no model metadata. */
+    resizeOptions?: ModelImageResizeOptions;
+    /** Custom operations for file reading. Default: local filesystem */
+    operations?: ReadOperations;
+}
+export declare function createReadToolDefinition(cwd: string, options?: ReadToolOptions): {
+    name: string;
+    metadata: {
+        readOnly: true;
+        concurrentSafe: true;
+        destructive: false;
+        needsApproval: false;
+        requiresUserInteraction: false;
+        sideEffectScope: "none";
+    };
+    label: string;
+    description: string;
+    promptSnippet: "Read file contents";
+    promptGuidelines: "Use read to examine files instead of cat or sed."[];
+    parameters: Type.TObject<{
+        path: Type.TString;
+        offset: Type.TOptional<Type.TInteger>;
+        limit: Type.TOptional<Type.TInteger>;
+    }>;
+    execute(_toolCallId: string, { path, offset, limit }: {
+        path: string;
+        offset?: number;
+        limit?: number;
+    }, signal?: AbortSignal, _onUpdate?: import("../../../../../agent/src/index.js").AgentToolUpdateCallback<ReadToolDetails | undefined> | undefined, ctx?: Partial<ToolContext>): Promise<{
+        content: (TextContent | ImageContent)[];
+        details: ReadToolDetails | undefined;
+    }>;
+};

package/dist/types/coding-agent/src/core/tools/pi/text-range-reader.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Count and hash the entire decoded file, but retain only a bounded prefix of the
+ * requested range. Never buffer a whole line: a single line can be arbitrarily large.
+ */
+export declare function readTextRange(chunks: AsyncIterable<string> | Iterable<string>, offset?: number, limit?: number): Promise<{
+    hash: string;
+    totalFileLines: number;
+    firstLineBytes: number;
+    truncation: {
+        content: string;
+        truncated: boolean;
+        truncatedBy: "lines" | "bytes" | null;
+        outputLines: number;
+        outputBytes: number;
+        lastLinePartial: boolean;
+        firstLineExceedsLimit: boolean;
+        maxLines: number;
+        maxBytes: number;
+        totalLines: number;
+        totalBytes: number;
+    };
+}>;

package/dist/types/coding-agent/src/core/tools/pi/tool-definition-wrapper.d.ts

@@ -0,0 +1,4 @@
+import type { AgentTool } from "../../../../../agent/src/index.js";
+import type { TSchema } from "typebox";
+import type { ToolDefinition } from "../../types.js";
+export declare function wrapToolDefinition<T extends TSchema, D, C>(definition: ToolDefinition<T, D, C>, context: (signal?: AbortSignal) => C, serializeDetails?: boolean): AgentTool<T>;

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

@@ -0,0 +1,60 @@
+/**
+ * Shared truncation utilities for tool outputs.
+ *
+ * Truncation is based on two independent limits - whichever is hit first wins:
+ * - Line limit (default: 2000 lines)
+ * - Byte limit (default: 50KB)
+ *
+ * Never returns partial lines (except bash tail truncation edge case).
+ */
+export declare const DEFAULT_MAX_LINES = 2000;
+export declare const DEFAULT_MAX_BYTES: number;
+export interface TruncationResult {
+    /** The truncated content */
+    content: string;
+    /** Whether truncation occurred */
+    truncated: boolean;
+    /** Which limit was hit: "lines", "bytes", or null if not truncated */
+    truncatedBy: "lines" | "bytes" | null;
+    /** Total number of lines in the original content */
+    totalLines: number;
+    /** Total number of bytes in the original content */
+    totalBytes: number;
+    /** Number of complete lines in the truncated output */
+    outputLines: number;
+    /** Number of bytes in the truncated output */
+    outputBytes: number;
+    /** Whether the last line was partially truncated (only for tail truncation edge case) */
+    lastLinePartial: boolean;
+    /** Whether the first line exceeded the byte limit (for head truncation) */
+    firstLineExceedsLimit: boolean;
+    /** The max lines limit that was applied */
+    maxLines: number;
+    /** The max bytes limit that was applied */
+    maxBytes: number;
+}
+export interface TruncationOptions {
+    /** Maximum number of lines (default: 2000) */
+    maxLines?: number;
+    /** Maximum number of bytes (default: 50KB) */
+    maxBytes?: number;
+}
+/**
+ * Format bytes as human-readable size.
+ */
+export declare function formatSize(bytes: number): string;
+/**
+ * Truncate content from the head (keep first N lines/bytes).
+ * Suitable for file reads where you want to see the beginning.
+ *
+ * Never returns partial lines. If first line exceeds byte limit,
+ * returns empty content with firstLineExceedsLimit=true.
+ */
+export declare function truncateHead(content: string, options?: TruncationOptions): TruncationResult;
+/**
+ * Truncate content from the tail (keep last N lines/bytes).
+ * Suitable for bash output where you want to see the end (errors, final results).
+ *
+ * May return partial first line if the last line of original content exceeds byte limit.
+ */
+export declare function truncateTail(content: string, options?: TruncationOptions): TruncationResult;

package/dist/types/coding-agent/src/core/tools/pi/utils/bmp-source.d.ts

@@ -0,0 +1,2 @@
+/** Normalize validated Windows BMPs to the uncompressed layout bmp-js reliably decodes. */
+export declare function normalizeBmp(input: Buffer): Buffer;

package/dist/types/coding-agent/src/core/tools/pi/utils/child-process.d.ts

@@ -0,0 +1,13 @@
+import type { ChildProcess } from "node:child_process";
+/**
+ * Wait for a child process to terminate without hanging on inherited stdio handles.
+ *
+ * A short-lived child can `exit` while a detached descendant keeps its stdout/stderr
+ * pipe open. We must not resolve and destroy the streams on a fixed deadline measured
+ * from `exit`, or output still being written past that deadline is silently lost
+ * (earendil-works/pi#5303). Instead, after `exit` we wait for the pipes to fall idle:
+ * the grace timer is re-armed on every chunk, so an actively writing descendant keeps
+ * us reading, while a quiet inherited handle (e.g. a Windows daemonized descendant
+ * that never lets `close` fire) still releases us after the grace elapses.
+ */
+export declare function waitForChildProcess(child: ChildProcess): Promise<number | null>;

package/dist/types/coding-agent/src/core/tools/pi/utils/image-budget.d.ts

@@ -0,0 +1,16 @@
+import type { ImageResizeOptions } from "./image-resize-core.js";
+export interface ImageBudget {
+    maxRawBytes: number;
+    maxBase64Bytes: number;
+    maxTokens?: number;
+    tokenToBase64CharRatio: number;
+}
+export declare function imageBudget(options?: ImageResizeOptions): ImageBudget;
+export declare function fitsImageBudget(bytes: Uint8Array, budget: ImageBudget): boolean;
+/** Model profiles can tighten Read's limits, never relax its independent 25K image-token budget. */
+export declare function readImageResizeOptions(options?: ImageResizeOptions): ImageResizeOptions;
+export type ImageProcessorErrorCode = "invalid_request" | "empty" | "processing_failed" | "too_large" | "unsupported";
+export declare class ImageProcessorError extends Error {
+    readonly code: ImageProcessorErrorCode;
+    constructor(code: ImageProcessorErrorCode, message: string);
+}

package/dist/types/coding-agent/src/core/tools/pi/utils/image-process.d.ts

@@ -0,0 +1,18 @@
+import { type ImageResizeOptions } from "./image-resize.js";
+export interface ProcessImageOptions {
+    autoResizeImages?: boolean;
+    resizeOptions?: ImageResizeOptions;
+}
+export type ProcessImageResult = {
+    ok: true;
+    data: string;
+    mimeType: string;
+    hints: string[];
+    strategy?: string;
+} | {
+    ok: false;
+    message: string;
+    code?: string;
+};
+/** Attachments deliberately omit maxTokens: 5 MiB base64, unlike Read's 200,000 bytes. */
+export declare function processImage(bytes: Uint8Array, mimeType: string, options?: ProcessImageOptions): Promise<ProcessImageResult>;

package/dist/types/coding-agent/src/core/tools/pi/utils/image-resize-core.d.ts

@@ -0,0 +1,26 @@
+export interface ImageResizeOptions {
+    maxWidth?: number;
+    maxHeight?: number;
+    /** Encoded base64 bytes, excluding the data URL prefix. Attachments default to 5 MiB. */
+    maxBytes?: number;
+    maxRawBytes?: number;
+    /** Image input tokens, never the model's output limit. Omitted deliberately for user attachments. */
+    maxTokens?: number;
+    tokenToBase64CharRatio?: number;
+    /** Optional stricter starting quality; the default ladder is 80, 60, 40, 20. */
+    jpegQuality?: number;
+}
+export interface ResizedImage {
+    data: string;
+    mimeType: string;
+    originalWidth: number;
+    originalHeight: number;
+    width: number;
+    height: number;
+    wasResized: boolean;
+    originalMimeType?: string;
+    animated?: boolean;
+    strategy: "original" | "png-optimized" | "preserve-format" | "resized" | "jpeg-quality" | "jpeg-fallback";
+}
+/** First fitting candidate wins. Compression can reach quality 20 / 200px: small text may be unreadable. */
+export declare function resizeImageInProcess(inputBytes: Uint8Array, mimeType: string, options?: ImageResizeOptions, autoResizeImages?: boolean): Promise<ResizedImage>;

package/dist/types/coding-agent/src/core/tools/pi/utils/image-resize.d.ts

@@ -0,0 +1,3 @@
+import type { ResizedImage } from "./image-resize-core.js";
+export type { ImageResizeOptions, ResizedImage } from "./image-resize-core.js";
+export declare function formatDimensionNote(result: ResizedImage): string | undefined;

package/dist/types/coding-agent/src/core/tools/pi/utils/image-source.d.ts

@@ -0,0 +1,11 @@
+import { type Sharp } from "sharp";
+export declare function imageFormat(bytes: Uint8Array): string | undefined;
+/** Decode the first frame with the same pixel guard for attachments and the read tool. */
+export declare function openImage(bytes: Uint8Array): Promise<{
+    pipeline: Sharp;
+    mimeType: string;
+    width: number;
+    height: number;
+    orientation: number;
+    animated: boolean;
+}>;

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

@@ -0,0 +1,3 @@
+export declare function detectSupportedImageMimeType(buffer: Uint8Array): string | null;
+export declare function detectSupportedImageMimeTypeFromFile(filePath: string): Promise<string | null>;
+export declare function isAnimatedPng(buffer: Uint8Array): boolean;

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

@@ -0,0 +1,16 @@
+export interface PathInputOptions {
+    /** Trim leading/trailing whitespace before normalization. */
+    trim?: boolean;
+    /** Expand leading `~` to a home directory. Defaults to true. */
+    expandTilde?: boolean;
+    /** Home directory used for `~` expansion. Defaults to `os.homedir()`. */
+    homeDir?: string;
+    /** Strip a leading `@`, used for CLI @file paths. */
+    stripAtPrefix?: boolean;
+    /** Normalize unicode space variants to regular spaces. */
+    normalizeUnicodeSpaces?: boolean;
+}
+/** Convert Git Bash, MSYS, Cygwin, and WSL drive paths to a form native Windows APIs accept. */
+export declare function normalizeWindowsShellPath(filePath: string): string;
+export declare function normalizePath(input: string, options?: PathInputOptions): string;
+export declare function resolvePath(input: string, baseDir?: string, options?: PathInputOptions): string;

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

@@ -0,0 +1,2 @@
+/** Inspect the opened handle without waiting for a FIFO writer, including through symlinks. */
+export declare function readRegularFile(path: string): Promise<Buffer>;

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

@@ -0,0 +1,18 @@
+export interface ShellConfig {
+    shell: string;
+    args: string[];
+    commandTransport?: "argv" | "stdin";
+}
+/**
+ * Resolve shell configuration based on platform and an optional explicit shell path.
+ * Resolution order:
+ * 1. User-specified shellPath
+ * 2. On Windows: Git Bash in known locations, then bash on PATH
+ * 3. On Unix: /bin/bash, then bash on PATH, then fallback to sh
+ */
+export declare function getShellConfig(customShellPath?: string): ShellConfig;
+export declare function getShellEnv(): NodeJS.ProcessEnv;
+/**
+ * Kill a process and all its children (cross-platform)
+ */
+export declare function killProcessTree(pid: number): void;

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

@@ -0,0 +1,5 @@
+/** Split a leading UTF-8 byte order mark from decoded text. */
+export declare function splitBom(content: string): {
+    bom: string;
+    text: string;
+};

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

@@ -0,0 +1,44 @@
+import { Type } from "typebox";
+import type { ToolContext } from "../../types.js";
+import type { FileReadState } from "./file-read-state.js";
+export declare const writeToolSystemPromptContribution: {
+    readonly snippet: "Create or overwrite files";
+    readonly guidelines: readonly ["Use write only for new files or complete rewrites."];
+};
+/**
+ * Pluggable operations for the write tool.
+ * Override these to delegate file writing to remote systems (for example SSH).
+ */
+export interface WriteOperations {
+    /** Write content to a file */
+    writeFile: (absolutePath: string, content: string) => Promise<void>;
+    /** Create directory recursively */
+    mkdir: (dir: string) => Promise<void>;
+}
+export interface WriteToolOptions {
+    /** Shared knowledge of file contents in the current model context. */
+    fileReadState?: FileReadState;
+    /** Custom operations for file writing. Default: local filesystem */
+    operations?: WriteOperations;
+}
+export declare function createWriteToolDefinition(cwd: string, options?: WriteToolOptions): {
+    name: string;
+    label: string;
+    description: string;
+    promptSnippet: "Create or overwrite files";
+    promptGuidelines: "Use write only for new files or complete rewrites."[];
+    parameters: Type.TObject<{
+        path: Type.TString;
+        content: Type.TString;
+    }>;
+    execute(_toolCallId: string, { path, content }: {
+        path: string;
+        content: string;
+    }, signal?: AbortSignal, _onUpdate?: import("../../../../../agent/src/index.js").AgentToolUpdateCallback<undefined> | undefined, ctx?: Partial<ToolContext>): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: undefined;
+    }>;
+};

package/dist/types/coding-agent/src/core/transcript-store.d.ts

@@ -0,0 +1,71 @@
+import type { ThinkingLevel } from "../../../agent/src/index.js";
+import type { Message } from "../../../ai/src/index.js";
+import type { SessionEntry, SessionHeader } from "./session-manager.js";
+/** A fixed generation and inclusive sequence watermark. Sequences start at 1. */
+export interface TranscriptSnapshot {
+    generation: string;
+    endSeq: number;
+}
+export interface IndexedSessionEntry {
+    seq: number;
+    entry: SessionEntry;
+}
+export interface TranscriptState {
+    model: {
+        provider: string;
+        modelId: string;
+    } | null;
+    thinkingLevel: ThinkingLevel;
+    lastThinkingLevel: ThinkingLevel;
+    hasThinkingEntry: boolean;
+    lastMessageSeq: number;
+    lastCompactionSeq: number;
+    name?: string;
+}
+export interface TranscriptContextPlan {
+    snapshot: TranscriptSnapshot;
+    /** Latest compaction at the snapshot watermark, if any. */
+    compaction?: IndexedSessionEntry;
+    /** Inclusive sequence of first retained entry; 1 when there is no compaction. */
+    firstKeptSeq: number;
+}
+/**
+ * SDK-neutral, indexed transcript access. Implementations own all writes and recovery.
+ * Readers MUST honor the snapshot generation and watermark, rejecting stale generations.
+ * Ranges are inclusive, ordered, lazy iterators; no implicit whole-transcript materialization.
+ * Append must durably persist the record before publishing its index/watermark.
+ */
+export interface TranscriptStore {
+    getHeader(): SessionHeader;
+    getFile(): string | undefined;
+    snapshot(): TranscriptSnapshot;
+    getStateAt(snapshot: TranscriptSnapshot): TranscriptState;
+    getTail(snapshot: TranscriptSnapshot): IndexedSessionEntry | undefined;
+    readEntryById(id: string, snapshot: TranscriptSnapshot): IndexedSessionEntry | undefined;
+    readRange(startSeq: number, endSeq: number, snapshot: TranscriptSnapshot, types?: readonly SessionEntry["type"][]): Iterable<IndexedSessionEntry>;
+    getContextPlan(snapshot: TranscriptSnapshot): TranscriptContextPlan;
+    /** Each group contains only an unresolved journal's updates, anchor and canonical turn. */
+    readUnresolvedToolJournals(snapshot: TranscriptSnapshot): Iterable<SessionEntry[]>;
+    append(entry: SessionEntry): void;
+    /** Optional asynchronous persistence; completion has the same durability/publication contract. */
+    appendAsync?(entry: SessionEntry): Promise<void>;
+    /** Implementations stage a fresh generation; preserve the old one on any failure. */
+    replace(header: SessionHeader, entries: Iterable<SessionEntry>): void;
+    replaceAsync?(header: SessionHeader, entries: Iterable<SessionEntry>, options?: {
+        remapIds?: boolean;
+    }): Promise<void>;
+}
+export interface MessageProvenance {
+    entryId: string;
+    seq: number;
+    kind: "message" | "compaction-system" | "compaction-summary";
+}
+export declare function setMessageProvenance(message: Message, source: MessageProvenance): void;
+export declare function getMessageProvenance(message: Message): MessageProvenance | undefined;
+/** Current product choices are separate from historical transcript checkpoints. */
+export interface SessionCurrentState {
+    get(): Pick<TranscriptState, "model" | "thinkingLevel" | "lastThinkingLevel" | "name">;
+    setModel(provider: string, modelId: string): void;
+    setThinkingLevel(level: ThinkingLevel): void;
+    setName(name: string): void;
+}

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

@@ -0,0 +1,60 @@
+import type { AgentTool, AgentToolResult, AgentToolUpdateCallback, ThinkingLevel } from "../../../agent/src/index.js";
+import type { JsonValue, Model } from "../../../ai/src/index.js";
+import type { Static, TSchema } from "typebox";
+import type { LoadedSkill, SkillList } from "./resources.js";
+import type { SessionManager } from "./session-manager.js";
+import type { ImageResizeOptions } from "./tools/pi/utils/image-resize-core.js";
+/** Resource discovery is separate from explicit customInstructions. */
+export interface ResourceLoader {
+    getBaseInstructions?(): string | undefined;
+    getInstructions?(): readonly string[];
+    reload?(): Promise<void>;
+    listSkills?(): SkillList;
+    loadSkill?(name: string): Promise<LoadedSkill>;
+    getDiagnostics?(): ResourceDiagnostic[];
+}
+export interface ResourceDiagnostic {
+    path: string;
+    message: string;
+}
+export declare function resourceInstructions(loader?: ResourceLoader): readonly string[];
+export declare function resourceBaseInstructions(loader?: ResourceLoader): string | undefined;
+export declare class StaticResourceLoader implements ResourceLoader {
+    private baseInstructions?;
+    private instructions;
+    constructor(options?: {
+        baseInstructions?: string;
+        instructions?: readonly string[];
+    });
+    getBaseInstructions(): string | undefined;
+    getInstructions(): string[];
+}
+/** Session context supplied to custom tools and built-in overrides. */
+export interface ToolContext {
+    cwd: string;
+    model: Model & {
+        inputLimits?: {
+            images?: {
+                resize?: ImageResizeOptions;
+            };
+        };
+    };
+    sessionManager: SessionManager;
+    thinkingLevel?: ThinkingLevel;
+    signal?: AbortSignal;
+    isIdle(): boolean;
+    getSystemPrompt(): string;
+    getToolNames?(): string[];
+}
+export interface ToolDefinition<TParameters extends TSchema = TSchema, TDetails = JsonValue | undefined, TContext = ToolContext> extends Pick<AgentTool, "executionMode" | "metadata" | "permission" | "requiresUserInteraction"> {
+    name: string;
+    label: string;
+    description: string;
+    parameters: TParameters;
+    promptSnippet?: string;
+    promptGuidelines?: string[];
+    /** Optional result schema metadata; tool results retain their existing runtime validation. */
+    outputSchema?: TSchema;
+    prepareArguments?: (args: unknown) => Static<TParameters>;
+    execute(toolCallId: string, params: Static<TParameters>, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallback<TDetails> | undefined, context: TContext): Promise<AgentToolResult<TDetails>>;
+}

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

@@ -0,0 +1,42 @@
+export type { AgentSessionEvent, InputContext } from "./core/agent-session.js";
+export { AgentSession } from "./core/agent-session.js";
+export type { ParsedInput } from "./core/commands.js";
+export { listCommands, parseInput } from "./core/commands.js";
+export type { CompactionOptions } from "./core/compaction.js";
+export { applyFileRewind, type FileRewindConflict, type FileRewindOptions, type FileRewindPlan, planFileRewind, } from "./core/file-rewind.js";
+export { syncDirectory } from "./core/fs.js";
+export * from "./core/image-limits.js";
+export * from "./core/images.js";
+export { type MarkdownFrontmatter, parseMarkdownFrontmatter } from "./core/markdown.js";
+export * from "./core/mentions.js";
+export type { ModelPerformance, ModelPerformanceTotals } from "./core/model-performance.js";
+export { modelPerformance, SessionPerformance, validPerformanceTotals } from "./core/model-performance.js";
+export type { MediaProjectionContext, ModelRuntimeOptions, ProviderChatModelConfig, ProviderConfigInput, } from "./core/model-runtime.js";
+export { ModelRuntime } from "./core/model-runtime.js";
+export { readFileBounded } from "./core/read-file-bounded.js";
+export { isSessionEntry, isSessionHeader, maxSessionEntryBytes } from "./core/record-validation.js";
+export type { DiscoveredSkill, LoadedSkill, SkillList, SkillMetadata } from "./core/resources.js";
+export { FileResourceLoader, SkillCatalog } from "./core/resources.js";
+export type { CreateAgentSessionOptions, CreateAgentSessionResult } from "./core/sdk.js";
+export { createAgentSession } from "./core/sdk.js";
+export type { SessionContext, SessionEntry, SessionHeader } from "./core/session-manager.js";
+export { SessionManager } from "./core/session-manager.js";
+export type { ContextUsage } from "./core/session-state.js";
+export { contextUsage, supportedThinkingLevels } from "./core/session-state.js";
+export type { ProviderRetrySettings, RetrySettings, Settings } from "./core/settings-manager.js";
+export { SettingsManager } from "./core/settings-manager.js";
+export { projectStreamedToolJournal } from "./core/streaming-tool-journal.js";
+export * from "./core/system-prompt.js";
+export * from "./core/tools/file-change.js";
+export type { BashToolOptions, EditToolOptions, ReadToolOptions, ToolContextFactory, WriteToolOptions, } from "./core/tools/index.js";
+export { createBashTool, createBashToolDefinition, createCodingTools, createEditTool, createEditToolDefinition, createLocalBashOperations, createReadTool, createReadToolDefinition, createWriteTool, createWriteToolDefinition, FileReadState, } from "./core/tools/index.js";
+export { getShellConfig, getShellEnv, killProcessTree } from "./core/tools/pi/utils/shell.js";
+export * from "./core/transcript-store.js";
+export type { ResourceDiagnostic, ResourceLoader, ToolContext, ToolDefinition, } from "./core/types.js";
+export { StaticResourceLoader } from "./core/types.js";
+export type { SessionContributions } from "./plugins/assembly.js";
+export { assembleSession, expandPluginCommand, pluginSnapshotData, snapshotPlugins, validatePluginSnapshot, } from "./plugins/assembly.js";
+export type { HookEvent, HookExecution, HookInput, HookInvocation, HookOutput, HookRegistration, } from "./plugins/hooks.js";
+export { HookRunner, hookEvents } from "./plugins/hooks.js";
+export { withPluginResources } from "./plugins/resources.js";
+export type { PluginCommand, PluginMetadata, PluginSkill, PluginSnapshot, SessionPlugin, } from "./plugins/types.js";

package/dist/types/coding-agent/src/plugins/assembly.d.ts

@@ -0,0 +1,37 @@
+import type { AgentTool } from "../../../agent/src/index.js";
+import type { TSchema } from "typebox";
+import type { ToolContext, ToolDefinition } from "../core/types.js";
+import type { PluginCommand, PluginSnapshot, SessionPlugin } from "./types.js";
+export interface SessionContributions {
+    plugins?: readonly SessionPlugin[];
+    customTools?: readonly ToolDefinition<TSchema, unknown>[];
+    toolOverrides?: readonly ToolDefinition<TSchema, unknown>[];
+    noTools?: "all" | "builtin";
+    tools?: readonly string[];
+    excludeTools?: readonly string[];
+}
+export declare function validatePluginSnapshot(value: unknown): asserts value is PluginSnapshot;
+/** Serializable field projection; snapshotPlugins also validates and copies the data. */
+export declare function pluginSnapshotData(plugin: PluginSnapshot): PluginSnapshot;
+export declare function snapshotPlugins(plugins: readonly SessionPlugin[]): PluginSnapshot[];
+/** Pure assembly: validate contributions and select tools without executing plugin code. */
+export declare function assembleSession(options: SessionContributions & {
+    builtinTools: readonly AgentTool[];
+    context?: (signal?: AbortSignal) => ToolContext;
+}): {
+    allTools: AgentTool<TSchema, import("../../../ai/src/index.js").JsonValue | undefined>[];
+    activeTools: AgentTool<TSchema, import("../../../ai/src/index.js").JsonValue | undefined>[];
+    commands: PluginCommand[];
+    skills: import("./types.js").PluginSkill[];
+    instructions: string[];
+    getInstructions: () => any[];
+    hooks: {
+        event: import("./hooks.js").HookEvent;
+        matcher?: string;
+        timeoutMs?: number;
+        onError?: "continue" | "block";
+        handler(input: import("./hooks.js").HookInput, signal: AbortSignal): import("./hooks.js").HookOutput | undefined | Promise<import("./hooks.js").HookOutput | undefined>;
+        pluginId: string;
+    }[];
+};
+export declare function expandPluginCommand(command: PluginCommand, args: string, cwd: string): string;