@letta-ai/letta-agent-sdk 0.8.73 → 0.8.74

package/src/remote-turn-coordinator.ts

@@ -3,9 +3,11 @@ import type {
   SDKLoopStatusMessage,
   SDKMessage,
   OutputFormat,
+  SDKQueueItem,
   SDKQueueUpdateMessage,
   SDKResultMessage,
   SDKStreamEventPayload,
+  SDKTurnOrigin,
   SessionDeviceStatus,
 } from "./types.js";
 import {
@@ -46,6 +48,9 @@ type RemoteTurnCoordinatorConfig = {
 
 const MAX_RECENTLY_SETTLED_RUN_IDS = 256;
 const TRAILING_USAGE_GRACE_MS = 100;
+const TURN_ORIGINS = new Set<string>([
+  "task_notification", "cron", "subagent", "system", "channel", "user",
+]);
 
 /**
  * Owns the portable session's turn correlation and stream queue.
@@ -64,6 +69,9 @@ export class RemoteTurnCoordinator {
   private activeTurn: TurnTracker | null = null;
   private pendingTurns: TurnTracker[] = [];
   private settledRunIds = new Set<string>();
+  /** Queue sources by client message id, to tag turns the session did not send. */
+  private queueOrigins = new Map<string, SDKTurnOrigin>();
+  private nextServerOrigin: SDKTurnOrigin = "unknown";
   private nextTurnId = 0;
   private messageCounter = 0;
   private clientMessageCounter = 0;
@@ -81,8 +89,10 @@ export class RemoteTurnCoordinator {
     return this._activeTurnStartedAt;
   }
 
+  /** Whether a turn this session sent is active or queued. */
   hasInFlightTurn(): boolean {
-    return this.activeTurn !== null || this.pendingTurns.length > 0;
+    return (this.activeTurn !== null && this.activeTurn.origin === undefined) ||
+      this.pendingTurns.length > 0;
   }
 
   /**
@@ -96,13 +106,29 @@ export class RemoteTurnCoordinator {
     outputFormat?: OutputFormat,
   ): TurnTracker {
     const otid = normalizeCallerOtid(callerOtid);
-    const turn: TurnTracker = {
-      id: ++this.nextTurnId,
-      runtime,
+    const turn = this.newTracker(runtime, {
       ...(otid !== undefined ? { otid } : {}),
       ...(outputFormat !== undefined ? { outputFormat } : {}),
       clientMessageId:
         otid ?? `sdk-message-${Date.now()}-${++this.clientMessageCounter}`,
+    });
+
+    if (this.activeTurn) {
+      this.pendingTurns.push(turn);
+    } else {
+      this.activateTurn(turn);
+    }
+    return turn;
+  }
+
+  private newTracker(
+    runtime: RuntimeScope,
+    identity: Pick<TurnTracker, "clientMessageId" | "otid" | "outputFormat" | "origin">,
+  ): TurnTracker {
+    return {
+      id: ++this.nextTurnId,
+      runtime,
+      ...identity,
       queuedAt: Date.now(),
       startedAt: 0,
       assistantText: "",
@@ -119,15 +145,44 @@ export class RemoteTurnCoordinator {
       abortRequested: false,
       timeout: null,
     };
+  }
 
-    if (this.activeTurn) {
-      this.pendingTurns.push(turn);
-    } else {
-      this.activateTurn(turn);
-    }
+  /**
+   * A run started while the session had no turn of its own in flight, such as
+   * a task notification or cron prompt. Track it like a sent turn so stream()
+   * yields its events and a result tagged with its origin.
+   */
+  private startServerTurn(runtime: RuntimeScope): TurnTracker {
+    const turn = this.newTracker(runtime, { clientMessageId: "", origin: this.nextServerOrigin });
+    this.nextServerOrigin = "unknown";
+    this.activateTurn(turn);
     return turn;
   }
 
+  private observeQueueOrigins(message: ProtocolMessage, queue: SDKQueueItem[]): void {
+    for (const item of queue) {
+      if (!item.clientMessageId) continue;
+      this.queueOrigins.set(item.clientMessageId,
+        TURN_ORIGINS.has(item.source) ? (item.source as SDKTurnOrigin) : "unknown");
+      if (this.queueOrigins.size > MAX_RECENTLY_SETTLED_RUN_IDS) {
+        this.queueOrigins.delete(this.queueOrigins.keys().next().value!);
+      }
+    }
+    for (const removed of Array.isArray(message.removed) ? message.removed : []) {
+      const { client_message_id: id, disposition, source } =
+        removed as { client_message_id?: unknown; disposition?: unknown; source?: unknown };
+      if (disposition !== "dequeued" || typeof id !== "string") continue;
+      const own = [this.activeTurn, ...this.pendingTurns]
+        .some((turn) => turn?.clientMessageId === id);
+      if (own) continue;
+      // Listeners that send `source` on removals cover items added and dequeued
+      // in the same update; older ones only expose it on the queued item.
+      this.nextServerOrigin = typeof source === "string" && TURN_ORIGINS.has(source)
+        ? (source as SDKTurnOrigin)
+        : this.queueOrigins.get(id) ?? "unknown";
+    }
+  }
+
   removeTrackedTurn(turn: TurnTracker): void {
     if (turn.timeout) clearTimeout(turn.timeout);
     if (turn.pendingTerminalTimeout) clearTimeout(turn.pendingTerminalTimeout);
@@ -139,6 +194,13 @@ export class RemoteTurnCoordinator {
     if (index !== -1) this.pendingTurns.splice(index, 1);
   }
 
+  /** A dropped transport cannot finish a turn the runtime started; end it here. */
+  failServerTurn(detail: string): void {
+    const active = this.activeTurn;
+    if (active?.origin === undefined) return;
+    this.failTurn(active, detail, { errorCode: "stream_closed", recoverable: true });
+  }
+
   markAbortRequested(): void {
     if (this.activeTurn) this.activeTurn.abortRequested = true;
   }
@@ -158,6 +220,7 @@ export class RemoteTurnCoordinator {
         type: "queue_update",
         queue: queueItems(message),
       };
+      this.observeQueueOrigins(message, sdkMessage.queue);
       this.enqueue(sdkMessage);
       return;
     }
@@ -219,12 +282,6 @@ export class RemoteTurnCoordinator {
     const delta = streamDeltaRecord(message);
     if (!delta) return;
     const messageType = streamDeltaMessageType(delta);
-    // Terminal metadata can trail the result it belongs to. It must never
-    // activate a queued turn or become evidence for that next turn.
-    const active =
-      messageType === "usage_statistics" || messageType === "stop_reason"
-        ? this.activeTurn
-        : this.activateNextTurnFromProtocol();
     const runId = streamDeltaRunId(delta);
     const isTurnEvidence =
       messageType === "assistant_message" ||
@@ -235,6 +292,13 @@ export class RemoteTurnCoordinator {
       messageType === "error_message" ||
       messageType === "loop_error" ||
       (runId !== undefined && (messageType === "usage_statistics" || messageType === "stop_reason"));
+    // Terminal metadata can trail the result it belongs to. It must never
+    // activate a queued turn or become evidence for that next turn.
+    const active =
+      messageType === "usage_statistics" || messageType === "stop_reason"
+        ? this.activeTurn
+        : (this.activateNextTurnFromProtocol() ??
+          (isTurnEvidence && runId !== undefined ? this.startServerTurn(runtime) : null));
     // Persisted user-message echoes and lifecycle status are not evidence that
     // the new model run started. In particular they may arrive after an abort.
     if (active && isTurnEvidence) {
@@ -806,6 +870,7 @@ export class RemoteTurnCoordinator {
         Date.now() - (tracker?.startedAt || this._activeTurnStartedAt),
       conversationId: turn.runtime.conversation_id,
       runIds: turn.runIds.length > 0 ? turn.runIds : undefined,
+      ...(tracker?.origin !== undefined ? { origin: tracker.origin } : {}),
     };
   }
 

package/src/runtime-tool-policy.ts

@@ -0,0 +1,114 @@
+import type { AppServerClient } from "@letta-ai/letta-code/app-server-client";
+import type { AnyAgentTool, ClientToolsetConfig } from "./types.js";
+
+/**
+ * A connection's tool selection for every turn on a conversation, including
+ * turns the runtime starts itself (task notifications, cron prompts, wakes).
+ * Mirrors Letta Code's `RuntimeToolPolicy` wire shape on `runtime_start` and
+ * `runtime_external_tools_update`; listeners without the capability ignore it.
+ */
+export type RuntimeToolPolicy = {
+  toolset?: { base?: ClientToolsetConfig["base"]; include?: string[] };
+  allowlist?: string[];
+  exclude_interactive?: boolean;
+};
+
+/** `app_server_info` capability advertising `tool_policy` support. */
+const RUNTIME_TOOL_POLICY_CAPABILITY = "runtime_tool_policy";
+/** Bounded so a listener that cannot answer never delays session startup long. */
+const CAPABILITY_PROBE_TIMEOUT_MS = 5_000;
+
+export function clientToolsetPayload(
+  toolset: ClientToolsetConfig,
+): NonNullable<RuntimeToolPolicy["toolset"]> {
+  return {
+    ...(toolset.base !== undefined ? { base: toolset.base } : {}),
+    ...(toolset.include !== undefined
+      ? { include: [...new Set(toolset.include)] }
+      : {}),
+  };
+}
+
+/**
+ * Build the policy from the same options a session accepts. SDK sessions are
+ * headless, so interactive user-input tools are always excluded.
+ */
+export function runtimeToolPolicy(
+  allowedTools: readonly string[] | undefined,
+  toolset: ClientToolsetConfig | undefined,
+): RuntimeToolPolicy {
+  return {
+    ...(toolset !== undefined ? { toolset: clientToolsetPayload(toolset) } : {}),
+    ...(allowedTools !== undefined ? { allowlist: [...new Set(allowedTools)] } : {}),
+    exclude_interactive: true,
+  };
+}
+
+/**
+ * Whether the connected listener applies `tool_policy` to every turn. Older
+ * listeners, and transports that cannot answer `app_server_info`, report false
+ * so callers keep sending the equivalent per-message fields.
+ */
+export async function supportsRuntimeToolPolicy(
+  client: Pick<AppServerClient, "info">,
+): Promise<boolean> {
+  try {
+    const info = await client.info({ timeoutMs: CAPABILITY_PROBE_TIMEOUT_MS });
+    const capabilities = info.capabilities as Record<string, unknown> | undefined;
+    return capabilities?.[RUNTIME_TOOL_POLICY_CAPABILITY] === true;
+  } catch {
+    return false;
+  }
+}
+
+/** The part of a registration a session on one of its conversations inherits. */
+export type InheritedTools = {
+  tools: AnyAgentTool[];
+  allowedTools?: string[];
+  toolset?: ClientToolsetConfig;
+};
+
+/** A session's own tool selection: its `tools` (plus MCP tools) and options. */
+export type SessionToolSelection = {
+  tools: AnyAgentTool[];
+  allowedTools?: string[];
+  toolset?: ClientToolsetConfig;
+};
+
+/**
+ * Where a session reads the registration covering its conversation. `current()`
+ * returns null once no registration covers it any more.
+ */
+export interface InheritedToolSource {
+  current(): InheritedTools | null;
+  onChange(listener: () => void): () => void;
+}
+
+/**
+ * Combine a registration with a session's own selection. The session's tools
+ * are added on top (its own wins on a name clash). Its `allowedTools` can only
+ * narrow the registration's: entries outside the registration's allowlist are
+ * dropped unless they name one of the session's own tools. Without its own
+ * `allowedTools`, the session gets the registration's plus its own tools.
+ */
+export function mergeInheritedTools(
+  inherited: InheritedTools | null,
+  own: SessionToolSelection,
+): SessionToolSelection {
+  if (!inherited) return own;
+  const tools = new Map(inherited.tools.map((tool) => [tool.name, tool]));
+  for (const tool of own.tools) tools.set(tool.name, tool);
+  const ownNames = new Set(own.tools.map((tool) => tool.name));
+  const registered = inherited.allowedTools;
+  const allowedTools = registered === undefined
+    ? own.allowedTools
+    : own.allowedTools === undefined
+      ? [...new Set([...registered, ...ownNames])]
+      : own.allowedTools.filter((name) => registered.includes(name) || ownNames.has(name));
+  const toolset = own.toolset ?? inherited.toolset;
+  return {
+    tools: [...tools.values()],
+    ...(allowedTools !== undefined ? { allowedTools } : {}),
+    ...(toolset !== undefined ? { toolset } : {}),
+  };
+}

package/src/structured-output-session.ts

@@ -64,7 +64,8 @@ export async function* streamStructuredTurns(config: {
       // External SDK tools have no terminal rule; stop after their successful return.
       void config.abort().catch(() => undefined);
     }
-    if (msg.type !== "result") {
+    // Results of turns the session did not send never settle its own turn.
+    if (msg.type !== "result" || msg.origin !== undefined) {
       yield msg;
       continue;
     }

package/src/tool-registration.ts

@@ -0,0 +1,311 @@
+import {
+  createAppServerClient,
+  type AppServerClient,
+  type AppServerSocketConstructor,
+} from "@letta-ai/letta-code/app-server-client";
+import type { ConversationRetrieveResponseMessage } from "@letta-ai/letta-code/app-server-protocol";
+import type { AppServerSessionOptions } from "./app-server-session.js";
+import { createExternalToolCallHandler, externalToolGroups } from "./external-tools.js";
+import { applyUniqueRequestIds } from "./request-ids.js";
+import {
+  runtimeToolPolicy,
+  supportsRuntimeToolPolicy,
+  type InheritedToolSource,
+} from "./runtime-tool-policy.js";
+import type { RuntimeScope } from "./remote-session-protocol.js";
+import type { AnyAgentTool, ClientToolsetConfig } from "./types.js";
+
+/** Options for `client.registerTools()`. */
+export interface RegisterToolsOptions {
+  /**
+   * Conversations that can call these tools. Pass a `conv-xxx` ID for a
+   * specific conversation or an `agent-xxx` ID for the agent's default
+   * conversation, as with `resumeSession()`.
+   */
+  conversations: string[];
+  /** Client tools, executed in this process like a session's `tools`. */
+  tools: AnyAgentTool[];
+  /**
+   * Tools every turn in these conversations may use, including turns the
+   * runtime starts itself (task notifications, cron prompts). Same meaning as
+   * the session option.
+   */
+  allowedTools?: string[];
+  /** Base toolset and bundled client tools, as on a session. */
+  toolset?: ClientToolsetConfig;
+}
+
+/** A live registration returned by `client.registerTools()`. */
+export interface ToolRegistration extends AsyncDisposable {
+  readonly conversations: readonly string[];
+  /** Replace any of the registered options. Omitted fields are kept. */
+  update(options: Partial<RegisterToolsOptions>): Promise<void>;
+  /** Remove these tools from their conversations. */
+  close(): Promise<void>;
+}
+
+type Entry = {
+  options: RegisterToolsOptions;
+  runtimes: RuntimeScope[];
+  call: ReturnType<typeof createExternalToolCallHandler>;
+};
+type Connection = { client: AppServerClient; owned: { close(): void } | null; toolPolicy: boolean };
+
+const RECONNECT_DELAYS_MS = [250, 1_000, 5_000, 15_000];
+const runtimeKey = (runtime: { agent_id: string | null; conversation_id: string }) =>
+  `${runtime.agent_id}:${runtime.conversation_id}`;
+
+/**
+ * Owns one long-lived app-server connection that registers client tools for
+ * many conversations. Tool calls are dispatched by the calling conversation,
+ * and every registration is published again after a reconnect.
+ */
+export class ToolRegistry {
+  private connection: Promise<Connection> | null = null;
+  private readonly entries = new Set<Entry>();
+  private readonly listeners = new Set<() => void>();
+  private reconnectAttempt = 0;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private closed = false;
+
+  constructor(private readonly options: AppServerSessionOptions) {}
+
+  async register(options: RegisterToolsOptions): Promise<ToolRegistration> {
+    if (this.closed) throw new Error("LettaAgentClient is closed");
+    const entry: Entry = { options, runtimes: [], call: createExternalToolCallHandler(new Map()) };
+    await this.apply(entry, options);
+    const registry = this;
+    return {
+      get conversations() {
+        return [...entry.options.conversations];
+      },
+      update: async (next) => {
+        if (!registry.entries.has(entry)) throw new Error("This tool registration is closed.");
+        await registry.apply(entry, { ...entry.options, ...next });
+      },
+      close: () => registry.remove(entry),
+      [Symbol.asyncDispose]: () => registry.remove(entry),
+    };
+  }
+
+  close(): void {
+    this.closed = true;
+    this.entries.clear();
+    this.disconnect();
+    this.notify();
+  }
+
+  /**
+   * The registration source for a session on `id`, or null when no
+   * registration covers it. Throws when the session's options conflict with
+   * the registration instead of narrowing it.
+   */
+  inheritFor(id: string, own: { tools?: AnyAgentTool[]; toolset?: ClientToolsetConfig }): InheritedToolSource | null {
+    const covering = this.covering(id);
+    if (!covering) return null;
+    const registered = new Set(covering.options.tools.map((tool) => tool.name));
+    const clash = own.tools?.find((tool) => registered.has(tool.name));
+    if (clash) {
+      throw new Error(`Tool ${clash.name} is already registered for ${id} with registerTools(); don't pass it to the session again.`);
+    }
+    if (
+      own.toolset !== undefined && covering.options.toolset !== undefined &&
+      JSON.stringify(own.toolset) !== JSON.stringify(covering.options.toolset)
+    ) {
+      throw new Error(`${id} already has a toolset from registerTools(); narrow it with the session's allowedTools instead.`);
+    }
+    return {
+      current: () => this.covering(id)?.options ?? null,
+      onChange: (listener) => {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+      },
+    };
+  }
+
+  private covering(id: string): Entry | undefined {
+    return [...this.entries].find((entry) =>
+      entry.options.conversations.includes(id) ||
+      entry.runtimes.some((runtime) =>
+        runtime.conversation_id === id ||
+        (runtime.conversation_id === "default" && runtime.agent_id === id)
+      )
+    );
+  }
+
+  private notify(): void {
+    for (const listener of [...this.listeners]) listener();
+  }
+
+  private async apply(entry: Entry, options: RegisterToolsOptions): Promise<void> {
+    if (!Array.isArray(options.conversations) || options.conversations.length === 0) {
+      throw new Error("registerTools() requires at least one conversation.");
+    }
+    if (!Array.isArray(options.tools)) throw new Error("registerTools() requires a tools array.");
+    const connection = await this.connect();
+    if (!connection.toolPolicy && (options.allowedTools || options.toolset)) {
+      throw new Error(
+        "registerTools() allowedTools and toolset require a Letta Code app server that supports runtime tool policies. Upgrade @letta-ai/letta-code.",
+      );
+    }
+    const runtimes = await Promise.all(
+      options.conversations.map((id) => resolveRuntime(connection.client, id)),
+    );
+    const taken = new Set(
+      [...this.entries].filter((other) => other !== entry)
+        .flatMap((other) => other.runtimes.map(runtimeKey)),
+    );
+    const overlap = options.conversations.find((_, index) => taken.has(runtimeKey(runtimes[index]!)));
+    if (overlap) throw new Error(`Tools are already registered for ${overlap}.`);
+
+    const keys = new Set(runtimes.map(runtimeKey));
+    const dropped = entry.runtimes.filter((runtime) => !keys.has(runtimeKey(runtime)));
+    // Claim the conversations before publishing so concurrent calls cannot
+    // register the same conversation twice; restore the old state on failure.
+    const previous = { ...entry };
+    const isNew = !this.entries.has(entry);
+    entry.options = options;
+    entry.runtimes = runtimes;
+    entry.call = createExternalToolCallHandler(new Map(options.tools.map((tool) => [tool.name, tool])));
+    this.entries.add(entry);
+    try {
+      await publish(connection.client, [
+        group(runtimes, options, connection.toolPolicy),
+        ...(dropped.length > 0 ? [{ runtimes: dropped, external_tools: [] }] : []),
+      ]);
+    } catch (error) {
+      Object.assign(entry, previous);
+      if (isNew) this.entries.delete(entry);
+      throw error;
+    }
+    this.notify();
+  }
+
+  private async remove(entry: Entry): Promise<void> {
+    if (!this.entries.delete(entry)) return;
+    this.notify();
+    if (this.entries.size === 0) {
+      // Closing the connection removes everything it registered.
+      this.disconnect();
+      return;
+    }
+    const connection = await this.connect();
+    await publish(connection.client, [{ runtimes: entry.runtimes, external_tools: [] }]);
+  }
+
+  private connect(): Promise<Connection> {
+    this.connection ??= this.open().catch((error: unknown) => {
+      this.connection = null;
+      throw error;
+    });
+    return this.connection;
+  }
+
+  private async open(): Promise<Connection> {
+    const owned = this.options.url ? null : await this.options.connect?.();
+    const url = this.options.url ?? owned?.url;
+    if (!url) throw new Error("registerTools() requires an app-server url.");
+    const client = applyUniqueRequestIds(createAppServerClient({
+      url,
+      ...(this.options.authToken !== undefined ? { authToken: this.options.authToken } : {}),
+      ...(this.options.WebSocket
+        ? { WebSocket: this.options.WebSocket as AppServerSocketConstructor }
+        : {}),
+      ...(this.options.requestTimeoutMs !== undefined
+        ? { requestTimeoutMs: this.options.requestTimeoutMs }
+        : {}),
+    }));
+    client.onExternalToolCall(async (request) => {
+      const runtime = request.runtime;
+      const entry = runtime &&
+        [...this.entries].find((candidate) => candidate.runtimes.some((r) => runtimeKey(r) === runtimeKey(runtime)));
+      if (!entry) throw new Error(`No tools registered for conversation ${runtime?.conversation_id}`);
+      return entry.call(request);
+    });
+    try {
+      await client.connect();
+    } catch (error) {
+      client.close();
+      owned?.close();
+      throw error;
+    }
+    client.onDisconnect(() => this.onDisconnect(client));
+    return { client, owned: owned ?? null, toolPolicy: await supportsRuntimeToolPolicy(client) };
+  }
+
+  private disconnect(): void {
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    this.reconnectTimer = null;
+    const connection = this.connection;
+    this.connection = null;
+    void connection?.then(({ client, owned }) => {
+      client.close();
+      owned?.close();
+    }, () => undefined);
+  }
+
+  private onDisconnect(client: AppServerClient): void {
+    void this.connection?.then((current) => {
+      if (current.client !== client) return;
+      current.owned?.close();
+      this.connection = null;
+      this.scheduleReconnect();
+    }, () => undefined);
+  }
+
+  private scheduleReconnect(): void {
+    if (this.closed || this.entries.size === 0 || this.reconnectTimer) return;
+    const delay = RECONNECT_DELAYS_MS[Math.min(this.reconnectAttempt, RECONNECT_DELAYS_MS.length - 1)];
+    this.reconnectAttempt += 1;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      void this.republish().catch(() => this.scheduleReconnect());
+    }, delay);
+    (this.reconnectTimer as { unref?: () => void }).unref?.();
+  }
+
+  private async republish(): Promise<void> {
+    const connection = await this.connect();
+    await publish(
+      connection.client,
+      [...this.entries].map((entry) => group(entry.runtimes, entry.options, connection.toolPolicy)),
+    );
+    this.reconnectAttempt = 0;
+  }
+}
+
+/** Older listeners may reject unknown group keys, so tool_policy is gated. */
+function group(runtimes: RuntimeScope[], options: RegisterToolsOptions, toolPolicy: boolean) {
+  return {
+    runtimes,
+    external_tools: externalToolGroups(options.tools) ?? [],
+    ...(toolPolicy ? { tool_policy: runtimeToolPolicy(options.allowedTools, options.toolset) } : {}),
+  };
+}
+
+async function publish(
+  client: AppServerClient,
+  updates: Array<{ runtimes: RuntimeScope[]; external_tools: unknown[]; tool_policy?: unknown }>,
+): Promise<void> {
+  const response = await client.runtimeExternalToolsUpdate(
+    { updates } as unknown as Parameters<AppServerClient["runtimeExternalToolsUpdate"]>[0],
+  );
+  if (!response.success) throw new Error(response.error ?? "Failed to register tools");
+}
+
+async function resolveRuntime(client: AppServerClient, id: string): Promise<RuntimeScope> {
+  if (!id.startsWith("conv-") && !id.startsWith("local-conv-")) {
+    return { agent_id: id, conversation_id: "default" };
+  }
+  const response = await client.request<ConversationRetrieveResponseMessage>(
+    { type: "conversation_retrieve", request_id: client.nextRequestId("conversation_retrieve"), conversation_id: id },
+    {
+      predicate: (message): message is ConversationRetrieveResponseMessage =>
+        message.type === "conversation_retrieve_response",
+    },
+  );
+  if (!response.success || !response.conversation) {
+    throw new Error(response.error ?? `Failed to retrieve conversation ${id}`);
+  }
+  return { agent_id: response.conversation.agent_id ?? null, conversation_id: id };
+}

package/src/types.ts

@@ -257,6 +257,20 @@ export interface AgentToolResult<T> {
  */
 export type AgentToolUpdateCallback<T> = (update: Partial<AgentToolResult<T>>) => void;
 
+/**
+ * Which call a tool is serving. Passed as the last argument to
+ * {@link AgentTool.execute}, so one tool instance can serve many
+ * conversations and keep per-conversation state keyed on `conversationId`.
+ */
+export interface AgentToolCallContext {
+  /** Same as the first `execute` argument. */
+  toolCallId: string;
+  /** Agent that made the call, or `null` when the runtime has no agent id. */
+  agentId: string | null;
+  /** Conversation that made the call. */
+  conversationId: string;
+}
+
 /**
  * Agent tool definition (matches pi-agent-core)
  */
@@ -273,12 +287,16 @@ export interface AgentTool<TParams, TResult> {
   /** JSON Schema for parameters (TypeBox or plain object) */
   parameters: TParams;
 
-  /** Execution function */
+  /**
+   * Execution function. `context` says which agent and conversation made the
+   * call; tools that don't need it can ignore it.
+   */
   execute: (
     toolCallId: string,
     args: unknown,
     signal?: AbortSignal,
     onUpdate?: AgentToolUpdateCallback<TResult>,
+    context?: AgentToolCallContext,
   ) => Promise<AgentToolResult<TResult>>;
 }
 
@@ -1087,8 +1105,28 @@ export interface SDKResultMessage {
   conversationId: string | null;
   /** Run IDs associated with this turn (if provided by the CLI). */
   runIds?: string[];
+  /**
+   * Set only on a turn this session did not send, such as a background task
+   * notification or a cron prompt. `stream()` yields these turns as they run
+   * and keeps going until the result of the session's own turn.
+   */
+  origin?: SDKTurnOrigin;
 }
 
+/**
+ * Who started a turn the session did not send: a queue source reported by
+ * the runtime, `"user"` for another client's message, or `"unknown"` when the
+ * runtime started the turn without reporting a source.
+ */
+export type SDKTurnOrigin =
+  | "task_notification"
+  | "cron"
+  | "subagent"
+  | "system"
+  | "channel"
+  | "user"
+  | "unknown";
+
 export interface SDKStreamEventDeltaPayload {
   type: string;
   index?: number;