agent-lattice 0.9.12 → 0.9.14

package/README.md

@@ -31,6 +31,25 @@ for await (const message of agent.query("Say hello")) {
 }
 ```
 
+`createAgent()` includes a private workspace and the built-in file/shell tools
+by default. Use `createBareAgent()` when your host wants to provide every prompt
+and tool explicitly:
+
+```ts
+import { createBareAgent, createBuiltinTools } from "agent-lattice";
+
+const agent = createBareAgent({
+  apiKey: process.env.DEEPSEEK_API_KEY,
+  baseURL: "https://api.deepseek.com/anthropic",
+  model: "deepseek-v4-flash",
+  systemPrompt: "You are a concise engineering assistant.",
+  tools: createBuiltinTools({
+    cwd: process.cwd(),
+    allowedDirectories: [process.cwd()],
+  }),
+});
+```
+
 Pass `{ stream: false }` to disable model streaming for a query:
 
 ```ts
@@ -208,6 +227,53 @@ const result = await agent.prompt("What is 2+2?");
 console.log(result.result);
 ```
 
+## Business Context For Tools
+
+Pass host application data through `context`. The SDK gives that context to
+tool handlers, but does not automatically put it into the model transcript. The
+model sees the data only if a tool returns it.
+
+```ts
+import { createBareAgent, tool } from "agent-lattice";
+import { z } from "zod/v4";
+
+type QcContext = {
+  patientRecordId: string;
+  scoringStandardId: string;
+};
+
+const readPatientRecordInput = z.object({});
+const qcTool = tool<QcContext>();
+
+const readPatientRecord = qcTool(
+  "read_patient_record",
+  "Read the current patient record",
+  readPatientRecordInput,
+  async (_input, { context }) => {
+    return {
+      content: JSON.stringify({
+        patientRecordId: context?.patientRecordId,
+        scoringStandardId: context?.scoringStandardId,
+      }),
+    };
+  },
+);
+
+const agent = createBareAgent<QcContext>({
+  apiKey: process.env.DEEPSEEK_API_KEY,
+  baseURL: "https://api.deepseek.com/anthropic",
+  model: "deepseek-v4-flash",
+  tools: [readPatientRecord],
+});
+
+const result = await agent.prompt("Review the current patient record.", {
+  context: {
+    patientRecordId: "ocr_123",
+    scoringStandardId: "tumor-treatment-process-v1",
+  },
+});
+```
+
 ## Permission Callback
 
 ```ts
@@ -342,7 +408,7 @@ const mcp = await connectMCPStreamableHTTPServer("https://mcp.example.com/mcp",
 `Agent` and `Team` satisfy the same `AgentLike` shape:
 
 ```ts
-type AgentLike = {
+type AgentLike<TContext = unknown> = {
   query(prompt, options?): AsyncGenerator<SDKMessage | TeamRunnerMessage>;
   prompt(prompt, options?): Promise<SDKResultMessage>;
 };
@@ -596,7 +662,8 @@ sends a diagnostic follow-up to the upstream mailbox.
 
 ## Agent Workspace Tools
 
-AgentLattice includes an opt-in set of workspace tools:
+`createAgent()` includes a private workspace and these built-in tools by
+default:
 
 - `Read`
 - `Write`
@@ -606,14 +673,18 @@ AgentLattice includes an opt-in set of workspace tools:
 - `Grep`
 - `Bash`
 
+Use `createBuiltinTools()` or `createAgentWorkspaceTools()` when you want to
+assemble the tool list yourself, especially with `createBareAgent()`:
+
 ```ts
-import { createAgent, createAgentWorkspaceTools } from "agent-lattice";
+import { createBareAgent, createBuiltinTools } from "agent-lattice";
 
-const agent = createAgent({
+const agent = createBareAgent({
   apiKey: process.env.DEEPSEEK_API_KEY,
   baseURL: "https://api.deepseek.com/anthropic",
   model: "deepseek-v4-flash",
-  tools: createAgentWorkspaceTools({
+  systemPrompt: "Use the configured project directory for file work.",
+  tools: createBuiltinTools({
     cwd: process.cwd(),
     allowedDirectories: [process.cwd()],
   }),
@@ -626,12 +697,12 @@ const agent = createAgent({
 });
 ```
 
-These tools are not enabled by default. `Read`, `LS`, `Glob`, and `Grep` are
-read-only observation tools and are not gated by workspace grants. `Write`,
-`Edit`, and obvious Bash writes are gated to the configured workspace roots and
-task-scoped shared workspace grants, so production hosts should pair write and
-shell access with a permission callback. Shell redirects to `/dev/null` are
-treated as discard targets, not workspace writes.
+`Read`, `LS`, `Glob`, and `Grep` are read-only observation tools and are not
+gated by workspace grants. `Write`, `Edit`, and obvious Bash writes are gated to
+the configured workspace roots and task-scoped shared workspace grants, so
+production hosts should pair write and shell access with a permission callback.
+Shell redirects to `/dev/null` are treated as discard targets, not workspace
+writes.
 
 ## Multi-turn Session
 

package/dist/index.d.ts

@@ -21,9 +21,9 @@ export type ToolResultBlock = {
 };
 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 AgentLike<TContext = unknown> = {
+    query(prompt: string | ContentBlock[], options?: QueryOptions<TContext>): AsyncGenerator<AgentLikeEvent>;
+    prompt(prompt: string | ContentBlock[], options?: QueryOptions<TContext>): Promise<SDKResultMessage>;
 };
 export type DelegateWaitMode = "result" | "accepted";
 export type AgentRuntimeSource = {
@@ -36,7 +36,7 @@ export type AgentRuntimeSource = {
 export type AgentRuntimeDelegateInput = {
     name: string;
     description?: string;
-    agent: AgentLike;
+    agent: AgentLike<any>;
     task: string;
     wait?: DelegateWaitMode;
     targetMailboxId?: string;
@@ -158,19 +158,21 @@ export interface ModelClient {
 export type ToolResult = {
     content: string | ContentBlock[];
 };
-export type ToolHandler<TInput = unknown> = (input: TInput, context: {
+export type ToolExecutionContext<TContext = unknown> = {
     signal?: AbortSignal;
     toolUseId: string;
-    runtime?: AgentRuntimeContext;
+    context?: TContext;
+    agentRuntime?: AgentRuntimeContext;
     permissions?: RuntimePermissions;
-}) => Promise<ToolResult> | ToolResult;
-export type ToolDefinition<TInput = unknown> = {
+};
+export type ToolHandler<TInput = unknown, TContext = unknown> = (input: TInput, context: ToolExecutionContext<TContext>) => Promise<ToolResult> | ToolResult;
+export type ToolDefinition<TInput = unknown, TContext = unknown> = {
     name: string;
     description: string;
     inputSchema: unknown;
     jsonSchema: Record<string, unknown>;
     parse(input: unknown): TInput;
-    handler: ToolHandler<TInput>;
+    handler: ToolHandler<TInput, TContext>;
 };
 export type SkillDefinition = {
     name: string;
@@ -220,7 +222,7 @@ export type MCPStdioServerOptions = MCPToolsOptions & {
 };
 export type MCPStdioConnection = {
     client: MCPClient;
-    tools: Array<ToolDefinition<any>>;
+    tools: Array<ToolDefinition<any, any>>;
     close(): Promise<void>;
 };
 export type MCPStreamableHTTPServerOptions = MCPToolsOptions & {
@@ -242,7 +244,7 @@ export type TeamMemberDefinition = {
     name: string;
     role: TeamMemberRole;
     focus?: string;
-    agent: AgentLike;
+    agent: AgentLike<any>;
     mailboxId?: string;
 };
 export type TeamMemberInput = TeamMemberDefinition;
@@ -294,18 +296,18 @@ export type SQLiteMailboxOptions = {
 };
 export type TeamOptions = {
     name: string;
-    lead: Agent;
+    lead: Agent<any>;
     members: TeamMemberDefinition[];
     mailbox?: TeamMailbox;
     exposeLeadMailboxTools?: boolean;
 };
 export type Team = {
     name: string;
-    lead: Agent;
+    lead: Agent<any>;
     members: TeamMemberDefinition[];
     mailbox: TeamMailbox;
-    tools: Array<ToolDefinition<any>>;
-    memberTools: Record<string, Array<ToolDefinition<any>>>;
+    tools: Array<ToolDefinition<any, any>>;
+    memberTools: Record<string, Array<ToolDefinition<any, 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>;
@@ -323,13 +325,13 @@ export type TeamDrainResult = {
 };
 export type TeamRunnerOptions = {
     team?: Team;
-    root?: AgentLike;
+    root?: AgentLike<any>;
     mailbox?: TeamMailbox;
     source?: AgentRuntimeSource;
     maxDelegateDepth?: number;
 };
 export type TeamRunner = {
-    root: AgentLike;
+    root: AgentLike<any>;
     mailbox: TeamMailbox;
     query(prompt: string | ContentBlock[], options?: QueryOptions): AsyncGenerator<TeamRunnerMessage>;
     prompt(prompt: string | ContentBlock[], options?: QueryOptions): Promise<SDKResultMessage>;
@@ -350,7 +352,7 @@ export type AgentWorkspaceOptions = string | {
     allowedDirectories?: string[];
     bashTimeoutMs?: number;
 };
-export type AgentOptions = {
+export type AgentOptions<TContext = unknown> = {
     apiKey?: string;
     baseURL?: string;
     name?: string;
@@ -358,22 +360,24 @@ export type AgentOptions = {
     systemPrompt?: string;
     maxTokens?: number;
     maxTurns?: number;
-    tools?: Array<ToolDefinition<any>>;
+    tools?: Array<ToolDefinition<any, TContext>>;
     skills?: SkillDefinition[];
     workspace?: AgentWorkspaceOptions;
     permission?: (request: PermissionRequest) => Promise<PermissionDecision> | PermissionDecision;
     modelClient?: ModelClient;
     tracer?: ContextTracer;
 };
+export type BareAgentOptions<TContext = unknown> = Omit<AgentOptions<TContext>, "workspace">;
 export type AgentWorkspaceToolsOptions = {
     cwd?: string;
     allowedDirectories?: string[];
     bashTimeoutMs?: number;
 };
-export type QueryOptions = {
+export type QueryOptions<TContext = unknown> = {
     stream?: boolean;
     signal?: AbortSignal;
-    runtime?: AgentRuntimeContext;
+    context?: TContext;
+    agentRuntime?: AgentRuntimeContext;
     permissions?: RuntimePermissions;
     tracer?: ContextTracer;
 };
@@ -453,7 +457,8 @@ 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 declare function tool<TContext = unknown>(): <TSchema>(name: string, description: string, inputSchema: TSchema, handler: ToolHandler<InferInput<TSchema>, TContext>) => ToolDefinition<InferInput<TSchema>, TContext>;
+export declare function tool<TSchema, TContext = unknown>(name: string, description: string, inputSchema: TSchema, handler: ToolHandler<InferInput<TSchema>, TContext>): ToolDefinition<InferInput<TSchema>, TContext>;
 export type DelegateToolOptions = {
     wait?: DelegateWaitMode;
     targetMailboxId?: string;
@@ -483,11 +488,13 @@ 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<{
+export declare function agentTool(name: string, agent: AgentLike<any>, options: AgentToolOptions): ToolDefinition<AgentToolInput>;
+export declare function delegateTool(name: string, description: string, agent: AgentLike<any>, options?: DelegateToolOptions): ToolDefinition<{
     task: string;
 }>;
-export declare function createAgent(options: AgentOptions): Agent;
+export declare function createAgent<TContext = unknown>(options: AgentOptions<TContext>): Agent<TContext>;
+export declare function createBareAgent<TContext = unknown>(options: BareAgentOptions<TContext>): Agent<TContext>;
+export declare function createBuiltinTools(options?: AgentWorkspaceToolsOptions): Array<ToolDefinition<any, any>>;
 export declare function createJsonlContextTracer(options: JsonlContextTracerOptions): ContextTracer;
 export declare function createCompositeContextTracer(tracers: Array<ContextTracer | undefined | null>): ContextTracer;
 export declare function createLangSmithContextTracer(options: LangSmithContextTracerOptions): ContextTracer;
@@ -501,21 +508,22 @@ 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 & {
+export declare function createAgentWorkspaceTools(options?: AgentWorkspaceToolsOptions): Array<ToolDefinition<any, any>>;
+export declare function query<TContext = unknown>(params: AgentOptions<TContext> & {
     prompt: string;
     stream?: boolean;
     signal?: AbortSignal;
+    context?: TContext;
 }): AsyncGenerator<SDKMessage>;
-export declare class Agent {
+export declare class Agent<TContext = unknown> {
     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;
+    constructor(options: AgentOptions<TContext>);
+    query(prompt: string | ContentBlock[], options?: QueryOptions<TContext>): AsyncGenerator<SDKMessage>;
+    prompt(prompt: string | ContentBlock[], options?: QueryOptions<TContext>): Promise<SDKResultMessage>;
+    addTools(tools: Array<ToolDefinition<any, TContext>>): void;
     private initMessage;
     private resultMessage;
     private modelTools;