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

package/dist/client-entry.js

@@ -10143,14 +10143,6 @@ function buildCreatedAgentTags(options = {}) {
   }
   return Array.from(new Set(tags));
 }
-var DEFAULT_SUMMARIZATION_MODEL = "letta/auto";
-var SYSTEM_REMINDER_TAG = "system-reminder";
-var SYSTEM_REMINDER_OPEN = `<${SYSTEM_REMINDER_TAG}>`;
-var SYSTEM_REMINDER_CLOSE = `</${SYSTEM_REMINDER_TAG}>`;
-var SYSTEM_ALERT_TAG = "system-alert";
-var SYSTEM_ALERT_OPEN = `<${SYSTEM_ALERT_TAG}>`;
-var SYSTEM_ALERT_CLOSE = `</${SYSTEM_ALERT_TAG}>`;
-var ELAPSED_DISPLAY_THRESHOLD_MS = 60 * 1000;
 var READ_ONLY_BLOCK_LABELS = ["memory_filesystem"];
 var human_default = `---
 label: human
@@ -12190,7 +12182,6 @@ async function getDefaultMemoryBlocks() {
 }
 var models = [];
 var BUILTIN_MODEL_ALIASES = new Map([
-  ["auto", "letta/auto"],
   ["auto-chat", "letta/auto-chat"],
   ["auto-fast", "letta/auto-fast"]
 ]);
@@ -12239,20 +12230,14 @@ function resolveModel(modelIdentifier) {
     return builtinHandle;
   return modelIdentifier.includes("/") ? modelIdentifier : null;
 }
+var UNSELECTED_MODEL_HANDLE = "local/default";
+function isLettaHostedModelHandle(handle) {
+  return handle.startsWith("letta/");
+}
 function getDefaultModel() {
-  if (models.length === 0)
-    return "letta/auto";
-  const autoModel = models.find((model) => model.id === "auto");
-  if (autoModel)
-    return autoModel.handle;
-  const defaultModel = models.find((model) => model.isDefault);
-  if (defaultModel)
-    return defaultModel.handle;
-  const firstModel = models[0];
-  if (!firstModel) {
-    throw new Error("Model catalog is unavailable.");
-  }
-  return firstModel.handle;
+  const candidates = models.filter((model) => !isLettaHostedModelHandle(model.handle));
+  const defaultModel = candidates.find((model) => model.isDefault) ?? candidates[0];
+  return defaultModel?.handle ?? UNSELECTED_MODEL_HANDLE;
 }
 var PERSONALITY_OPTIONS = [
   {
@@ -12514,7 +12499,7 @@ async function buildCreateAgentRequest(options = {}) {
     initial_message_sequence: [],
     parallel_tool_calls: options.parallelToolCalls ?? true,
     compaction_settings: {
-      model: options.compactionModel ?? DEFAULT_SUMMARIZATION_MODEL
+      model: options.compactionModel ?? modelHandle
     },
     ...options.embedding !== undefined ? { embedding: options.embedding } : {},
     ...options.isSubagent ? { hidden: true } : options.hidden !== undefined ? { hidden: options.hidden } : {}
@@ -13128,7 +13113,7 @@ async function* streamStructuredTurns(config) {
         return;
       });
     }
-    if (msg.type !== "result") {
+    if (msg.type !== "result" || msg.origin !== undefined) {
       yield msg;
       continue;
     }
@@ -13245,9 +13230,115 @@ function expandMcpToolWildcards(allowedTools, mcpTools) {
   return [...new Set(expanded)];
 }
 
+// src/external-tools.ts
+function externalToolGroups(tools) {
+  if (!tools || tools.length === 0)
+    return;
+  return [
+    {
+      tools: tools.map((tool) => ({
+        name: tool.name,
+        label: tool.label,
+        description: tool.description,
+        parameters: tool.parameters
+      }))
+    }
+  ];
+}
+var MAX_REMEMBERED_EXTERNAL_TOOL_CALLS = 200;
+function createExternalToolCallHandler(externalTools, fallbackRuntime) {
+  const calls = new Map;
+  const execute = 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 = 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;
+  };
+}
+
+// src/runtime-tool-policy.ts
+var RUNTIME_TOOL_POLICY_CAPABILITY = "runtime_tool_policy";
+var CAPABILITY_PROBE_TIMEOUT_MS = 5000;
+function clientToolsetPayload(toolset) {
+  return {
+    ...toolset.base !== undefined ? { base: toolset.base } : {},
+    ...toolset.include !== undefined ? { include: [...new Set(toolset.include)] } : {}
+  };
+}
+function runtimeToolPolicy(allowedTools, toolset) {
+  return {
+    ...toolset !== undefined ? { toolset: clientToolsetPayload(toolset) } : {},
+    ...allowedTools !== undefined ? { allowlist: [...new Set(allowedTools)] } : {},
+    exclude_interactive: true
+  };
+}
+async function supportsRuntimeToolPolicy(client) {
+  try {
+    const info = await client.info({ timeoutMs: CAPABILITY_PROBE_TIMEOUT_MS });
+    const capabilities = info.capabilities;
+    return capabilities?.[RUNTIME_TOOL_POLICY_CAPABILITY] === true;
+  } catch {
+    return false;
+  }
+}
+function mergeInheritedTools(inherited, own) {
+  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 } : {}
+  };
+}
+
 // src/remote-turn-coordinator.ts
 var MAX_RECENTLY_SETTLED_RUN_IDS = 256;
 var TRAILING_USAGE_GRACE_MS = 100;
+var TURN_ORIGINS = new Set([
+  "task_notification",
+  "cron",
+  "subagent",
+  "system",
+  "channel",
+  "user"
+]);
 
 class RemoteTurnCoordinator {
   label;
@@ -13259,6 +13350,8 @@ class RemoteTurnCoordinator {
   activeTurn = null;
   pendingTurns = [];
   settledRunIds = new Set;
+  queueOrigins = new Map;
+  nextServerOrigin = "unknown";
   nextTurnId = 0;
   messageCounter = 0;
   clientMessageCounter = 0;
@@ -13274,16 +13367,27 @@ class RemoteTurnCoordinator {
     return this._activeTurnStartedAt;
   }
   hasInFlightTurn() {
-    return this.activeTurn !== null || this.pendingTurns.length > 0;
+    return this.activeTurn !== null && this.activeTurn.origin === undefined || this.pendingTurns.length > 0;
   }
   trackSentTurn(runtime, callerOtid, outputFormat) {
     const otid = normalizeCallerOtid(callerOtid);
-    const turn = {
-      id: ++this.nextTurnId,
-      runtime,
+    const turn = this.newTracker(runtime, {
       ...otid !== undefined ? { otid } : {},
       ...outputFormat !== undefined ? { outputFormat } : {},
-      clientMessageId: otid ?? `sdk-message-${Date.now()}-${++this.clientMessageCounter}`,
+      clientMessageId: otid ?? `sdk-message-${Date.now()}-${++this.clientMessageCounter}`
+    });
+    if (this.activeTurn) {
+      this.pendingTurns.push(turn);
+    } else {
+      this.activateTurn(turn);
+    }
+    return turn;
+  }
+  newTracker(runtime, identity) {
+    return {
+      id: ++this.nextTurnId,
+      runtime,
+      ...identity,
       queuedAt: Date.now(),
       startedAt: 0,
       assistantText: "",
@@ -13300,13 +13404,32 @@ class RemoteTurnCoordinator {
       abortRequested: false,
       timeout: null
     };
-    if (this.activeTurn) {
-      this.pendingTurns.push(turn);
-    } else {
-      this.activateTurn(turn);
-    }
+  }
+  startServerTurn(runtime) {
+    const turn = this.newTracker(runtime, { clientMessageId: "", origin: this.nextServerOrigin });
+    this.nextServerOrigin = "unknown";
+    this.activateTurn(turn);
     return turn;
   }
+  observeQueueOrigins(message, queue) {
+    for (const item of queue) {
+      if (!item.clientMessageId)
+        continue;
+      this.queueOrigins.set(item.clientMessageId, TURN_ORIGINS.has(item.source) ? item.source : "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;
+      if (disposition !== "dequeued" || typeof id !== "string")
+        continue;
+      const own = [this.activeTurn, ...this.pendingTurns].some((turn) => turn?.clientMessageId === id);
+      if (own)
+        continue;
+      this.nextServerOrigin = typeof source === "string" && TURN_ORIGINS.has(source) ? source : this.queueOrigins.get(id) ?? "unknown";
+    }
+  }
   removeTrackedTurn(turn) {
     if (turn.timeout)
       clearTimeout(turn.timeout);
@@ -13320,6 +13443,12 @@ class RemoteTurnCoordinator {
     if (index !== -1)
       this.pendingTurns.splice(index, 1);
   }
+  failServerTurn(detail) {
+    const active = this.activeTurn;
+    if (active?.origin === undefined)
+      return;
+    this.failTurn(active, detail, { errorCode: "stream_closed", recoverable: true });
+  }
   markAbortRequested() {
     if (this.activeTurn)
       this.activeTurn.abortRequested = true;
@@ -13339,6 +13468,7 @@ class RemoteTurnCoordinator {
         type: "queue_update",
         queue: queueItems(message)
       };
+      this.observeQueueOrigins(message, sdkMessage2.queue);
       this.enqueue(sdkMessage2);
       return;
     }
@@ -13381,9 +13511,9 @@ class RemoteTurnCoordinator {
     if (!delta)
       return;
     const messageType = streamDeltaMessageType(delta);
-    const active = messageType === "usage_statistics" || messageType === "stop_reason" ? this.activeTurn : this.activateNextTurnFromProtocol();
     const runId = streamDeltaRunId(delta);
     const isTurnEvidence = messageType === "assistant_message" || messageType === "reasoning_message" || messageType === "tool_call_message" || messageType === "approval_request_message" || messageType === "tool_return_message" || messageType === "error_message" || messageType === "loop_error" || runId !== undefined && (messageType === "usage_statistics" || messageType === "stop_reason");
+    const active = messageType === "usage_statistics" || messageType === "stop_reason" ? this.activeTurn : this.activateNextTurnFromProtocol() ?? (isTurnEvidence && runId !== undefined ? this.startServerTurn(runtime) : null);
     if (active && isTurnEvidence) {
       active.observedTurnEvidence = true;
       if (runId)
@@ -13841,7 +13971,8 @@ class RemoteTurnCoordinator {
       stopReason,
       durationMs: Date.now() - (tracker?.startedAt || this._activeTurnStartedAt),
       conversationId: turn.runtime.conversation_id,
-      runIds: turn.runIds.length > 0 ? turn.runIds : undefined
+      runIds: turn.runIds.length > 0 ? turn.runIds : undefined,
+      ...tracker?.origin !== undefined ? { origin: tracker.origin } : {}
     };
   }
   enqueue(message) {
@@ -14083,9 +14214,8 @@ class RemoteClientSessionCore {
     }
     await this.send(message);
     for await (const msg of this.stream()) {
-      if (msg.type === "result") {
+      if (msg.type === "result" && msg.origin === undefined)
         return msg;
-      }
     }
     return {
       type: "result",
@@ -14121,7 +14251,7 @@ class RemoteClientSessionCore {
       if (!msg)
         break;
       yield msg;
-      if (msg.type === "result")
+      if (msg.type === "result" && msg.origin === undefined)
         break;
     }
   }
@@ -14431,6 +14561,7 @@ class RemoteClientSessionCore {
         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();
@@ -14571,38 +14702,6 @@ function agentToolNames(agent) {
     return typeof name === "string" && name.length > 0 ? [name] : [];
   });
 }
-function externalToolGroups(tools) {
-  if (!tools || tools.length === 0)
-    return;
-  return [
-    {
-      tools: tools.map((tool) => ({
-        name: tool.name,
-        label: tool.label,
-        description: tool.description,
-        parameters: tool.parameters
-      }))
-    }
-  ];
-}
-function createExternalToolCallHandler(externalTools) {
-  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 } : {}
-    };
-  };
-}
 async function resolveAppServerToolApproval(options, toolName, toolInput, context) {
   if ("outputFormat" in options && options.outputFormat !== undefined && toolName === STRUCTURED_OUTPUT_TOOL) {
     return { behavior: "allow", updatedInput: null, updatedPermissions: [] };
@@ -14779,11 +14878,26 @@ class AppServerRuntimeController {
   options;
   clientToolAllowlist;
   clientToolset;
-  constructor(client, options, clientToolAllowlist, clientToolset) {
+  toolPolicyApplied;
+  constructor(client, options, clientToolAllowlist, clientToolset, toolPolicyApplied = false) {
     this.client = client;
     this.options = options;
     this.clientToolAllowlist = clientToolAllowlist;
     this.clientToolset = clientToolset;
+    this.toolPolicyApplied = toolPolicyApplied;
+  }
+  async updateToolSelection(runtime, selection) {
+    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) } : {}
+      }]
+    });
+    if (!response.success)
+      throw new Error(response.error ?? "Failed to update session tools");
   }
   onMessage(handler) {
     return this.client.onMessage((message, channel) => {
@@ -14805,14 +14919,11 @@ class AppServerRuntimeController {
         }
       ]
     };
-    if (this.clientToolAllowlist !== undefined) {
+    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 = {
@@ -14824,7 +14935,8 @@ class AppServerRuntimeController {
         }
       };
     }
-    payload.exclude_interactive_tools = true;
+    if (!this.toolPolicyApplied)
+      payload.exclude_interactive_tools = true;
     this.client.input({
       runtime,
       payload
@@ -14916,6 +15028,9 @@ class AppServerSession extends RemoteClientSessionCore {
   mcpCleanup = Promise.resolve();
   removeExternalToolHandler = null;
   removeControlRequestHandler = null;
+  inheritedTools = null;
+  removeInheritedListener = null;
+  ownSelection = null;
   constructor(remoteOptions, mode) {
     super(mode, {
       label: "app-server",
@@ -14927,6 +15042,27 @@ class AppServerSession extends RemoteClientSessionCore {
       this.externalTools.set(tool.name, tool);
     }
   }
+  inheritTools(source) {
+    this.inheritedTools = source;
+    this.removeInheritedListener = source.onChange(() => {
+      this.refreshInheritedTools().catch(() => {
+        return;
+      });
+    });
+  }
+  applyToolSelection() {
+    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;
+  }
+  async refreshInheritedTools() {
+    if (!this.ownSelection || !this.runtime || !(this.controller instanceof AppServerRuntimeController))
+      return;
+    const selection = this.applyToolSelection();
+    await this.controller.updateToolSelection(this.runtime, selection);
+  }
   shouldEnableMemfs(options) {
     if (this.mode.kind !== "create-agent")
       return false;
@@ -14942,6 +15078,9 @@ class AppServerSession extends RemoteClientSessionCore {
       ...this.remoteOptions.requestTimeoutMs !== undefined ? { requestTimeoutMs: this.remoteOptions.requestTimeoutMs } : {}
     }));
     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, {
       cwd: options.cwd,
       reservedToolNames: this.externalTools.keys()
@@ -14949,13 +15088,22 @@ 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,
       getRuntime: () => this.runtime,
       getOptions: () => this.currentOptions()
     });
-    if (this.externalTools.size > 0) {
-      this.removeExternalToolHandler = client.onExternalToolCall(createExternalToolCallHandler(this.externalTools));
+    if (this.externalTools.size > 0 || this.inheritedTools) {
+      this.removeExternalToolHandler = client.onExternalToolCall(createExternalToolCallHandler(this.externalTools, () => this.runtime));
     }
     try {
       await client.connect();
@@ -14966,19 +15114,17 @@ class AppServerSession extends RemoteClientSessionCore {
           throw new Error(`Local query() requires a Letta Code app-server with local conversation support (connected version: ${info.letta_code_version}). Upgrade @letta-ai/letta-code.`);
         }
       }
-      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 : [...tools ?? [], ...mcpToolNames];
       return {
-        controller: new AppServerRuntimeController(client, this.remoteOptions, allowedTools, clientToolset),
+        controller: new AppServerRuntimeController(client, this.remoteOptions, allowedTools, clientToolset, toolPolicyApplied),
         runtime: response.runtime,
         model: typeof response.agent?.model === "string" ? response.agent.model : typeof response.conversation?.model === "string" ? response.conversation.model : "",
         modelSettings: objectRecord(response.agent?.model_settings) ?? objectRecord(response.conversation?.model_settings) ?? null,
@@ -14996,6 +15142,10 @@ class AppServerSession extends RemoteClientSessionCore {
     }
   }
   onCoreClose() {
+    if (this.closed) {
+      this.removeInheritedListener?.();
+      this.removeInheritedListener = null;
+    }
     this.removeExternalToolHandler?.();
     this.removeExternalToolHandler = null;
     this.removeControlRequestHandler?.();
@@ -15026,11 +15176,11 @@ class AppServerSession extends RemoteClientSessionCore {
     this.ownedConnection = connection;
     return connection.url;
   }
-  async startRuntime(client) {
-    const command = await this.buildRuntimeStartCommand(client);
+  async startRuntime(client, toolPolicy) {
+    const command = await this.buildRuntimeStartCommand(client, toolPolicy);
     return client.runtimeStart(command);
   }
-  async buildRuntimeStartCommand(client) {
+  async buildRuntimeStartCommand(client, toolPolicy) {
     const options = this.mode.options;
     const command = {
       client_info: {
@@ -15061,6 +15211,7 @@ class AppServerSession extends RemoteClientSessionCore {
     const groups = externalToolGroups([...this.externalTools.values()]);
     if (groups)
       command.external_tools = groups;
+    command.tool_policy = toolPolicy;
     if (this.mode.kind === "create-agent") {
       command.create_agent = {
         body: await createAgentBody(this.mode.options),
@@ -15543,6 +15694,9 @@ class CloudStatusTransport {
     if (channel === "control" && message.type === "stream_delta") {
       return false;
     }
+    if (channel === "stream" && message.type === "external_tool_call_request") {
+      return false;
+    }
     if (this.isDuplicate(message))
       return false;
     this.trackEventSequence(message);
@@ -16039,7 +16193,7 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
       getOptions: () => this.currentOptions()
     });
     if (this.externalTools.size > 0) {
-      this.removeExternalToolHandler = client.onExternalToolCall(createExternalToolCallHandler(this.externalTools));
+      this.removeExternalToolHandler = client.onExternalToolCall(createExternalToolCallHandler(this.externalTools, () => this.runtime));
     }
   }
   cleanupTransportHandlers() {
@@ -16097,6 +16251,7 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
     const groups = externalToolGroups([...this.externalTools.values()]);
     if (groups)
       command.external_tools = groups;
+    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);
   }
   async afterRuntimeInitialized() {
@@ -16662,6 +16817,221 @@ function createQuery(createSession, params) {
   });
 }
 
+// src/tool-registration.ts
+var RECONNECT_DELAYS_MS = [250, 1000, 5000, 15000];
+var runtimeKey = (runtime) => `${runtime.agent_id}:${runtime.conversation_id}`;
+
+class ToolRegistry {
+  options;
+  connection = null;
+  entries = new Set;
+  listeners = new Set;
+  reconnectAttempt = 0;
+  reconnectTimer = null;
+  closed = false;
+  constructor(options) {
+    this.options = options;
+  }
+  async register(options) {
+    if (this.closed)
+      throw new Error("LettaAgentClient is closed");
+    const 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() {
+    this.closed = true;
+    this.entries.clear();
+    this.disconnect();
+    this.notify();
+  }
+  inheritFor(id, own) {
+    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);
+      }
+    };
+  }
+  covering(id) {
+    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));
+  }
+  notify() {
+    for (const listener of [...this.listeners])
+      listener();
+  }
+  async apply(entry, options) {
+    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)));
+    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();
+  }
+  async remove(entry) {
+    if (!this.entries.delete(entry))
+      return;
+    this.notify();
+    if (this.entries.size === 0) {
+      this.disconnect();
+      return;
+    }
+    const connection = await this.connect();
+    await publish(connection.client, [{ runtimes: entry.runtimes, external_tools: [] }]);
+  }
+  connect() {
+    this.connection ??= this.open().catch((error) => {
+      this.connection = null;
+      throw error;
+    });
+    return this.connection;
+  }
+  async open() {
+    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 } : {},
+      ...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) };
+  }
+  disconnect() {
+    if (this.reconnectTimer)
+      clearTimeout(this.reconnectTimer);
+    this.reconnectTimer = null;
+    const connection = this.connection;
+    this.connection = null;
+    connection?.then(({ client, owned }) => {
+      client.close();
+      owned?.close();
+    }, () => {
+      return;
+    });
+  }
+  onDisconnect(client) {
+    this.connection?.then((current) => {
+      if (current.client !== client)
+        return;
+      current.owned?.close();
+      this.connection = null;
+      this.scheduleReconnect();
+    }, () => {
+      return;
+    });
+  }
+  scheduleReconnect() {
+    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;
+      this.republish().catch(() => this.scheduleReconnect());
+    }, delay);
+    this.reconnectTimer.unref?.();
+  }
+  async republish() {
+    const connection = await this.connect();
+    await publish(connection.client, [...this.entries].map((entry) => group(entry.runtimes, entry.options, connection.toolPolicy)));
+    this.reconnectAttempt = 0;
+  }
+}
+function group(runtimes, options, toolPolicy) {
+  return {
+    runtimes,
+    external_tools: externalToolGroups(options.tools) ?? [],
+    ...toolPolicy ? { tool_policy: runtimeToolPolicy(options.allowedTools, options.toolset) } : {}
+  };
+}
+async function publish(client, updates) {
+  const response = await client.runtimeExternalToolsUpdate({ updates });
+  if (!response.success)
+    throw new Error(response.error ?? "Failed to register tools");
+}
+async function resolveRuntime(client, id) {
+  if (!id.startsWith("conv-") && !id.startsWith("local-conv-")) {
+    return { agent_id: id, conversation_id: "default" };
+  }
+  const response = await client.request({ type: "conversation_retrieve", request_id: client.nextRequestId("conversation_retrieve"), conversation_id: id }, {
+    predicate: (message) => 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 };
+}
+
 // src/validation.ts
 var VALID_SKILL_SOURCES = [
   "bundled",
@@ -16938,6 +17308,7 @@ class LettaAgentClientBase {
   agentRepositoriesClient = null;
   cloudClient = null;
   managementTransport = null;
+  toolRegistry = null;
   closed = false;
   closePromise = null;
   constructor(options = {}) {
@@ -17056,20 +17427,21 @@ class LettaAgentClientBase {
     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(), {
+      const session2 = looksLikeConversationId(id) ? new AppServerSession(this.appServerSessionOptions(), {
+        kind: "session",
+        conversationId: id,
+        options
+      }) : new AppServerSession(this.appServerSessionOptions(), {
         kind: "session",
         agentId: id,
         defaultConversation: true,
         options
       });
+      if (inherited)
+        session2.inheritTools(inherited);
+      return session2;
     }
     if (this.backend === "cloud") {
       if (looksLikeConversationId(id)) {
@@ -17086,7 +17458,10 @@ class LettaAgentClientBase {
         options
       }, this.getCloudClient());
     }
-    return this.resumeLocalSession(id, options);
+    const session = this.resumeLocalSession(id, options);
+    if (inherited && session instanceof AppServerSession)
+      session.inheritTools(inherited);
+    return session;
   }
   async prompt(message, agentId, options = {}) {
     this.assertOpen();
@@ -17294,10 +17669,23 @@ class LettaAgentClientBase {
     }
     return this.managementTransport;
   }
+  registerTools(options) {
+    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);
+  }
+  localAppServerConnection() {
+    throw this.localBackendUnavailableError();
+  }
   close() {
     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();
@@ -17842,4 +18230,4 @@ export {
   CloudManagedSandboxExpiredError
 };
 
-//# debugId=37BAC87F328A3A1864756E2164756E21
+//# debugId=214DC938EA1FA61564756E2164756E21