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

package/dist/types/agent/src/tool-execution.d.ts

@@ -0,0 +1,9 @@
+import type { AssistantMessage, ToolCall, ToolResultMessage } from "../../ai/src/index.js";
+import type { AgentContext, AgentEventSink, AgentLoopConfig, AgentToolResult } from "./types.js";
+export declare const toolFailure: (error: unknown) => AgentToolResult;
+export declare function toolResultMessage(call: ToolCall, result: AgentToolResult): ToolResultMessage;
+export declare function finishToolCall(call: ToolCall, result: AgentToolResult, emit: AgentEventSink): Promise<ToolResultMessage>;
+/** Shared execution path for Pi batches and ZCode's streamed read-only calls. */
+export declare function createToolExecutor(context: AgentContext, assistant: AssistantMessage, config: AgentLoopConfig, emit: AgentEventSink, signal?: AbortSignal): {
+    schedule: (call: ToolCall) => Promise<() => Promise<ToolResultMessage>>;
+};

package/dist/types/agent/src/types.d.ts

@@ -0,0 +1,144 @@
+import type { AssistantMessage, AssistantMessageEvent, AssistantMessageEventStream, ImageContent, JsonValue, Message, Model, SimpleStreamOptions, TextContent, Tool, ToolCall, ToolResultMessage, TranscriptContext } from "../../ai/src/index.js";
+import type { Static, TSchema } from "typebox";
+export interface CustomAgentMessages {
+}
+export type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessages];
+export type ThinkingLevel = "off" | import("../../ai/src/index.js").ThinkingLevel;
+export type ToolExecutionMode = "sequential" | "parallel";
+export interface ToolExecutionMetadata {
+    readOnly?: boolean;
+    concurrentSafe?: boolean;
+    destructive?: boolean;
+    needsApproval?: boolean;
+    requiresUserInteraction?: boolean;
+    sideEffectScope?: "none" | "workspace" | "git" | "network" | "system" | "session" | "userInteraction";
+}
+export type StreamFn = (model: Model, context: TranscriptContext, options?: SimpleStreamOptions) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>;
+export interface AgentToolResult<T = JsonValue | undefined> {
+    content: (TextContent | ImageContent)[];
+    details: T;
+    isError?: boolean;
+    structuredContent?: JsonValue;
+}
+export type AgentToolUpdateCallback<T = JsonValue | undefined> = (partialResult: AgentToolResult<T>) => void;
+export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = JsonValue | undefined> extends Tool<TParameters> {
+    label: string;
+    promptSnippet?: string;
+    promptGuidelines?: string[];
+    executionMode?: ToolExecutionMode;
+    metadata?: ToolExecutionMetadata;
+    permission?: {
+        sideEffectScope?: ToolExecutionMetadata["sideEffectScope"];
+    };
+    requiresUserInteraction?: boolean;
+    prepareArguments?: (args: unknown) => Static<TParameters>;
+    execute(toolCallId: string, params: Static<TParameters>, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<TDetails>): Promise<AgentToolResult<TDetails>>;
+}
+export interface AgentContext {
+    messages: AgentMessage[];
+    tools?: AgentTool[];
+}
+export interface PrepareNextTurnContext {
+    message: AssistantMessage;
+    toolResults: ToolResultMessage[];
+    context: AgentContext;
+    newMessages: AgentMessage[];
+}
+export interface AgentLoopTurnUpdate {
+    context?: AgentContext;
+}
+export interface BeforeToolCallContext {
+    assistantMessage: AssistantMessage;
+    toolCall: ToolCall;
+    args: unknown;
+    context: AgentContext;
+}
+export interface BeforeToolCallResult {
+    block?: boolean;
+    reason?: string;
+    args?: unknown;
+}
+export interface AfterToolCallContext extends BeforeToolCallContext {
+    result: AgentToolResult;
+    isError: boolean;
+}
+export interface AfterToolCallResult {
+    content?: (TextContent | ImageContent)[];
+    details?: JsonValue;
+    isError?: boolean;
+}
+export interface AgentLoopConfig extends SimpleStreamOptions {
+    model: Model;
+    convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
+    transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
+    getApiKey?: (provider: string) => string | undefined | Promise<string | undefined>;
+    beforeToolCall?: (context: BeforeToolCallContext, signal?: AbortSignal) => Promise<BeforeToolCallResult | undefined>;
+    afterToolCall?: (context: AfterToolCallContext, signal?: AbortSignal) => Promise<AfterToolCallResult | undefined>;
+    toolExecution?: ToolExecutionMode;
+    streamingToolExecution?: "off" | "readOnly";
+    /** Queue-only input: consume at request start or after successful intermediate responses/tools.
+     * Never interrupts generation; final answers leave queued input for the next request. */
+    getPendingMessages?: () => AgentMessage[];
+    /** Inputs consumed once at a completed model/tool boundary, never during a tool call. */
+    getSteeringMessages?: () => AgentMessage[];
+    prepareNextTurnWithContext?: (turn: PrepareNextTurnContext, signal?: AbortSignal) => Promise<AgentLoopTurnUpdate | undefined>;
+    /** Called only before a normal final response settles; returned messages continue the loop. */
+    beforeStop?: (message: AssistantMessage, signal?: AbortSignal) => Promise<AgentMessage[] | undefined>;
+}
+export type AgentEvent = {
+    type: "agent_start";
+} | {
+    type: "agent_end";
+    messages: AgentMessage[];
+} | {
+    type: "turn_start";
+} | {
+    type: "turn_end";
+    message: AgentMessage;
+    toolResults: ToolResultMessage[];
+} | {
+    type: "message_start" | "message_end";
+    message: AgentMessage;
+} | {
+    type: "message_update";
+    message: AgentMessage;
+    assistantMessageEvent: AssistantMessageEvent;
+} | {
+    type: "tool_execution_start";
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+    /** Complete provider declaration for durable recovery before message_end. */
+    toolCall?: ToolCall;
+    executionTiming?: "during_stream";
+} | {
+    type: "tool_execution_update";
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+    partialResult: AgentToolResult;
+} | {
+    type: "tool_execution_end";
+    toolCallId: string;
+    toolName: string;
+    result: AgentToolResult;
+    isError: boolean;
+};
+export type AgentEventSink = (event: AgentEvent) => void | Promise<void>;
+export interface AgentState {
+    readonly systemPrompt: string;
+    model: Model;
+    thinkingLevel: ThinkingLevel;
+    messages: AgentMessage[];
+    tools: AgentTool[];
+    readonly isStreaming: boolean;
+    readonly streamingMessage?: AgentMessage;
+    readonly pendingToolCalls: ReadonlySet<string>;
+    readonly errorMessage?: string;
+}
+export type AgentInitialState = Partial<Omit<AgentState, "isStreaming" | "streamingMessage" | "pendingToolCalls" | "errorMessage">>;
+export interface AgentOptions extends Pick<AgentLoopConfig, "transformContext" | "getApiKey" | "beforeToolCall" | "afterToolCall" | "onPayload" | "onResponse" | "toolExecution" | "streamingToolExecution" | "prepareNextTurnWithContext" | "getSteeringMessages" | "getPendingMessages" | "beforeStop"> {
+    initialState?: AgentInitialState;
+    streamFn: StreamFn;
+    convertToLlm?: AgentLoopConfig["convertToLlm"];
+}

package/dist/types/agent-sdk/src/hooks.d.ts

@@ -0,0 +1,12 @@
+import type { HookRegistration } from "../../coding-agent/src/index.js";
+import type { HookEvent, Options } from "./types.js";
+export declare function coreHooks(options: Options, transcript: string): HookRegistration[];
+export declare function lifecycleHook(options: Options, event: HookEvent, input: import("./types.js").BaseHookInput & {
+    agent_id?: string;
+    agent_type?: string;
+    reason?: string;
+    trigger?: "manual" | "auto";
+    custom_instructions?: string;
+    stop_hook_active?: boolean;
+    last_assistant_message?: string;
+}, signal: AbortSignal): Promise<void>;

package/dist/types/agent-sdk/src/host.d.ts

@@ -0,0 +1,4 @@
+/** Native host integration uses the same engine while retaining indexed history and projections. */
+export type { AgentSession, CreateAgentSessionOptions, CreateAgentSessionResult, InputContext, ParsedInput, ResourceLoader, SessionPlugin, ToolDefinition, } from "../../coding-agent/src/index.js";
+export { createAgentSession, SessionManager, SettingsManager } from "../../coding-agent/src/index.js";
+export { nativeStopReason, queryResult } from "./query-result.js";

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

@@ -0,0 +1,4 @@
+export { ModelRuntime } from "../../coding-agent/src/index.js";
+export { type QueryParams, query } from "./query.js";
+export { forkSession, getSessionInfo, getSessionMessages, type ListSessionsOptions, listSessions, renameSession, type SDKSessionInfo, type SessionMessage, tagSession, } from "./sessions.js";
+export * from "./types.js";

package/dist/types/agent-sdk/src/messages.d.ts

@@ -0,0 +1,12 @@
+import { type AssistantMessage, type Message, type Usage as NativeUsage } from "../../ai/src/index.js";
+import type { SessionEntry } from "../../coding-agent/src/index.js";
+import type { SDKAssistantMessage, SDKUserMessage, Usage } from "./types.js";
+export declare const emptyUsage: () => Usage;
+export declare function usage(value: NativeUsage): Usage;
+export declare function stableUuid(id: string): string;
+export declare function messageText(message: Message): string;
+export declare function assistantMessage(message: AssistantMessage, sessionId: string, uuid?: string, parent?: string | null): SDKAssistantMessage;
+export declare function userMessage(message: Extract<Message, {
+    role: "user" | "toolResult";
+}>, sessionId: string, uuid: string, parent?: string | null): SDKUserMessage;
+export declare function messageUuids(entries: readonly SessionEntry[]): Map<string, string>;

package/dist/types/agent-sdk/src/permissions.d.ts

@@ -0,0 +1,10 @@
+import type { HookRegistration } from "../../coding-agent/src/index.js";
+import type { Options, SDKPermissionDenial } from "./types.js";
+interface Rule {
+    name: string;
+    argument?: string;
+}
+export declare function permissionRules(rules?: readonly string[]): Rule[];
+export declare function matchesRule(rule: Rule, name: string, input: Record<string, unknown>, cwd: string): boolean;
+export declare function permissionHook(options: Options, denials: SDKPermissionDenial[], interrupt: () => void): HookRegistration;
+export {};

package/dist/types/agent-sdk/src/query-result.d.ts

@@ -0,0 +1,7 @@
+import { type QueryParams } from "./query.js";
+import type { SDKMessage, SDKResultMessage } from "./types.js";
+/** Consume a query and return its successful terminal result. */
+export declare function queryResult(params: QueryParams, observe?: (message: SDKMessage) => void): Promise<Extract<SDKResultMessage, {
+    subtype: "success";
+}>>;
+export declare function nativeStopReason(reason: string | null): string;

package/dist/types/agent-sdk/src/query.d.ts

@@ -0,0 +1,6 @@
+import type { Options, Query, SDKUserMessage } from "./types.js";
+export interface QueryParams {
+    prompt: string | AsyncIterable<SDKUserMessage>;
+    options?: Options;
+}
+export declare function query(params: QueryParams): Query;

package/dist/types/agent-sdk/src/resources.d.ts

@@ -0,0 +1,16 @@
+import { type LoadedSkill, type ResourceLoader, type SkillList } from "../../coding-agent/src/index.js";
+import type { Options } from "./types.js";
+/** SDK opt-in settings discovery; no project code or config executes during loading. */
+export declare class SdkResources implements ResourceLoader {
+    private instructions;
+    private skills;
+    private options;
+    private cwd;
+    constructor(options: Options, cwd: string);
+    getInstructions(): string[];
+    listSkills(): SkillList;
+    loadSkill(name: string): Promise<LoadedSkill>;
+    reload(): Promise<void>;
+}
+/** Agent markdown is data; execution still goes through the SDK's registered tools. */
+export declare function pluginAgents(snapshot: import("../../coding-agent/src/index.js").PluginSnapshot): Record<string, import("./types.js").AgentDefinition>;

package/dist/types/agent-sdk/src/runtime.d.ts

@@ -0,0 +1,7 @@
+import { type Model } from "../../ai/src/index.js";
+import { ModelRuntime } from "../../coding-agent/src/index.js";
+import type { Options } from "./types.js";
+export declare function runtimeFor(options: Options): Promise<ModelRuntime>;
+export declare function selectModel(runtime: ModelRuntime, name?: string): Promise<Model>;
+export declare function thinkingLevel(options: Options): "off" | "low" | "medium" | "high" | "xhigh" | "max";
+export declare const sdkHome: (options: Options) => string;

package/dist/types/agent-sdk/src/sessions.d.ts

@@ -0,0 +1,48 @@
+import { SessionManager } from "../../coding-agent/src/index.js";
+import type { Options, RewindFilesResult } from "./types.js";
+export interface SDKSessionInfo {
+    sessionId: string;
+    summary: string;
+    lastModified: number;
+    fileSize?: number;
+    customTitle?: string;
+    firstPrompt?: string;
+    cwd?: string;
+    tag?: string;
+}
+export interface ListSessionsOptions {
+    dir?: string;
+    limit?: number;
+    includeWorktrees?: boolean;
+    zpi?: {
+        agentDir?: string;
+    };
+}
+export interface SessionMessage {
+    type: "user" | "assistant" | "system";
+    uuid: string;
+    session_id: string;
+    message: unknown;
+    parent_tool_use_id: string | null;
+    parent_agent_id: string | null;
+}
+export declare const agentDirectory: (options?: {
+    agentDir?: string;
+}) => string;
+export declare function listSessions(options?: ListSessionsOptions): Promise<SDKSessionInfo[]>;
+export declare function getSessionInfo(sessionId: string, options?: ListSessionsOptions): Promise<SDKSessionInfo | undefined>;
+export declare function getSessionMessages(sessionId: string, options?: ListSessionsOptions & {
+    limit?: number;
+    offset?: number;
+    includeSystemMessages?: boolean;
+}): Promise<SessionMessage[]>;
+export declare function renameSession(sessionId: string, title: string, options?: ListSessionsOptions): Promise<void>;
+export declare function tagSession(sessionId: string, tag: string | null, options?: ListSessionsOptions): Promise<void>;
+export declare function forkSession(sessionId: string, options?: ListSessionsOptions & {
+    upToMessageId?: string;
+    title?: string;
+}): Promise<{
+    sessionId: string;
+}>;
+export declare function openSession(options: Options, cwd: string): Promise<SessionManager>;
+export declare function rewindFiles(manager: SessionManager, userMessageId: string, dryRun?: boolean): Promise<RewindFilesResult>;

package/dist/types/agent-sdk/src/tasks.d.ts

@@ -0,0 +1,8 @@
+import type { ToolDefinition } from "../../coding-agent/src/index.js";
+import { type TObject } from "typebox";
+export declare class Tasks {
+    private tasks;
+    start(run: (signal: AbortSignal) => Promise<string>): string;
+    tools(): ToolDefinition<TObject>[];
+    close(): Promise<void>;
+}

package/dist/types/agent-sdk/src/tools.d.ts

@@ -0,0 +1,5 @@
+import { type ToolContext, type ToolDefinition } from "../../coding-agent/src/index.js";
+import { type TObject } from "typebox";
+import type { Tasks } from "./tasks.js";
+import type { Options } from "./types.js";
+export declare function canonicalTools(cwd: string, outputDir: string, context: () => ToolContext, options: Options, tasks: Tasks): ToolDefinition<TObject>[];