experimental-agent 0.1.1 → 0.1.2

package/dist/client-DjcE0ATp.d.mts

@@ -1,710 +0,0 @@
-import { g as SandboxRecord, e as SandboxError, m as Storage, N as NetworkPolicy, f as SandboxNotFoundError, l as StorageError, k as StorageConfig, h as Session, U as UsageSummary, d as SandboxConfig, n as SessionError, i as SessionNotFoundError, T as TypedStorage, S as StorageMethods } from './types-DuTc4UQW.mjs';
-import * as ai from 'ai';
-import { JSONSchema7, ToolSet, InferToolInput, ModelMessage, GatewayModelId, UIMessageChunk, UIMessage, InferUITools } from 'ai';
-import { z } from 'zod';
-
-/**
- * Summary of a discovered skill, used in the system prompt
- * to inform the LLM about available skills.
- */
-type SkillSummary = {
-    name: string;
-    description: string;
-    /** Full path to the SKILL.md file inside the sandbox */
-    skillMdPath: string;
-};
-/**
- * A file ready to be uploaded to the sandbox.
- * Content can be text (string) or binary (Buffer).
- */
-type UploadableFile = {
-    /** Relative path within the upload destination */
-    path: string;
-    content: string | Buffer;
-};
-/**
- * Path or paths to skills directories inside the sandbox.
- */
-type SkillsDir = string | string[];
-
-type SandboxSetup = {
-    /** Explicit key the developer controls. Bump to invalidate and re-run setup. */
-    key: string;
-    /** Async function that receives a bare Sandbox and does setup work. */
-    run: (sandbox: Sandbox) => Promise<void>;
-};
-type OnRestart = (sandbox: Sandbox) => Promise<void>;
-type SandboxLifecycleInput = {
-    id: string;
-    vercelSandboxId: string;
-    storageConfig: StorageConfig;
-};
-type LogEntry = {
-    stream: "stdout" | "stderr";
-    data: string;
-};
-type ExecResult = {
-    commandId: string;
-    logs: () => AsyncIterable<LogEntry>;
-    result: Promise<{
-        stdout: string;
-        stderr: string;
-        exitCode: number;
-    }>;
-};
-type SandboxStatus = "pending" | "running" | "stopping" | "stopped" | "failed";
-interface SandboxLifecycle {
-    start: () => Promise<SandboxError | SandboxStatus>;
-    snapshot: () => Promise<SandboxError | {
-        snapshotId: string;
-    }>;
-    stop: () => Promise<SandboxError | undefined>;
-    getStatus: () => Promise<SandboxError | SandboxStatus>;
-    getCreatedAt: () => Promise<SandboxError | Date>;
-    getRemainingTimeout: () => Promise<SandboxError | number>;
-}
-interface Sandbox<TTags extends TagsSchema = TagsSchema> {
-    id: SandboxRecord["id"];
-    config: SandboxRecord["config"];
-    exec: (opts: {
-        command: string;
-        args?: string[];
-        signal?: AbortSignal;
-    }) => Promise<SandboxError | ExecResult>;
-    /**
-     * Get the public domain URL for an exposed port.
-     * Only available for Vercel sandboxes with exposed ports.
-     */
-    getDomain: (port: number) => Promise<SandboxError | string>;
-    kill: (opts: {
-        commandId: string;
-        storage: Storage;
-    }) => Promise<SandboxError | undefined>;
-    readFile: (opts: {
-        path: string;
-    }) => Promise<SandboxError | Buffer | null>;
-    writeFiles: (opts: {
-        files: UploadableFile[];
-        destPath: string;
-    }) => Promise<void>;
-    lifecycle?: SandboxLifecycle;
-    /**
-     * Dynamically update the network policy on a running sandbox.
-     * Only available for Vercel sandboxes.
-     *
-     * @example
-     * ```ts
-     * // Lock down to specific domains
-     * await sandbox.updateNetworkPolicy({ allow: ["github.com", "*.github.com"] });
-     *
-     * // Deny all network access
-     * await sandbox.updateNetworkPolicy("deny-all");
-     *
-     * // Restore full access
-     * await sandbox.updateNetworkPolicy("allow-all");
-     * ```
-     */
-    updateNetworkPolicy: (policy: NonNullable<NetworkPolicy>) => Promise<SandboxError | NonNullable<NetworkPolicy>>;
-    tag: {
-        list: () => Promise<SandboxNotFoundError | StorageError | TTags>;
-        get: (key: string) => Promise<SandboxNotFoundError | StorageError | TTags[typeof key] | undefined>;
-        set: (key: string, value: unknown) => Promise<StorageError | undefined>;
-        setMany: (tags: Record<string, unknown>) => Promise<StorageError | undefined>;
-    };
-}
-
-/**
- * Metadata about how the sandbox was set up.
- * Used by the workflow to emit the correct status indicator.
- * Returned as a promise because the metadata is determined asynchronously
- * during sandbox creation, before _onReady runs setup.
- */
-type SandboxSetupMeta = {
-    /** Whether setup.run() needs to execute (cold start, no snapshot). */
-    needsSetupRun: boolean;
-    /** Whether the sandbox was created from a snapshot. */
-    createdFromSnapshot: boolean;
-};
-
-type GenerationOptions = {
-    /** Max tool-use steps per assistant response. Default: unlimited. */
-    maxSteps?: number;
-    temperature?: number;
-    topK?: number;
-    topP?: number;
-    frequencyPenalty?: number;
-    presencePenalty?: number;
-    maxOutputTokens?: number;
-    /** Provider-specific HTTP headers. */
-    headers?: Record<string, string>;
-};
-
-type ToolContext<TContext = Record<string, unknown>> = {
-    session: Session;
-    sandbox: Sandbox;
-    storage: Storage;
-    context: TContext;
-};
-declare const builtInTools: {
-    Read: ai.Tool<{
-        path: string;
-        startLine?: number | undefined;
-        endLine?: number | undefined;
-    }, {
-        content: string;
-        metadata: {
-            totalLines: number;
-            linesShown: number;
-            startLine: number;
-            endLine: number;
-            isPaginated: boolean;
-            fileSize: string;
-            path: string;
-        };
-    }>;
-    Grep: ai.Tool<{
-        pattern: string;
-        caseSensitive: boolean;
-        filesWithMatches: boolean;
-        path?: string | undefined;
-        fileType?: string | undefined;
-        glob?: string | undefined;
-        contextLines?: number | undefined;
-        maxCount?: number | undefined;
-    }, {
-        matches: string;
-        summary: {
-            matchCount: number;
-            fileCount: number;
-            searchPath: string;
-            pattern: string;
-        };
-    }>;
-    List: ai.Tool<{
-        includeHidden: boolean;
-        filesOnly: boolean;
-        path?: string | undefined;
-        depth?: number | undefined;
-        pattern?: string | undefined;
-    }, {
-        listing: string;
-        summary: {
-            totalItems: number;
-            totalFiles: number;
-            totalDirs: number;
-            searchPath: string;
-            depth?: number | undefined;
-        };
-    }>;
-    Write: ai.Tool<{
-        path: string;
-        content: string;
-    }, {
-        success: boolean;
-        path: string;
-        bytesWritten: number;
-        error?: string | undefined;
-    }>;
-    Edit: ai.Tool<{
-        path: string;
-        old_string: string;
-        new_string: string;
-    }, {
-        success: boolean;
-        path: string;
-        error?: string | undefined;
-    }>;
-    Bash: ai.Tool<{
-        command: string;
-        waitUntil?: number | undefined;
-    }, {
-        pid: number;
-        output: string;
-        exitCode: number;
-        status: "running" | "completed" | "failed";
-        cwd: string;
-        outputFile: string;
-    }>;
-    JavaScript: ai.Tool<{
-        code: string;
-    }, any>;
-};
-type BuiltInToolName = keyof typeof builtInTools;
-declare const builtinToolNames: { [K in BuiltInToolName]: K; };
-
-type ToolMetadata = {
-    name: string;
-    description?: string;
-    inputSchema?: JSONSchema7;
-};
-type ToolsExecuteParams = {
-    name: string;
-    input: unknown;
-    session: Session;
-    sandboxRecord: SandboxRecord;
-    context: Record<string, unknown>;
-};
-type HookToolBeforeParams = {
-    name: string;
-    input: unknown;
-    context: ToolContext;
-};
-type HookToolBeforeResult = {
-    input?: unknown;
-    stop?: boolean;
-};
-type HookToolAfterParams = {
-    name: string;
-    input: unknown;
-    result: unknown;
-    context: ToolContext;
-};
-type HookToolAfterResult = {
-    result?: unknown;
-    stop?: boolean;
-};
-type ToolsNeedsApprovalParams = {
-    toolName: string;
-    input: unknown;
-    toolCallId: string;
-    messages: unknown[];
-};
-type ToolsNeedsApprovalResult = boolean;
-type HookStatusParams = {
-    status: AgentStatus;
-};
-type HookStatusResult = Record<string, never>;
-
-type SessionUsage = {
-    total: UsageSummary & {
-        messageCount: number;
-    };
-    byMessageId: Record<string, UsageSummary | null>;
-};
-
-type SendInput = string | {
-    role?: UIMessage["role"];
-    parts: UIMessage["parts"];
-    id?: string;
-};
-/**
- * Transient status indicators emitted over the stream during long-running phases.
- * Delivered to the client as `data-status` chunks with `transient: true` — not persisted.
- */
-type AgentStatus = {
-    type: "sandbox-setup";
-} | {
-    type: "sandbox-setup-cold";
-} | {
-    type: "loading-skills";
-} | {
-    type: "processing-approvals";
-} | {
-    type: "needs-approval";
-} | {
-    type: "thinking";
-} | {
-    type: "custom";
-    status: string;
-};
-/**
- * Augmented `ReadableStream` returned by `session.stream()`.
- * Passes `instanceof ReadableStream` and works with `createUIMessageStreamResponse({ stream })`.
- */
-type AgentStream = ReadableStream<UIMessageChunk> & {
-    /** Write a typed status update to the stream (transient, not persisted). */
-    writeStatus: (status: AgentStatus) => void;
-};
-/**
- * Data part types emitted by every agent over the stream.
- * Used as the `DATA_PARTS` generic for `UIMessage`.
- */
-type AgentDataTypes = {
-    status: AgentStatus;
-};
-/**
- * Infer a typed UIMessage from an agent instance.
- * Tool parts are discriminated by `type: "tool-${name}"` with typed input/output.
- * Data parts include `data-status` with typed `AgentStatus`.
- *
- * @example
- * ```ts
- * const myAgent = agent({ tools: { myTool: tool({...}) } });
- * type MyMessage = typeof myAgent.$UIMessage;
- * // MyMessage.parts includes { type: "tool-myTool"; input: MyInput; output: MyOutput; ... }
- * // onData callback receives { type: "data-status"; data: AgentStatus }
- * ```
- */
-type InferUIMessage<A> = A extends {
-    tools: infer T extends ToolSet;
-} ? UIMessage<unknown, AgentDataTypes, InferUITools<T>> : UIMessage<unknown, AgentDataTypes>;
-type ToolName<Tools> = Extract<keyof Tools, string> | BuiltInToolName;
-type ToolInput<Tools, K> = K extends BuiltInToolName ? InferToolInput<(typeof builtInTools)[K]> : K extends keyof Tools ? Tools[K] extends ai.Tool ? InferToolInput<Tools[K]> : unknown : unknown;
-type NeedsApprovalMap<Tools> = {
-    [K in ToolName<Tools>]?: boolean | ((input: ToolInput<Tools, K>, options: {
-        toolCallId: string;
-        messages: ModelMessage[];
-        experimental_context: unknown;
-    }) => boolean | Promise<boolean>);
-};
-/**
- * Options that can be set per-session, overriding agent-level defaults.
- */
-type SessionOptions<Tools extends ToolSet, TTags extends Record<string, unknown> = Record<string, never>> = {
-    /** The AI model to use. */
-    model?: GatewayModelId;
-    /** System prompt for the AI model. */
-    system?: string;
-    /** Sandbox configuration or ID. If string, uses as sandbox ID with its config. */
-    sandbox?: (SandboxConfig & {
-        setup?: SandboxSetup;
-        onRestart?: OnRestart;
-    }) | string;
-    /** Key-value metadata tags for the session. */
-    tags?: TTags;
-    /** Directory containing skill definitions for the agent. */
-    skillsDir?: SkillsDir;
-    /**
-     * Names of tools to activate for this session.
-     * If not specified, all agent-level tools are active.
-     * Use this to restrict which tools are available per-session.
-     */
-    activeTools?: (Extract<keyof Tools, string> | BuiltInToolName)[];
-    /** Generation options (temperature, maxSteps, etc.). Overrides agent-level defaults. */
-    generation?: GenerationOptions;
-};
-type SessionUpdateOptions<Tools extends ToolSet> = Pick<SessionOptions<Tools>, "model" | "system" | "skillsDir" | "activeTools" | "generation">;
-/**
- * Configuration options for creating an agent instance.
- *
- * @example
- * ```ts
- * const myAgent = agent({
- *   model: "anthropic/claude-opus-4.5",
- *   system: "You are a helpful assistant...",
- *   tagsSchema: z.object({ userId: z.string() }),
- *   contextSchema: z.object({ authToken: z.string() }),
- * });
- * ```
- */
-type AgentOptions<Tools extends ToolSet, TTags extends Record<string, unknown> = Record<string, never>, TContext extends Record<string, unknown> = Record<string, never>> = {
-    /**
-     * Agent name. Used to isolate storage data - different names have separate data.
-     * @default "default"
-     */
-    name?: string;
-    /**
-     * Storage backend configuration.
-     * - `{ type: "local" }` - filesystem storage (dev)
-     * - `{ type: "vercel" }` - Vercel managed storage (prod)
-     * - `{ type: "custom", url: "..." }` - custom HTTP backend
-     * @default Inferred from environment: `{ type: "vercel" }` when `VERCEL_OIDC_TOKEN` is set, `{ type: "local" }` otherwise.
-     */
-    storage?: StorageConfig;
-    /**
-     * Custom tools available to the agent.
-     * These are exposed via the RPC handler and called over HTTP.
-     */
-    tools?: Tools;
-    /**
-     * Hooks for intercepting agent operations.
-     */
-    hooks?: AgentHooks;
-    /**
-     * Schema for session tags. All sessions share this schema.
-     * Tags are persisted in storage and survive across requests.
-     */
-    tagsSchema?: z.ZodType<TTags>;
-    /**
-     * Schema for transient tool context. Passed per-request via send().
-     * NOT persisted - use for secrets like auth tokens.
-     */
-    contextSchema?: z.ZodType<TContext>;
-    /**
-     * Approval rules for tools you don't own (built-in or third-party).
-     * Maps tool names to a boolean or a function that decides whether to ask.
-     *
-     * @example
-     * ```ts
-     * needsApproval: {
-     *   Bash: (input) => input.command.startsWith("rm"),
-     *   Write: true,
-     * }
-     * ```
-     */
-    needsApproval?: NeedsApprovalMap<Tools>;
-    /**
-     * Sandbox configuration with optional setup and restart hooks.
-     *
-     * - `setup.key`: explicit string to control snapshot invalidation (bump to re-run)
-     * - `setup.run`: async function that runs once to initialize the sandbox, then gets snapshotted
-     * - `onRestart`: async function that runs every time a sandbox resumes from a snapshot
-     *
-     * @example
-     * ```ts
-     * sandbox: {
-     *   type: "vercel",
-     *   setup: {
-     *     key: "dev-env-v3",
-     *     run: async (sandbox) => {
-     *       await sandbox.exec({ command: "npm", args: ["i", "-g", "vercel"] })
-     *     },
-     *   },
-     *   onRestart: async (sandbox) => {
-     *     await sandbox.exec({ command: "bash", args: ["-c", "npm run dev &"] })
-     *   },
-     * }
-     * ```
-     */
-    sandbox?: (SandboxConfig & {
-        setup?: SandboxSetup;
-        onRestart?: OnRestart;
-    }) | string;
-} & Omit<SessionOptions<Tools, TTags>, "tags" | "sandbox">;
-/**
- * Base type for session/sandbox tags. Used for generic constraints.
- * For agent-level tag validation, use `tagsSchema` option with a zod schema.
- */
-type TagsSchema = Record<string, unknown>;
-/**
- * Hooks for intercepting agent operations.
- */
-type AgentHooks = {
-    /** Called before a tool is executed. Can modify input or throw to block. */
-    "tool.before"?: (opts: {
-        name: string;
-        input: unknown;
-        context: ToolContext;
-    }) => Promise<undefined | {
-        input: unknown;
-    }>;
-    /** Called after a tool is executed. Can modify result. */
-    "tool.after"?: (opts: {
-        name: string;
-        input: unknown;
-        result: unknown;
-        context: ToolContext;
-    }) => Promise<undefined | {
-        result: unknown;
-    }>;
-    /** Called when the agent emits a transient status indicator. */
-    status?: (status: AgentStatus) => void | Promise<void>;
-};
-/**
- * RPC response type for dispatch.
- */
-type RpcResult<T = unknown> = {
-    result: T;
-} | {
-    error: {
-        code: string;
-        message: string;
-    };
-    status?: number;
-};
-/**
- * Direct RPC payload for step function calls (no HTTP).
- */
-type RpcPayload = {
-    name?: string;
-    method: string;
-    params: unknown;
-};
-/**
- * All RPC methods available on the agent handler.
- * Combines tools methods, hooks, and storage methods.
- */
-type AgentRpcMethods = {
-    "tools.list": {
-        params: Record<string, never>;
-        result: ToolMetadata[];
-    };
-    "tools.execute": {
-        params: ToolsExecuteParams;
-        result: unknown;
-    };
-    "tools.needsApproval": {
-        params: ToolsNeedsApprovalParams;
-        result: ToolsNeedsApprovalResult;
-    };
-    "hook.tool.before": {
-        params: HookToolBeforeParams;
-        result: HookToolBeforeResult;
-    };
-    "hook.tool.after": {
-        params: HookToolAfterParams;
-        result: HookToolAfterResult;
-    };
-    "hook.status": {
-        params: HookStatusParams;
-        result: HookStatusResult;
-    };
-} & StorageMethods;
-type AgentRpcMethodName = keyof AgentRpcMethods;
-/**
- * Result type for RPC override handlers.
- * - `{ ok: true; result: T }` - return this result
- * - `{ ok: false; error: string }` - return this error
- * - `null` - use default handler
- */
-type AgentRpcResult<T> = {
-    ok: true;
-    result: T;
-} | {
-    ok: false;
-    error: string;
-} | null;
-/**
- * Override handlers for agent RPC methods.
- * Each method can be individually overridden.
- * Return `null` to fall back to the default handler.
- */
-type AgentRpcOverrides = {
-    [K in AgentRpcMethodName]?: (params: AgentRpcMethods[K]["params"]) => Promise<AgentRpcResult<AgentRpcMethods[K]["result"]>>;
-};
-declare const agent: <Tools extends {}, TTags extends Record<string, unknown> = Record<string, never>, TContext extends Record<string, unknown> = Record<string, never>>(options: AgentOptions<Tools, TTags, TContext>) => {
-    session: (sessionId: string, sessionOptions?: SessionOptions<Tools, TTags>) => Promise<{
-        send: ({ input, interruptIfStreaming, context, }: {
-            input: SendInput | SendInput[];
-            interruptIfStreaming?: boolean;
-            context?: TContext;
-        }) => Promise<void | SessionError | StorageError>;
-        stream: (opts?: {
-            messageId?: string;
-        }) => Promise<AgentStream | Error>;
-        ui: () => Promise<StorageError | {
-            messages: UIMessage<unknown, AgentDataTypes, InferUITools<{
-                Read: ai.Tool<{
-                    path: string;
-                    startLine?: number | undefined;
-                    endLine?: number | undefined;
-                }, {
-                    content: string;
-                    metadata: {
-                        totalLines: number;
-                        linesShown: number;
-                        startLine: number;
-                        endLine: number;
-                        isPaginated: boolean;
-                        fileSize: string;
-                        path: string;
-                    };
-                }>;
-                Grep: ai.Tool<{
-                    pattern: string;
-                    caseSensitive: boolean;
-                    filesWithMatches: boolean;
-                    path?: string | undefined;
-                    fileType?: string | undefined;
-                    glob?: string | undefined;
-                    contextLines?: number | undefined;
-                    maxCount?: number | undefined;
-                }, {
-                    matches: string;
-                    summary: {
-                        matchCount: number;
-                        fileCount: number;
-                        searchPath: string;
-                        pattern: string;
-                    };
-                }>;
-                List: ai.Tool<{
-                    includeHidden: boolean;
-                    filesOnly: boolean;
-                    path?: string | undefined;
-                    depth?: number | undefined;
-                    pattern?: string | undefined;
-                }, {
-                    listing: string;
-                    summary: {
-                        totalItems: number;
-                        totalFiles: number;
-                        totalDirs: number;
-                        searchPath: string;
-                        depth?: number | undefined;
-                    };
-                }>;
-                Write: ai.Tool<{
-                    path: string;
-                    content: string;
-                }, {
-                    success: boolean;
-                    path: string;
-                    bytesWritten: number;
-                    error?: string | undefined;
-                }>;
-                Edit: ai.Tool<{
-                    path: string;
-                    old_string: string;
-                    new_string: string;
-                }, {
-                    success: boolean;
-                    path: string;
-                    error?: string | undefined;
-                }>;
-                Bash: ai.Tool<{
-                    command: string;
-                    waitUntil?: number | undefined;
-                }, {
-                    pid: number;
-                    output: string;
-                    exitCode: number;
-                    status: "running" | "completed" | "failed";
-                    cwd: string;
-                    outputFile: string;
-                }>;
-                JavaScript: ai.Tool<{
-                    code: string;
-                }, any>;
-            } & Tools>>[];
-            streamingMessageId: string | null;
-            usage: SessionUsage;
-        }>;
-        tag: {
-            list: () => Promise<SessionNotFoundError | StorageError | TTags>;
-            get: <K extends keyof TTags & string>(key: K) => Promise<TTags[K] | undefined | Error>;
-            set: <K extends keyof TTags & string>(key: K, value: TTags[K]) => Promise<undefined | Error>;
-            setMany: (tags: Partial<TTags>) => Promise<undefined | Error>;
-        };
-        sandbox: Sandbox<TTags> & {
-            _onReady?: Promise<void>;
-            _setupMeta?: Promise<SandboxSetupMeta>;
-        };
-        interrupt: () => Promise<StorageError | undefined>;
-        resolveApproval: ({ approvalId, approved, reason, }: {
-            approvalId: string;
-            approved: boolean;
-            reason?: string;
-        }) => Promise<undefined | Error>;
-        usage: () => Promise<SessionUsage | Error>;
-        update: (updateOptions: SessionUpdateOptions<Tools> & {
-            tags?: TTags;
-        }) => Promise<undefined | Error>;
-    }>;
-    sandbox: (sandboxId: string, opts?: {
-        config?: SandboxConfig;
-        tags?: TTags;
-        setup?: SandboxSetup;
-        onRestart?: OnRestart;
-    }) => Promise<Sandbox<TTags> & {
-        _onReady?: Promise<void>;
-        _setupMeta?: Promise<SandboxSetupMeta>;
-    }>;
-    readonly storage: TypedStorage<TTags>;
-    /**
-     * RPC handler for agent operations.
-     * Handles tools.list, tools.execute, storage RPC, and hooks.
-     *
-     * Called internally by the `rpc` step function during workflow execution.
-     * Can also be exposed via HTTP for external access if needed.
-     */
-    handler: (input: Request | RpcPayload, overrides?: AgentRpcOverrides) => Promise<Response | RpcResult>;
-    tools: typeof builtInTools & Tools;
-    /** Phantom property for type inference. Use `typeof myAgent.$UIMessage` to get the typed UIMessage. */
-    $UIMessage: UIMessage<unknown, AgentDataTypes, InferUITools<typeof builtInTools & Tools>>;
-    /** Agent name used as key for the RPC registry. Set by the loader init. */
-    _agentName: string;
-    rpc: (params: RpcPayload) => Promise<RpcResult>;
-};
-
-export { type AgentDataTypes as A, type BuiltInToolName as B, type ExecResult as E, type GenerationOptions as G, type InferUIMessage as I, type OnRestart as O, type RpcPayload as R, type Sandbox as S, type TagsSchema as T, type UploadableFile as U, type RpcResult as a, type AgentOptions as b, type AgentStatus as c, type AgentStream as d, type SandboxSetup as e, type SendInput as f, type SessionOptions as g, type SkillSummary as h, type ToolContext as i, agent as j, builtinToolNames as k, type SandboxLifecycleInput as l };