agent-lattice 0.18.0 → 0.20.0

package/README.md

@@ -86,7 +86,7 @@ them, so keep expensive handling off the loop itself.
 | `stream_event` | While the model is responding | Raw provider stream event for incremental rendering. |
 | `assistant` | After each model turn is assembled | The `AssistantModelMessage` with text / `tool_use` blocks and provider metadata. |
 | `user` | After a whole tool batch finishes | Tool results as `ToolResultBlock[]`; the prompt is never echoed. |
-| `result` | Once, at the end of the query | Final text, `subtype` (`"success"`, `"interrupted"`, or an error variant), and token usage. |
+| `result` | Once, at the end of the query | Final text, `subtype` (`"success"`, `"interrupted"`, or an error variant), optional `structuredResult`, and token usage. |
 
 For the exact per-event guarantees see
 [Streaming Events](https://docs.claude-code-sdk.com/concepts/streaming-events/).
@@ -150,6 +150,14 @@ Anthropic-compatible providers (for example DeepSeek's
 `https://api.deepseek.com/anthropic` endpoint) default thinking to on —
 omitting the field would leave it enabled.
 
+On DeepSeek, the on/off switch is the only thinking control that works:
+DeepSeek accepts `budget_tokens` but ignores the value, treats `adaptive` as
+plain enabled thinking, and does not support `reasoning_effort` at all. Its own
+thinking-strength knob is `output_config.effort`, which the SDK does not expose
+yet. See
+[Provider Compatibility](https://docs.claude-code-sdk.com/reference/provider-compatibility/)
+for the full matrix.
+
 For Kimi K3 through an Anthropic-compatible endpoint or gateway, use
 `reasoningEffort` to send the provider's top-level `reasoning_effort` parameter:
 
@@ -308,6 +316,82 @@ root and share one trace session. Each Agent keeps its own SDK session identity,
 recorded as `agent_session_id` metadata, so tracing does not change Agent state
 or returned SDK messages.
 
+## Langfuse Context Tracing
+
+*Requires 0.19.0 or later.*
+
+The Langfuse adapter targets the current Langfuse JS SDK generation
+(`@langfuse/tracing` v5), which is OpenTelemetry-based. Register the
+`LangfuseSpanProcessor` once at process startup, then create the tracer —
+no other wiring needed.
+
+Configure Langfuse with its standard environment variables:
+
+```bash
+LANGFUSE_PUBLIC_KEY=<your-langfuse-public-key>
+LANGFUSE_SECRET_KEY=<your-langfuse-secret-key>
+LANGFUSE_BASE_URL=https://us.cloud.langfuse.com # or your self-hosted host
+```
+
+```bash
+npm install @langfuse/otel @opentelemetry/sdk-trace-node
+```
+
+```ts
+// instrumentation: register the span processor before agents run.
+import { LangfuseSpanProcessor } from "@langfuse/otel";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+
+export const langfuseSpanProcessor = new LangfuseSpanProcessor();
+
+const tracerProvider = new NodeTracerProvider({
+  spanProcessors: [langfuseSpanProcessor],
+});
+tracerProvider.register();
+```
+
+```ts
+import {
+  createAgent,
+  createCompositeContextTracer,
+  createJsonlContextTracer,
+  createLangfuseContextTracer,
+} from "agent-lattice";
+import { langfuseSpanProcessor } from "./instrumentation";
+
+const tracer = createCompositeContextTracer([
+  createJsonlContextTracer({ path: ".agent-runs/session.jsonl" }),
+  createLangfuseContextTracer({
+    // Drained by tracer.flush()/close() so spans reach Langfuse before a
+    // short-lived process exits.
+    spanProcessor: langfuseSpanProcessor,
+    tags: ["local-debug"],
+  }),
+]);
+
+const agent = createAgent({
+  apiKey: process.env.DEEPSEEK_API_KEY,
+  baseURL: "https://api.deepseek.com/anthropic",
+  model: "deepseek-v4-flash",
+  tracer,
+});
+
+try {
+  await agent.prompt("Trace this run.", { stream: false });
+} finally {
+  await tracer.close?.();
+}
+```
+
+Langfuse receives one trace per SDK query: the agent run is a root `chain`
+observation carrying the trace name, session id, and tags; model turns appear
+as child `generation` observations and SDK tool calls as child `tool`
+observations. For a `Team` query, delegated runs nest as child `chain`
+observations under the team root, so one handoff invocation stays one trace.
+
+`startObservation` defaults to the bundled `@langfuse/tracing` function; pass
+`startObservation` only to inject a custom runtime or a test fake.
+
 Custom sinks can implement the same interface for SQLite, OpenTelemetry, object
 storage, or host-specific observability. A `ContextTracer` port object exposes
 methods only — `failOnError` is bound when the factory creates the tracer, not
@@ -339,6 +423,12 @@ const agent = createAgent({
 });
 ```
 
+Pass an explicit `deepseek-*` model name — unknown names are silently mapped to
+`deepseek-v4-flash`. For which SDK options DeepSeek actually honors (thinking
+budgets are ignored; `reasoningEffort` does not apply; structured output is not
+supported), see
+[Provider Compatibility](https://docs.claude-code-sdk.com/reference/provider-compatibility/).
+
 ## Custom Tool
 
 ```ts
@@ -386,6 +476,92 @@ started concurrently, their `tool_result` blocks still enter the history, and
 model call is skipped. When several tools in a batch set `endTurn`, the first
 one's content becomes the result text.
 
+A tool can also return `structuredResult` next to `endTurn: true` to carry a
+structured payload to `SDKResultMessage.structuredResult`
+(*requires 0.20.0 or later*). Without `endTurn`, `structuredResult` is
+ignored.
+
+## Structured Output Via submit_output
+
+*Requires 0.20.0 or later.*
+
+Set `AgentOptions.outputSchema` when a run must deliver a typed result rather
+than free text. The SDK injects a built-in `submit_output` tool (exported as
+`SUBMIT_OUTPUT_TOOL_NAME`) whose input schema is your schema converted to JSON
+Schema — a zod schema works directly, since `OutputSchema<T>` is just
+`{ parse(input: unknown): T }`:
+
+```ts
+import { createAgent } from "agent-lattice";
+import { z } from "zod/v4";
+
+const reviewSchema = z.object({
+  approved: z.boolean(),
+  issues: z.array(z.string()),
+});
+
+const reviewer = createAgent({
+  model: "claude-sonnet-4-6",
+  systemPrompt: "Review the change and submit your verdict.",
+  outputSchema: reviewSchema,
+});
+
+const result = await reviewer.prompt("Review the patch in this workspace.");
+if (result.subtype === "success") {
+  console.log(result.structuredResult); // { approved: false, issues: [...] }
+}
+```
+
+The structure is enforced by the harness, not by prompt discipline:
+
+- The model submits its answer by calling `submit_output`. The payload is
+  validated against the schema first; a validation failure goes back into the
+  loop as an error `tool_result`, so the model can fix it and retry. A valid
+  submission ends the run with `subtype: "success"` and the payload on
+  `SDKResultMessage.structuredResult`.
+- If the model ends its turn without calling `submit_output`, the run fails
+  with `subtype: "error_missing_output"` and a `MissingOutputError`. There is
+  no fallback that parses the final text as JSON.
+- `submit_output` must be the only tool call in its batch. A batch that mixes
+  it with other calls — or contains two submissions — is rejected with code
+  `submit_output_exclusive_batch` and the loop continues.
+- The name is reserved: registering your own `submit_output` tool while
+  `outputSchema` is set throws from `createAgent`/`addTools`.
+
+Unlike `outputFormat` (which relies on the provider's
+`response_format`/`json_schema` support — DeepSeek ignores it, see
+[Provider Compatibility](https://docs.claude-code-sdk.com/reference/provider-compatibility/)),
+`submit_output` only requires a model that can call tools, so it ports to any
+tool-capable provider.
+
+The same schema composes with `agentTool()` for parent/child delegation: pass
+it to the child agent and to `AgentToolOptions.outputSchema` on the parent
+side, and an `ask` call returns the child's validated output as a JSON string:
+
+```ts
+import { agentTool, createAgent } from "agent-lattice";
+
+const child = createAgent({
+  model: "claude-sonnet-4-5",
+  systemPrompt: "You review code and submit a structured verdict.",
+  outputSchema: reviewSchema, // child submits via submit_output
+});
+
+const parent = createAgent({
+  model: "claude-sonnet-4-6",
+  tools: [
+    agentTool("review", child, {
+      description: "Ask the reviewer to audit a change.",
+      outputSchema: reviewSchema, // validates the child's submission
+    }),
+  ],
+});
+```
+
+If the child ends without submitting or submits a payload that fails the
+parent's schema, the tool returns an `is_error` `tool_result` starting with
+`child_output_invalid:`, so the parent model sees the failure and can retry.
+
 ## Concurrent Tool Calls
 
 The model requests concurrency by returning multiple `tool_use` blocks in one

package/dist/index.d.ts

@@ -4,6 +4,8 @@ import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.
 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 { startObservation as bundledLangfuseStartObservation } from "@langfuse/tracing";
+import type { LangfuseChain, LangfuseGeneration, LangfuseObservation, LangfuseTool } from "@langfuse/tracing";
 import { z } from "zod/v4";
 export type TextBlock = TextBlockParam;
 export type ImageBlock = ImageBlockParam;
@@ -68,7 +70,7 @@ export type AgentRuntimeDelegateResult = {
     workspaceGrants?: WorkspaceGrant[];
 };
 export type AgentRuntimeFailure = {
-    code: "max_turns_exceeded" | "api_error" | "tool_execution_error" | "permission_denied" | "agent_error";
+    code: "max_turns_exceeded" | "api_error" | "tool_execution_error" | "permission_denied" | "missing_output" | "agent_error";
     message: string;
     name: string;
 };
@@ -153,6 +155,27 @@ export type LangSmithContextTracerOptions = {
     redact?: (event: ContextTraceEvent) => ContextTraceEvent | undefined;
     failOnError?: boolean;
 };
+export type LangfuseKVMap = Record<string, unknown>;
+export type LangfuseObservationLike = LangfuseObservation;
+export type LangfuseChainLike = LangfuseChain;
+export type LangfuseGenerationLike = LangfuseGeneration;
+export type LangfuseToolLike = LangfuseTool;
+export type LangfuseStartObservation = typeof bundledLangfuseStartObservation;
+/** Drained by the Langfuse tracer's flush()/close(); a LangfuseSpanProcessor satisfies this. */
+export type LangfuseFlushableSpanProcessor = {
+    forceFlush(): Promise<void>;
+};
+export type LangfuseContextTracerOptions = {
+    /** Defaults to the bundled @langfuse/tracing startObservation; inject a compatible function for custom runtimes or tests. */
+    startObservation?: LangfuseStartObservation;
+    /** Span processor drained on flush()/close() — pass the LangfuseSpanProcessor registered with your OpenTelemetry setup. */
+    spanProcessor?: LangfuseFlushableSpanProcessor;
+    name?: string;
+    tags?: string[];
+    metadata?: LangfuseKVMap;
+    redact?: (event: ContextTraceEvent) => ContextTraceEvent | undefined;
+    failOnError?: boolean;
+};
 export type ModelMessage = {
     role: "user" | "assistant";
     content: string | ContentBlock[];
@@ -240,6 +263,11 @@ export type ToolResult = {
     content: string | ContentBlock[];
     /** End the run after this tool batch: finish with subtype "success" instead of calling the model again. */
     endTurn?: boolean;
+    /**
+     * Structured payload carried to `SDKResultMessage.structuredResult` when this
+     * tool also ends the run with `endTurn`. Ignored otherwise.
+     */
+    structuredResult?: unknown;
 };
 export type ToolKind = "tool" | "agent_tool";
 export type ToolBatchCall = {
@@ -558,6 +586,16 @@ export type AgentOptions<TContext = unknown> = {
     requestTimeoutMs?: number;
     tools?: Array<ToolDefinition<any, TContext>>;
     toolBatchPolicy?: ToolBatchPolicy<TContext>;
+    /**
+     * Declares the run's structured output contract. When set, the SDK injects a
+     * `submit_output` tool with this schema: the run only ends successfully once
+     * the model submits a payload through it, and the validated payload lands on
+     * `SDKResultMessage.structuredResult`. Ending the turn without submitting
+     * fails the run with subtype `error_missing_output`. The tool must be the
+     * only call in its batch, and its name is reserved (registering a user tool
+     * with the same name throws).
+     */
+    outputSchema?: OutputSchema;
     /** Lifecycle callbacks that rewrite tool results and outgoing model requests. */
     hooks?: AgentHooks<TContext>;
     /**
@@ -659,12 +697,18 @@ export type SDKResultMessage = {
      * way, keeping completed turns in history so a follow-up query can continue
      * the conversation. `is_error` stays `false` for it.
      */
-    subtype: "success" | "interrupted" | "error" | "error_max_turns" | "error_abort" | "error_timeout";
+    subtype: "success" | "interrupted" | "error" | "error_max_turns" | "error_abort" | "error_timeout" | "error_missing_output";
     is_error: boolean;
     result: string;
     session_id: string;
     num_turns: number;
     error?: Error;
+    /**
+     * Validated structured payload submitted via the `submit_output` tool (see
+     * `AgentOptions.outputSchema`), or by any tool that ended the run with both
+     * `endTurn` and `ToolResult.structuredResult`. Absent otherwise.
+     */
+    structuredResult?: unknown;
     /** Summed over every model request in the query. Zeroed when unreported. */
     usage: TokenUsage;
     /**
@@ -711,6 +755,12 @@ export declare class ToolExecutionError extends AgentSDKError {
 }
 export declare class MaxTurnsError extends AgentSDKError {
 }
+/**
+ * A run with `AgentOptions.outputSchema` ended without the model calling the
+ * `submit_output` tool, so no structured output was produced.
+ */
+export declare class MissingOutputError extends AgentSDKError {
+}
 export declare class AbortError extends AgentSDKError {
 }
 /** A second query was started on an Agent that was still running one. */
@@ -729,6 +779,20 @@ export declare class ToolPermissionDeniedError extends AgentSDKError {
 }
 export declare function tool<TContext = unknown>(): <TSchema>(name: string, description: string, inputSchema: TSchema, handler: ToolHandler<InferInput<TSchema>, TContext>, options?: ToolOptions<InferInput<TSchema>>) => ToolDefinition<InferInput<TSchema>, TContext>;
 export declare function tool<TSchema, TContext = unknown>(name: string, description: string, inputSchema: TSchema, handler: ToolHandler<InferInput<TSchema>, TContext>, options?: ToolOptions<InferInput<TSchema>>): ToolDefinition<InferInput<TSchema>, TContext>;
+/**
+ * A schema describing structured output: a zod schema, or any object with a
+ * compatible `parse` method. The SDK validates submitted payloads with it and
+ * converts it to the JSON schema shown to the model.
+ */
+export type OutputSchema<TOutput = unknown> = {
+    parse(input: unknown): TOutput;
+};
+/**
+ * Name of the tool the SDK injects when `AgentOptions.outputSchema` is set.
+ * Reserved in that configuration: registering a user tool with the same name
+ * throws at `createAgent`/`addTools` time.
+ */
+export declare const SUBMIT_OUTPUT_TOOL_NAME = "submit_output";
 export type DelegateToolOptions = {
     wait?: DelegateWaitMode;
     targetMailboxId?: string;
@@ -757,6 +821,14 @@ export type AgentToolInput = z.infer<typeof agentToolInputSchema>;
 export type AgentToolOptions = {
     description: string;
     targetMailboxId?: string;
+    /**
+     * Expected structured output of the target, declared with the same schema
+     * the target uses for its own `AgentOptions.outputSchema`. With mode "ask"
+     * the tool result is the target's validated structured output as JSON; a
+     * target that ends without submitting — or submits a payload that fails this
+     * schema — produces a `child_output_invalid` tool error the parent can retry.
+     */
+    outputSchema?: OutputSchema;
 };
 /**
  * An AgentLike is a live session: it keeps its conversation history across
@@ -804,6 +876,16 @@ export declare function createJsonlContextTracer(options: JsonlContextTracerOpti
 export declare function createCompositeAgentHooks<TContext = unknown>(hooks: Array<AgentHooks<TContext> | undefined | null>): AgentHooks<TContext>;
 export declare function createCompositeContextTracer(tracers: Array<ContextTracer | undefined | null>): ContextTracer;
 export declare function createLangSmithContextTracer(options?: LangSmithContextTracerOptions): ContextTracer;
+/**
+ * Langfuse trace sink built on the current @langfuse/tracing (v5) SDK. The SDK
+ * is OpenTelemetry-based: the host registers a LangfuseSpanProcessor (from
+ * @langfuse/otel) with a tracer provider, and this adapter maps context trace
+ * events onto observations — a chain per agent run, a generation per model
+ * turn, a tool observation per tool call, and event observations for
+ * everything else. Pass the registered span processor so flush()/close() can
+ * drain pending spans before a short-lived process exits.
+ */
+export declare function createLangfuseContextTracer(options?: LangfuseContextTracerOptions): 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>>>>;