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

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

@@ -0,0 +1,82 @@
+import type { AgentToolResult } from "../../../agent/src/index.js";
+export declare const hookEvents: readonly ["SessionStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PostToolUseFailure", "Stop", "InputAccepted", "RunStart", "RunEnd", "Notification"];
+export type HookEvent = (typeof hookEvents)[number];
+export type HookInput = {
+    sessionId: string;
+    cwd: string;
+    invocationId: string;
+} & ({
+    event: "SessionStart";
+    source: "startup" | "resume";
+} | {
+    event: "UserPromptSubmit";
+    prompt: string;
+} | {
+    event: "PreToolUse" | "PostToolUse" | "PostToolUseFailure";
+    toolCallId: string;
+    toolName: string;
+    toolInput: unknown;
+    toolResult?: AgentToolResult;
+} | {
+    event: "Stop";
+    response: string;
+    stopHookActive: boolean;
+} | {
+    event: "InputAccepted";
+    prompt: string;
+} | {
+    event: "RunStart";
+    runId: string;
+    prompt: string;
+    sessionCreated: boolean;
+    userInitiated: boolean;
+} | {
+    event: "RunEnd";
+    runId: string;
+    status: "completed" | "aborted" | "error";
+} | {
+    event: "Notification";
+    runId: string;
+    notificationType: "task_completed" | "task_failed";
+    message: string;
+});
+type WithoutInvocation<T> = T extends unknown ? Omit<T, "invocationId"> : never;
+export type HookInvocation = WithoutInvocation<HookInput>;
+export interface HookOutput {
+    block?: boolean;
+    reason?: string;
+    updatedInput?: unknown;
+    additionalContext?: string;
+}
+export interface HookRegistration {
+    event: HookEvent;
+    matcher?: string;
+    timeoutMs?: number;
+    onError?: "continue" | "block";
+    handler(input: HookInput, signal: AbortSignal): HookOutput | undefined | Promise<HookOutput | undefined>;
+}
+export interface HookExecution {
+    invocationId: string;
+    pluginId?: string;
+    event: HookEvent;
+    index: number;
+    status: "completed" | "blocked" | "error" | "cancelled" | "timeout";
+    durationMs: number;
+}
+export declare const maxHookContextChars = 24000;
+export declare function validateHookRegistration(hook: HookRegistration): void;
+export declare class HookRunner {
+    private hooks;
+    private observe;
+    constructor(hooks: readonly (HookRegistration & {
+        pluginId?: string;
+    })[], observe?: (event: HookExecution) => void);
+    get hasToolHooks(): boolean;
+    run(input: HookInvocation, signal?: AbortSignal, validateInput?: (input: unknown) => unknown): Promise<{
+        block: boolean;
+        reason?: string;
+        updatedInput?: unknown;
+        additionalContexts: string[];
+    }>;
+}
+export {};

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

@@ -0,0 +1,4 @@
+import type { ResourceLoader } from "../core/types.js";
+import type { PluginSkill } from "./types.js";
+/** Adds explicit frozen plugin skills without changing filesystem discovery. */
+export declare function withPluginResources(loader: ResourceLoader, skills: readonly PluginSkill[]): ResourceLoader;

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

@@ -0,0 +1,26 @@
+import type { AgentLoopConfig, AgentMessage } from "../../../agent/src/index.js";
+import { type HookExecution, type HookRegistration, HookRunner } from "./hooks.js";
+/** Bridges lifecycle decisions to the loop; the runner never owns session history. */
+export declare class SessionHooks {
+    readonly runner: HookRunner;
+    private started;
+    private startMessages;
+    private pending;
+    private callOrder;
+    private continuations;
+    private context;
+    constructor(context: {
+        sessionId: string;
+        cwd: string;
+        source: "startup" | "resume";
+    }, hooks: readonly (HookRegistration & {
+        pluginId?: string;
+    })[], observe: (event: HookExecution) => void);
+    beginRun(): void;
+    preparePrompt(prompt: string, signal?: AbortSignal): Promise<AgentMessage[]>;
+    drainMessages(): AgentMessage[];
+    beforeToolCall: NonNullable<AgentLoopConfig["beforeToolCall"]>;
+    afterToolCall: NonNullable<AgentLoopConfig["afterToolCall"]>;
+    beforeStop: NonNullable<AgentLoopConfig["beforeStop"]>;
+    private enqueue;
+}

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

@@ -0,0 +1,41 @@
+import type { JsonObject } from "../../../ai/src/index.js";
+import type { TSchema } from "typebox";
+import type { ToolDefinition } from "../core/types.js";
+import type { HookRegistration } from "./hooks.js";
+export interface PluginCommand {
+    name: string;
+    description: string;
+    /** Literal prompt template; only {{cwd}} and {{arguments}} are expanded once. */
+    prompt: string;
+}
+export interface PluginSkill {
+    name: string;
+    description: string;
+    path: string;
+    baseDir: string;
+    body: string;
+}
+/** Serializable contributions frozen by a host at first-send admission. */
+export interface PluginSnapshot {
+    id: string;
+    version: string;
+    name?: string;
+    description?: string;
+    instructions?: readonly string[];
+    commands?: readonly PluginCommand[];
+    skills?: readonly PluginSkill[];
+    /** Host-resolved runtime identity, never an import path. */
+    runtime?: string;
+    options?: JsonObject;
+}
+export type PluginMetadata = Pick<PluginSnapshot, "id" | "version" | "name" | "description">;
+/** Explicit native registration. Discovery never imports arbitrary workspace code. */
+export interface SessionPlugin extends PluginSnapshot {
+    tools?: readonly ToolDefinition<TSchema, unknown>[];
+    /** Explicitly replace an existing built-in; collisions are rejected during assembly. */
+    toolOverrides?: readonly ToolDefinition<TSchema, unknown>[];
+    /** Pure current-state reader. Local block names are scoped to this plugin by the SDK.
+     * Omitted/empty blocks withdraw prior versions; no plugin-owned diffing or history writes. */
+    contextInstructions?: () => Readonly<Record<string, string>>;
+    hooks?: readonly HookRegistration[];
+}

package/dist/types/plugin-compat/src/command-hooks.d.ts

@@ -0,0 +1,184 @@
+import { type HookInput, type HookOutput, type HookRegistration } from "../../coding-agent/src/index.js";
+export interface CommandHook {
+    event: string;
+    matcher?: string;
+    type: "command" | "process";
+    command: string;
+    args: string[];
+    timeoutMs: number;
+}
+export interface CommandHookContext {
+    root: string;
+    dataDirectory: string;
+    id: string;
+    name: string;
+    transcriptPath?: string;
+    env?: Record<string, string | undefined>;
+    validate?: () => void;
+}
+export declare function parseCommandHook(hook: unknown, event: string, match: unknown): CommandHook;
+export declare function decodeHookOutput(value: unknown, event: HookInput["event"]): HookOutput | undefined;
+export declare function hookInputPayload(input: HookInput, transcriptPath?: string): {
+    sessionId: string;
+    cwd: string;
+    invocationId: string;
+    event: "SessionStart";
+    source: "startup" | "resume";
+    hookEventName: "InputAccepted" | "Notification" | "PostToolUse" | "PostToolUseFailure" | "PreToolUse" | "RunEnd" | "RunStart" | "SessionStart" | "Stop" | "UserPromptSubmit";
+    hook_event_name: "InputAccepted" | "Notification" | "PostToolUse" | "PostToolUseFailure" | "PreToolUse" | "RunEnd" | "RunStart" | "SessionStart" | "Stop" | "UserPromptSubmit";
+    session_id: string;
+    transcriptPath?: string | undefined;
+    transcript_path?: string | undefined;
+    tool_name?: string | undefined;
+    tool_input?: unknown;
+    tool_use_id?: string | undefined;
+    tool_response?: import("../../agent/src/index.js").AgentToolResult<import("../../ai/src/index.js").JsonValue | undefined> | undefined;
+    error?: string | undefined;
+    stop_hook_active?: boolean | undefined;
+    last_assistant_message?: string | undefined;
+    notification_type?: "task_completed" | "task_failed" | undefined;
+} | {
+    sessionId: string;
+    cwd: string;
+    invocationId: string;
+    event: "UserPromptSubmit";
+    prompt: string;
+    hookEventName: "InputAccepted" | "Notification" | "PostToolUse" | "PostToolUseFailure" | "PreToolUse" | "RunEnd" | "RunStart" | "SessionStart" | "Stop" | "UserPromptSubmit";
+    hook_event_name: "InputAccepted" | "Notification" | "PostToolUse" | "PostToolUseFailure" | "PreToolUse" | "RunEnd" | "RunStart" | "SessionStart" | "Stop" | "UserPromptSubmit";
+    session_id: string;
+    transcriptPath?: string | undefined;
+    transcript_path?: string | undefined;
+    tool_name?: string | undefined;
+    tool_input?: unknown;
+    tool_use_id?: string | undefined;
+    tool_response?: import("../../agent/src/index.js").AgentToolResult<import("../../ai/src/index.js").JsonValue | undefined> | undefined;
+    error?: string | undefined;
+    stop_hook_active?: boolean | undefined;
+    last_assistant_message?: string | undefined;
+    notification_type?: "task_completed" | "task_failed" | undefined;
+} | {
+    sessionId: string;
+    cwd: string;
+    invocationId: string;
+    event: "PreToolUse" | "PostToolUse" | "PostToolUseFailure";
+    toolCallId: string;
+    toolName: string;
+    toolInput: unknown;
+    toolResult?: import("../../agent/src/index.js").AgentToolResult;
+    hookEventName: "InputAccepted" | "Notification" | "PostToolUse" | "PostToolUseFailure" | "PreToolUse" | "RunEnd" | "RunStart" | "SessionStart" | "Stop" | "UserPromptSubmit";
+    hook_event_name: "InputAccepted" | "Notification" | "PostToolUse" | "PostToolUseFailure" | "PreToolUse" | "RunEnd" | "RunStart" | "SessionStart" | "Stop" | "UserPromptSubmit";
+    session_id: string;
+    transcriptPath?: string | undefined;
+    transcript_path?: string | undefined;
+    tool_name?: string | undefined;
+    tool_input?: unknown;
+    tool_use_id?: string | undefined;
+    tool_response?: import("../../agent/src/index.js").AgentToolResult<import("../../ai/src/index.js").JsonValue | undefined> | undefined;
+    error?: string | undefined;
+    stop_hook_active?: boolean | undefined;
+    last_assistant_message?: string | undefined;
+    notification_type?: "task_completed" | "task_failed" | undefined;
+} | {
+    sessionId: string;
+    cwd: string;
+    invocationId: string;
+    event: "Stop";
+    response: string;
+    stopHookActive: boolean;
+    hookEventName: "InputAccepted" | "Notification" | "PostToolUse" | "PostToolUseFailure" | "PreToolUse" | "RunEnd" | "RunStart" | "SessionStart" | "Stop" | "UserPromptSubmit";
+    hook_event_name: "InputAccepted" | "Notification" | "PostToolUse" | "PostToolUseFailure" | "PreToolUse" | "RunEnd" | "RunStart" | "SessionStart" | "Stop" | "UserPromptSubmit";
+    session_id: string;
+    transcriptPath?: string | undefined;
+    transcript_path?: string | undefined;
+    tool_name?: string | undefined;
+    tool_input?: unknown;
+    tool_use_id?: string | undefined;
+    tool_response?: import("../../agent/src/index.js").AgentToolResult<import("../../ai/src/index.js").JsonValue | undefined> | undefined;
+    error?: string | undefined;
+    stop_hook_active?: boolean | undefined;
+    last_assistant_message?: string | undefined;
+    notification_type?: "task_completed" | "task_failed" | undefined;
+} | {
+    sessionId: string;
+    cwd: string;
+    invocationId: string;
+    event: "InputAccepted";
+    prompt: string;
+    hookEventName: "InputAccepted" | "Notification" | "PostToolUse" | "PostToolUseFailure" | "PreToolUse" | "RunEnd" | "RunStart" | "SessionStart" | "Stop" | "UserPromptSubmit";
+    hook_event_name: "InputAccepted" | "Notification" | "PostToolUse" | "PostToolUseFailure" | "PreToolUse" | "RunEnd" | "RunStart" | "SessionStart" | "Stop" | "UserPromptSubmit";
+    session_id: string;
+    transcriptPath?: string | undefined;
+    transcript_path?: string | undefined;
+    tool_name?: string | undefined;
+    tool_input?: unknown;
+    tool_use_id?: string | undefined;
+    tool_response?: import("../../agent/src/index.js").AgentToolResult<import("../../ai/src/index.js").JsonValue | undefined> | undefined;
+    error?: string | undefined;
+    stop_hook_active?: boolean | undefined;
+    last_assistant_message?: string | undefined;
+    notification_type?: "task_completed" | "task_failed" | undefined;
+} | {
+    sessionId: string;
+    cwd: string;
+    invocationId: string;
+    event: "RunStart";
+    runId: string;
+    prompt: string;
+    sessionCreated: boolean;
+    userInitiated: boolean;
+    hookEventName: "InputAccepted" | "Notification" | "PostToolUse" | "PostToolUseFailure" | "PreToolUse" | "RunEnd" | "RunStart" | "SessionStart" | "Stop" | "UserPromptSubmit";
+    hook_event_name: "InputAccepted" | "Notification" | "PostToolUse" | "PostToolUseFailure" | "PreToolUse" | "RunEnd" | "RunStart" | "SessionStart" | "Stop" | "UserPromptSubmit";
+    session_id: string;
+    transcriptPath?: string | undefined;
+    transcript_path?: string | undefined;
+    tool_name?: string | undefined;
+    tool_input?: unknown;
+    tool_use_id?: string | undefined;
+    tool_response?: import("../../agent/src/index.js").AgentToolResult<import("../../ai/src/index.js").JsonValue | undefined> | undefined;
+    error?: string | undefined;
+    stop_hook_active?: boolean | undefined;
+    last_assistant_message?: string | undefined;
+    notification_type?: "task_completed" | "task_failed" | undefined;
+} | {
+    sessionId: string;
+    cwd: string;
+    invocationId: string;
+    event: "RunEnd";
+    runId: string;
+    status: "completed" | "aborted" | "error";
+    hookEventName: "InputAccepted" | "Notification" | "PostToolUse" | "PostToolUseFailure" | "PreToolUse" | "RunEnd" | "RunStart" | "SessionStart" | "Stop" | "UserPromptSubmit";
+    hook_event_name: "InputAccepted" | "Notification" | "PostToolUse" | "PostToolUseFailure" | "PreToolUse" | "RunEnd" | "RunStart" | "SessionStart" | "Stop" | "UserPromptSubmit";
+    session_id: string;
+    transcriptPath?: string | undefined;
+    transcript_path?: string | undefined;
+    tool_name?: string | undefined;
+    tool_input?: unknown;
+    tool_use_id?: string | undefined;
+    tool_response?: import("../../agent/src/index.js").AgentToolResult<import("../../ai/src/index.js").JsonValue | undefined> | undefined;
+    error?: string | undefined;
+    stop_hook_active?: boolean | undefined;
+    last_assistant_message?: string | undefined;
+    notification_type?: "task_completed" | "task_failed" | undefined;
+} | {
+    sessionId: string;
+    cwd: string;
+    invocationId: string;
+    event: "Notification";
+    runId: string;
+    notificationType: "task_completed" | "task_failed";
+    message: string;
+    hookEventName: "InputAccepted" | "Notification" | "PostToolUse" | "PostToolUseFailure" | "PreToolUse" | "RunEnd" | "RunStart" | "SessionStart" | "Stop" | "UserPromptSubmit";
+    hook_event_name: "InputAccepted" | "Notification" | "PostToolUse" | "PostToolUseFailure" | "PreToolUse" | "RunEnd" | "RunStart" | "SessionStart" | "Stop" | "UserPromptSubmit";
+    session_id: string;
+    transcriptPath?: string | undefined;
+    transcript_path?: string | undefined;
+    tool_name?: string | undefined;
+    tool_input?: unknown;
+    tool_use_id?: string | undefined;
+    tool_response?: import("../../agent/src/index.js").AgentToolResult<import("../../ai/src/index.js").JsonValue | undefined> | undefined;
+    error?: string | undefined;
+    stop_hook_active?: boolean | undefined;
+    last_assistant_message?: string | undefined;
+    notification_type?: "task_completed" | "task_failed" | undefined;
+};
+export declare function bindCommandHooks(hooks: readonly CommandHook[], context: CommandHookContext): HookRegistration[];

package/dist/types/plugin-compat/src/index.d.ts

@@ -0,0 +1,11 @@
+import { type PluginSnapshot, type SessionPlugin } from "../../coding-agent/src/index.js";
+export { bindCommandHooks, type CommandHook, decodeHookOutput, hookInputPayload, parseCommandHook, } from "./command-hooks.js";
+/** Import reads data only. No module import, installation scripts or hooks run here. */
+export declare function importLocalPlugin(source: string, storage: string): Promise<PluginSnapshot>;
+export declare function isExternalPlugin(snapshot: PluginSnapshot): boolean;
+export declare function assertExternalPlugin(snapshot: PluginSnapshot, storage: string, verifyFiles?: boolean): void;
+export declare function bindExternalPlugin(snapshot: PluginSnapshot, options: {
+    storage: string;
+    transcriptPath?: string;
+    env?: Record<string, string | undefined>;
+}): SessionPlugin;

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@zpi-dev/agent-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.61",
+  "type": "module",
+  "description": "TypeScript Agent SDK for ZPI with a Claude-compatible public API",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./host": {
+      "development": "./src/host.ts",
+      "types": "./dist/host.d.ts",
+      "import": "./dist/host.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=24 <25"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-agent-sdk.mjs",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "sharp": "0.35.5",
+    "typebox": "1.3.27",
+    "openai": "7.19.0",
+    "@anthropic-ai/sdk": "0.124.0"
+  },
+  "devDependencies": {
+    "@zpi-dev/ai": "0.1.61",
+    "@zpi-dev/agent": "0.1.61",
+    "@zpi-dev/coding-agent": "0.1.61",
+    "@zpi-dev/plugin-compat": "0.1.61",
+    "yaml": "2.9.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/1316151417/zpi.git",
+    "directory": "packages/agent-sdk"
+  },
+  "homepage": "http://101.200.240.206/zpi/docs/features/sdk",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}