agent-lattice 0.25.1 → 0.26.0

package/README.md

@@ -701,6 +701,17 @@ the target's lifecycle: an `AgentSpec` spawns a fresh session per call, while an
 `AgentLike` target keeps history across calls and is usually not safe to call
 concurrently. *Requires 0.24.0 or later.*
 
+For durable child sessions, `AgentToolOptions.prepareTarget` runs after the
+child's input has been validated and mapped to a task, before the child starts.
+It receives the target, task, tool-use ID, parent run ID, trace session ID, and
+abort signal; return the `AgentLike` to call. A host can spawn the supplied
+`AgentSpec` with a per-call `HistoryStore` and return an adapter that records
+its event stream. Without the hook, a spec still spawns a fresh session as
+before. Direct `ask` child trace events share the parent's trace session and
+carry both `parent_run_id` and `parent_tool_use_id`, so concurrent calls to the
+same child can be distinguished. The host owns cleanup if preparing a child
+fails. *Requires 0.26.0 or later.*
+
 When concurrency is available, the SDK tells the model to batch independent
 calls and to use separate assistant responses when a later call needs an earlier
 result. Runtime safety checks and `toolBatchPolicy` remain authoritative.

package/dist/index.d.ts

@@ -117,6 +117,7 @@ export type ContextTraceEvent = {
     session_id: string;
     run_id: string;
     parent_run_id?: string;
+    parent_tool_use_id?: string;
     seq: number;
     source: AgentRuntimeSource;
     type: ContextTraceEventType;
@@ -298,6 +299,11 @@ export type ToolBatchPolicy<TContext = unknown> = {
 export type ToolExecutionContext<TContext = unknown> = {
     signal?: AbortSignal;
     toolUseId: string;
+    /** Current agent query, when the tool is called from an agent loop. */
+    trace?: {
+        sessionId: string;
+        runId: string;
+    };
     context?: TContext;
     agentRuntime?: AgentRuntimeContext;
     permissions?: RuntimePermissions;
@@ -853,6 +859,21 @@ export type AgentToolOptions = {
      * never shown to the model.
      */
     metadata?: Record<string, unknown>;
+    /**
+     * Resolve the child session for this invocation after input validation and
+     * task mapping, before the child runs. A host can spawn an AgentSpec with a
+     * per-call HistoryStore and return an AgentLike that records its event stream.
+     * The default is to spawn a spec or reuse a live AgentLike target.
+     */
+    prepareTarget?: (invocation: {
+        target: AgentToolTarget;
+        toolName: string;
+        toolUseId: string;
+        task: string | ContentBlock[];
+        parentRunId?: string;
+        traceSessionId?: string;
+        signal?: AbortSignal;
+    }) => AgentLike<any> | Promise<AgentLike<any>>;
     /**
      * Expected structured output of the target. When omitted, the declaration is
      * inherited from the target itself (an Agent's or AgentSpec's