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

package/src/app-server-session.ts

@@ -1,7 +1,6 @@
 import {
   createAppServerClient,
   type AppServerClient,
-  type AppServerExternalToolCallHandler,
   type AppServerSocketConstructor,
 } from "@letta-ai/letta-code/app-server-client";
 import type {
@@ -25,6 +24,16 @@ import {
   type McpToolBridge,
 } from "./mcp-runtime.js";
 import { applyUniqueRequestIds } from "./request-ids.js";
+import { createExternalToolCallHandler, externalToolGroups } from "./external-tools.js";
+import {
+  clientToolsetPayload,
+  mergeInheritedTools,
+  runtimeToolPolicy,
+  supportsRuntimeToolPolicy,
+  type InheritedToolSource,
+  type RuntimeToolPolicy,
+  type SessionToolSelection,
+} from "./runtime-tool-policy.js";
 import {
   RemoteClientSessionCore,
   ensureSuccess,
@@ -104,41 +113,6 @@ export type AppServerSessionOptions = Partial<LettaCodeRemoteClientOptions> & {
 
 export type AppServerSessionMode = RuntimeSessionMode;
 
-export function externalToolGroups(tools: AnyAgentTool[] | undefined): Array<Record<string, unknown>> | undefined {
-  if (!tools || tools.length === 0) return undefined;
-  return [
-    {
-      tools: tools.map((tool) => ({
-        name: tool.name,
-        label: tool.label,
-        description: tool.description,
-        parameters: tool.parameters as Record<string, unknown>,
-      })),
-    },
-  ];
-}
-
-export function createExternalToolCallHandler(
-  externalTools: Map<string, AnyAgentTool>,
-): AppServerExternalToolCallHandler {
-  return async (request) => {
-    const tool = externalTools.get(request.tool_name);
-    if (!tool) {
-      throw new Error(`Unknown external tool: ${request.tool_name}`);
-    }
-    const result = await tool.execute(request.tool_call_id, request.input);
-    return {
-      content: result.content.map((part) => ({
-        type: part.type,
-        ...(part.text !== undefined ? { text: part.text } : {}),
-        ...(part.data !== undefined ? { data: part.data } : {}),
-        ...(part.mimeType !== undefined ? { mimeType: part.mimeType } : {}),
-      })),
-      ...(result.isError === true ? { is_error: true } : {}),
-    };
-  };
-}
-
 type AppServerApprovalOptions = LettaCodeClientSessionOptions | CreateAgentOptions;
 
 type AppServerApprovalResponseDecision =
@@ -393,10 +367,32 @@ export class AppServerRuntimeController implements RemoteClientRuntimeController
   constructor(
     private readonly client: AppServerClient,
     private readonly options: AppServerSessionOptions,
-    private readonly clientToolAllowlist?: readonly string[],
-    private readonly clientToolset?: ClientToolsetConfig,
+    private clientToolAllowlist?: readonly string[],
+    private clientToolset?: ClientToolsetConfig,
+    /** The listener applies runtime_start's tool_policy to every turn. */
+    private readonly toolPolicyApplied = false,
   ) {}
 
+  /**
+   * Replace this connection's tools and policy for the runtime, as when a
+   * `registerTools()` registration the session inherits changes. Older
+   * listeners get the tools here and the selection with each message.
+   */
+  async updateToolSelection(runtime: RuntimeScope, selection: SessionToolSelection): Promise<void> {
+    this.clientToolAllowlist = selection.allowedTools;
+    this.clientToolset = selection.toolset;
+    const response = await this.client.runtimeExternalToolsUpdate({
+      updates: [{
+        runtimes: [runtime],
+        external_tools: externalToolGroups(selection.tools) ?? [],
+        ...(this.toolPolicyApplied
+          ? { tool_policy: runtimeToolPolicy(selection.allowedTools, selection.toolset) }
+          : {}),
+      }],
+    } as unknown as Parameters<AppServerClient["runtimeExternalToolsUpdate"]>[0]);
+    if (!response.success) throw new Error(response.error ?? "Failed to update session tools");
+  }
+
   onMessage(handler: (message: ProtocolMessage, channel?: string) => void): () => void {
     return this.client.onMessage((message, channel) => {
       handler(message as unknown as ProtocolMessage, channel);
@@ -425,18 +421,12 @@ export class AppServerRuntimeController implements RemoteClientRuntimeController
         },
       ],
     };
-    if (this.clientToolAllowlist !== undefined) {
+    // Older listeners only honour tool selection sent with each message.
+    if (!this.toolPolicyApplied && this.clientToolAllowlist !== undefined) {
       payload.client_tool_allowlist = [...new Set(this.clientToolAllowlist)];
     }
-    if (this.clientToolset !== undefined) {
-      payload.client_toolset = {
-        ...(this.clientToolset.base !== undefined
-          ? { base: this.clientToolset.base }
-          : {}),
-        ...(this.clientToolset.include !== undefined
-          ? { include: [...new Set(this.clientToolset.include)] }
-          : {}),
-      };
+    if (!this.toolPolicyApplied && this.clientToolset !== undefined) {
+      payload.client_toolset = clientToolsetPayload(this.clientToolset);
     }
     if (options.outputFormat !== undefined) {
       payload.response_format = {
@@ -451,7 +441,7 @@ export class AppServerRuntimeController implements RemoteClientRuntimeController
     // SDK sessions are headless: interactive user-input tools are always
     // excluded from the toolset (harnesses without support ignore the flag
     // and the SDK's runtime denial still applies).
-    payload.exclude_interactive_tools = true;
+    if (!this.toolPolicyApplied) payload.exclude_interactive_tools = true;
     this.client.input({
       runtime,
       payload,
@@ -590,6 +580,10 @@ export class AppServerSession extends RemoteClientSessionCore {
   private mcpCleanup: Promise<void> = Promise.resolve();
   private removeExternalToolHandler: (() => void) | null = null;
   private removeControlRequestHandler: (() => void) | null = null;
+  private inheritedTools: InheritedToolSource | null = null;
+  private removeInheritedListener: (() => void) | null = null;
+  /** This session's own selection, after MCP tools and wildcards resolve. */
+  private ownSelection: SessionToolSelection | null = null;
 
   constructor(
     private readonly remoteOptions: AppServerSessionOptions,
@@ -605,6 +599,34 @@ export class AppServerSession extends RemoteClientSessionCore {
     }
   }
 
+  /**
+   * Use the tools and policy of the `registerTools()` registration covering
+   * this conversation, and follow its updates while the session is open.
+   */
+  inheritTools(source: InheritedToolSource): void {
+    this.inheritedTools = source;
+    this.removeInheritedListener = source.onChange(() => {
+      void this.refreshInheritedTools().catch(() => undefined);
+    });
+  }
+
+  /** Rebuild the effective tool map in place; call handlers hold the map. */
+  private applyToolSelection(): SessionToolSelection {
+    const selection = mergeInheritedTools(
+      this.inheritedTools?.current() ?? null,
+      this.ownSelection ?? { tools: [] },
+    );
+    this.externalTools.clear();
+    for (const tool of selection.tools) this.externalTools.set(tool.name, tool);
+    return selection;
+  }
+
+  private async refreshInheritedTools(): Promise<void> {
+    if (!this.ownSelection || !this.runtime || !(this.controller instanceof AppServerRuntimeController)) return;
+    const selection = this.applyToolSelection();
+    await this.controller.updateToolSelection(this.runtime, selection);
+  }
+
   protected override shouldEnableMemfs(options: LettaCodeClientSessionOptions | CreateAgentOptions): boolean {
     if (this.mode.kind !== "create-agent") return false;
     return (options as CreateAgentOptions).memfs !== false;
@@ -627,6 +649,8 @@ export class AppServerSession extends RemoteClientSessionCore {
     }));
 
     const options = this.currentOptions();
+    this.externalTools.clear();
+    for (const tool of this.mode.options.tools ?? []) this.externalTools.set(tool.name, tool);
     this.mcpBridge = await connectMcpServers(
       "mcpServers" in options ? options.mcpServers : undefined,
       {
@@ -637,6 +661,15 @@ export class AppServerSession extends RemoteClientSessionCore {
     for (const tool of this.mcpBridge.tools) {
       this.externalTools.set(tool.name, tool);
     }
+    const mcpToolNames = this.mcpBridge.tools.map((tool) => tool.name);
+    const ownToolset = "toolset" in options ? options.toolset : undefined;
+    const ownAllowedTools = expandMcpToolWildcards(options.allowedTools, mcpToolNames);
+    this.ownSelection = {
+      tools: [...this.externalTools.values()],
+      ...(ownAllowedTools !== undefined ? { allowedTools: ownAllowedTools } : {}),
+      ...(ownToolset !== undefined ? { toolset: ownToolset } : {}),
+    };
+    const { allowedTools, toolset: clientToolset } = this.applyToolSelection();
 
     this.removeControlRequestHandler = registerAppServerControlRequestHandler({
       client,
@@ -644,9 +677,9 @@ export class AppServerSession extends RemoteClientSessionCore {
       getOptions: () => this.currentOptions(),
     });
 
-    if (this.externalTools.size > 0) {
+    if (this.externalTools.size > 0 || this.inheritedTools) {
       this.removeExternalToolHandler = client.onExternalToolCall(
-        createExternalToolCallHandler(this.externalTools),
+        createExternalToolCallHandler(this.externalTools, () => this.runtime),
       );
     }
 
@@ -667,21 +700,19 @@ export class AppServerSession extends RemoteClientSessionCore {
           );
         }
       }
-      const response = await this.startRuntime(client);
+      const response = await this.startRuntime(
+        client,
+        runtimeToolPolicy(allowedTools, clientToolset),
+      );
       if (!response.success || !response.runtime) {
         throw new Error(response.error ?? "Failed to start app-server runtime");
       }
 
       this.watchTransportDisconnect(client);
+      const toolPolicyApplied = await supportsRuntimeToolPolicy(client);
 
       const tools = agentToolNames(response.agent);
       const skillSources = options.skillSources;
-      const clientToolset = "toolset" in options ? options.toolset : undefined;
-      const mcpToolNames = this.mcpBridge?.tools.map((tool) => tool.name) ?? [];
-      const allowedTools = expandMcpToolWildcards(
-        options.allowedTools,
-        mcpToolNames,
-      );
       const availableTools =
         tools === undefined && mcpToolNames.length === 0
           ? undefined
@@ -692,6 +723,7 @@ export class AppServerSession extends RemoteClientSessionCore {
           this.remoteOptions,
           allowedTools,
           clientToolset,
+          toolPolicyApplied,
         ),
         runtime: response.runtime,
         model:
@@ -719,6 +751,10 @@ export class AppServerSession extends RemoteClientSessionCore {
   }
 
   protected override onCoreClose(): void {
+    if (this.closed) {
+      this.removeInheritedListener?.();
+      this.removeInheritedListener = null;
+    }
     this.removeExternalToolHandler?.();
     this.removeExternalToolHandler = null;
     this.removeControlRequestHandler?.();
@@ -756,12 +792,16 @@ export class AppServerSession extends RemoteClientSessionCore {
 
   private async startRuntime(
     client: AppServerClient,
+    toolPolicy: RuntimeToolPolicy,
   ): Promise<RuntimeStartResponseMessage> {
-    const command = await this.buildRuntimeStartCommand(client);
+    const command = await this.buildRuntimeStartCommand(client, toolPolicy);
     return client.runtimeStart(command);
   }
 
-  private async buildRuntimeStartCommand(client: AppServerClient): Promise<RuntimeStartCommand> {
+  private async buildRuntimeStartCommand(
+    client: AppServerClient,
+    toolPolicy: RuntimeToolPolicy,
+  ): Promise<RuntimeStartCommand> {
     const options = this.mode.options;
     const command: Record<string, unknown> = {
       client_info: {
@@ -799,6 +839,10 @@ export class AppServerSession extends RemoteClientSessionCore {
     }
     const groups = externalToolGroups([...this.externalTools.values()]);
     if (groups) command.external_tools = groups;
+    // Sent on create, resume and every reconnect: the listener keeps it only
+    // while this connection is open, and applies it to every turn, including
+    // task notifications and cron prompts the runtime starts itself.
+    command.tool_policy = toolPolicy;
 
     if (this.mode.kind === "create-agent") {
       command.create_agent = {

package/src/client-base.ts

@@ -33,6 +33,11 @@ import type {
   ModelsClient,
 } from "./management-types.js";
 import { createQuery } from "./query.js";
+import {
+  ToolRegistry,
+  type RegisterToolsOptions,
+  type ToolRegistration,
+} from "./tool-registration.js";
 import type {
   Query,
   QueryOptions,
@@ -161,6 +166,7 @@ export class LettaAgentClientBase implements AsyncDisposable {
   private agentRepositoriesClient: AgentRepositoriesClient | null = null;
   private cloudClient: Letta | null = null;
   private managementTransport: ManagementTransport | null = null;
+  private toolRegistry: ToolRegistry | null = null;
   private closed = false;
   private closePromise: Promise<void> | null = null;
 
@@ -351,6 +357,11 @@ export class LettaAgentClientBase implements AsyncDisposable {
    *
    * `options.environment` overrides the client's default execution target for
    * Letta Cloud sessions. Remote app-server URLs already select the runtime.
+   *
+   * If `client.registerTools()` covers this conversation, the session uses the
+   * registration's tools, `allowedTools` and `toolset` and follows its
+   * updates. Session `tools` are added on top, and session `allowedTools` can
+   * only narrow the registration's.
    */
   resumeSession(
     id: string,
@@ -360,21 +371,25 @@ export class LettaAgentClientBase implements AsyncDisposable {
     const sessionOptions = stripCloudExecutionOptions(options);
     validateCreateSessionOptions(sessionOptions);
     this.assertSessionBackend("resumeSession", options);
+    const inherited = this.backend === "cloud"
+      ? null
+      : this.toolRegistry?.inheritFor(id, sessionOptions) ?? null;
 
     if (this.backend === "remote") {
-      if (looksLikeConversationId(id)) {
-        return new AppServerSession(this.appServerSessionOptions(), {
-          kind: "session",
-          conversationId: id,
-          options,
-        });
-      }
-      return new AppServerSession(this.appServerSessionOptions(), {
-        kind: "session",
-        agentId: id,
-        defaultConversation: true,
-        options,
-      });
+      const session = looksLikeConversationId(id)
+        ? new AppServerSession(this.appServerSessionOptions(), {
+            kind: "session",
+            conversationId: id,
+            options,
+          })
+        : new AppServerSession(this.appServerSessionOptions(), {
+            kind: "session",
+            agentId: id,
+            defaultConversation: true,
+            options,
+          });
+      if (inherited) session.inheritTools(inherited);
+      return session;
     }
     if (this.backend === "cloud") {
       if (looksLikeConversationId(id)) {
@@ -399,7 +414,9 @@ export class LettaAgentClientBase implements AsyncDisposable {
         this.getCloudClient(),
       );
     }
-    return this.resumeLocalSession(id, options);
+    const session = this.resumeLocalSession(id, options);
+    if (inherited && session instanceof AppServerSession) session.inheritTools(inherited);
+    return session;
   }
 
   /**
@@ -740,6 +757,30 @@ export class LettaAgentClientBase implements AsyncDisposable {
     return this.managementTransport;
   }
 
+  /**
+   * Register client tools for many conversations over one long-lived
+   * connection. Every turn in those conversations can call them, including
+   * turns the runtime starts itself, such as task notifications and cron
+   * prompts, with or without an open session.
+   */
+  registerTools(options: RegisterToolsOptions): Promise<ToolRegistration> {
+    this.assertOpen();
+    if (this.backend === "cloud") {
+      return Promise.reject(new Error(
+        'registerTools() requires backend: "local" or "remote". Cloud sessions register tools through the tools session option.',
+      ));
+    }
+    this.toolRegistry ??= new ToolRegistry(
+      this.backend === "remote" ? this.remoteOptions() : this.localAppServerConnection(),
+    );
+    return this.toolRegistry.register(options);
+  }
+
+  /** How the local backend reaches its App Server; overridden by the Node client. */
+  protected localAppServerConnection(): AppServerSessionOptions {
+    throw this.localBackendUnavailableError();
+  }
+
   /**
    * Release resources owned directly by this client, including its pooled
    * management connection. The Node client also stops its shared local App
@@ -748,6 +789,8 @@ export class LettaAgentClientBase implements AsyncDisposable {
   close(): Promise<void> {
     if (this.closePromise) return this.closePromise;
     this.closed = true;
+    this.toolRegistry?.close();
+    this.toolRegistry = null;
     const transport = this.managementTransport;
     this.managementTransport = null;
     const close = transport?.close() ?? Promise.resolve();

package/src/client-entry.ts

@@ -26,6 +26,7 @@ export class LettaAgentClient extends LettaAgentClientBase {
 export { CloudManagedSandboxExpiredError } from "./cloud-session.js";
 export { ConversationForkHydrationError } from "./management-errors.js";
 export { RepositoriesClient } from "./repositories.js";
+export type { RegisterToolsOptions, ToolRegistration } from "./tool-registration.js";
 export type * from "./sandbox-files.js";
 export type {
   Computer,

package/src/client.ts

@@ -42,11 +42,15 @@ export class LettaAgentClient extends LettaAgentClientBase {
   }
 
   protected override createLocalManagementTransport(): ManagementTransport {
+    return new AppServerManagementTransport(this.localAppServerConnection());
+  }
+
+  protected override localAppServerConnection() {
     const localOptions = (
       this.options as LettaCodeLocalClientOptions
     ).appServer;
     const sharedServer = this.sharedLocalServer();
-    return new AppServerManagementTransport({
+    return {
       ...(localOptions?.url !== undefined
         ? { url: localOptions.url }
         : {
@@ -58,7 +62,7 @@ export class LettaAgentClient extends LettaAgentClientBase {
       ...(localOptions?.requestTimeoutMs !== undefined
         ? { requestTimeoutMs: localOptions.requestTimeoutMs }
         : {}),
-    });
+    };
   }
 
   protected override async createLocalAgent(

package/src/cloud-session.ts

@@ -14,16 +14,16 @@ import {
 import {
   AppServerRuntimeController,
   agentToolNames,
-  createExternalToolCallHandler,
-  externalToolGroups,
   registerAppServerControlRequestHandler,
 } from "./app-server-session.js";
+import { createExternalToolCallHandler, externalToolGroups } from "./external-tools.js";
 import { createCloudStatusTransportConstructor } from "./cloud-status-transport.js";
 import {
   connectMcpServers,
   expandMcpToolWildcards,
   type McpToolBridge,
 } from "./mcp-runtime.js";
+import { runtimeToolPolicy } from "./runtime-tool-policy.js";
 import { CloudManagementTransport } from "./cloud-management.js";
 import {
   createCloudClient,
@@ -588,7 +588,7 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
     });
     if (this.externalTools.size > 0) {
       this.removeExternalToolHandler = client.onExternalToolCall(
-        createExternalToolCallHandler(this.externalTools),
+        createExternalToolCallHandler(this.externalTools, () => this.runtime),
       );
     }
   }
@@ -656,6 +656,15 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
     }
     const groups = externalToolGroups([...this.externalTools.values()]);
     if (groups) command.external_tools = groups;
+    // Re-sent on idle-transport recovery so a new connection restores it.
+    // Per-message fields are still sent: Cloud does not confirm the capability.
+    command.tool_policy = runtimeToolPolicy(
+      expandMcpToolWildcards(
+        options.allowedTools,
+        this.mcpBridge?.tools.map((tool) => tool.name) ?? [],
+      ),
+      "toolset" in options ? options.toolset : undefined,
+    );
 
     return (await client.runtimeStart(
       command as Parameters<AppServerClient["runtimeStart"]>[0],

package/src/cloud-status-transport.ts

@@ -189,6 +189,10 @@ export class CloudStatusTransport implements AppServerSocketLike {
     if (channel === "control" && message.type === "stream_delta") {
       return false;
     }
+    // Tool requests are answered on control; the stream copy is a duplicate.
+    if (channel === "stream" && message.type === "external_tool_call_request") {
+      return false;
+    }
     if (this.isDuplicate(message)) return false;
     this.trackEventSequence(message);
     return true;

package/src/external-tools.ts

@@ -0,0 +1,69 @@
+import type { AppServerExternalToolCallHandler } from "@letta-ai/letta-code/app-server-client";
+import type { RuntimeScope } from "./remote-session-protocol.js";
+import type { AgentToolCallContext, AnyAgentTool } from "./types.js";
+
+/** The `external_tools` groups that advertise client tools to the runtime. */
+export function externalToolGroups(tools: AnyAgentTool[] | undefined): Array<Record<string, unknown>> | undefined {
+  if (!tools || tools.length === 0) return undefined;
+  return [
+    {
+      tools: tools.map((tool) => ({
+        name: tool.name,
+        label: tool.label,
+        description: tool.description,
+        parameters: tool.parameters as Record<string, unknown>,
+      })),
+    },
+  ];
+}
+
+const MAX_REMEMBERED_EXTERNAL_TOOL_CALLS = 200;
+
+/**
+ * Run a runtime's external tool call against the client tools by name.
+ * `fallbackRuntime` covers listeners that send calls without a `runtime`.
+ */
+export function createExternalToolCallHandler(
+  externalTools: Map<string, AnyAgentTool>,
+  fallbackRuntime?: () => RuntimeScope | null,
+): AppServerExternalToolCallHandler {
+  // A request can be delivered more than once (e.g. relayed on more than one
+  // socket). Share one execution per request_id so a tool never runs twice.
+  const calls = new Map<string, ReturnType<AppServerExternalToolCallHandler>>();
+  const execute: AppServerExternalToolCallHandler = async (request) => {
+    const tool = externalTools.get(request.tool_name);
+    if (!tool) {
+      throw new Error(`Unknown external tool: ${request.tool_name}`);
+    }
+    const runtime = request.runtime ?? fallbackRuntime?.() ?? null;
+    const context: AgentToolCallContext | undefined = runtime
+      ? { toolCallId: request.tool_call_id, agentId: runtime.agent_id, conversationId: runtime.conversation_id }
+      : undefined;
+    const result = await tool.execute(request.tool_call_id, request.input, undefined, undefined, context);
+    return {
+      content: result.content.map((part) => ({
+        type: part.type,
+        ...(part.text !== undefined ? { text: part.text } : {}),
+        ...(part.data !== undefined ? { data: part.data } : {}),
+        ...(part.mimeType !== undefined ? { mimeType: part.mimeType } : {}),
+      })),
+      ...(result.isError === true ? { is_error: true } : {}),
+    };
+  };
+  return (request) => {
+    const requestId = request.request_id;
+    if (typeof requestId !== "string" || requestId.length === 0) {
+      return execute(request);
+    }
+    const existing = calls.get(requestId);
+    if (existing) return existing;
+    const call = execute(request);
+    calls.set(requestId, call);
+    while (calls.size > MAX_REMEMBERED_EXTERNAL_TOOL_CALLS) {
+      const oldest = calls.keys().next().value;
+      if (oldest === undefined) break;
+      calls.delete(oldest);
+    }
+    return call;
+  };
+}

package/src/index.ts

@@ -68,6 +68,7 @@ export type {
   SDKToolResultMessage,
   SDKReasoningMessage,
   SDKResultMessage,
+  SDKTurnOrigin,
   SDKErrorCode,
   SDKStreamEventMessage,
   SDKStreamEventPayload,
@@ -147,6 +148,7 @@ export type {
   BootstrapStateResult,
   // Tool types
   AgentTool,
+  AgentToolCallContext,
   AgentToolResult,
   AgentToolResultContent,
   AgentToolUpdateCallback,
@@ -190,6 +192,7 @@ export type {
 } from "./management-types.js";
 
 export { RepositoriesClient } from "./repositories.js";
+export type { RegisterToolsOptions, ToolRegistration } from "./tool-registration.js";
 export { ConversationForkHydrationError } from "./management-errors.js";
 export type {
   Computer,

package/src/remote-client-session-core.ts

@@ -289,9 +289,7 @@ export abstract class RemoteClientSessionCore implements LettaCodeSession {
     }
     await this.send(message);
     for await (const msg of this.stream()) {
-      if (msg.type === "result") {
-        return msg;
-      }
+      if (msg.type === "result" && msg.origin === undefined) return msg;
     }
     return {
       type: "result",
@@ -323,7 +321,8 @@ export abstract class RemoteClientSessionCore implements LettaCodeSession {
       const msg = await this.turns.nextMessage();
       if (!msg) break;
       yield msg;
-      if (msg.type === "result") break;
+      // Results of turns the runtime started are yielded; only ours end the pass.
+      if (msg.type === "result" && msg.origin === undefined) break;
     }
   }
 
@@ -717,6 +716,7 @@ export abstract class RemoteClientSessionCore implements LettaCodeSession {
         this.controller?.close();
         this.controller = null;
         const error = new Error(`${this.label} connection closed before send`);
+        this.turns.failServerTurn(error.message);
         for (const cancel of [...this.deviceStatusRefreshCancels]) cancel(error);
         this.deviceStatusRefreshCancels.clear();
         this.onIdleTransportDisconnect();

package/src/remote-session-protocol.ts

@@ -10,6 +10,7 @@ import type {
   RecoverPendingApprovalsResult,
   ReasoningEffort,
   SDKErrorCode,
+  SDKTurnOrigin,
   OutputFormat,
   SDKQueueItem,
   SendMessage,
@@ -151,6 +152,8 @@ export type TurnTracker = {
   /** Caller-supplied OTID for this turn's user message, when one was provided. */
   otid?: string;
   outputFormat?: OutputFormat;
+  /** Set when the runtime started this turn rather than the session. */
+  origin?: SDKTurnOrigin;
   queuedAt: number;
   startedAt: number;
   assistantText: string;