agent-lattice 0.9.12

package/dist/index.d.ts

@@ -0,0 +1,529 @@
+import type { DocumentBlockParam, ImageBlockParam, TextBlockParam } from "@anthropic-ai/sdk/resources/messages.mjs";
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import { type StdioServerParameters } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { type StreamableHTTPClientTransportOptions } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type { RunEvent, RunTree, RunTreeConfig } from "langsmith/run_trees";
+import { z } from "zod/v4";
+export type TextBlock = TextBlockParam;
+export type ImageBlock = ImageBlockParam;
+export type DocumentBlock = DocumentBlockParam;
+export type ToolUseBlock = {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+};
+export type ToolResultBlock = {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string | ContentBlock[];
+    is_error?: boolean;
+};
+export type ContentBlock = TextBlock | ImageBlock | DocumentBlock | ToolUseBlock | ToolResultBlock;
+export type AgentLikeEvent = SDKMessage | TeamRunnerMessage;
+export type AgentLike = {
+    query(prompt: string | ContentBlock[], options?: QueryOptions): AsyncGenerator<AgentLikeEvent>;
+    prompt(prompt: string | ContentBlock[], options?: QueryOptions): Promise<SDKResultMessage>;
+};
+export type DelegateWaitMode = "result" | "accepted";
+export type AgentRuntimeSource = {
+    kind: "root" | "team_member" | "agent";
+    name?: string;
+    team?: string;
+    member?: string;
+    mailbox?: string;
+};
+export type AgentRuntimeDelegateInput = {
+    name: string;
+    description?: string;
+    agent: AgentLike;
+    task: string;
+    wait?: DelegateWaitMode;
+    targetMailboxId?: string;
+    workspaceGrants?: WorkspaceGrantInput[];
+};
+export type AgentRuntimeDelegateResult = {
+    status: "completed" | "accepted";
+    content: string;
+    request: TeamMessage;
+    reply?: TeamMessage;
+    result?: SDKResultMessage;
+    workspaceGrants?: WorkspaceGrant[];
+};
+export type WorkspaceAccess = "read" | "write" | "execute";
+export type WorkspaceGrantInput = {
+    root: string;
+    access?: WorkspaceAccess[];
+    reason?: string;
+    expiresAt?: number;
+};
+export type WorkspaceGrant = WorkspaceGrantInput & {
+    kind: "workspace";
+    root: string;
+    access: WorkspaceAccess[];
+    grantor?: AgentRuntimeSource;
+    grantee?: AgentRuntimeSource;
+    workItemId?: string;
+};
+export type RuntimePermissions = {
+    workspaceGrants?: WorkspaceGrantInput[];
+};
+export type PermissionDenialReasonCode = "outside_allowed_roots" | "grant_not_authorized" | "expired_grant";
+export type PermissionDenial = {
+    status: "permission_denied";
+    tool: string;
+    operation: WorkspaceAccess;
+    requestedPath?: string;
+    reasonCode: PermissionDenialReasonCode;
+    reason: string;
+    allowedRoots: string[];
+    suggestedNextStep: string;
+};
+export type AgentRuntimeContext = {
+    source: AgentRuntimeSource;
+    permissions: RuntimePermissions;
+    delegate(input: AgentRuntimeDelegateInput): Promise<AgentRuntimeDelegateResult>;
+    emit(message: TeamRunnerMessage): void;
+};
+export type ContextTraceEventType = "run_start" | "user_message" | "model_request" | "assistant_message" | "tool_use" | "tool_result" | "team_message" | "result" | "error";
+export type ContextTraceEvent = {
+    version: 1;
+    timestamp: string;
+    session_id: string;
+    run_id: string;
+    parent_run_id?: string;
+    seq: number;
+    source: AgentRuntimeSource;
+    type: ContextTraceEventType;
+    data: Record<string, unknown>;
+};
+export type ContextTracer = {
+    failOnError?: boolean;
+    onEvent(event: ContextTraceEvent): Promise<void> | void;
+    flush?(): Promise<void>;
+    close?(): Promise<void>;
+};
+export type JsonlContextTracerOptions = {
+    path?: string;
+    dir?: string;
+    redact?: (event: ContextTraceEvent) => ContextTraceEvent | undefined;
+    failOnError?: boolean;
+};
+export type LangSmithKVMap = Record<string, unknown>;
+export type LangSmithRunTreeConfig = RunTreeConfig;
+export type LangSmithRunEvent = RunEvent;
+export type LangSmithRunTreeLike = RunTree;
+export type LangSmithRunTreeConstructor = new (config: LangSmithRunTreeConfig) => LangSmithRunTreeLike;
+export type LangSmithWriteReplicaConfig = NonNullable<LangSmithRunTreeConfig["replicas"]>[number];
+export type LangSmithContextTracerOptions = {
+    RunTree?: LangSmithRunTreeConstructor;
+    runTree?: (config: LangSmithRunTreeConfig) => LangSmithRunTreeLike;
+    projectName?: string;
+    name?: string;
+    apiUrl?: string;
+    apiKey?: string;
+    workspaceId?: string;
+    client?: LangSmithRunTreeConfig["client"];
+    tags?: string[];
+    metadata?: LangSmithKVMap;
+    redact?: (event: ContextTraceEvent) => ContextTraceEvent | undefined;
+    failOnError?: boolean;
+};
+export type ModelMessage = {
+    role: "user" | "assistant";
+    content: string | ContentBlock[];
+};
+export type AssistantModelMessage = {
+    role: "assistant";
+    content: ContentBlock[];
+};
+export type ModelToolDefinition = {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+};
+export type ModelRequest = {
+    model: string;
+    systemPrompt?: string;
+    maxTokens: number;
+    messages: ModelMessage[];
+    tools: ModelToolDefinition[];
+    stream: boolean;
+    onStreamEvent?: (event: Record<string, unknown>) => void;
+    signal?: AbortSignal;
+};
+export interface ModelClient {
+    createMessage(request: ModelRequest): Promise<AssistantModelMessage>;
+}
+export type ToolResult = {
+    content: string | ContentBlock[];
+};
+export type ToolHandler<TInput = unknown> = (input: TInput, context: {
+    signal?: AbortSignal;
+    toolUseId: string;
+    runtime?: AgentRuntimeContext;
+    permissions?: RuntimePermissions;
+}) => Promise<ToolResult> | ToolResult;
+export type ToolDefinition<TInput = unknown> = {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+    jsonSchema: Record<string, unknown>;
+    parse(input: unknown): TInput;
+    handler: ToolHandler<TInput>;
+};
+export type SkillDefinition = {
+    name: string;
+    description: string;
+    instructions: string;
+    path?: string;
+};
+export type SkillInput = {
+    name: string;
+    description: string;
+    instructions: string;
+    path?: string;
+};
+export type MCPContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: string;
+    [key: string]: unknown;
+};
+export type MCPTool = {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+};
+export type MCPListToolsResult = {
+    tools: MCPTool[];
+};
+export type MCPCallToolResult = {
+    content?: MCPContentBlock[];
+    structuredContent?: unknown;
+    isError?: boolean;
+};
+export type MCPClient = {
+    listTools(): Promise<MCPListToolsResult>;
+    callTool(input: {
+        name: string;
+        arguments?: Record<string, unknown>;
+    }): Promise<MCPCallToolResult>;
+};
+export type MCPToolsOptions = {
+    namePrefix?: string;
+};
+export type MCPStdioServerOptions = MCPToolsOptions & {
+    clientName?: string;
+    clientVersion?: string;
+};
+export type MCPStdioConnection = {
+    client: MCPClient;
+    tools: Array<ToolDefinition<any>>;
+    close(): Promise<void>;
+};
+export type MCPStreamableHTTPServerOptions = MCPToolsOptions & {
+    clientName?: string;
+    clientVersion?: string;
+    authProvider?: OAuthClientProvider;
+    requestInit?: RequestInit;
+    fetch?: StreamableHTTPClientTransportOptions["fetch"];
+    reconnectionOptions?: StreamableHTTPClientTransportOptions["reconnectionOptions"];
+    sessionId?: string;
+};
+export type MCPStreamableHTTPConnection = MCPStdioConnection & {
+    finishAuth(authorizationCode: string): Promise<void>;
+    terminateSession(): Promise<void>;
+    sessionId: string | undefined;
+};
+export type TeamMemberRole = "lead" | "head" | "executor";
+export type TeamMemberDefinition = {
+    name: string;
+    role: TeamMemberRole;
+    focus?: string;
+    agent: AgentLike;
+    mailboxId?: string;
+};
+export type TeamMemberInput = TeamMemberDefinition;
+export type TeamMessageStatus = "pending" | "processing" | "done" | "failed" | "cancelled" | "read";
+export type TeamMessageRole = "upstream_request" | "delegation" | "executor_result" | "downstream_reply" | "upstream_report" | "followup" | "message";
+export type TeamMessage = {
+    id: string;
+    from: string;
+    to: string;
+    content: string;
+    status: TeamMessageStatus;
+    createdAt: number;
+    threadId: string;
+    parentMessageId?: string;
+    workItemId?: string;
+    workItemRole?: TeamMessageRole;
+    upstreamMessageId?: string;
+    metadata?: Record<string, unknown>;
+};
+export type TeamSendOptions = {
+    threadId?: string;
+    parentMessageId?: string;
+    workItemId?: string;
+    workItemRole?: TeamMessageRole;
+    upstreamMessageId?: string;
+    metadata?: Record<string, unknown>;
+};
+export type TeamMailbox = {
+    send(from: string, to: string, content: string, options?: TeamSendOptions): Promise<TeamMessage>;
+    inbox(mailboxId: string, options?: {
+        status?: TeamMessageStatus | "all";
+    }): Promise<TeamMessage[]>;
+    get(messageId: string): Promise<TeamMessage | undefined>;
+    claimNext(mailboxId: string): Promise<TeamMessage | undefined>;
+    updateStatus(messageId: string, status: TeamMessageStatus): Promise<boolean>;
+};
+export type SQLiteStatementLike = {
+    run(...params: unknown[]): unknown;
+    get(...params: unknown[]): unknown;
+    all(...params: unknown[]): unknown[];
+};
+export type SQLiteDatabaseLike = {
+    prepare(sql: string): SQLiteStatementLike;
+    exec?(sql: string): unknown;
+};
+export type SQLiteMailboxOptions = {
+    database: SQLiteDatabaseLike;
+    tableName?: string;
+};
+export type TeamOptions = {
+    name: string;
+    lead: Agent;
+    members: TeamMemberDefinition[];
+    mailbox?: TeamMailbox;
+    exposeLeadMailboxTools?: boolean;
+};
+export type Team = {
+    name: string;
+    lead: Agent;
+    members: TeamMemberDefinition[];
+    mailbox: TeamMailbox;
+    tools: Array<ToolDefinition<any>>;
+    memberTools: Record<string, Array<ToolDefinition<any>>>;
+    send(from: string, to: string, content: string, options?: TeamSendOptions): Promise<TeamMessage>;
+    drain(options?: TeamDrainOptions): Promise<TeamDrainResult>;
+    query(prompt: string | ContentBlock[], options?: QueryOptions): AsyncGenerator<TeamRunnerMessage>;
+    prompt(prompt: string | ContentBlock[], options?: QueryOptions): Promise<SDKResultMessage>;
+};
+export type TeamDrainOptions = {
+    maxRounds?: number;
+    maxMessages?: number;
+    signal?: AbortSignal;
+};
+export type TeamDrainResult = {
+    processed: number;
+    failed: number;
+    rounds: number;
+};
+export type TeamRunnerOptions = {
+    team?: Team;
+    root?: AgentLike;
+    mailbox?: TeamMailbox;
+    source?: AgentRuntimeSource;
+    maxDelegateDepth?: number;
+};
+export type TeamRunner = {
+    root: AgentLike;
+    mailbox: TeamMailbox;
+    query(prompt: string | ContentBlock[], options?: QueryOptions): AsyncGenerator<TeamRunnerMessage>;
+    prompt(prompt: string | ContentBlock[], options?: QueryOptions): Promise<SDKResultMessage>;
+};
+export type PermissionRequest = {
+    toolName: string;
+    input: Record<string, unknown>;
+    toolUseId: string;
+};
+export type PermissionDecision = {
+    behavior: "allow";
+} | {
+    behavior: "deny";
+    message: string;
+};
+export type AgentWorkspaceOptions = string | {
+    cwd: string;
+    allowedDirectories?: string[];
+    bashTimeoutMs?: number;
+};
+export type AgentOptions = {
+    apiKey?: string;
+    baseURL?: string;
+    name?: string;
+    model: string;
+    systemPrompt?: string;
+    maxTokens?: number;
+    maxTurns?: number;
+    tools?: Array<ToolDefinition<any>>;
+    skills?: SkillDefinition[];
+    workspace?: AgentWorkspaceOptions;
+    permission?: (request: PermissionRequest) => Promise<PermissionDecision> | PermissionDecision;
+    modelClient?: ModelClient;
+    tracer?: ContextTracer;
+};
+export type AgentWorkspaceToolsOptions = {
+    cwd?: string;
+    allowedDirectories?: string[];
+    bashTimeoutMs?: number;
+};
+export type QueryOptions = {
+    stream?: boolean;
+    signal?: AbortSignal;
+    runtime?: AgentRuntimeContext;
+    permissions?: RuntimePermissions;
+    tracer?: ContextTracer;
+};
+export type SDKSystemInitMessage = {
+    type: "system";
+    subtype: "init";
+    model: string;
+    tools: string[];
+    session_id: string;
+};
+export type SDKAssistantMessage = {
+    type: "assistant";
+    message: AssistantModelMessage;
+    session_id: string;
+};
+export type SDKUserMessage = {
+    type: "user";
+    message: ModelMessage;
+    session_id: string;
+    tool_use_result?: string | ContentBlock[];
+    error?: Error;
+};
+export type SDKStreamEventMessage = {
+    type: "stream_event";
+    event: Record<string, unknown>;
+    session_id: string;
+};
+export type SDKResultMessage = {
+    type: "result";
+    subtype: "success" | "error" | "error_max_turns" | "error_abort";
+    is_error: boolean;
+    result: string;
+    session_id: string;
+    num_turns: number;
+    error?: Error;
+};
+export type SDKMessage = SDKSystemInitMessage | SDKStreamEventMessage | SDKAssistantMessage | SDKUserMessage | SDKResultMessage;
+export type TeamRunnerSource = AgentRuntimeSource;
+export type TeamRunnerTeamMessage = {
+    type: "team_message";
+    subtype: "sent" | "claimed" | "replied" | "followup" | "done" | "failed";
+    source: TeamRunnerSource;
+    mailbox: string;
+    message: TeamMessage;
+};
+export type TeamRunnerAgentMessage = {
+    type: "agent_message";
+    source: TeamRunnerSource;
+    message: SDKMessage;
+};
+export type TeamRunnerAgentLifecycleMessage = {
+    type: "team_agent";
+    subtype: "started" | "finished";
+    source: TeamRunnerSource;
+};
+export type TeamRunnerStreamEventMessage = {
+    type: "stream_event";
+    source: TeamRunnerSource;
+    event: Record<string, unknown>;
+    session_id: string;
+};
+export type TeamRunnerMessage = SDKMessage | TeamRunnerTeamMessage | TeamRunnerAgentMessage | TeamRunnerAgentLifecycleMessage | TeamRunnerStreamEventMessage;
+export declare class AgentSDKError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare class APIError extends AgentSDKError {
+}
+export declare class ToolExecutionError extends AgentSDKError {
+}
+export declare class MaxTurnsError extends AgentSDKError {
+}
+export declare class AbortError extends AgentSDKError {
+}
+export declare class ToolPermissionDeniedError extends AgentSDKError {
+    readonly denial: PermissionDenial;
+    constructor(denial: PermissionDenial);
+}
+export declare function tool<TSchema>(name: string, description: string, inputSchema: TSchema, handler: ToolHandler<InferInput<TSchema>>): ToolDefinition<InferInput<TSchema>>;
+export type DelegateToolOptions = {
+    wait?: DelegateWaitMode;
+    targetMailboxId?: string;
+    workspaceGrants?: WorkspaceGrantInput[];
+};
+export type AgentToolMode = "ask" | "handoff" | "observe";
+export declare const agentToolInputSchema: z.ZodObject<{
+    mode: z.ZodEnum<{
+        ask: "ask";
+        handoff: "handoff";
+        observe: "observe";
+    }>;
+    task: z.ZodString;
+    expectedOutput: z.ZodOptional<z.ZodString>;
+    acceptanceCriteria: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    workspaceGrants: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        root: z.ZodString;
+        access: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            write: "write";
+        }>>>;
+        reason: z.ZodOptional<z.ZodString>;
+        expiresAt: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type AgentToolInput = z.infer<typeof agentToolInputSchema>;
+export type AgentToolOptions = {
+    description: string;
+    targetMailboxId?: string;
+};
+export declare function agentTool(name: string, agent: AgentLike, options: AgentToolOptions): ToolDefinition<AgentToolInput>;
+export declare function delegateTool(name: string, description: string, agent: AgentLike, options?: DelegateToolOptions): ToolDefinition<{
+    task: string;
+}>;
+export declare function createAgent(options: AgentOptions): Agent;
+export declare function createJsonlContextTracer(options: JsonlContextTracerOptions): ContextTracer;
+export declare function createCompositeContextTracer(tracers: Array<ContextTracer | undefined | null>): ContextTracer;
+export declare function createLangSmithContextTracer(options: LangSmithContextTracerOptions): ContextTracer;
+export declare function skill(input: SkillInput): SkillDefinition;
+export declare function loadSkill(path: string): Promise<SkillDefinition>;
+export declare function createMCPTools(client: MCPClient, options?: MCPToolsOptions): Promise<Array<ToolDefinition<Record<string, unknown>>>>;
+export declare function connectMCPStdioServer(server: StdioServerParameters, options?: MCPStdioServerOptions): Promise<MCPStdioConnection>;
+export declare function connectMCPStreamableHTTPServer(url: string | URL, options?: MCPStreamableHTTPServerOptions): Promise<MCPStreamableHTTPConnection>;
+export declare function teamMember(input: TeamMemberInput): TeamMemberDefinition;
+export declare function createMemoryMailbox(): TeamMailbox;
+export declare function createSQLiteMailbox(options: SQLiteMailboxOptions): TeamMailbox;
+export declare function createTeam(options: TeamOptions): Team;
+export declare function createTeamRunner(options: TeamRunnerOptions): TeamRunner;
+export declare function createAgentWorkspaceTools(options?: AgentWorkspaceToolsOptions): Array<ToolDefinition<any>>;
+export declare function query(params: AgentOptions & {
+    prompt: string;
+    stream?: boolean;
+    signal?: AbortSignal;
+}): AsyncGenerator<SDKMessage>;
+export declare class Agent {
+    private readonly options;
+    private readonly modelClient;
+    private readonly messages;
+    private readonly sessionId;
+    constructor(options: AgentOptions);
+    query(prompt: string | ContentBlock[], options?: QueryOptions): AsyncGenerator<SDKMessage>;
+    prompt(prompt: string | ContentBlock[], options?: QueryOptions): Promise<SDKResultMessage>;
+    addTools(tools: Array<ToolDefinition<any>>): void;
+    private initMessage;
+    private resultMessage;
+    private modelTools;
+    private messagesForModel;
+    private selectSkills;
+    private runTool;
+}
+type InferInput<TSchema> = TSchema extends {
+    parse(input: unknown): infer TInput;
+} ? TInput : Record<string, unknown>;
+export {};