@letta-ai/letta-agent-sdk 0.2.1

package/dist/index.js

@@ -0,0 +1,4994 @@
+import { createRequire } from "node:module";
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/transport.ts
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+function sdkLog(tag, ...args) {
+  if (process.env.DEBUG_SDK)
+    console.error(`[SDK-Transport] [${tag}]`, ...args);
+}
+var SDK_AGENT_ORIGIN_TAG = "origin:letta-code";
+function shouldApplyNewAgentDefaults(options) {
+  return options.createOnly === true;
+}
+function includeSdkAgentOriginTag(tags) {
+  const normalizedTags = [];
+  let hasOriginTag = false;
+  for (const tag of tags ?? []) {
+    if (tag === SDK_AGENT_ORIGIN_TAG) {
+      if (hasOriginTag)
+        continue;
+      hasOriginTag = true;
+    }
+    normalizedTags.push(tag);
+  }
+  if (!hasOriginTag) {
+    normalizedTags.push(SDK_AGENT_ORIGIN_TAG);
+  }
+  return normalizedTags;
+}
+function buildCliArgs(options) {
+  const args = [
+    "--output-format",
+    "stream-json",
+    "--input-format",
+    "stream-json"
+  ];
+  const applyNewAgentDefaults = shouldApplyNewAgentDefaults(options);
+  if (options.conversationId) {
+    args.push("--conversation", options.conversationId);
+  } else if (options.agentId) {
+    args.push("--agent", options.agentId);
+    if (options.newConversation) {
+      args.push("--new");
+    } else if (options.defaultConversation) {
+      args.push("--conversation", "default");
+    }
+  } else if (options.createOnly) {
+    args.push("--new-agent");
+  } else if (options.newConversation) {
+    args.push("--new");
+  }
+  if (options.model) {
+    args.push("-m", options.model);
+  }
+  if (options.includePartialMessages) {
+    args.push("--include-partial-messages");
+  }
+  if (options.embedding) {
+    args.push("--embedding", options.embedding);
+  }
+  if (options.systemPrompt !== undefined) {
+    if (typeof options.systemPrompt === "string") {
+      const validPresets = [
+        "default",
+        "letta-claude",
+        "letta-codex",
+        "letta-gemini",
+        "claude",
+        "codex",
+        "gemini"
+      ];
+      if (validPresets.includes(options.systemPrompt)) {
+        args.push("--system", options.systemPrompt);
+      } else {
+        args.push("--system-custom", options.systemPrompt);
+      }
+    } else {
+      args.push("--system", options.systemPrompt.preset);
+      if (options.systemPrompt.append) {
+        args.push("--system-append", options.systemPrompt.append);
+      }
+    }
+  }
+  if (options.memory !== undefined && !options.agentId) {
+    if (options.memory.length === 0) {
+      args.push("--init-blocks", "");
+    } else {
+      const presetNames = [];
+      const memoryBlocksJson = [];
+      for (const item of options.memory) {
+        if (typeof item === "string") {
+          presetNames.push(item);
+        } else if ("blockId" in item) {
+          memoryBlocksJson.push(item);
+        } else {
+          memoryBlocksJson.push(item);
+        }
+      }
+      if (memoryBlocksJson.length > 0) {
+        args.push("--memory-blocks", JSON.stringify(memoryBlocksJson));
+        if (presetNames.length > 0) {
+          console.warn("[letta-agent-sdk] Using custom memory blocks. " + `Preset blocks are ignored when custom blocks are provided: ${presetNames.join(", ")}`);
+        }
+      } else if (presetNames.length > 0) {
+        args.push("--init-blocks", presetNames.join(","));
+      }
+    }
+  }
+  if (!options.agentId) {
+    if (options.persona !== undefined) {
+      args.push("--block-value", `persona=${options.persona}`);
+    }
+    if (options.human !== undefined) {
+      args.push("--block-value", `human=${options.human}`);
+    }
+  }
+  if (options.permissionMode === "bypassPermissions") {
+    args.push("--yolo");
+  } else if (options.permissionMode && options.permissionMode !== "default") {
+    args.push("--permission-mode", options.permissionMode);
+  }
+  if (options.allowedTools) {
+    args.push("--allowedTools", options.allowedTools.join(","));
+  }
+  if (options.disallowedTools) {
+    args.push("--disallowedTools", options.disallowedTools.join(","));
+  }
+  const tags = applyNewAgentDefaults ? includeSdkAgentOriginTag(options.tags) : options.tags;
+  if (tags && tags.length > 0) {
+    args.push("--tags", tags.join(","));
+  }
+  if (applyNewAgentDefaults) {
+    args.push("--memfs");
+  }
+  if (options.skillSources !== undefined) {
+    const sources = [...new Set(options.skillSources)];
+    if (sources.length === 0) {
+      args.push("--no-skills");
+    } else {
+      args.push("--skill-sources", sources.join(","));
+    }
+  }
+  if (options.systemInfoReminder === false) {
+    args.push("--no-system-info-reminder");
+  }
+  if (options.dreaming?.trigger !== undefined) {
+    args.push("--reflection-trigger", options.dreaming.trigger);
+  }
+  if (options.dreaming?.behavior !== undefined) {
+    args.push("--reflection-behavior", options.dreaming.behavior);
+  }
+  if (options.dreaming?.stepCount !== undefined) {
+    args.push("--reflection-step-count", String(options.dreaming.stepCount));
+  }
+  return args;
+}
+
+class SubprocessTransport {
+  options;
+  process = null;
+  stdout = null;
+  messageQueue = [];
+  messageResolvers = [];
+  closed = false;
+  agentId;
+  wireMessageCount = 0;
+  lastMessageAt = 0;
+  stderrLines = [];
+  constructor(options = {}) {
+    this.options = options;
+  }
+  async connect() {
+    const args = this.buildArgs();
+    const cliPath = await this.findCli();
+    sdkLog("connect", `CLI: ${cliPath}`);
+    sdkLog("connect", `args: ${args.join(" ")}`);
+    sdkLog("connect", `cwd: ${this.options.cwd || process.cwd()}`);
+    sdkLog("connect", `permissionMode: ${this.options.permissionMode || "default"}`);
+    this.process = spawn("node", [cliPath, ...args], {
+      cwd: this.options.cwd || process.cwd(),
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env }
+    });
+    const pid = this.process.pid;
+    sdkLog("connect", `CLI process spawned, pid=${pid}`);
+    if (!this.process.stdout || !this.process.stdin) {
+      throw new Error("Failed to create subprocess pipes");
+    }
+    this.stdout = createInterface({
+      input: this.process.stdout,
+      crlfDelay: Infinity
+    });
+    this.stdout.on("line", (line) => {
+      if (!line.trim())
+        return;
+      try {
+        const msg = JSON.parse(line);
+        this.handleMessage(msg);
+      } catch {
+        sdkLog("stdout", `[non-JSON] ${line.slice(0, 500)}`);
+      }
+    });
+    if (this.process.stderr) {
+      this.process.stderr.on("data", (data) => {
+        const msg = data.toString().trim();
+        if (msg) {
+          console.error("[letta-agent-sdk] CLI stderr:", msg);
+          this.stderrLines.push(msg);
+        }
+      });
+    }
+    this.process.on("close", (code, signal) => {
+      if (code !== 0 && code !== null) {
+        console.error(`[letta-agent-sdk] CLI process exited with code ${code}`);
+      }
+      sdkLog("close", `CLI process exited: pid=${pid} code=${code} signal=${signal} wireMessages=${this.wireMessageCount} msSinceLastMsg=${this.lastMessageAt ? Date.now() - this.lastMessageAt : 0} pendingResolvers=${this.messageResolvers.length} queueLen=${this.messageQueue.length}`);
+      this.closed = true;
+      for (const resolve of this.messageResolvers) {
+        resolve(null);
+      }
+      this.messageResolvers = [];
+    });
+    this.process.on("error", (err) => {
+      console.error("[letta-agent-sdk] CLI process error:", err);
+      this.closed = true;
+    });
+  }
+  async write(data) {
+    if (!this.process?.stdin || this.closed) {
+      const err = new Error(`Transport not connected (closed=${this.closed}, pid=${this.process?.pid}, stdin=${!!this.process?.stdin})`);
+      sdkLog("write", err.message);
+      throw err;
+    }
+    const payload = data;
+    sdkLog("write", `type=${payload.type} subtype=${payload.request?.subtype || payload.response?.subtype || "N/A"}`);
+    this.process.stdin.write(JSON.stringify(data) + `
+`);
+  }
+  async read() {
+    if (this.messageQueue.length > 0) {
+      return this.messageQueue.shift();
+    }
+    if (this.closed) {
+      sdkLog("read", `returning null (closed), total wireMessages=${this.wireMessageCount}`);
+      return null;
+    }
+    sdkLog("read", `waiting for next message (resolvers=${this.messageResolvers.length + 1}, queue=${this.messageQueue.length})`);
+    return new Promise((resolve) => {
+      this.messageResolvers.push(resolve);
+    });
+  }
+  async* messages() {
+    while (true) {
+      const msg = await this.read();
+      if (msg === null) {
+        sdkLog("messages", `iterator ending (closed=${this.closed}, wireMessages=${this.wireMessageCount})`);
+        break;
+      }
+      yield msg;
+    }
+  }
+  close() {
+    sdkLog("close", `explicit close called (wireMessages=${this.wireMessageCount}, pendingResolvers=${this.messageResolvers.length}, pid=${this.process?.pid})`);
+    if (this.process) {
+      this.process.stdin?.end();
+      this.process.kill();
+      this.process = null;
+    }
+    this.closed = true;
+    for (const resolve of this.messageResolvers) {
+      resolve(null);
+    }
+    this.messageResolvers = [];
+  }
+  get isClosed() {
+    return this.closed;
+  }
+  getStderr() {
+    return this.stderrLines.join(`
+`);
+  }
+  handleMessage(msg) {
+    this.wireMessageCount++;
+    this.lastMessageAt = Date.now();
+    const wirePayload = msg;
+    const msgType = wirePayload.message_type || wirePayload.subtype || "";
+    sdkLog("wire", `#${this.wireMessageCount} type=${msg.type} ${msgType ? `msg_type=${msgType}` : ""} resolvers=${this.messageResolvers.length} queue=${this.messageQueue.length}`);
+    if (msg.type === "result") {
+      const result = wirePayload;
+      sdkLog("wire", `RESULT: subtype=${result.subtype} stop_reason=${result.stop_reason || "N/A"} duration=${result.duration_ms}ms resultLen=${result.result?.length || 0}`);
+    }
+    if (msg.type === "system" && "subtype" in msg && msg.subtype === "init") {
+      this.agentId = msg.agent_id;
+      sdkLog("wire", `INIT: agent_id=${this.agentId}`);
+    }
+    if (msg.type === "control_request") {
+      const req = wirePayload;
+      sdkLog("wire", `CONTROL_REQUEST: id=${req.request_id} subtype=${req.request?.subtype} tool=${req.request?.tool_name || "N/A"}`);
+    }
+    if (this.messageResolvers.length > 0) {
+      const resolve = this.messageResolvers.shift();
+      resolve(msg);
+    } else {
+      this.messageQueue.push(msg);
+    }
+  }
+  buildArgs() {
+    return buildCliArgs(this.options);
+  }
+  async findCli() {
+    const { existsSync } = await import("node:fs");
+    const { dirname, join } = await import("node:path");
+    const { fileURLToPath } = await import("node:url");
+    if (process.env.LETTA_CLI_PATH && existsSync(process.env.LETTA_CLI_PATH)) {
+      return process.env.LETTA_CLI_PATH;
+    }
+    try {
+      const { createRequire: createRequire2 } = await import("node:module");
+      const require2 = createRequire2(import.meta.url);
+      const resolved = require2.resolve("@letta-ai/letta-code");
+      if (existsSync(resolved)) {
+        return resolved;
+      }
+    } catch {}
+    const __filename2 = fileURLToPath(import.meta.url);
+    const __dirname2 = dirname(__filename2);
+    const localPaths = [
+      join(__dirname2, "../../@letta-ai/letta-code/letta.js"),
+      join(__dirname2, "../../../letta-code-prod/letta.js"),
+      join(__dirname2, "../../../letta-code/letta.js")
+    ];
+    for (const p of localPaths) {
+      if (existsSync(p)) {
+        return p;
+      }
+    }
+    throw new Error("Letta Code CLI not found. Set LETTA_CLI_PATH or install @letta-ai/letta-code.");
+  }
+}
+
+// src/interactiveToolPolicy.ts
+var INTERACTIVE_APPROVAL_TOOLS = new Set([
+  "AskUserQuestion",
+  "EnterPlanMode",
+  "ExitPlanMode"
+]);
+var RUNTIME_USER_INPUT_TOOLS = new Set(["AskUserQuestion", "ExitPlanMode"]);
+var HEADLESS_AUTO_ALLOW_TOOLS = new Set(["EnterPlanMode"]);
+function requiresRuntimeUserInput(toolName) {
+  return RUNTIME_USER_INPUT_TOOLS.has(toolName);
+}
+function isHeadlessAutoAllowTool(toolName) {
+  return HEADLESS_AUTO_ALLOW_TOOLS.has(toolName);
+}
+
+// src/session.ts
+function sessionLog(tag, ...args) {
+  if (process.env.DEBUG_SDK)
+    console.error(`[SDK-Session] [${tag}]`, ...args);
+}
+var MAX_BUFFERED_STREAM_MESSAGES = 100;
+var DEFAULT_MAX_APPROVAL_RECOVERY_ATTEMPTS = 1;
+var DEFAULT_APPROVAL_RECOVERY_TIMEOUT_MS = 5000;
+var KNOWN_SDK_ERROR_CODES = new Set([
+  "approval_conflict",
+  "approval_conflict_terminal",
+  "protocol_error",
+  "error",
+  "llm_api_error",
+  "max_steps",
+  "interrupted",
+  "stream_closed"
+]);
+function isKnownSdkErrorCode(value) {
+  return KNOWN_SDK_ERROR_CODES.has(value);
+}
+function toSdkErrorCode(value) {
+  if (!value || value.length === 0)
+    return;
+  return isKnownSdkErrorCode(value) ? value : undefined;
+}
+function isUnknownControlSubtypeError(errorMessage, subtype) {
+  if (!errorMessage)
+    return false;
+  return errorMessage.toLowerCase().includes(`unknown control request subtype: ${subtype}`.toLowerCase());
+}
+function extractApiErrorDetail(apiError) {
+  const detail = apiError?.detail;
+  if (typeof detail !== "string")
+    return;
+  const trimmed = detail.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+function isApprovalConflictSignal(params) {
+  if (params.stopReason === "requires_approval")
+    return true;
+  const haystack = [params.detail, params.message].filter((value) => typeof value === "string" && value.length > 0).join(`
+`).toLowerCase();
+  if (!haystack)
+    return false;
+  return haystack.includes("waiting for approval on a tool call") || haystack.includes("cannot send a new message") || haystack.includes("requires_approval");
+}
+
+class Session {
+  options;
+  transport;
+  _agentId = null;
+  _sessionId = null;
+  _conversationId = null;
+  initialized = false;
+  externalTools = new Map;
+  streamQueue = [];
+  streamResolvers = [];
+  pumpPromise = null;
+  pumpClosed = false;
+  droppedStreamMessages = 0;
+  sendGeneration = 0;
+  lastCompletedRunIds = new Set;
+  controlResponseWaiters = new Map;
+  constructor(options = {}) {
+    this.options = options;
+    if (options.reasoningEffort !== undefined) {
+      throw new Error("reasoningEffort is not supported by this session. Create a Cloud, Remote, or local agent session before setting reasoning effort.");
+    }
+    this.transport = new SubprocessTransport(options);
+    if (options.tools) {
+      for (const tool of options.tools) {
+        this.externalTools.set(tool.name, tool);
+      }
+    }
+  }
+  async initialize() {
+    if (this.initialized) {
+      throw new Error("Session already initialized");
+    }
+    sessionLog("init", "connecting transport...");
+    await this.transport.connect();
+    sessionLog("init", "transport connected, sending initialize request");
+    await this.transport.write({
+      type: "control_request",
+      request_id: "init_1",
+      request: { subtype: "initialize" }
+    });
+    sessionLog("init", "waiting for init message from CLI...");
+    for await (const msg of this.transport.messages()) {
+      sessionLog("init", `received wire message: type=${msg.type}`);
+      if (msg.type === "control_request") {
+        const handled = await this.handleControlRequest(msg);
+        if (!handled) {
+          const wireMsgAny = msg;
+          sessionLog("init", `DROPPED unsupported control_request: subtype=${wireMsgAny.request?.subtype || "N/A"}`);
+        }
+        continue;
+      }
+      if (msg.type === "system" && "subtype" in msg && msg.subtype === "init") {
+        const initMsg = msg;
+        this._agentId = initMsg.agent_id;
+        this._sessionId = initMsg.session_id;
+        this._conversationId = initMsg.conversation_id;
+        this.initialized = true;
+        this.startBackgroundPump();
+        if (this.externalTools.size > 0) {
+          await this.registerExternalTools();
+        }
+        const allTools = [
+          ...initMsg.tools,
+          ...Array.from(this.externalTools.keys())
+        ];
+        sessionLog("init", `initialized: agent=${initMsg.agent_id} conversation=${initMsg.conversation_id} model=${initMsg.model} tools=${allTools.length} (${this.externalTools.size} external)`);
+        return {
+          type: "init",
+          agentId: initMsg.agent_id,
+          sessionId: initMsg.session_id,
+          conversationId: initMsg.conversation_id,
+          model: initMsg.model,
+          tools: allTools,
+          memfsEnabled: initMsg.memfs_enabled,
+          skillSources: initMsg.skill_sources,
+          systemInfoReminderEnabled: initMsg.system_info_reminder_enabled,
+          dreaming: initMsg.reflection_trigger && initMsg.reflection_behavior && typeof initMsg.reflection_step_count === "number" ? {
+            trigger: initMsg.reflection_trigger,
+            behavior: initMsg.reflection_behavior,
+            stepCount: initMsg.reflection_step_count
+          } : undefined
+        };
+      }
+    }
+    const stderr = this.transport.getStderr();
+    const detail = stderr ? `
+CLI stderr:
+${stderr}` : "";
+    sessionLog("init", `ERROR: transport closed before init message received${detail}`);
+    throw new Error(`Failed to initialize session - no init message received${detail}`);
+  }
+  async send(message) {
+    if (!this.initialized) {
+      sessionLog("send", "auto-initializing (not yet initialized)");
+      await this.initialize();
+    }
+    const preview = typeof message === "string" ? message.slice(0, 100) : Array.isArray(message) ? `[multimodal: ${message.length} parts]` : String(message).slice(0, 100);
+    sessionLog("send", `sending message: ${preview}${typeof message === "string" && message.length > 100 ? "..." : ""}`);
+    if (this.streamQueue.length > 0) {
+      sessionLog("send", `clearing ${this.streamQueue.length} stale messages from previous turn`);
+      this.streamQueue.length = 0;
+    }
+    await this.transport.write({
+      type: "user",
+      message: { role: "user", content: message }
+    });
+    this.sendGeneration++;
+    sessionLog("send", `message written to transport (generation=${this.sendGeneration})`);
+  }
+  async runTurn(message, options = {}) {
+    const maxApprovalRecoveryAttempts = this.resolveMaxApprovalRecoveryAttempts(options);
+    const recoveryTimeoutMs = this.resolveApprovalRecoveryTimeoutMs(options);
+    let recoveryAttempts = 0;
+    let result = await this.runSingleTurn(message);
+    while (!result.success && result.approvalConflict === true && recoveryAttempts < maxApprovalRecoveryAttempts) {
+      recoveryAttempts += 1;
+      const recovery = await this.recoverPendingApprovals({
+        timeoutMs: recoveryTimeoutMs
+      });
+      if (!recovery.recovered) {
+        return this.toTerminalApprovalConflictResult(result, {
+          recoveryAttempts,
+          detail: recovery.detail
+        });
+      }
+      result = await this.runSingleTurn(message);
+    }
+    if (!result.success && result.approvalConflict === true) {
+      return this.toTerminalApprovalConflictResult(result, { recoveryAttempts });
+    }
+    if (recoveryAttempts > 0) {
+      result.recoveryAttempts = recoveryAttempts;
+    }
+    return result;
+  }
+  async recoverPendingApprovals(options = {}) {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+    const timeoutMs = options.timeoutMs ?? this.options.approvalRecoveryTimeoutMs ?? DEFAULT_APPROVAL_RECOVERY_TIMEOUT_MS;
+    if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+      throw new Error("Invalid approval recovery timeout. Expected a positive integer.");
+    }
+    const requestId = `recover-approvals-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+    let resp;
+    try {
+      resp = await this.requestControlResponse(requestId, {
+        subtype: "recover_pending_approvals",
+        ...this._agentId ? { agent_id: this._agentId } : {},
+        ...this._conversationId ? { conversation_id: this._conversationId } : {}
+      }, { timeoutMs });
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      return {
+        recovered: false,
+        unsupported: false,
+        detail
+      };
+    }
+    if (resp.subtype === "error") {
+      const detail = resp.error ?? "recover_pending_approvals failed";
+      return {
+        recovered: false,
+        pendingApproval: true,
+        unsupported: isUnknownControlSubtypeError(detail, "recover_pending_approvals"),
+        detail
+      };
+    }
+    return {
+      recovered: true,
+      pendingApproval: false,
+      unsupported: false
+    };
+  }
+  resolveMaxApprovalRecoveryAttempts(options) {
+    const value = options.maxApprovalRecoveryAttempts ?? this.options.maxApprovalRecoveryAttempts ?? DEFAULT_MAX_APPROVAL_RECOVERY_ATTEMPTS;
+    if (!Number.isInteger(value) || value < 0) {
+      throw new Error("Invalid maxApprovalRecoveryAttempts. Expected a non-negative integer.");
+    }
+    return value;
+  }
+  resolveApprovalRecoveryTimeoutMs(options) {
+    const value = options.recoveryTimeoutMs ?? this.options.approvalRecoveryTimeoutMs ?? DEFAULT_APPROVAL_RECOVERY_TIMEOUT_MS;
+    if (!Number.isInteger(value) || value <= 0) {
+      throw new Error("Invalid approval recovery timeout. Expected a positive integer.");
+    }
+    return value;
+  }
+  toTerminalApprovalConflictResult(result, options) {
+    return {
+      ...result,
+      success: false,
+      error: "approval_conflict_terminal",
+      errorCode: "approval_conflict_terminal",
+      approvalConflict: true,
+      recoverable: false,
+      recoveryAttempts: options.recoveryAttempts,
+      errorDetail: options.detail || result.errorDetail || "Approval conflict remained unresolved after bounded SDK recovery."
+    };
+  }
+  async runSingleTurn(message) {
+    await this.send(message);
+    let latestApprovalConflictDetail;
+    let latestNonConflictErrorDetail;
+    for await (const msg of this.stream()) {
+      if (msg.type === "error") {
+        const detail = msg.errorDetail || msg.message;
+        if (msg.approvalConflict) {
+          latestApprovalConflictDetail = detail;
+        } else {
+          latestNonConflictErrorDetail = detail;
+        }
+        continue;
+      }
+      if (msg.type === "result") {
+        if (!msg.success && !msg.errorDetail) {
+          if (msg.approvalConflict && latestApprovalConflictDetail) {
+            return {
+              ...msg,
+              errorDetail: latestApprovalConflictDetail
+            };
+          }
+          if (!msg.approvalConflict && latestNonConflictErrorDetail) {
+            return {
+              ...msg,
+              errorDetail: latestNonConflictErrorDetail
+            };
+          }
+        }
+        return msg;
+      }
+    }
+    return {
+      type: "result",
+      success: false,
+      error: "stream_closed",
+      errorCode: "stream_closed",
+      recoverable: false,
+      errorDetail: "Stream ended before terminal result",
+      durationMs: 0,
+      conversationId: this._conversationId
+    };
+  }
+  async* stream() {
+    const streamStart = Date.now();
+    const minGeneration = this.sendGeneration;
+    let yieldCount = 0;
+    let staleCount = 0;
+    let staleRunIdCount = 0;
+    let gotResult = false;
+    const currentStreamRunIds = new Set;
+    const staleRunIds = new Set(this.lastCompletedRunIds);
+    const approvalConflictDetailsByRunId = new Map;
+    let latestApprovalConflictDetail;
+    this.startBackgroundPump();
+    sessionLog("stream", `starting stream (agent=${this._agentId}, conversation=${this._conversationId}, generation=${minGeneration})`);
+    while (true) {
+      const bufferedMsg = await this.nextBufferedMessage();
+      if (!bufferedMsg) {
+        break;
+      }
+      if (bufferedMsg.generation < minGeneration) {
+        staleCount++;
+        sessionLog("stream", `discarding stale message: type=${bufferedMsg.message.type} generation=${bufferedMsg.generation} (current=${minGeneration})`);
+        continue;
+      }
+      if (bufferedMsg.runId && staleRunIds.has(bufferedMsg.runId)) {
+        staleRunIdCount++;
+        sessionLog("stream", `discarding stale message: type=${bufferedMsg.message.type} runId=${bufferedMsg.runId}`);
+        continue;
+      }
+      if (bufferedMsg.runId) {
+        currentStreamRunIds.add(bufferedMsg.runId);
+      }
+      const sdkMsg = bufferedMsg.message;
+      if (sdkMsg.type === "error" && sdkMsg.approvalConflict) {
+        const detail = sdkMsg.errorDetail || sdkMsg.message;
+        if (detail) {
+          latestApprovalConflictDetail = detail;
+          if (sdkMsg.runId) {
+            approvalConflictDetailsByRunId.set(sdkMsg.runId, detail);
+          }
+        }
+      }
+      let normalizedMsg = sdkMsg;
+      if (sdkMsg.type === "result" && !sdkMsg.success) {
+        let detail = sdkMsg.errorDetail;
+        if (!detail && Array.isArray(sdkMsg.runIds)) {
+          for (const runId of sdkMsg.runIds) {
+            const fromRun = approvalConflictDetailsByRunId.get(runId);
+            if (fromRun) {
+              detail = fromRun;
+              break;
+            }
+          }
+        }
+        if (!detail) {
+          detail = latestApprovalConflictDetail;
+        }
+        const approvalConflict = sdkMsg.approvalConflict === true || isApprovalConflictSignal({
+          detail,
+          message: sdkMsg.errorCode || sdkMsg.error,
+          stopReason: sdkMsg.stopReason
+        });
+        if (approvalConflict) {
+          const normalizedErrorCode = !sdkMsg.errorCode || sdkMsg.errorCode === "error" ? "approval_conflict" : sdkMsg.errorCode;
+          const normalizedError = !sdkMsg.error || sdkMsg.error === "error" ? normalizedErrorCode : sdkMsg.error;
+          normalizedMsg = {
+            ...sdkMsg,
+            approvalConflict: true,
+            recoverable: sdkMsg.recoverable ?? true,
+            ...detail ? { errorDetail: detail } : {},
+            errorCode: normalizedErrorCode,
+            error: normalizedError
+          };
+        } else if (!sdkMsg.errorCode && sdkMsg.error) {
+          const errorCode = toSdkErrorCode(sdkMsg.error);
+          if (errorCode) {
+            normalizedMsg = {
+              ...sdkMsg,
+              errorCode
+            };
+          }
+        }
+      }
+      yieldCount++;
+      sessionLog("stream", `yield #${yieldCount}: type=${normalizedMsg.type}${normalizedMsg.type === "result" ? ` success=${normalizedMsg.success} error=${normalizedMsg.error || "none"}` : ""}`);
+      yield normalizedMsg;
+      if (normalizedMsg.type === "result") {
+        gotResult = true;
+        this.updateCompletedRunIds(normalizedMsg.runIds, currentStreamRunIds);
+        break;
+      }
+    }
+    const elapsed = Date.now() - streamStart;
+    sessionLog("stream", `stream ended: duration=${elapsed}ms yielded=${yieldCount} staleFiltered=${staleCount} staleRunIdFiltered=${staleRunIdCount} dropped=${this.droppedStreamMessages} gotResult=${gotResult}`);
+    if (!gotResult) {
+      sessionLog("stream", "WARNING: stream ended WITHOUT a result message -- transport may have closed unexpectedly");
+    }
+  }
+  startBackgroundPump() {
+    if (this.pumpPromise) {
+      return;
+    }
+    this.pumpClosed = false;
+    this.pumpPromise = this.runBackgroundPump().catch((err) => {
+      sessionLog("pump", `ERROR: ${err instanceof Error ? err.message : String(err)}`);
+    }).finally(() => {
+      this.pumpClosed = true;
+      this.resolveAllStreamWaiters(null);
+    });
+  }
+  async runBackgroundPump() {
+    sessionLog("pump", "background pump started");
+    const indexToToolCallId = new Map;
+    for await (const wireMsg of this.transport.messages()) {
+      const wireMsgAny = wireMsg;
+      if (wireMsg.type === "control_request") {
+        const handled = await this.handleControlRequest(wireMsg);
+        if (!handled) {
+          sessionLog("pump", `DROPPED unsupported control_request: subtype=${wireMsgAny.request?.subtype || "N/A"}`);
+        }
+        continue;
+      }
+      if (wireMsg.type === "control_response") {
+        const respMsg = wireMsg;
+        const requestId = respMsg.response?.request_id;
+        if (requestId && this.controlResponseWaiters.has(requestId)) {
+          const resolve = this.controlResponseWaiters.get(requestId);
+          this.controlResponseWaiters.delete(requestId);
+          resolve(respMsg.response);
+        } else {
+          sessionLog("pump", `DROPPED unmatched control_response: request_id=${requestId ?? "N/A"}`);
+        }
+        continue;
+      }
+      const messageType = wireMsgAny.message_type;
+      if (wireMsg.type === "message" && (messageType === "tool_call_message" || messageType === "approval_request_message")) {
+        const toolCalls = wireMsgAny.tool_calls;
+        const toolCall = wireMsgAny.tool_call;
+        const tc = toolCalls?.[0] || toolCall;
+        if (tc) {
+          const fnObj = tc.function;
+          const tcId = tc.tool_call_id ?? tc.id;
+          const tcIndex = tc.index;
+          if (tcId && tcIndex !== undefined) {
+            indexToToolCallId.set(tcIndex, tcId);
+          } else if (!tcId && tcIndex !== undefined) {
+            const resolvedId = indexToToolCallId.get(tcIndex);
+            if (resolvedId) {
+              if (fnObj) {
+                tc.id = resolvedId;
+              } else {
+                tc.tool_call_id = resolvedId;
+              }
+            }
+          }
+        }
+      }
+      const sdkMsg = this.transformMessage(wireMsg);
+      if (sdkMsg) {
+        this.enqueueStreamMessage(sdkMsg);
+      } else {
+        sessionLog("pump", `DROPPED wire message: type=${wireMsg.type} message_type=${wireMsgAny.message_type || "N/A"} subtype=${wireMsgAny.subtype || "N/A"}`);
+      }
+    }
+    sessionLog("pump", "background pump ended");
+  }
+  async handleControlRequest(controlReq) {
+    const subtype = controlReq.request.subtype;
+    sessionLog("pump", `control_request: subtype=${subtype} tool=${controlReq.request.tool_name || "N/A"}`);
+    if (subtype === "can_use_tool") {
+      await this.handleCanUseTool(controlReq.request_id, controlReq.request);
+      return true;
+    }
+    if (subtype === "execute_external_tool") {
+      const rawReq = controlReq.request;
+      await this.handleExecuteExternalTool(controlReq.request_id, {
+        subtype: "execute_external_tool",
+        tool_call_id: rawReq.tool_call_id,
+        tool_name: rawReq.tool_name,
+        input: rawReq.input
+      });
+      return true;
+    }
+    return false;
+  }
+  enqueueStreamMessage(msg) {
+    const bufferedMsg = {
+      message: msg,
+      generation: this.sendGeneration,
+      runId: this.getMessageRunId(msg)
+    };
+    if (this.streamResolvers.length > 0) {
+      const resolve = this.streamResolvers.shift();
+      resolve(bufferedMsg);
+      return;
+    }
+    if (this.streamQueue.length >= MAX_BUFFERED_STREAM_MESSAGES) {
+      this.streamQueue.shift();
+      this.droppedStreamMessages++;
+      sessionLog("pump", `stream queue overflow: dropped oldest message (total_dropped=${this.droppedStreamMessages}, max=${MAX_BUFFERED_STREAM_MESSAGES})`);
+    }
+    this.streamQueue.push(bufferedMsg);
+  }
+  async nextBufferedMessage() {
+    if (this.streamQueue.length > 0) {
+      return this.streamQueue.shift();
+    }
+    if (this.pumpClosed) {
+      return null;
+    }
+    return new Promise((resolve) => {
+      this.streamResolvers.push(resolve);
+    });
+  }
+  resolveAllStreamWaiters(msg) {
+    for (const resolve of this.streamResolvers) {
+      resolve(msg);
+    }
+    this.streamResolvers = [];
+    for (const resolve of this.controlResponseWaiters.values()) {
+      resolve({ subtype: "error", error: "session closed" });
+    }
+    this.controlResponseWaiters.clear();
+  }
+  getMessageRunId(msg) {
+    switch (msg.type) {
+      case "assistant":
+      case "tool_call":
+      case "tool_result":
+      case "reasoning":
+      case "error":
+      case "retry":
+        return msg.runId;
+      default:
+        return;
+    }
+  }
+  updateCompletedRunIds(resultRunIds, streamedRunIds) {
+    const nextRunIds = new Set;
+    if (Array.isArray(resultRunIds)) {
+      for (const runId of resultRunIds) {
+        if (runId) {
+          nextRunIds.add(runId);
+        }
+      }
+    }
+    for (const runId of streamedRunIds) {
+      if (runId) {
+        nextRunIds.add(runId);
+      }
+    }
+    this.lastCompletedRunIds = nextRunIds;
+  }
+  async registerExternalTools() {
+    const toolDefs = Array.from(this.externalTools.values()).map((tool) => ({
+      name: tool.name,
+      label: tool.label,
+      description: tool.description,
+      parameters: this.schemaToJsonSchema(tool.parameters)
+    }));
+    sessionLog("registerTools", `registering ${toolDefs.length} external tools: ${toolDefs.map((t) => t.name).join(", ")}`);
+    await this.transport.write({
+      type: "control_request",
+      request_id: `register_tools_${Date.now()}`,
+      request: {
+        subtype: "register_external_tools",
+        tools: toolDefs
+      }
+    });
+  }
+  schemaToJsonSchema(schema) {
+    if (schema && typeof schema === "object") {
+      const s = schema;
+      return {
+        type: s.type,
+        properties: s.properties,
+        required: s.required,
+        additionalProperties: s.additionalProperties,
+        description: s.description
+      };
+    }
+    return { type: "object" };
+  }
+  async handleExecuteExternalTool(requestId, req) {
+    const tool = this.externalTools.get(req.tool_name);
+    if (!tool) {
+      sessionLog("executeExternalTool", `ERROR: unknown tool ${req.tool_name}`);
+      await this.transport.write({
+        type: "control_response",
+        response: {
+          subtype: "external_tool_result",
+          request_id: requestId,
+          tool_call_id: req.tool_call_id,
+          content: [{ type: "text", text: `Unknown external tool: ${req.tool_name}` }],
+          is_error: true
+        }
+      });
+      return;
+    }
+    try {
+      sessionLog("executeExternalTool", `executing ${req.tool_name} (call_id=${req.tool_call_id})`);
+      const result = await tool.execute(req.tool_call_id, req.input);
+      await this.transport.write({
+        type: "control_response",
+        response: {
+          subtype: "external_tool_result",
+          request_id: requestId,
+          tool_call_id: req.tool_call_id,
+          content: result.content,
+          is_error: false
+        }
+      });
+      sessionLog("executeExternalTool", `${req.tool_name} completed successfully`);
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      sessionLog("executeExternalTool", `${req.tool_name} failed: ${errorMessage}`);
+      await this.transport.write({
+        type: "control_response",
+        response: {
+          subtype: "external_tool_result",
+          request_id: requestId,
+          tool_call_id: req.tool_call_id,
+          content: [{ type: "text", text: `Tool execution error: ${errorMessage}` }],
+          is_error: true
+        }
+      });
+    }
+  }
+  async handleCanUseTool(requestId, req) {
+    let response;
+    const toolName = req.tool_name;
+    const hasCallback = typeof this.options.canUseTool === "function";
+    const toolNeedsRuntimeUserInput = requiresRuntimeUserInput(toolName);
+    const autoAllowWithoutCallback = isHeadlessAutoAllowTool(toolName);
+    sessionLog("canUseTool", `tool=${toolName} mode=${this.options.permissionMode || "default"} requestId=${requestId}`);
+    if (toolNeedsRuntimeUserInput && !hasCallback) {
+      response = {
+        behavior: "deny",
+        message: "No canUseTool callback registered",
+        interrupt: false
+      };
+    } else if (this.options.permissionMode === "bypassPermissions" && !toolNeedsRuntimeUserInput) {
+      sessionLog("canUseTool", `AUTO-ALLOW ${toolName} (bypassPermissions)`);
+      response = {
+        behavior: "allow",
+        updatedInput: null,
+        updatedPermissions: []
+      };
+    } else if (hasCallback) {
+      try {
+        const result = await this.options.canUseTool(toolName, req.input);
+        if (result.behavior === "allow") {
+          response = {
+            behavior: "allow",
+            updatedInput: result.updatedInput ?? null,
+            updatedPermissions: []
+          };
+        } else {
+          response = {
+            behavior: "deny",
+            message: result.message ?? "Denied by canUseTool callback",
+            interrupt: false
+          };
+        }
+      } catch (err) {
+        response = {
+          behavior: "deny",
+          message: err instanceof Error ? err.message : "Callback error",
+          interrupt: false
+        };
+      }
+    } else if (autoAllowWithoutCallback) {
+      sessionLog("canUseTool", `AUTO-ALLOW ${toolName} (default behavior)`);
+      response = {
+        behavior: "allow",
+        updatedInput: null,
+        updatedPermissions: []
+      };
+    } else {
+      response = {
+        behavior: "deny",
+        message: "No canUseTool callback registered",
+        interrupt: false
+      };
+    }
+    const responseBehavior = "behavior" in response ? response.behavior : "unknown";
+    sessionLog("canUseTool", `responding: requestId=${requestId} behavior=${responseBehavior}`);
+    await this.transport.write({
+      type: "control_response",
+      response: {
+        subtype: "success",
+        request_id: requestId,
+        response
+      }
+    });
+    sessionLog("canUseTool", `response sent for ${toolName}`);
+  }
+  async abort() {
+    if (!this.initialized || this.pumpClosed)
+      return;
+    sessionLog("abort", `aborting session (agent=${this._agentId})`);
+    await this.transport.write({
+      type: "control_request",
+      request_id: `interrupt-${Date.now()}`,
+      request: { subtype: "interrupt" }
+    });
+  }
+  async requestControlResponse(requestId, request, options = {}) {
+    const responsePromise = new Promise((resolve) => {
+      this.controlResponseWaiters.set(requestId, resolve);
+    });
+    try {
+      await this.transport.write({
+        type: "control_request",
+        request_id: requestId,
+        request
+      });
+    } catch (error) {
+      this.controlResponseWaiters.delete(requestId);
+      throw error;
+    }
+    let timeoutHandle;
+    try {
+      if (typeof options.timeoutMs === "number") {
+        return await Promise.race([
+          responsePromise,
+          new Promise((_, reject) => {
+            timeoutHandle = setTimeout(() => {
+              this.controlResponseWaiters.delete(requestId);
+              reject(new Error(`Timed out waiting for control_response (${requestId})`));
+            }, options.timeoutMs);
+          })
+        ]);
+      }
+      return await responsePromise;
+    } finally {
+      if (timeoutHandle) {
+        clearTimeout(timeoutHandle);
+      }
+    }
+  }
+  async listMessages(options = {}) {
+    if (!this.initialized) {
+      throw new Error("Session must be initialized before calling listMessages()");
+    }
+    const requestId = `list-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+    const resp = await this.requestControlResponse(requestId, {
+      subtype: "list_messages",
+      ...options.conversationId ? { conversation_id: options.conversationId } : {},
+      ...options.before ? { before: options.before } : {},
+      ...options.after ? { after: options.after } : {},
+      ...options.order ? { order: options.order } : {},
+      ...options.limit !== undefined ? { limit: options.limit } : {}
+    });
+    if (!resp) {
+      throw new Error("Session closed before listMessages response arrived");
+    }
+    if (resp.subtype === "error") {
+      throw new Error(resp.error ?? "listMessages failed");
+    }
+    const payload = resp.response;
+    return {
+      messages: payload?.messages ?? [],
+      nextBefore: payload?.next_before ?? null,
+      hasMore: payload?.has_more ?? false
+    };
+  }
+  async listModels() {
+    throw new Error("listModels() is not supported by this session. Use a Cloud, Remote, or local agent session.");
+  }
+  async sendCommand(_command, _options) {
+    throw new Error("sendCommand() is not supported by this session. Use a Cloud, Remote, or local agent session.");
+  }
+  async updateModel(_update) {
+    throw new Error("updateModel() is not supported by this session. Use a Cloud, Remote, or local agent session.");
+  }
+  async bootstrapState(options = {}) {
+    if (!this.initialized) {
+      throw new Error("Session must be initialized before calling bootstrapState()");
+    }
+    const requestId = `bootstrap-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+    const resp = await this.requestControlResponse(requestId, {
+      subtype: "bootstrap_session_state",
+      ...options.limit !== undefined ? { limit: options.limit } : {},
+      ...options.order ? { order: options.order } : {}
+    });
+    if (!resp) {
+      throw new Error("Session closed before bootstrapState response arrived");
+    }
+    if (resp.subtype === "error") {
+      throw new Error(resp.error ?? "bootstrapState failed");
+    }
+    const payload = resp.response;
+    const state = {
+      agentId: payload?.agent_id ?? this._agentId ?? "",
+      conversationId: payload?.conversation_id ?? this._conversationId ?? "",
+      model: payload?.model,
+      memfsEnabled: payload?.memfs_enabled ?? false,
+      messages: payload?.messages ?? [],
+      nextBefore: payload?.next_before ?? null,
+      hasMore: payload?.has_more ?? false,
+      hasPendingApproval: payload?.has_pending_approval ?? false
+    };
+    if (payload?.tools !== undefined)
+      state.tools = payload.tools;
+    if (payload?.timings !== undefined)
+      state.timings = payload.timings;
+    return state;
+  }
+  async updateToolset(_toolsetPreference) {
+    throw new Error("updateToolset() is not supported by this session. Use a Cloud, Remote, or local agent session.");
+  }
+  close() {
+    sessionLog("close", `closing session (agent=${this._agentId}, conversation=${this._conversationId})`);
+    this.transport.close();
+    this.pumpClosed = true;
+    this.resolveAllStreamWaiters(null);
+  }
+  get agentId() {
+    return this._agentId;
+  }
+  get sessionId() {
+    return this._sessionId;
+  }
+  get conversationId() {
+    return this._conversationId;
+  }
+  async[Symbol.asyncDispose]() {
+    this.close();
+  }
+  transformMessage(wireMsg) {
+    if (wireMsg.type === "system" && "subtype" in wireMsg && wireMsg.subtype === "init") {
+      const msg = wireMsg;
+      return {
+        type: "init",
+        agentId: msg.agent_id,
+        sessionId: msg.session_id,
+        conversationId: msg.conversation_id,
+        model: msg.model,
+        tools: msg.tools,
+        memfsEnabled: msg.memfs_enabled,
+        skillSources: msg.skill_sources,
+        systemInfoReminderEnabled: msg.system_info_reminder_enabled,
+        dreaming: msg.reflection_trigger && msg.reflection_behavior && typeof msg.reflection_step_count === "number" ? {
+          trigger: msg.reflection_trigger,
+          behavior: msg.reflection_behavior,
+          stepCount: msg.reflection_step_count
+        } : undefined
+      };
+    }
+    if (wireMsg.type === "message" && "message_type" in wireMsg) {
+      const msg = wireMsg;
+      const runId = msg.run_id || undefined;
+      if (msg.message_type === "assistant_message" && msg.content) {
+        return {
+          type: "assistant",
+          content: msg.content,
+          uuid: msg.uuid,
+          runId
+        };
+      }
+      if (msg.message_type === "tool_call_message" || msg.message_type === "approval_request_message") {
+        const toolCallRaw = msg.tool_calls?.[0] || msg.tool_call;
+        if (toolCallRaw) {
+          const fnObj = toolCallRaw.function;
+          const toolCallId = toolCallRaw.tool_call_id ?? toolCallRaw.id;
+          if (!toolCallId) {
+            const detail = `Missing tool_call_id in ${msg.message_type} (uuid=${msg.uuid || "unknown"})`;
+            sessionLog("transform", detail);
+            return {
+              type: "error",
+              message: detail,
+              errorCode: "protocol_error",
+              stopReason: "protocol_error",
+              runId,
+              apiError: {
+                error_type: "protocol_error",
+                detail,
+                message_type: msg.message_type
+              },
+              recoverable: false,
+              errorDetail: detail
+            };
+          }
+          const toolName = toolCallRaw.name ?? fnObj?.name ?? "?";
+          const toolArgs = toolCallRaw.arguments ?? fnObj?.arguments ?? "";
+          let toolInput = {};
+          try {
+            toolInput = JSON.parse(toolArgs);
+          } catch {
+            toolInput = { raw: toolArgs };
+          }
+          return {
+            type: "tool_call",
+            toolCallId,
+            toolName,
+            toolInput,
+            rawArguments: toolArgs || undefined,
+            uuid: msg.uuid,
+            runId
+          };
+        }
+      }
+      if (msg.message_type === "tool_return_message" && msg.tool_call_id) {
+        return {
+          type: "tool_result",
+          toolCallId: msg.tool_call_id,
+          content: msg.tool_return || "",
+          isError: msg.status === "error",
+          uuid: msg.uuid,
+          runId
+        };
+      }
+      if (msg.message_type === "reasoning_message" && msg.reasoning) {
+        return {
+          type: "reasoning",
+          content: msg.reasoning,
+          uuid: msg.uuid,
+          runId
+        };
+      }
+    }
+    if (wireMsg.type === "stream_event") {
+      const msg = wireMsg;
+      const eventPayload = msg.event ?? {};
+      return {
+        type: "stream_event",
+        event: eventPayload,
+        uuid: msg.uuid
+      };
+    }
+    if (wireMsg.type === "result") {
+      const msg = wireMsg;
+      const runIds = Array.isArray(msg.run_ids) ? msg.run_ids.filter((id) => typeof id === "string") : undefined;
+      const approvalConflict = isApprovalConflictSignal({
+        stopReason: msg.stop_reason
+      });
+      const legacyError = msg.subtype !== "success" ? approvalConflict && msg.subtype === "error" ? "approval_conflict" : msg.subtype : undefined;
+      const errorCode = toSdkErrorCode(legacyError);
+      return {
+        type: "result",
+        success: msg.subtype === "success",
+        result: msg.result,
+        error: legacyError,
+        errorCode,
+        ...approvalConflict ? {
+          approvalConflict: true,
+          recoverable: true
+        } : {},
+        stopReason: msg.stop_reason,
+        durationMs: msg.duration_ms,
+        totalCostUsd: msg.total_cost_usd,
+        conversationId: msg.conversation_id,
+        runIds
+      };
+    }
+    if (wireMsg.type === "error") {
+      const msg = wireMsg;
+      const errorDetail = extractApiErrorDetail(msg.api_error);
+      const approvalConflict = isApprovalConflictSignal({
+        detail: errorDetail,
+        message: msg.message,
+        stopReason: msg.stop_reason
+      });
+      const errorCode = approvalConflict ? "approval_conflict" : toSdkErrorCode(msg.stop_reason);
+      return {
+        type: "error",
+        message: msg.message,
+        ...errorCode ? { errorCode } : {},
+        ...approvalConflict ? {
+          approvalConflict: true,
+          recoverable: true
+        } : {},
+        ...errorDetail ? { errorDetail } : {},
+        stopReason: msg.stop_reason,
+        runId: msg.run_id,
+        apiError: msg.api_error
+      };
+    }
+    if (wireMsg.type === "retry") {
+      const msg = wireMsg;
+      return {
+        type: "retry",
+        reason: msg.reason,
+        attempt: msg.attempt,
+        maxAttempts: msg.max_attempts,
+        delayMs: msg.delay_ms,
+        runId: msg.run_id
+      };
+    }
+    return null;
+  }
+}
+
+// node_modules/@letta-ai/letta-code/dist/app-server-client.js
+var DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+var WEBSOCKET_OPEN_STATE = 1;
+function getGlobalWebSocket() {
+  return globalThis.WebSocket;
+}
+function normalizeBaseUrl(url) {
+  const parsed = new URL(url);
+  if (parsed.protocol === "http:")
+    parsed.protocol = "ws:";
+  if (parsed.protocol === "https:")
+    parsed.protocol = "wss:";
+  if (parsed.protocol !== "ws:" && parsed.protocol !== "wss:") {
+    throw new Error(`Unsupported app-server URL protocol: ${parsed.protocol}`);
+  }
+  if (!parsed.pathname || parsed.pathname === "/") {
+    parsed.pathname = "/ws";
+  }
+  return parsed;
+}
+function resolveAppServerChannelUrl(url, channel) {
+  const parsed = normalizeBaseUrl(url);
+  parsed.searchParams.set("channel", channel);
+  return parsed.toString();
+}
+function attachSocketListener(socket, type, listener) {
+  if (socket.addEventListener && socket.removeEventListener) {
+    socket.addEventListener(type, listener);
+    return () => socket.removeEventListener?.(type, listener);
+  }
+  if (socket.on) {
+    socket.on(type, listener);
+    return () => socket.off?.(type, listener);
+  }
+  throw new Error("WebSocket implementation does not support event listeners");
+}
+function onceSocketEvent(socket, type, listener) {
+  if (socket.once) {
+    socket.once(type, listener);
+    return () => socket.off?.(type, listener);
+  }
+  let detach = () => {};
+  detach = attachSocketListener(socket, type, (event) => {
+    detach();
+    listener(event);
+  });
+  return detach;
+}
+function waitForSocketOpen(socket) {
+  if (socket.readyState === WEBSOCKET_OPEN_STATE) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve, reject) => {
+    let detachOpen = () => {};
+    let detachError = () => {};
+    const cleanup = () => {
+      detachOpen();
+      detachError();
+    };
+    detachOpen = onceSocketEvent(socket, "open", () => {
+      cleanup();
+      resolve();
+    });
+    detachError = onceSocketEvent(socket, "error", (event) => {
+      cleanup();
+      reject(new Error(`App-server WebSocket failed to open: ${String(event)}`));
+    });
+  });
+}
+function rawEventData(event) {
+  if (event && typeof event === "object" && "data" in event) {
+    return event.data;
+  }
+  return event;
+}
+function messageDataToString(data) {
+  const raw = rawEventData(data);
+  if (typeof raw === "string")
+    return raw;
+  if (raw instanceof ArrayBuffer) {
+    return new TextDecoder().decode(raw);
+  }
+  if (raw instanceof Uint8Array) {
+    return new TextDecoder().decode(raw);
+  }
+  if (ArrayBuffer.isView(raw)) {
+    return new TextDecoder().decode(new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength));
+  }
+  return String(raw);
+}
+function parseProtocolMessage(event) {
+  return JSON.parse(messageDataToString(event));
+}
+function appServerSocketOptions(authToken) {
+  if (authToken === undefined) {
+    return;
+  }
+  const token = authToken.trim();
+  if (!token) {
+    throw new Error("app-server auth token must not be empty");
+  }
+  return { headers: { Authorization: `Bearer ${token}` } };
+}
+function sameRuntime(a, b) {
+  return a?.agent_id === b.agent_id && a?.conversation_id === b.conversation_id;
+}
+function isWaitingLoopStatus(message) {
+  return message.loop_status.status === "WAITING_ON_INPUT";
+}
+function isWaitingOnApprovalLoopStatus(message) {
+  return message.loop_status.status === "WAITING_ON_APPROVAL";
+}
+function streamDeltaRunId(message) {
+  const runId = message.delta.run_id;
+  return typeof runId === "string" ? runId : null;
+}
+function streamDeltaMessageType(message) {
+  const messageType = message.delta.message_type;
+  return typeof messageType === "string" ? messageType : null;
+}
+function streamDeltaStopReason(message) {
+  const stopReason = message.delta.stop_reason;
+  return typeof stopReason === "string" ? stopReason : null;
+}
+function streamDeltaErrorMessage(message) {
+  const delta = message.delta;
+  const apiMessage = delta.api_error?.message ?? delta.api_error?.detail;
+  if (typeof apiMessage === "string" && apiMessage.length > 0)
+    return apiMessage;
+  if (typeof delta.message === "string" && delta.message.length > 0)
+    return delta.message;
+  return "App-server turn failed";
+}
+
+class AppServerClient {
+  control;
+  stream;
+  requestTimeoutMs;
+  pending = new Map;
+  messageHandlers = new Set;
+  sendHandlers = new Set;
+  activeTurnRuntimes = new Set;
+  nextRequestNumber = 0;
+  constructor(options) {
+    const WebSocket = options.WebSocket ?? getGlobalWebSocket();
+    if (!WebSocket) {
+      throw new Error("No WebSocket implementation available");
+    }
+    this.requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    const socketOptions = appServerSocketOptions(options.authToken);
+    this.control = new WebSocket(resolveAppServerChannelUrl(options.url, "control"), socketOptions);
+    this.stream = new WebSocket(resolveAppServerChannelUrl(options.url, "stream"), socketOptions);
+    attachSocketListener(this.control, "message", (event) => {
+      this.handleMessage(event, "control");
+    });
+    attachSocketListener(this.stream, "message", (event) => {
+      this.handleMessage(event, "stream");
+    });
+    const rejectPending = () => this.rejectAllPending("App-server socket closed");
+    attachSocketListener(this.control, "close", rejectPending);
+    attachSocketListener(this.stream, "close", rejectPending);
+  }
+  async connect() {
+    await Promise.all([
+      waitForSocketOpen(this.control),
+      waitForSocketOpen(this.stream)
+    ]);
+    return this;
+  }
+  close() {
+    this.rejectAllPending("App-server client closed");
+    this.control.close();
+    this.stream.close();
+  }
+  onMessage(handler) {
+    this.messageHandlers.add(handler);
+    return () => this.messageHandlers.delete(handler);
+  }
+  onSend(handler) {
+    this.sendHandlers.add(handler);
+    return () => this.sendHandlers.delete(handler);
+  }
+  nextRequestId(prefix = "req") {
+    this.nextRequestNumber += 1;
+    return `${prefix}-${this.nextRequestNumber}`;
+  }
+  send(command) {
+    for (const handler of this.sendHandlers) {
+      handler(command);
+    }
+    this.control.send(JSON.stringify(command));
+  }
+  request(commandOrType, bodyOrOptions = {}, maybeOptions = {}) {
+    const isTypeRequest = typeof commandOrType === "string";
+    const command = isTypeRequest ? {
+      type: commandOrType,
+      request_id: bodyOrOptions.request_id ?? this.nextRequestId(commandOrType),
+      ...bodyOrOptions
+    } : commandOrType;
+    const options = isTypeRequest ? maybeOptions : bodyOrOptions;
+    const timeoutMs = options.timeoutMs ?? this.requestTimeoutMs;
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pending.delete(command.request_id);
+        reject(new Error(`Timed out waiting for ${command.request_id}`));
+      }, timeoutMs);
+      this.pending.set(command.request_id, {
+        resolve: (message) => resolve(message),
+        reject,
+        predicate: options.predicate,
+        timeout
+      });
+      try {
+        this.send(command);
+      } catch (error) {
+        clearTimeout(timeout);
+        this.pending.delete(command.request_id);
+        reject(error instanceof Error ? error : new Error(String(error)));
+      }
+    });
+  }
+  runtimeStart(command, options = {}) {
+    return this.request({
+      type: "runtime_start",
+      request_id: command.request_id ?? this.nextRequestId("runtime-start"),
+      ...command
+    }, {
+      ...options,
+      predicate: (message) => message.type === "runtime_start_response"
+    });
+  }
+  sync(command, options = {}) {
+    return this.request({
+      type: "sync",
+      request_id: command.request_id ?? this.nextRequestId("sync"),
+      ...command
+    }, {
+      ...options,
+      predicate: (message) => message.type === "sync_response"
+    });
+  }
+  abort(command, options = {}) {
+    return this.request({
+      type: "abort_message",
+      request_id: command.request_id ?? this.nextRequestId("abort"),
+      ...command
+    }, {
+      ...options,
+      predicate: (message) => message.type === "abort_message_response"
+    });
+  }
+  onExternalToolCall(handler) {
+    return this.onMessage((message, channel) => {
+      if (channel !== "control" || message.type !== "external_tool_call_request") {
+        return;
+      }
+      Promise.resolve(handler(message)).then((result) => {
+        this.send({
+          type: "external_tool_call_response",
+          request_id: message.request_id,
+          result
+        });
+      }).catch((error) => {
+        this.send({
+          type: "external_tool_call_response",
+          request_id: message.request_id,
+          error: error instanceof Error ? error.message : String(error)
+        });
+      });
+    });
+  }
+  input(command) {
+    this.send({ type: "input", ...command });
+  }
+  runTurn(command, options = {}) {
+    const runtimeKey = `${command.runtime.agent_id}/${command.runtime.conversation_id}`;
+    if (this.activeTurnRuntimes.has(runtimeKey)) {
+      return Promise.reject(new Error(`A turn is already in flight for ${runtimeKey}`));
+    }
+    this.activeTurnRuntimes.add(runtimeKey);
+    const timeoutMs = options.timeoutMs ?? this.requestTimeoutMs;
+    const commandWithIds = this.withClientMessageIds(command);
+    const runIds = new Set;
+    let observedTurnEvidence = false;
+    let observedRequiresApprovalStop = false;
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        cleanup();
+        reject(new Error(`Timed out waiting for app-server turn on ${command.runtime.agent_id}/${command.runtime.conversation_id}`));
+      }, timeoutMs);
+      const cleanup = () => {
+        clearTimeout(timeout);
+        this.activeTurnRuntimes.delete(runtimeKey);
+        offMessage();
+      };
+      const finish = (completedBy, terminalMessage, stopReason) => {
+        cleanup();
+        resolve({
+          runtime: command.runtime,
+          stopReason,
+          runIds: [...runIds],
+          clientMessageIds: commandWithIds.clientMessageIds,
+          completedBy,
+          terminalMessage
+        });
+      };
+      const fail = (error) => {
+        cleanup();
+        reject(error);
+      };
+      const offMessage = this.onMessage((message) => {
+        if (!sameRuntime(message.runtime, command.runtime)) {
+          return;
+        }
+        if (message.type === "stream_delta") {
+          observedTurnEvidence = true;
+          const runId = streamDeltaRunId(message);
+          if (runId)
+            runIds.add(runId);
+          const messageType = streamDeltaMessageType(message);
+          if (messageType === "loop_error" || messageType === "error_message") {
+            fail(new Error(streamDeltaErrorMessage(message)));
+            return;
+          }
+          if (messageType === "stop_reason") {
+            const stopReason = streamDeltaStopReason(message);
+            if (stopReason === "requires_approval") {
+              observedRequiresApprovalStop = true;
+              return;
+            }
+            finish("stop_reason", message, stopReason);
+          }
+          return;
+        }
+        if (message.type === "update_loop_status") {
+          const hadTurnEvidenceBeforeLoopStatus = observedTurnEvidence || observedRequiresApprovalStop;
+          if (!hadTurnEvidenceBeforeLoopStatus && (isWaitingOnApprovalLoopStatus(message) || options.allowLoopStatusFallback === true && isWaitingLoopStatus(message))) {
+            return;
+          }
+          for (const runId of message.loop_status.active_run_ids) {
+            observedTurnEvidence = true;
+            runIds.add(runId);
+          }
+          if (hadTurnEvidenceBeforeLoopStatus && isWaitingOnApprovalLoopStatus(message)) {
+            finish("loop_status_waiting_on_approval", message, "requires_approval");
+            return;
+          }
+          if (options.allowLoopStatusFallback === true && hadTurnEvidenceBeforeLoopStatus && isWaitingLoopStatus(message)) {
+            finish("loop_status_waiting_fallback", message, null);
+          }
+        }
+      });
+      try {
+        this.input(commandWithIds.command);
+      } catch (error) {
+        fail(error instanceof Error ? error : new Error(String(error)));
+      }
+    });
+  }
+  withClientMessageIds(command) {
+    if (command.payload.kind !== "create_message") {
+      return { command, clientMessageIds: [] };
+    }
+    const clientMessageIds = [];
+    const messages = command.payload.messages.map((message) => {
+      if (message.role !== "user")
+        return message;
+      const existing = message.client_message_id;
+      const clientMessageId = typeof existing === "string" && existing.length > 0 ? existing : this.nextRequestId("client-message");
+      clientMessageIds.push(clientMessageId);
+      return { ...message, client_message_id: clientMessageId };
+    });
+    return {
+      command: {
+        ...command,
+        payload: { ...command.payload, messages }
+      },
+      clientMessageIds
+    };
+  }
+  handleMessage(event, channel) {
+    const message = parseProtocolMessage(event);
+    for (const handler of this.messageHandlers) {
+      handler(message, channel);
+    }
+    const requestId = message && typeof message === "object" && "request_id" in message ? message.request_id : undefined;
+    if (channel !== "control" || typeof requestId !== "string") {
+      return;
+    }
+    const pending = this.pending.get(requestId);
+    if (!pending || pending.predicate && !pending.predicate(message)) {
+      return;
+    }
+    clearTimeout(pending.timeout);
+    this.pending.delete(requestId);
+    pending.resolve(message);
+  }
+  rejectAllPending(reason) {
+    for (const [requestId, pending] of this.pending) {
+      clearTimeout(pending.timeout);
+      this.pending.delete(requestId);
+      pending.reject(new Error(reason));
+    }
+  }
+}
+function createAppServerClient(options) {
+  return new AppServerClient(options);
+}
+
+// src/local-app-server.ts
+import { spawn as spawn2 } from "node:child_process";
+
+// src/cli-resolver.ts
+import { existsSync } from "node:fs";
+import { createRequire as createRequire2 } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+var require2 = createRequire2(import.meta.url);
+var __filename2 = fileURLToPath(import.meta.url);
+var __dirname2 = dirname(__filename2);
+function findLettaCli() {
+  const envPath = process.env.LETTA_CLI_PATH;
+  if (envPath && existsSync(envPath)) {
+    return envPath;
+  }
+  try {
+    return require2.resolve("@letta-ai/letta-code");
+  } catch {}
+  const localPaths = [
+    join(__dirname2, "..", "node_modules", "@letta-ai", "letta-code", "letta.js"),
+    join(__dirname2, "../../@letta-ai/letta-code/letta.js"),
+    join(__dirname2, "../../../letta-code-prod/letta.js"),
+    join(__dirname2, "../../../letta-code/letta.js"),
+    join(__dirname2, "..", "..", "letta-code", "letta.js")
+  ];
+  for (const path of localPaths) {
+    if (existsSync(path)) {
+      return path;
+    }
+  }
+  throw new Error("Could not find Letta Code CLI. Set LETTA_CLI_PATH environment variable or install @letta-ai/letta-code.");
+}
+
+// src/local-app-server.ts
+var DEFAULT_LISTEN_URL = "ws://127.0.0.1:0";
+var DEFAULT_STARTUP_TIMEOUT_MS = 30000;
+var LISTENING_RE = /^Listening on\s+(ws:\/\/\S+)\s*$/m;
+function appendLine(buffer, chunk) {
+  return buffer + String(chunk);
+}
+function tryExtractListeningUrl(output) {
+  const match = output.match(LISTENING_RE);
+  return match?.[1] ?? null;
+}
+function buildLocalAppServerArgs(cliPath, options = {}) {
+  return [
+    cliPath,
+    ...options.backend !== undefined ? ["--backend", options.backend] : [],
+    "app-server",
+    "--listen",
+    options.listen ?? DEFAULT_LISTEN_URL
+  ];
+}
+function terminateProcess(child) {
+  if (child.exitCode !== null || child.signalCode !== null)
+    return;
+  child.kill("SIGTERM");
+  setTimeout(() => {
+    if (child.exitCode === null && child.signalCode === null) {
+      child.kill("SIGKILL");
+    }
+  }, 1000).unref?.();
+}
+function startLocalAppServer(options = {}) {
+  const cliPath = options.cliPath ?? findLettaCli();
+  const args = buildLocalAppServerArgs(cliPath, options);
+  const startupTimeoutMs = options.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
+  return new Promise((resolve, reject) => {
+    const child = spawn2(process.execPath, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env, ...options.env ?? {} }
+    });
+    let settled = false;
+    let output = "";
+    const cleanup = () => {
+      child.stdout?.off("data", onStdout);
+      child.stderr?.off("data", onStderr);
+      child.off("error", onError);
+      child.off("exit", onExit);
+      clearTimeout(timeout);
+    };
+    const fail = (error) => {
+      if (settled)
+        return;
+      settled = true;
+      cleanup();
+      terminateProcess(child);
+      reject(error);
+    };
+    const succeed = (url) => {
+      if (settled)
+        return;
+      settled = true;
+      cleanup();
+      resolve({
+        url,
+        close: () => terminateProcess(child)
+      });
+    };
+    const onOutput = (chunk) => {
+      output = appendLine(output, chunk);
+      const url = tryExtractListeningUrl(output);
+      if (url)
+        succeed(url);
+    };
+    const onStdout = (chunk) => onOutput(chunk);
+    const onStderr = (chunk) => {
+      output = appendLine(output, chunk);
+    };
+    const onError = (error) => fail(error);
+    const onExit = (code, signal) => {
+      if (settled)
+        return;
+      fail(new Error(`Local Letta Code app-server exited before listening (code=${code ?? "null"}, signal=${signal ?? "null"}).${output ? ` Output:
+${output.trim()}` : ""}`));
+    };
+    const timeout = setTimeout(() => {
+      fail(new Error(`Timed out waiting for local Letta Code app-server to start.${output ? ` Output:
+${output.trim()}` : ""}`));
+    }, startupTimeoutMs);
+    child.stdout?.on("data", onStdout);
+    child.stderr?.on("data", onStderr);
+    child.once("error", onError);
+    child.once("exit", onExit);
+  });
+}
+
+// src/remote-client-session-core.ts
+var FAILURE_STOP_REASONS = new Set([
+  "error",
+  "llm_api_error",
+  "max_steps",
+  "interrupted",
+  "cancelled",
+  "canceled"
+]);
+var REASONING_EFFORTS = new Set([
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh"
+]);
+var KNOWN_SDK_ERROR_CODES2 = new Set([
+  "approval_conflict",
+  "approval_conflict_terminal",
+  "protocol_error",
+  "error",
+  "llm_api_error",
+  "max_steps",
+  "interrupted",
+  "stream_closed"
+]);
+function mapPermissionMode(mode) {
+  if (mode === undefined || mode === "default")
+    return;
+  if (mode === "acceptEdits")
+    return "acceptEdits";
+  if (mode === "bypassPermissions")
+    return "unrestricted";
+  if (mode === "plan")
+    return "memory";
+  return;
+}
+function ensureSuccess(message, fallback) {
+  if (message.success === false) {
+    throw new Error(typeof message.error === "string" ? message.error : fallback);
+  }
+}
+function toSdkErrorCode2(value) {
+  if (!value || value.length === 0)
+    return;
+  return KNOWN_SDK_ERROR_CODES2.has(value) ? value : undefined;
+}
+function isReasoningEffort(value) {
+  return typeof value === "string" && REASONING_EFFORTS.has(value);
+}
+function nonEmptyString(value, name) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`Invalid ${name}. Expected a non-empty string.`);
+  }
+  return value;
+}
+function normalizeUpdateModelInput(update) {
+  if (typeof update === "string") {
+    if (update.length === 0) {
+      throw new Error("Invalid model. Expected a non-empty string.");
+    }
+    return { model: update };
+  }
+  if (!update || typeof update !== "object" || Array.isArray(update)) {
+    throw new Error("Invalid updateModel options. Expected a model string or options object.");
+  }
+  const model = nonEmptyString(update.model, "model");
+  const modelId = nonEmptyString(update.modelId, "modelId");
+  const modelHandle = nonEmptyString(update.modelHandle, "modelHandle");
+  const reasoningEffort = update.reasoningEffort;
+  if (reasoningEffort !== undefined && !isReasoningEffort(reasoningEffort)) {
+    throw new Error(`Invalid reasoningEffort '${String(reasoningEffort)}'. Valid values: ${[...REASONING_EFFORTS].join(", ")}`);
+  }
+  if (model !== undefined && (modelId !== undefined || modelHandle !== undefined)) {
+    throw new Error("Invalid updateModel options. Use either model or explicit modelId/modelHandle, not both.");
+  }
+  if (model === undefined && modelId === undefined && modelHandle === undefined && reasoningEffort === undefined) {
+    throw new Error("Invalid updateModel options. Provide model, modelId, modelHandle, or reasoningEffort.");
+  }
+  return {
+    ...model !== undefined ? { model } : {},
+    ...modelId !== undefined ? { modelId } : {},
+    ...modelHandle !== undefined ? { modelHandle } : {},
+    ...reasoningEffort !== undefined ? { reasoningEffort } : {}
+  };
+}
+function modelPayloadWithoutReasoning(input) {
+  const payload = {};
+  if (input.modelId !== undefined)
+    payload.model_id = input.modelId;
+  if (input.modelHandle !== undefined)
+    payload.model_handle = input.modelHandle;
+  if (input.model !== undefined) {
+    if (input.model.includes("/"))
+      payload.model_handle = input.model;
+    else
+      payload.model_id = input.model;
+  }
+  return payload;
+}
+function toBaseModelHandle(handle, byokProviderAliases) {
+  if (!handle)
+    return;
+  const slashIndex = handle.indexOf("/");
+  if (slashIndex === -1)
+    return handle;
+  const provider = handle.slice(0, slashIndex);
+  const model = handle.slice(slashIndex + 1);
+  const baseProvider = byokProviderAliases?.[provider];
+  return baseProvider ? `${baseProvider}/${model}` : handle;
+}
+function getContextWindow(value) {
+  const contextWindow = value?.context_window;
+  return typeof contextWindow === "number" ? contextWindow : undefined;
+}
+function getReasoningEffort(entry) {
+  const effort = entry.updateArgs?.reasoning_effort;
+  return typeof effort === "string" ? effort : undefined;
+}
+function sameContextCandidates(candidates, contextWindow) {
+  if (contextWindow === undefined)
+    return candidates;
+  const matches = candidates.filter((entry) => getContextWindow(entry.updateArgs) === contextWindow);
+  return matches.length > 0 ? matches : candidates;
+}
+function isApprovalConflictSignal2(params) {
+  if (params.stopReason === "requires_approval")
+    return true;
+  const haystack = [params.detail, params.message].filter((value) => typeof value === "string" && value.length > 0).join(`
+`).toLowerCase();
+  return haystack.includes("waiting for approval on a tool call") || haystack.includes("cannot send a new message") || haystack.includes("requires_approval");
+}
+function resolveDreamingSettings(dreaming) {
+  if (!dreaming)
+    return null;
+  return {
+    trigger: dreaming.trigger ?? "step-count",
+    step_count: dreaming.stepCount ?? 5
+  };
+}
+function extractTextFromContent(content) {
+  if (typeof content === "string")
+    return content;
+  if (Array.isArray(content)) {
+    const pieces = [];
+    for (const part of content) {
+      if (typeof part === "string") {
+        pieces.push(part);
+        continue;
+      }
+      if (part && typeof part === "object") {
+        const record = part;
+        if (typeof record.text === "string") {
+          pieces.push(record.text);
+        }
+      }
+    }
+    const joined = pieces.join("");
+    return joined.length > 0 ? joined : null;
+  }
+  if (content && typeof content === "object") {
+    const record = content;
+    if (typeof record.text === "string")
+      return record.text;
+  }
+  return null;
+}
+function toolInputFromArguments(args) {
+  if (args && typeof args === "object" && !Array.isArray(args)) {
+    return { input: args };
+  }
+  const raw = typeof args === "string" ? args : "";
+  if (!raw)
+    return { input: {} };
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return { input: parsed, raw };
+    }
+  } catch {}
+  return { input: { raw }, raw };
+}
+function firstToolCall(delta) {
+  const toolCalls = delta.tool_calls;
+  if (Array.isArray(toolCalls)) {
+    const first = toolCalls[0];
+    return first && typeof first === "object" ? first : undefined;
+  }
+  if (toolCalls && typeof toolCalls === "object") {
+    return toolCalls;
+  }
+  const toolCall = delta.tool_call;
+  return toolCall && typeof toolCall === "object" ? toolCall : undefined;
+}
+function firstToolReturn(delta) {
+  const toolReturns = delta.tool_returns;
+  if (Array.isArray(toolReturns)) {
+    const first = toolReturns[0];
+    return first && typeof first === "object" ? first : undefined;
+  }
+  return;
+}
+function sameRuntime2(message, runtime) {
+  const msgRuntime = message.runtime;
+  if (msgRuntime) {
+    return msgRuntime.agent_id === runtime.agent_id && msgRuntime.conversation_id === runtime.conversation_id;
+  }
+  const messageAgentId = typeof message.agent_id === "string" ? message.agent_id : typeof message.agentId === "string" ? message.agentId : undefined;
+  const messageConversationId = typeof message.conversation_id === "string" ? message.conversation_id : typeof message.conversationId === "string" ? message.conversationId : undefined;
+  if (messageAgentId && messageAgentId !== runtime.agent_id)
+    return false;
+  if (messageConversationId && messageConversationId !== runtime.conversation_id)
+    return false;
+  return true;
+}
+function streamDeltaRecord(message) {
+  if (message.type !== "stream_delta")
+    return null;
+  const delta = message.delta;
+  return delta && typeof delta === "object" && !Array.isArray(delta) ? delta : null;
+}
+function streamDeltaMessageType2(delta) {
+  return typeof delta.message_type === "string" ? delta.message_type : undefined;
+}
+function streamDeltaRunId2(delta) {
+  return typeof delta.run_id === "string" ? delta.run_id : undefined;
+}
+function streamDeltaStopReason2(delta) {
+  return typeof delta.stop_reason === "string" ? delta.stop_reason : undefined;
+}
+function loopStatusRecord(message) {
+  if (message.type !== "update_loop_status")
+    return null;
+  const loopStatus = message.loop_status;
+  return loopStatus && typeof loopStatus === "object" && !Array.isArray(loopStatus) ? loopStatus : null;
+}
+function loopStatusValue(message) {
+  const loopStatus = loopStatusRecord(message);
+  return typeof loopStatus?.status === "string" ? loopStatus.status : undefined;
+}
+function loopStatusRunIds(message) {
+  const activeRunIds = loopStatusRecord(message)?.active_run_ids;
+  return Array.isArray(activeRunIds) ? activeRunIds.filter((runId) => typeof runId === "string") : [];
+}
+function queueItems(message) {
+  const queue = message.queue;
+  if (!Array.isArray(queue))
+    return [];
+  return queue.flatMap((item) => {
+    if (!item || typeof item !== "object" || Array.isArray(item))
+      return [];
+    const record = item;
+    if (typeof record.id !== "string")
+      return [];
+    return [
+      {
+        id: record.id,
+        clientMessageId: typeof record.client_message_id === "string" ? record.client_message_id : "",
+        kind: typeof record.kind === "string" ? record.kind : "message",
+        source: typeof record.source === "string" ? record.source : "user",
+        content: record.content,
+        enqueuedAt: typeof record.enqueued_at === "string" ? record.enqueued_at : ""
+      }
+    ];
+  });
+}
+function normalizeSendMessage(message) {
+  return message;
+}
+
+class RemoteClientSessionCore {
+  mode;
+  controller = null;
+  runtime = null;
+  initialized = false;
+  closed = false;
+  activeTurnStartedAt = 0;
+  _agentId = null;
+  _sessionId = null;
+  _conversationId = null;
+  _model = "";
+  _modelSettings = null;
+  label;
+  requestTimeoutMs;
+  streamQueue = [];
+  streamResolvers = [];
+  removeMessageHandler = null;
+  activeTurn = null;
+  pendingTurns = [];
+  nextTurnId = 0;
+  messageCounter = 0;
+  clientMessageCounter = 0;
+  toolNames;
+  constructor(mode, config) {
+    this.mode = mode;
+    this.label = config.label;
+    this.requestTimeoutMs = config.requestTimeoutMs;
+  }
+  async initialize() {
+    if (this.initialized) {
+      throw new Error("Session already initialized");
+    }
+    if (this.closed) {
+      throw new Error("Session is closed");
+    }
+    try {
+      const init = await this.initializeRuntimeController();
+      this.controller = init.controller;
+      this.runtime = init.runtime;
+      this._agentId = init.runtime.agent_id;
+      this._conversationId = init.runtime.conversation_id;
+      this._sessionId = `${init.runtime.agent_id}:${init.runtime.conversation_id}`;
+      this._modelSettings = init.modelSettings ?? null;
+      this._model = typeof init.model === "string" ? init.model : typeof this._modelSettings?.model === "string" ? this._modelSettings.model : "";
+      this.toolNames = init.tools;
+      this.removeMessageHandler = this.controller.onMessage(this.handleProtocolMessage);
+      this.initialized = true;
+      await this.afterRuntimeInitialized();
+      await this.applyPostInitializeOptions();
+      const initMessage = {
+        type: "init",
+        agentId: init.runtime.agent_id,
+        sessionId: this._sessionId,
+        conversationId: init.runtime.conversation_id,
+        model: this._model
+      };
+      if (this.toolNames !== undefined)
+        initMessage.tools = this.toolNames;
+      return initMessage;
+    } catch (error) {
+      this.close();
+      throw error;
+    }
+  }
+  async send(message) {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+    if (!this.controller || !this.runtime) {
+      throw new Error("Session is not initialized");
+    }
+    await this.beforeTurn();
+    const turn = this.trackSentTurn(this.runtime);
+    try {
+      this.controller.sendTurnMessage(this.runtime, message, {
+        clientMessageId: turn.clientMessageId
+      });
+    } catch (error) {
+      this.removeTrackedTurn(turn);
+      throw error;
+    }
+  }
+  async runTurn(message, _options = {}) {
+    if (this.activeTurn || this.pendingTurns.length > 0) {
+      throw new Error(`A turn is already in flight for this ${this.label} session. Use send() and stream() to let the listener queue messages.`);
+    }
+    await this.send(message);
+    for await (const msg of this.stream()) {
+      if (msg.type === "result") {
+        return msg;
+      }
+    }
+    return {
+      type: "result",
+      success: false,
+      error: "stream_closed",
+      errorCode: "stream_closed",
+      recoverable: false,
+      errorDetail: "Stream ended before terminal result",
+      durationMs: Date.now() - this.activeTurnStartedAt,
+      conversationId: this._conversationId
+    };
+  }
+  async* stream() {
+    while (true) {
+      const msg = await this.nextMessage();
+      if (!msg)
+        break;
+      yield msg;
+      if (msg.type === "result")
+        break;
+    }
+  }
+  async abort() {
+    if (!this.initialized)
+      return;
+    if (!this.controller || !this.runtime)
+      return;
+    if (this.activeTurn)
+      this.activeTurn.abortRequested = true;
+    await this.controller.abort(this.runtime);
+  }
+  async sendCommand(command, options) {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+    if (!this.controller) {
+      throw new Error("Session is not initialized");
+    }
+    if (!command || typeof command !== "object" || Array.isArray(command)) {
+      throw new Error("Invalid command. Expected a protocol command object.");
+    }
+    if (typeof command.type !== "string" || command.type.length === 0) {
+      throw new Error("Invalid command. Expected a non-empty type.");
+    }
+    if (!options || !options.responseType && !options.predicate && options.timeoutMs === undefined) {
+      this.controller.send(command);
+      return;
+    }
+    const { type, ...body } = command;
+    const response = await this.controller.request(type, body, {
+      ...options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {},
+      predicate: options.predicate ? (message) => options.predicate?.(message) === true : options.responseType ? (message) => message.type === options.responseType : undefined
+    });
+    return response;
+  }
+  async listModels() {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+    if (!this.controller) {
+      throw new Error("Session is not initialized");
+    }
+    return this.controller.listModels();
+  }
+  async updateModel(update) {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+    if (!this.controller || !this.runtime) {
+      throw new Error("Session is not initialized");
+    }
+    const normalized = normalizeUpdateModelInput(update);
+    const payload = await this.resolveUpdateModelPayload(normalized);
+    const result = await this.controller.updateModel(this.runtime, payload);
+    if (result.modelHandle !== undefined) {
+      this._model = result.modelHandle;
+    } else if (payload.model_handle !== undefined) {
+      this._model = payload.model_handle;
+    } else if (typeof result.modelSettings?.model === "string") {
+      this._model = result.modelSettings.model;
+    }
+    if ("modelSettings" in result) {
+      this._modelSettings = result.modelSettings ?? null;
+    }
+    return result;
+  }
+  async recoverPendingApprovals(options = {}) {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+    if (!this.controller || !this.runtime) {
+      throw new Error("Session is not initialized");
+    }
+    return this.controller.recoverPendingApprovals(this.runtime, options);
+  }
+  async listMessages(options = {}) {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+    if (!this.controller) {
+      throw new Error("Session is not initialized");
+    }
+    const conversationId = options.conversationId ?? this._conversationId;
+    if (!conversationId) {
+      throw new Error("No conversation id available for listMessages()");
+    }
+    return this.controller.listMessages(conversationId, options);
+  }
+  async bootstrapState(options = {}) {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+    const page = await this.listMessages({
+      limit: options.limit,
+      order: options.order
+    });
+    const state = {
+      agentId: this._agentId ?? "",
+      conversationId: this._conversationId ?? "",
+      model: this._model,
+      messages: page.messages
+    };
+    if (this.toolNames !== undefined) {
+      state.tools = this.toolNames;
+    }
+    if (page.nextBefore !== undefined) {
+      state.nextBefore = page.nextBefore;
+    }
+    if (page.hasMore !== undefined) {
+      state.hasMore = page.hasMore;
+    }
+    return state;
+  }
+  close() {
+    if (this.closed)
+      return;
+    this.closed = true;
+    this.removeMessageHandler?.();
+    this.removeMessageHandler = null;
+    if (this.activeTurn?.timeout)
+      clearTimeout(this.activeTurn.timeout);
+    for (const turn of this.pendingTurns) {
+      if (turn.timeout)
+        clearTimeout(turn.timeout);
+    }
+    this.activeTurn = null;
+    this.pendingTurns.length = 0;
+    this.controller?.close();
+    this.controller = null;
+    this.onCoreClose();
+    this.resolveAll(null);
+  }
+  get agentId() {
+    return this._agentId;
+  }
+  get sessionId() {
+    return this._sessionId;
+  }
+  get conversationId() {
+    return this._conversationId;
+  }
+  async[Symbol.asyncDispose]() {
+    this.close();
+  }
+  async changeDeviceState(updates) {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+    if (!this.controller || !this.runtime) {
+      throw new Error("Session is not initialized");
+    }
+    const payload = {};
+    if (updates.cwd !== undefined)
+      payload.cwd = updates.cwd;
+    const mode = mapPermissionMode(updates.permissionMode);
+    if (mode !== undefined)
+      payload.mode = mode;
+    if (updates.agentId !== undefined)
+      payload.agent_id = updates.agentId;
+    if (updates.conversationId !== undefined)
+      payload.conversation_id = updates.conversationId;
+    this.controller.send({
+      type: "change_device_state",
+      runtime: this.runtime,
+      payload
+    });
+  }
+  async updateToolset(toolsetPreference) {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+    if (!this.controller || !this.runtime) {
+      throw new Error("Session is not initialized");
+    }
+    const response = await this.controller.request("update_toolset", {
+      runtime: this.runtime,
+      toolset_preference: toolsetPreference
+    }, { predicate: (message) => message.type === "update_toolset_response" });
+    ensureSuccess(response, "Failed to update toolset");
+  }
+  async afterRuntimeInitialized() {}
+  async beforeTurn() {}
+  onCoreClose() {}
+  currentOptions() {
+    return this.mode.options;
+  }
+  shouldEnableMemfs(options) {
+    return false;
+  }
+  enableMemfsBody() {
+    if (!this.runtime)
+      return {};
+    return { agent_id: this.runtime.agent_id };
+  }
+  setModel(model) {
+    this._model = model;
+  }
+  trackSentTurn(runtime) {
+    const turn = {
+      id: ++this.nextTurnId,
+      runtime,
+      clientMessageId: `sdk-message-${Date.now()}-${++this.clientMessageCounter}`,
+      queuedAt: Date.now(),
+      startedAt: 0,
+      assistantText: "",
+      runIds: new Set,
+      observedTurnEvidence: false,
+      observedRequiresApprovalStop: false,
+      abortRequested: false,
+      timeout: null
+    };
+    if (this.activeTurn) {
+      this.pendingTurns.push(turn);
+    } else {
+      this.activateTurn(turn);
+    }
+    return turn;
+  }
+  activateTurn(turn) {
+    this.activeTurn = turn;
+    turn.startedAt = Date.now();
+    this.activeTurnStartedAt = turn.startedAt;
+    if (this.requestTimeoutMs !== undefined) {
+      turn.timeout = setTimeout(() => {
+        this.failTurn(turn, `Timed out waiting for ${this.label} turn`);
+      }, this.requestTimeoutMs);
+      turn.timeout.unref?.();
+    }
+  }
+  activateNextTurnFromProtocol() {
+    if (this.activeTurn)
+      return this.activeTurn;
+    const next = this.pendingTurns.shift();
+    if (!next)
+      return null;
+    this.activateTurn(next);
+    return next;
+  }
+  removeTrackedTurn(turn) {
+    if (turn.timeout)
+      clearTimeout(turn.timeout);
+    if (this.activeTurn === turn) {
+      this.activeTurn = null;
+      return;
+    }
+    const index = this.pendingTurns.indexOf(turn);
+    if (index !== -1)
+      this.pendingTurns.splice(index, 1);
+  }
+  failTurn(turn, detail) {
+    if (this.activeTurn !== turn)
+      return;
+    this.enqueue({
+      type: "error",
+      message: detail,
+      errorCode: "error",
+      stopReason: "error",
+      errorDetail: detail,
+      recoverable: false
+    });
+    this.completeActiveTurn({
+      runtime: turn.runtime,
+      stopReason: "error",
+      runIds: [...turn.runIds],
+      success: false,
+      detail,
+      errorCode: "error"
+    });
+  }
+  completeActiveTurn(turn) {
+    const active = this.activeTurn;
+    if (!active)
+      return;
+    if (active.timeout) {
+      clearTimeout(active.timeout);
+      active.timeout = null;
+    }
+    this.enqueue(this.resultFromTurn(turn, active));
+    this.activeTurn = null;
+  }
+  async resolveUpdateModelPayload(input) {
+    if (input.reasoningEffort === undefined) {
+      return modelPayloadWithoutReasoning(input);
+    }
+    if (!this.controller) {
+      throw new Error("Session is not initialized");
+    }
+    const catalog = await this.controller.listModels();
+    const byId = new Map(catalog.entries.map((entry) => [entry.id, entry]));
+    const aliases = catalog.byokProviderAliases;
+    let baseEntry;
+    let explicitHandle;
+    let targetHandle;
+    if (input.modelId !== undefined) {
+      baseEntry = byId.get(input.modelId);
+      explicitHandle = input.modelHandle;
+      targetHandle = baseEntry?.handle ?? toBaseModelHandle(input.modelHandle, aliases);
+    } else if (input.modelHandle !== undefined) {
+      explicitHandle = input.modelHandle;
+      targetHandle = toBaseModelHandle(input.modelHandle, aliases);
+    } else if (input.model !== undefined) {
+      baseEntry = byId.get(input.model);
+      if (baseEntry) {
+        targetHandle = baseEntry.handle;
+      } else {
+        explicitHandle = input.model;
+        targetHandle = toBaseModelHandle(input.model, aliases);
+      }
+    } else {
+      explicitHandle = this._model || undefined;
+      targetHandle = toBaseModelHandle(this._model || undefined, aliases);
+    }
+    if (!targetHandle) {
+      throw new Error("reasoningEffort requires a current model or explicit model/modelId/modelHandle.");
+    }
+    const candidates = catalog.entries.filter((entry) => entry.handle === targetHandle || entry.handle === explicitHandle);
+    if (candidates.length === 0) {
+      throw new Error(`reasoningEffort requires a model from listModels(); no catalog entry found for ${targetHandle}.`);
+    }
+    const contextWindow = getContextWindow(baseEntry?.updateArgs) ?? getContextWindow(this._modelSettings);
+    const scopedCandidates = sameContextCandidates(candidates, contextWindow);
+    const matchingEntry = scopedCandidates.find((entry) => getReasoningEffort(entry) === input.reasoningEffort) ?? candidates.find((entry) => getReasoningEffort(entry) === input.reasoningEffort);
+    if (!matchingEntry) {
+      throw new Error(`No ${input.reasoningEffort} reasoning tier found for model ${targetHandle}.`);
+    }
+    const payload = { model_id: matchingEntry.id };
+    if (explicitHandle !== undefined) {
+      payload.model_handle = explicitHandle;
+    }
+    return payload;
+  }
+  async applyPostInitializeOptions() {
+    if (!this.controller || !this.runtime)
+      return;
+    const options = this.currentOptions();
+    if (this.shouldEnableMemfs(options)) {
+      const response = await this.controller.request("enable_memfs", this.enableMemfsBody(), { predicate: (message) => message.type === "enable_memfs_response" });
+      ensureSuccess(response, "Failed to enable memfs");
+    }
+    const dreamingSettings = resolveDreamingSettings(options.dreaming);
+    if (dreamingSettings) {
+      const response = await this.controller.request("set_reflection_settings", {
+        runtime: this.runtime,
+        settings: dreamingSettings,
+        scope: "both"
+      }, { predicate: (message) => message.type === "set_reflection_settings_response" });
+      ensureSuccess(response, "Failed to update dreaming settings");
+    }
+    if (this.mode.kind !== "session")
+      return;
+    if (this.mode.options.model !== undefined || this.mode.options.reasoningEffort !== undefined) {
+      await this.updateModel({
+        ...this.mode.options.model !== undefined ? { model: this.mode.options.model } : {},
+        ...this.mode.options.reasoningEffort !== undefined ? { reasoningEffort: this.mode.options.reasoningEffort } : {}
+      });
+    }
+  }
+  handleProtocolMessage = (message) => {
+    if (!this.runtime || !sameRuntime2(message, this.runtime))
+      return;
+    if (message.type === "update_queue") {
+      const sdkMessage2 = {
+        type: "queue_update",
+        queue: queueItems(message)
+      };
+      this.enqueue(sdkMessage2);
+      return;
+    }
+    if (message.type === "update_loop_status") {
+      this.handleLoopStatusMessage(message);
+      return;
+    }
+    const delta = streamDeltaRecord(message);
+    if (!delta)
+      return;
+    const active = this.activateNextTurnFromProtocol();
+    if (active) {
+      active.observedTurnEvidence = true;
+      const runId = streamDeltaRunId2(delta);
+      if (runId)
+        active.runIds.add(runId);
+    }
+    const sdkMessage = this.transformStreamDelta(delta);
+    if (sdkMessage) {
+      this.enqueue(sdkMessage);
+    }
+    this.handleTurnTerminalDelta(delta, sdkMessage);
+  };
+  handleLoopStatusMessage(message) {
+    const status = loopStatusValue(message);
+    if (!status)
+      return;
+    const activeRunIds = loopStatusRunIds(message);
+    const sdkMessage = {
+      type: "loop_status",
+      status,
+      activeRunIds
+    };
+    this.enqueue(sdkMessage);
+    const active = this.activeTurn;
+    if (!active)
+      return;
+    for (const runId of activeRunIds)
+      active.runIds.add(runId);
+    const hadTurnEvidence = active.observedTurnEvidence || active.observedRequiresApprovalStop;
+    if (!hadTurnEvidence)
+      return;
+    if (status === "WAITING_ON_APPROVAL") {
+      this.completeActiveTurn({
+        runtime: active.runtime,
+        stopReason: "requires_approval",
+        runIds: [...active.runIds]
+      });
+      return;
+    }
+    if (status === "WAITING_ON_INPUT" && active.abortRequested) {
+      this.completeActiveTurn({
+        runtime: active.runtime,
+        stopReason: "interrupted",
+        runIds: [...active.runIds],
+        success: false,
+        detail: "Interrupted",
+        errorCode: "interrupted"
+      });
+      return;
+    }
+    if (status === "WAITING_ON_INPUT" && active.observedTurnEvidence) {
+      this.completeActiveTurn({
+        runtime: active.runtime,
+        stopReason: null,
+        runIds: [...active.runIds]
+      });
+    }
+  }
+  handleTurnTerminalDelta(delta, sdkMessage) {
+    const active = this.activeTurn;
+    if (!active)
+      return;
+    const messageType = streamDeltaMessageType2(delta);
+    if (messageType === "stop_reason") {
+      const stopReason = streamDeltaStopReason2(delta) ?? null;
+      if (stopReason === "requires_approval") {
+        active.observedRequiresApprovalStop = true;
+        return;
+      }
+      this.completeActiveTurn({
+        runtime: active.runtime,
+        stopReason,
+        runIds: [...active.runIds]
+      });
+      return;
+    }
+    if (sdkMessage?.type === "error") {
+      this.completeActiveTurn({
+        runtime: active.runtime,
+        stopReason: sdkMessage.stopReason,
+        runIds: [...active.runIds],
+        success: false,
+        detail: sdkMessage.errorDetail ?? sdkMessage.message,
+        errorCode: sdkMessage.errorCode
+      });
+    }
+  }
+  transformStreamDelta(delta) {
+    const messageType = typeof delta.message_type === "string" ? delta.message_type : undefined;
+    const runId = typeof delta.run_id === "string" ? delta.run_id : undefined;
+    const uuid = typeof delta.id === "string" ? delta.id : `${this.label}-${++this.messageCounter}`;
+    if (messageType === "assistant_message") {
+      const content = extractTextFromContent(delta.content);
+      if (!content)
+        return null;
+      if (this.activeTurn)
+        this.activeTurn.assistantText += content;
+      return { type: "assistant", content, uuid, runId };
+    }
+    if (messageType === "reasoning_message") {
+      const content = typeof delta.reasoning === "string" ? delta.reasoning : extractTextFromContent(delta.content);
+      if (!content)
+        return null;
+      return { type: "reasoning", content, uuid, runId };
+    }
+    if (messageType === "tool_call_message" || messageType === "approval_request_message") {
+      const toolCall = firstToolCall(delta);
+      if (!toolCall)
+        return null;
+      const fn = toolCall.function && typeof toolCall.function === "object" ? toolCall.function : undefined;
+      const toolCallId = (typeof toolCall.tool_call_id === "string" ? toolCall.tool_call_id : undefined) ?? (typeof toolCall.id === "string" ? toolCall.id : undefined);
+      if (!toolCallId) {
+        const detail = `Missing tool_call_id in ${messageType} (uuid=${uuid})`;
+        return {
+          type: "error",
+          message: detail,
+          errorCode: "protocol_error",
+          stopReason: "protocol_error",
+          runId,
+          recoverable: false,
+          errorDetail: detail
+        };
+      }
+      const toolName = (typeof toolCall.name === "string" ? toolCall.name : undefined) ?? (typeof fn?.name === "string" ? fn.name : undefined) ?? "?";
+      const { input, raw } = toolInputFromArguments(toolCall.arguments ?? fn?.arguments);
+      return {
+        type: "tool_call",
+        toolCallId,
+        toolName,
+        toolInput: input,
+        rawArguments: raw,
+        uuid,
+        runId
+      };
+    }
+    if (messageType === "tool_return_message") {
+      const toolReturn = firstToolReturn(delta) ?? delta;
+      const toolCallId = (typeof delta.tool_call_id === "string" ? delta.tool_call_id : undefined) ?? (typeof toolReturn.tool_call_id === "string" ? toolReturn.tool_call_id : undefined);
+      if (!toolCallId)
+        return null;
+      const content = extractTextFromContent(delta.tool_return ?? toolReturn.tool_return ?? toolReturn.content) ?? "";
+      const status = typeof delta.status === "string" ? delta.status : toolReturn.status;
+      return {
+        type: "tool_result",
+        toolCallId,
+        content,
+        isError: status === "error",
+        uuid,
+        runId
+      };
+    }
+    if (messageType === "error_message" || messageType === "loop_error") {
+      const detail = (typeof delta.detail === "string" ? delta.detail : undefined) ?? (typeof delta.message === "string" ? delta.message : undefined) ?? `${this.label} turn failed`;
+      const stopReason = (typeof delta.stop_reason === "string" ? delta.stop_reason : undefined) ?? (typeof delta.error_type === "string" ? delta.error_type : undefined) ?? "error";
+      const approvalConflict = isApprovalConflictSignal2({
+        detail,
+        message: typeof delta.message === "string" ? delta.message : undefined,
+        stopReason
+      });
+      return {
+        type: "error",
+        message: detail,
+        errorCode: approvalConflict ? "approval_conflict" : toSdkErrorCode2(stopReason),
+        approvalConflict: approvalConflict || undefined,
+        recoverable: approvalConflict ? true : false,
+        errorDetail: detail,
+        stopReason,
+        runId
+      };
+    }
+    if (messageType === "retry") {
+      return {
+        type: "retry",
+        reason: typeof delta.reason === "string" ? delta.reason : "error",
+        attempt: typeof delta.attempt === "number" ? delta.attempt : 0,
+        maxAttempts: typeof delta.max_attempts === "number" ? delta.max_attempts : 0,
+        delayMs: typeof delta.delay_ms === "number" ? delta.delay_ms : 0,
+        runId
+      };
+    }
+    if (messageType === "stop_reason" || messageType === "ping") {
+      return null;
+    }
+    return {
+      type: "stream_event",
+      event: delta,
+      uuid
+    };
+  }
+  resultFromTurn(turn, tracker) {
+    const stopReason = turn.stopReason ?? (turn.success === false ? "error" : undefined);
+    const approvalConflict = isApprovalConflictSignal2({
+      detail: turn.detail,
+      stopReason
+    });
+    const success = turn.success !== undefined ? turn.success && !approvalConflict && !FAILURE_STOP_REASONS.has(stopReason ?? "") : !approvalConflict && !FAILURE_STOP_REASONS.has(stopReason ?? "");
+    const errorCode = approvalConflict ? "approval_conflict" : turn.errorCode ?? toSdkErrorCode2(stopReason);
+    return {
+      type: "result",
+      success,
+      result: success ? tracker?.assistantText || undefined : undefined,
+      error: success ? undefined : errorCode ?? stopReason ?? "error",
+      errorCode: success ? undefined : errorCode ?? "error",
+      approvalConflict: approvalConflict || undefined,
+      recoverable: approvalConflict ? true : success ? undefined : false,
+      errorDetail: success ? undefined : turn.detail,
+      stopReason,
+      durationMs: Date.now() - (tracker?.startedAt || this.activeTurnStartedAt),
+      conversationId: turn.runtime.conversation_id,
+      runIds: turn.runIds.length > 0 ? turn.runIds : undefined
+    };
+  }
+  enqueue(message) {
+    const resolver = this.streamResolvers.shift();
+    if (resolver) {
+      resolver(message);
+      return;
+    }
+    this.streamQueue.push(message);
+  }
+  nextMessage() {
+    const next = this.streamQueue.shift();
+    if (next)
+      return Promise.resolve(next);
+    if (this.closed)
+      return Promise.resolve(null);
+    return new Promise((resolve) => {
+      this.streamResolvers.push(resolve);
+    });
+  }
+  resolveAll(value) {
+    for (const resolve of this.streamResolvers.splice(0)) {
+      resolve(value);
+    }
+  }
+}
+
+// src/app-server-session.ts
+function agentToolNames(agent) {
+  const tools = agent?.tools;
+  if (!Array.isArray(tools))
+    return;
+  return tools.flatMap((tool) => {
+    if (typeof tool === "string" && tool.length > 0)
+      return [tool];
+    if (!tool || typeof tool !== "object")
+      return [];
+    const name = tool.name;
+    return typeof name === "string" && name.length > 0 ? [name] : [];
+  });
+}
+var SDK_AGENT_ORIGIN_TAG2 = "origin:letta-code";
+function isPresetSystemPrompt(value) {
+  return [
+    "default",
+    "letta-claude",
+    "letta-codex",
+    "letta-gemini",
+    "claude",
+    "codex",
+    "gemini"
+  ].includes(value);
+}
+function includeSdkAgentOriginTag2(tags) {
+  const normalizedTags = [];
+  let hasOriginTag = false;
+  for (const tag of tags ?? []) {
+    if (tag === SDK_AGENT_ORIGIN_TAG2) {
+      if (hasOriginTag)
+        continue;
+      hasOriginTag = true;
+    }
+    normalizedTags.push(tag);
+  }
+  if (!hasOriginTag) {
+    normalizedTags.push(SDK_AGENT_ORIGIN_TAG2);
+  }
+  return normalizedTags;
+}
+function assertRemoteCreateAgentOptionsSupported(options) {
+  if (options.allowedTools !== undefined || options.disallowedTools !== undefined) {
+    throw new Error("App-server createAgent() does not yet support allowedTools/disallowedTools.");
+  }
+  if (options.canUseTool !== undefined) {
+    throw new Error("App-server createAgent() does not yet support canUseTool callbacks.");
+  }
+  if (options.skillSources !== undefined) {
+    throw new Error("App-server createAgent() does not yet support skillSources overrides.");
+  }
+  if (options.systemInfoReminder !== undefined) {
+    throw new Error("App-server createAgent() does not yet support systemInfoReminder overrides.");
+  }
+  if (options.dreaming?.behavior !== undefined) {
+    throw new Error("App-server createAgent() does not yet support dreaming.behavior overrides.");
+  }
+}
+function assertRemoteSessionOptionsSupported(action, options) {
+  if (options.systemPrompt !== undefined) {
+    throw new Error(`App-server ${action}() does not yet support systemPrompt overrides for existing agents.`);
+  }
+  if (options.allowedTools !== undefined || options.disallowedTools !== undefined) {
+    throw new Error(`App-server ${action}() does not yet support allowedTools/disallowedTools.`);
+  }
+  if (options.skillSources !== undefined) {
+    throw new Error(`App-server ${action}() does not yet support skillSources overrides.`);
+  }
+  if (options.systemInfoReminder !== undefined) {
+    throw new Error(`App-server ${action}() does not yet support systemInfoReminder overrides.`);
+  }
+  if (options.dreaming?.behavior !== undefined) {
+    throw new Error(`App-server ${action}() does not yet support dreaming.behavior overrides.`);
+  }
+  if (options.memfsStartup !== undefined) {
+    throw new Error(`App-server ${action}() does not support memfsStartup.`);
+  }
+  if (options.includePartialMessages !== undefined) {
+    throw new Error(`App-server ${action}() streams app-server deltas directly and does not support includePartialMessages.`);
+  }
+}
+function normalizeMemoryBlock(block) {
+  const normalized = { ...block };
+  if (normalized.value === undefined && typeof normalized.content === "string") {
+    normalized.value = normalized.content;
+  }
+  return normalized;
+}
+function createAgentBody(options, settings = {}) {
+  assertRemoteCreateAgentOptionsSupported(options);
+  const includeOriginTag = settings.includeSdkOriginTag ?? true;
+  const body = {};
+  if (includeOriginTag || options.tags !== undefined) {
+    body.tags = includeOriginTag ? includeSdkAgentOriginTag2(options.tags) : options.tags;
+  }
+  if (options.model !== undefined)
+    body.model = options.model;
+  if (options.embedding !== undefined)
+    body.embedding = options.embedding;
+  if (options.systemPrompt !== undefined) {
+    if (typeof options.systemPrompt === "string") {
+      if (isPresetSystemPrompt(options.systemPrompt)) {
+        throw new Error("App-server createAgent() does not yet support system prompt presets.");
+      }
+      body.system = options.systemPrompt;
+    } else {
+      throw new Error("App-server createAgent() does not yet support system prompt preset objects.");
+    }
+  }
+  const memoryBlocks = [];
+  const blockIds = [];
+  for (const item of options.memory ?? []) {
+    if (typeof item === "string") {
+      throw new Error("App-server createAgent() does not yet support memory preset names.");
+    }
+    if ("blockId" in item) {
+      blockIds.push(item.blockId);
+    } else {
+      memoryBlocks.push(normalizeMemoryBlock(item));
+    }
+  }
+  if (options.persona !== undefined) {
+    memoryBlocks.push({ label: "persona", value: options.persona });
+  }
+  if (options.human !== undefined) {
+    memoryBlocks.push({ label: "human", value: options.human });
+  }
+  if (memoryBlocks.length > 0)
+    body.memory_blocks = memoryBlocks;
+  if (blockIds.length > 0)
+    body.block_ids = blockIds;
+  return body;
+}
+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 } : {}
+      }))
+    };
+  };
+}
+async function resolveAppServerToolApproval(options, toolName, toolInput) {
+  const hasCallback = typeof options.canUseTool === "function";
+  const toolNeedsRuntimeUserInput = requiresRuntimeUserInput(toolName);
+  if (toolNeedsRuntimeUserInput && !hasCallback) {
+    return {
+      behavior: "deny",
+      message: "No canUseTool callback registered",
+      interrupt: false
+    };
+  }
+  if (options.permissionMode === "bypassPermissions" && !toolNeedsRuntimeUserInput) {
+    return { behavior: "allow", updatedInput: null, updatedPermissions: [] };
+  }
+  if (hasCallback) {
+    try {
+      const result = await options.canUseTool(toolName, toolInput);
+      if (result.behavior === "allow") {
+        return {
+          behavior: "allow",
+          message: result.message,
+          updatedInput: result.updatedInput ?? null,
+          updatedPermissions: result.updatedPermissions ?? []
+        };
+      }
+      return {
+        behavior: "deny",
+        message: result.message ?? "Denied by canUseTool callback",
+        interrupt: result.interrupt ?? false
+      };
+    } catch (error) {
+      return {
+        behavior: "deny",
+        message: error instanceof Error ? error.message : "Callback error",
+        interrupt: false
+      };
+    }
+  }
+  if (isHeadlessAutoAllowTool(toolName)) {
+    return { behavior: "allow", updatedInput: null, updatedPermissions: [] };
+  }
+  return {
+    behavior: "deny",
+    message: "No canUseTool callback registered",
+    interrupt: false
+  };
+}
+function permissionSuggestionId(value) {
+  if (typeof value === "string")
+    return value;
+  if (!value || typeof value !== "object")
+    return null;
+  const record = value;
+  if (typeof record.id === "string")
+    return record.id;
+  if (typeof record.suggestion_id === "string")
+    return record.suggestion_id;
+  if (typeof record.permission_suggestion_id === "string")
+    return record.permission_suggestion_id;
+  return null;
+}
+function toAppServerApprovalDecision(decision) {
+  if (decision.behavior === "deny") {
+    return {
+      behavior: "deny",
+      message: decision.message
+    };
+  }
+  const selectedPermissionSuggestionIds = (decision.updatedPermissions ?? []).map(permissionSuggestionId).filter((id) => id !== null);
+  return {
+    behavior: "allow",
+    ...decision.message !== undefined ? { message: decision.message } : {},
+    updated_input: decision.updatedInput ?? null,
+    selected_permission_suggestion_ids: selectedPermissionSuggestionIds
+  };
+}
+function stringRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return;
+  const record = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (typeof entry === "string")
+      record[key] = entry;
+  }
+  return record;
+}
+function objectRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return;
+  return { ...value };
+}
+function normalizeListModelsResponse(response) {
+  if (!response.success) {
+    throw new Error(response.error ?? "listModels failed");
+  }
+  const entries = Array.isArray(response.entries) ? response.entries.flatMap((entry) => {
+    if (!entry || typeof entry !== "object")
+      return [];
+    const record = entry;
+    if (typeof record.id !== "string" || typeof record.handle !== "string" || typeof record.label !== "string" || typeof record.description !== "string") {
+      return [];
+    }
+    const updateArgs = objectRecord(record.updateArgs);
+    return [
+      {
+        id: record.id,
+        handle: record.handle,
+        label: record.label,
+        description: record.description,
+        ...typeof record.isDefault === "boolean" ? { isDefault: record.isDefault } : {},
+        ...typeof record.isFeatured === "boolean" ? { isFeatured: record.isFeatured } : {},
+        ...typeof record.free === "boolean" ? { free: record.free } : {},
+        ...updateArgs ? { updateArgs } : {}
+      }
+    ];
+  }) : [];
+  const result = { entries };
+  if (response.available_handles === null) {
+    result.availableHandles = null;
+  } else if (Array.isArray(response.available_handles)) {
+    result.availableHandles = response.available_handles.filter((handle) => typeof handle === "string");
+  }
+  const aliases = stringRecord(response.byok_provider_aliases);
+  if (aliases)
+    result.byokProviderAliases = aliases;
+  return result;
+}
+function normalizeUpdateModelResponse(response) {
+  if (!response.success) {
+    throw new Error(response.error ?? "Failed to update model");
+  }
+  const result = {};
+  if (response.applied_to === "agent" || response.applied_to === "conversation") {
+    result.appliedTo = response.applied_to;
+  }
+  if (typeof response.model_id === "string")
+    result.modelId = response.model_id;
+  if (typeof response.model_handle === "string")
+    result.modelHandle = response.model_handle;
+  if (response.model_settings === null) {
+    result.modelSettings = null;
+  } else if (response.model_settings && typeof response.model_settings === "object") {
+    result.modelSettings = { ...response.model_settings };
+  }
+  return result;
+}
+function runtimeScopeFromMessage(message) {
+  if (message.runtime)
+    return message.runtime;
+  const agentId = typeof message.agent_id === "string" ? message.agent_id : null;
+  const conversationId = typeof message.conversation_id === "string" ? message.conversation_id : null;
+  if (agentId && conversationId) {
+    return { agent_id: agentId, conversation_id: conversationId };
+  }
+  return null;
+}
+function registerAppServerControlRequestHandler(config) {
+  return config.client.onMessage((rawMessage, channel) => {
+    const message = rawMessage;
+    if (channel !== "control" || message.type !== "control_request")
+      return;
+    respondToAppServerControlRequest(config, message).catch(() => {});
+  });
+}
+async function respondToAppServerControlRequest(config, message) {
+  const runtime = runtimeScopeFromMessage(message) ?? config.getRuntime();
+  if (!runtime)
+    return;
+  const requestId = typeof message.request_id === "string" ? message.request_id : undefined;
+  const request = message.request;
+  if (!requestId || !request || typeof request !== "object")
+    return;
+  const requestRecord = request;
+  if (requestRecord.subtype !== "can_use_tool")
+    return;
+  const toolName = typeof requestRecord.tool_name === "string" ? requestRecord.tool_name : "unknown";
+  const toolInput = requestRecord.input && typeof requestRecord.input === "object" && !Array.isArray(requestRecord.input) ? requestRecord.input : {};
+  const decision = await resolveAppServerToolApproval(config.getOptions(), toolName, toolInput);
+  config.client.input({
+    runtime,
+    payload: {
+      kind: "approval_response",
+      request_id: requestId,
+      decision: toAppServerApprovalDecision(decision)
+    }
+  });
+}
+
+class AppServerRuntimeController {
+  client;
+  options;
+  constructor(client, options) {
+    this.client = client;
+    this.options = options;
+  }
+  onMessage(handler) {
+    return this.client.onMessage((message, channel) => {
+      handler(message, channel);
+    });
+  }
+  send(command) {
+    this.client.send(command);
+  }
+  sendTurnMessage(runtime, message, options) {
+    const payload = {
+      kind: "create_message",
+      messages: [
+        {
+          role: "user",
+          content: normalizeSendMessage(message),
+          client_message_id: options.clientMessageId
+        }
+      ]
+    };
+    this.client.input({
+      runtime,
+      payload
+    });
+  }
+  async abort(runtime) {
+    await this.client.abort({ runtime });
+  }
+  request(type, body, options = {}) {
+    const request = this.client.request.bind(this.client);
+    return request(type, body, options);
+  }
+  async listModels() {
+    const response = await this.request("list_models", {}, { predicate: (message) => message.type === "list_models_response" });
+    return normalizeListModelsResponse(response);
+  }
+  async updateModel(runtime, payload) {
+    const response = await this.request("update_model", {
+      runtime,
+      payload
+    }, { predicate: (message) => message.type === "update_model_response" });
+    return normalizeUpdateModelResponse(response);
+  }
+  async recoverPendingApprovals(runtime, options = {}) {
+    const response = await this.client.sync({
+      runtime,
+      recover_approvals: true,
+      force_device_status: true
+    }, options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {});
+    if (!response.success) {
+      return {
+        recovered: false,
+        unsupported: false,
+        detail: response.error ?? "Failed to recover pending approvals"
+      };
+    }
+    return { recovered: true, unsupported: false };
+  }
+  async listMessages(conversationId, options = {}) {
+    const query = {};
+    if (options.before !== undefined)
+      query.before = options.before;
+    if (options.after !== undefined)
+      query.after = options.after;
+    if (options.order !== undefined)
+      query.order = options.order;
+    if (options.limit !== undefined)
+      query.limit = options.limit;
+    const response = await this.request("conversation_messages_list", {
+      conversation_id: conversationId,
+      ...Object.keys(query).length > 0 ? { query } : {}
+    }, { predicate: (message) => message.type === "conversation_messages_list_response" });
+    if (!response.success) {
+      throw new Error(response.error ?? "listMessages failed");
+    }
+    const result = {
+      messages: response.messages ?? []
+    };
+    const nextBefore = typeof response.nextBefore === "string" || response.nextBefore === null ? response.nextBefore : typeof response.next_before === "string" || response.next_before === null ? response.next_before : undefined;
+    if (nextBefore !== undefined)
+      result.nextBefore = nextBefore;
+    const hasMore = typeof response.hasMore === "boolean" ? response.hasMore : typeof response.has_more === "boolean" ? response.has_more : undefined;
+    if (hasMore !== undefined)
+      result.hasMore = hasMore;
+    return result;
+  }
+  close() {
+    this.client.close();
+  }
+}
+
+class AppServerSession extends RemoteClientSessionCore {
+  remoteOptions;
+  ownedAppServer = null;
+  externalTools = new Map;
+  removeExternalToolHandler = null;
+  removeControlRequestHandler = null;
+  constructor(remoteOptions, mode) {
+    super(mode, {
+      label: "app-server",
+      requestTimeoutMs: remoteOptions.requestTimeoutMs
+    });
+    this.remoteOptions = remoteOptions;
+    const tools = mode.options.tools;
+    for (const tool of tools ?? []) {
+      this.externalTools.set(tool.name, tool);
+    }
+  }
+  shouldEnableMemfs(options) {
+    return this.mode.kind === "create-agent";
+  }
+  async initializeRuntimeController() {
+    const url = await this.resolveAppServerUrl();
+    const client = createAppServerClient({
+      url,
+      ...this.remoteOptions.authToken !== undefined ? { authToken: this.remoteOptions.authToken } : {},
+      ...this.remoteOptions.WebSocket ? { WebSocket: this.remoteOptions.WebSocket } : {},
+      ...this.remoteOptions.requestTimeoutMs !== undefined ? { requestTimeoutMs: this.remoteOptions.requestTimeoutMs } : {}
+    });
+    this.removeControlRequestHandler = registerAppServerControlRequestHandler({
+      client,
+      getRuntime: () => this.runtime,
+      getOptions: () => this.currentOptions()
+    });
+    if (this.externalTools.size > 0) {
+      this.removeExternalToolHandler = client.onExternalToolCall(createExternalToolCallHandler(this.externalTools));
+    }
+    try {
+      await client.connect();
+      const response = await this.startRuntime(client);
+      if (!response.success || !response.runtime) {
+        throw new Error(response.error ?? "Failed to start app-server runtime");
+      }
+      const tools = agentToolNames(response.agent);
+      return {
+        controller: new AppServerRuntimeController(client, this.remoteOptions),
+        runtime: response.runtime,
+        model: typeof response.agent?.model === "string" ? response.agent.model : "",
+        modelSettings: response.agent?.model_settings ?? null,
+        ...tools !== undefined ? { tools } : {}
+      };
+    } catch (error) {
+      this.removeExternalToolHandler?.();
+      this.removeExternalToolHandler = null;
+      this.removeControlRequestHandler?.();
+      this.removeControlRequestHandler = null;
+      client.close();
+      throw error;
+    }
+  }
+  onCoreClose() {
+    this.removeExternalToolHandler?.();
+    this.removeExternalToolHandler = null;
+    this.removeControlRequestHandler?.();
+    this.removeControlRequestHandler = null;
+    this.ownedAppServer?.close();
+    this.ownedAppServer = null;
+  }
+  async resolveAppServerUrl() {
+    if (this.remoteOptions.url) {
+      return this.remoteOptions.url;
+    }
+    if (this.remoteOptions.local !== true) {
+      throw new Error("App-server session requires a url unless local app-server spawning is enabled.");
+    }
+    this.ownedAppServer = await startLocalAppServer({
+      listen: this.remoteOptions.localListen,
+      backend: this.remoteOptions.localBackend,
+      startupTimeoutMs: this.remoteOptions.localStartupTimeoutMs,
+      env: this.remoteOptions.localEnv
+    });
+    return this.ownedAppServer.url;
+  }
+  async startRuntime(client) {
+    const command = await this.buildRuntimeStartCommand(client);
+    const response = await client.runtimeStart(command);
+    return response;
+  }
+  async buildRuntimeStartCommand(client) {
+    const options = this.mode.options;
+    const command = {
+      client_info: {
+        name: "@letta-ai/letta-agent-sdk",
+        title: "Letta Agent SDK"
+      },
+      recover_approvals: false,
+      force_device_status: true
+    };
+    const mode = mapPermissionMode(options.permissionMode);
+    if (mode)
+      command.mode = mode;
+    if (options.cwd !== undefined)
+      command.cwd = options.cwd;
+    const groups = externalToolGroups(options.tools);
+    if (groups)
+      command.external_tools = groups;
+    if (this.mode.kind === "create-agent") {
+      command.create_agent = {
+        body: createAgentBody(this.mode.options, {
+          includeSdkOriginTag: this.remoteOptions.includeSdkOriginTag
+        }),
+        pin_global: this.remoteOptions.pinGlobalAgent ?? true
+      };
+      return command;
+    }
+    if (this.mode.agentId) {
+      command.agent_id = this.mode.agentId;
+      if (this.mode.newConversation) {
+        command.create_conversation = { body: {} };
+      } else if (this.mode.defaultConversation) {
+        command.conversation_id = "default";
+      }
+      return command;
+    }
+    if (this.mode.conversationId) {
+      const agentId = await this.resolveConversationAgentId(client, this.mode.conversationId);
+      command.agent_id = agentId;
+      command.conversation_id = this.mode.conversationId;
+      return command;
+    }
+    throw new Error("App-server createSession() requires an agent id. Call createAgent() first or pass an agent id.");
+  }
+  async resolveConversationAgentId(client, conversationId) {
+    const request = client.request.bind(client);
+    const response = await request("conversation_retrieve", { conversation_id: conversationId }, { predicate: (message) => message.type === "conversation_retrieve_response" });
+    if (!response.success || !response.conversation?.agent_id) {
+      throw new Error(response.error ?? `Failed to retrieve conversation ${conversationId}`);
+    }
+    return response.conversation.agent_id;
+  }
+}
+
+// src/remote.ts
+function getDefaultApiKey() {
+  if (typeof process === "undefined") {
+    return;
+  }
+  return process.env.LETTA_API_KEY;
+}
+function createHeaders(options) {
+  const apiKey = options.apiKey ?? getDefaultApiKey();
+  return {
+    ...apiKey ? { Authorization: `Bearer ${apiKey}` } : {},
+    ...options.headers ?? {}
+  };
+}
+function getFetch(options) {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  if (!fetchImpl) {
+    throw new Error("Remote environments require a fetch implementation");
+  }
+  return fetchImpl.bind(globalThis);
+}
+function normalizeBaseUrl2(baseUrl) {
+  return (baseUrl ?? "https://api.letta.com").replace(/\/$/, "");
+}
+function ensureOnline(environment, target) {
+  if (!environment.connectionId) {
+    const label = "deviceId" in target ? target.deviceId : ("environmentId" in target) ? target.environmentId : ("connectionName" in target) ? target.connectionName : environment.deviceId;
+    throw new Error(`Remote environment is offline: ${label}`);
+  }
+  return {
+    connectionId: environment.connectionId,
+    environment,
+    target
+  };
+}
+async function parseJsonResponse(response) {
+  const text = await response.text();
+  const body = text ? JSON.parse(text) : null;
+  if (!response.ok) {
+    const message = body && typeof body === "object" && "message" in body ? String(body.message) : response.statusText;
+    throw new Error(`Letta API request failed (${response.status}): ${message}`);
+  }
+  return body;
+}
+
+class RemoteEnvironmentClient {
+  options;
+  baseUrl;
+  fetchImpl;
+  constructor(options = {}) {
+    this.options = options;
+    this.baseUrl = normalizeBaseUrl2(options.baseUrl);
+    this.fetchImpl = getFetch(options);
+  }
+  async listEnvironments() {
+    const url = new URL(`${this.baseUrl}/v1/environments`);
+    const response = await this.fetchImpl(url, {
+      headers: createHeaders(this.options)
+    });
+    return parseJsonResponse(response);
+  }
+  async getEnvironmentByDeviceId(deviceId) {
+    const response = await this.fetchImpl(`${this.baseUrl}/v1/environments/${encodeURIComponent(deviceId)}`, { headers: createHeaders(this.options) });
+    return parseJsonResponse(response);
+  }
+  async resolveEnvironment(target) {
+    if ("connectionId" in target) {
+      return { connectionId: target.connectionId, target };
+    }
+    if ("deviceId" in target) {
+      return ensureOnline(await this.getEnvironmentByDeviceId(target.deviceId), target);
+    }
+    const { connections } = await this.listEnvironments();
+    if ("environmentId" in target) {
+      const match2 = connections.find((env) => env.id === target.environmentId);
+      if (!match2) {
+        throw new Error(`Remote environment not found: ${target.environmentId}`);
+      }
+      return ensureOnline(match2, target);
+    }
+    const matches = connections.filter((env) => env.connectionName === target.connectionName);
+    if (matches.length === 0) {
+      throw new Error(`Remote environment not found: ${target.connectionName}`);
+    }
+    if (matches.length > 1) {
+      throw new Error(`Remote environment name is ambiguous: ${target.connectionName}`);
+    }
+    const match = matches[0];
+    if (!match) {
+      throw new Error(`Remote environment not found: ${target.connectionName}`);
+    }
+    return ensureOnline(match, target);
+  }
+}
+
+// src/cloud-session.ts
+var DEFAULT_CLOUD_API_BASE_URL = "https://api.letta.com";
+var DEFAULT_TURN_TIMEOUT_MS = 120000;
+var DEFAULT_PING_INTERVAL_MS = 30000;
+var DEFAULT_SANDBOX_TTL_MINUTES = 5;
+var MIN_SANDBOX_TTL_MINUTES = 1;
+var MAX_SANDBOX_TTL_MINUTES = 60;
+var DEFAULT_SANDBOX_READY_TIMEOUT_MS = 120000;
+var DEFAULT_SANDBOX_READY_POLL_INTERVAL_MS = 1000;
+var SDK_AGENT_ORIGIN = "@letta-ai/letta-agent-sdk";
+
+class CloudManagedSandboxOwnershipError extends Error {
+}
+function getDefaultApiKey2() {
+  const env = globalThis.process?.env;
+  return env?.LETTA_API_KEY ?? env?.LETTA_CLOUD_API_KEY;
+}
+function bearerTokenFromHeaders(headers) {
+  const authorization = headers?.Authorization ?? headers?.authorization;
+  if (!authorization)
+    return;
+  const match = /^Bearer\s+(.+)$/i.exec(authorization);
+  return match?.[1];
+}
+function getCloudApiKey(options) {
+  return options.apiKey ?? bearerTokenFromHeaders(options.headers) ?? getDefaultApiKey2();
+}
+function getFetch2(fetchOverride) {
+  const resolved = fetchOverride ?? globalThis.fetch;
+  if (!resolved) {
+    throw new Error("No fetch implementation available for cloud backend.");
+  }
+  return resolved.bind(globalThis);
+}
+function getWebSocketConstructor(websocketOverride) {
+  const resolved = websocketOverride ?? globalThis.WebSocket;
+  if (!resolved) {
+    throw new Error("No WebSocket implementation available for cloud backend.");
+  }
+  return resolved;
+}
+function normalizeCloudApiBaseUrl(url) {
+  const parsed = new URL(url ?? DEFAULT_CLOUD_API_BASE_URL);
+  parsed.pathname = parsed.pathname.replace(/\/+$/, "");
+  parsed.search = "";
+  parsed.hash = "";
+  return parsed.toString().replace(/\/$/, "");
+}
+function cloudHeaders(options) {
+  const headers = {
+    "Content-Type": "application/json",
+    ...options.headers ?? {}
+  };
+  const apiKey = getCloudApiKey(options);
+  if (apiKey && !headers.Authorization && !headers.authorization) {
+    headers.Authorization = `Bearer ${apiKey}`;
+  }
+  return headers;
+}
+function cloudWebSocketHeaders(options) {
+  const headers = { ...options.headers ?? {} };
+  delete headers.authorization;
+  delete headers.Authorization;
+  const apiKey = getCloudApiKey(options);
+  if (apiKey)
+    headers.Authorization = `Bearer ${apiKey}`;
+  return Object.keys(headers).length > 0 ? headers : undefined;
+}
+async function parseJsonResponse2(response) {
+  const text = await response.text();
+  if (!text)
+    return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+function responseErrorMessage(body, fallback) {
+  if (body && typeof body === "object") {
+    const record = body;
+    const message = record.message ?? record.error ?? record.detail;
+    const reasonText = record.reason_text;
+    const pieces = [message, reasonText].filter((value) => typeof value === "string" && value.length > 0);
+    if (pieces.length > 0)
+      return pieces.join(": ");
+  }
+  return fallback;
+}
+function assertOkResponse(response, body, action) {
+  if (!response.ok) {
+    throw new Error(responseErrorMessage(body, `${action} failed with HTTP ${response.status}`));
+  }
+}
+function validatePositiveInteger(value, name) {
+  if (value !== undefined && (!Number.isInteger(value) || value <= 0)) {
+    throw new Error(`Invalid ${name}. Expected a positive integer.`);
+  }
+}
+function validateIntegerRange(value, name, min, max) {
+  if (value === undefined)
+    return;
+  if (!Number.isInteger(value) || value < min || value > max) {
+    throw new Error(`Invalid ${name}. Expected an integer between ${min} and ${max}.`);
+  }
+}
+function validateCloudSandboxOptions(options, name) {
+  if (options === undefined)
+    return;
+  if (options === null || typeof options !== "object" || Array.isArray(options)) {
+    throw new Error(`Invalid ${name}. Expected an object.`);
+  }
+  validateIntegerRange(options.ttlMinutes, `${name}.ttlMinutes`, MIN_SANDBOX_TTL_MINUTES, MAX_SANDBOX_TTL_MINUTES);
+  validatePositiveInteger(options.readyTimeoutMs, `${name}.readyTimeoutMs`);
+  validatePositiveInteger(options.readyPollIntervalMs, `${name}.readyPollIntervalMs`);
+  validatePositiveInteger(options.refreshIntervalMs, `${name}.refreshIntervalMs`);
+  if (options.terminateOnClose !== undefined && typeof options.terminateOnClose !== "boolean") {
+    throw new Error(`Invalid ${name}.terminateOnClose. Expected a boolean.`);
+  }
+}
+function validateCloudClientOptions(options) {
+  validatePositiveInteger(options.requestTimeoutMs, "requestTimeoutMs");
+  validatePositiveInteger(options.appServer?.requestTimeoutMs, "appServer.requestTimeoutMs");
+  validatePositiveInteger(options.appServer?.startupTimeoutMs, "appServer.startupTimeoutMs");
+  validateCloudSandboxOptions(options.sandbox, "sandbox");
+  if (options.environment !== undefined && options.sandbox !== undefined) {
+    throw new Error("Constellation sessions cannot specify both environment and sandbox options.");
+  }
+  if (options.webSocketAuth !== undefined && options.webSocketAuth !== "header" && options.webSocketAuth !== "query") {
+    throw new Error("Invalid webSocketAuth. Valid values: header, query.");
+  }
+}
+function environmentToRemoteTarget(environment) {
+  if (typeof environment === "string") {
+    return { connectionName: environment };
+  }
+  if ("name" in environment) {
+    return { connectionName: environment.name };
+  }
+  if ("id" in environment) {
+    return { environmentId: environment.id };
+  }
+  if ("connectionId" in environment) {
+    return { connectionId: environment.connectionId };
+  }
+  if ("deviceId" in environment) {
+    return { deviceId: environment.deviceId };
+  }
+  throw new Error("Unknown cloud environment selector.");
+}
+function buildCloudStatusWebSocketUrl(params) {
+  const base = new URL(normalizeCloudApiBaseUrl(params.apiBaseUrl));
+  if (base.protocol === "http:") {
+    base.protocol = "ws:";
+  } else if (base.protocol === "https:") {
+    base.protocol = "wss:";
+  } else if (base.protocol !== "ws:" && base.protocol !== "wss:") {
+    throw new Error(`Unsupported cloud apiBaseUrl protocol: ${base.protocol}`);
+  }
+  base.pathname = `/v1/environments/${encodeURIComponent(params.connectionId)}/status/ws`;
+  base.searchParams.set("agentId", params.agentId);
+  base.searchParams.set("conversationId", params.conversationId);
+  base.searchParams.set("channel", "stream");
+  if (params.authMode === "query" && params.apiKey) {
+    base.searchParams.set("token", params.apiKey);
+  }
+  return base.toString();
+}
+function addSocketListener(socket, type, listener) {
+  if (socket.addEventListener) {
+    socket.addEventListener(type, listener);
+    return () => socket.removeEventListener?.(type, listener);
+  }
+  if (socket.on) {
+    socket.on(type, listener);
+    return () => socket.off?.(type, listener);
+  }
+  throw new Error("WebSocket implementation does not support event listeners.");
+}
+function messageEventData(event) {
+  if (typeof event === "string")
+    return event;
+  if (event && typeof event === "object") {
+    const data = event.data;
+    if (typeof data === "string")
+      return data;
+    if (data instanceof ArrayBuffer) {
+      return new TextDecoder().decode(data);
+    }
+    if (data instanceof Uint8Array) {
+      return new TextDecoder().decode(data);
+    }
+  }
+  return null;
+}
+function createCloudStatusWebSocketConstructor(params) {
+  const WebSocketCtor = getWebSocketConstructor(params.cloudOptions.WebSocket);
+  const authMode = params.cloudOptions.webSocketAuth ?? "header";
+  const cloudHeaders2 = authMode === "header" ? cloudWebSocketHeaders(params.cloudOptions) : undefined;
+  const pingIntervalMs = params.cloudOptions.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS;
+  const state = {
+    runtime: params.runtime,
+    seenIdempotencyKeys: new Set,
+    seenIdempotencyOrder: [],
+    lastEventSeq: null,
+    controlSocket: null
+  };
+
+  class CloudStatusSocketAdapter {
+    socket;
+    channel;
+    listenerRemovers = new Map;
+    pingTimer = null;
+    removeCloseListener = null;
+    constructor(url, options) {
+      this.channel = new URL(url).searchParams.get("channel");
+      const mergedHeaders = authMode === "header" ? {
+        ...options?.headers ?? {},
+        ...cloudHeaders2 ?? {}
+      } : undefined;
+      const socketOptions = mergedHeaders && Object.keys(mergedHeaders).length > 0 ? { headers: mergedHeaders } : undefined;
+      this.socket = new WebSocketCtor(url, socketOptions);
+      if (this.channel === "control") {
+        state.controlSocket = this;
+      }
+      this.removeCloseListener = addSocketListener(this.socket, "close", () => {
+        this.stopPing();
+        if (state.controlSocket === this)
+          state.controlSocket = null;
+      });
+      this.startPing(pingIntervalMs);
+    }
+    get readyState() {
+      return this.socket.readyState;
+    }
+    send(data) {
+      this.socket.send(data);
+    }
+    close() {
+      this.stopPing();
+      this.removeCloseListener?.();
+      this.removeCloseListener = null;
+      if (state.controlSocket === this)
+        state.controlSocket = null;
+      this.socket.close();
+    }
+    addEventListener(type, listener) {
+      const wrapped = type === "message" ? (event) => {
+        if (this.handleIncomingMessage(event)) {
+          listener(event);
+        }
+      } : listener;
+      const remove = addSocketListener(this.socket, type, wrapped);
+      let typeRemovers = this.listenerRemovers.get(type);
+      if (!typeRemovers) {
+        typeRemovers = new Map;
+        this.listenerRemovers.set(type, typeRemovers);
+      }
+      typeRemovers.set(listener, remove);
+    }
+    removeEventListener(type, listener) {
+      const typeRemovers = this.listenerRemovers.get(type);
+      const remove = typeRemovers?.get(listener);
+      if (!remove)
+        return;
+      remove();
+      typeRemovers?.delete(listener);
+      if (typeRemovers?.size === 0) {
+        this.listenerRemovers.delete(type);
+      }
+    }
+    handleIncomingMessage(event) {
+      const data = messageEventData(event);
+      if (!data)
+        return true;
+      let message;
+      try {
+        message = JSON.parse(data);
+      } catch {
+        return true;
+      }
+      this.ackIfSequenced(message);
+      if (this.channel === "control" && message.type === "stream_delta") {
+        return false;
+      }
+      if (this.isDuplicate(message))
+        return false;
+      this.trackEventSeq(message);
+      return true;
+    }
+    ackIfSequenced(message) {
+      if (typeof message.seq !== "number")
+        return;
+      this.sendCloudCommand({ type: "ack", seq: message.seq });
+    }
+    isDuplicate(message) {
+      const idempotencyKey = typeof message.idempotency_key === "string" ? message.idempotency_key : undefined;
+      if (!idempotencyKey)
+        return false;
+      if (state.seenIdempotencyKeys.has(idempotencyKey))
+        return true;
+      state.seenIdempotencyKeys.add(idempotencyKey);
+      state.seenIdempotencyOrder.push(idempotencyKey);
+      while (state.seenIdempotencyOrder.length > 1000) {
+        const oldest = state.seenIdempotencyOrder.shift();
+        if (oldest)
+          state.seenIdempotencyKeys.delete(oldest);
+      }
+      return false;
+    }
+    trackEventSeq(message) {
+      if (typeof message.event_seq !== "number")
+        return;
+      if (state.lastEventSeq !== null && message.event_seq > state.lastEventSeq + 1) {
+        this.sendSync(true);
+      }
+      if (state.lastEventSeq === null || message.event_seq > state.lastEventSeq) {
+        state.lastEventSeq = message.event_seq;
+      }
+    }
+    sendSync(recoverApprovals) {
+      const target = state.controlSocket?.readyState === 1 ? state.controlSocket : this;
+      target.sendCloudCommand({
+        type: "sync",
+        runtime: state.runtime,
+        recover_approvals: recoverApprovals,
+        force_device_status: true
+      });
+    }
+    sendCloudCommand(command) {
+      if (this.readyState !== 1)
+        return;
+      try {
+        this.socket.send(JSON.stringify(command));
+      } catch {}
+    }
+    startPing(intervalMs) {
+      if (this.pingTimer)
+        return;
+      this.pingTimer = setInterval(() => {
+        this.sendCloudCommand({ type: "ping" });
+      }, intervalMs);
+      this.pingTimer.unref?.();
+    }
+    stopPing() {
+      if (!this.pingTimer)
+        return;
+      clearInterval(this.pingTimer);
+      this.pingTimer = null;
+    }
+  }
+  return CloudStatusSocketAdapter;
+}
+function isCloudConversation(value) {
+  return Boolean(value && typeof value === "object" && typeof value.id === "string");
+}
+function isCloudAgentSandbox(value) {
+  return Boolean(value && typeof value === "object" && typeof value.sandboxId === "string" && typeof value.deviceId === "string" && typeof value.connectionName === "string");
+}
+function isCloudAgentSandboxRefresh(value) {
+  return Boolean(value && typeof value === "object" && typeof value.success === "boolean" && typeof value.sandboxId === "string" && typeof value.ttlMinutes === "number");
+}
+function isRetryableManagedSandboxResolveError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes("Remote environment is offline") || message.toLowerCase().includes("not found") || message.includes("(404)");
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function externalToolsByName(tools) {
+  const result = new Map;
+  for (const tool of tools ?? []) {
+    result.set(tool.name, tool);
+  }
+  return result;
+}
+function cloudHarnessAppServerOptions(clientOptions) {
+  const appServer = clientOptions.appServer;
+  const apiKey = getCloudApiKey(clientOptions);
+  const localEnv = {
+    ...apiKey ? { LETTA_API_KEY: apiKey } : {},
+    ...clientOptions.apiBaseUrl ? { LETTA_BASE_URL: normalizeCloudApiBaseUrl(clientOptions.apiBaseUrl) } : {}
+  };
+  return {
+    local: appServer?.url === undefined,
+    localBackend: "api",
+    ...appServer?.url !== undefined ? { url: appServer.url } : {},
+    ...appServer?.WebSocket !== undefined ? { WebSocket: appServer.WebSocket } : {},
+    ...clientOptions.requestTimeoutMs !== undefined || appServer?.requestTimeoutMs !== undefined ? { requestTimeoutMs: appServer?.requestTimeoutMs ?? clientOptions.requestTimeoutMs } : {},
+    ...appServer?.listen !== undefined ? { localListen: appServer.listen } : {},
+    ...appServer?.startupTimeoutMs !== undefined ? { localStartupTimeoutMs: appServer.startupTimeoutMs } : {},
+    ...Object.keys(localEnv).length > 0 ? { localEnv } : {}
+  };
+}
+async function createCloudAgent(clientOptions, agentOptions) {
+  const session = new AppServerSession(cloudHarnessAppServerOptions(clientOptions), {
+    kind: "create-agent",
+    options: agentOptions
+  });
+  const initMsg = await session.initialize();
+  session.close();
+  return initMsg.agentId;
+}
+function assertCloudSessionOptionsSupported(action, options) {
+  validateCloudSandboxOptions(options.sandbox, "sandbox");
+  if (options.environment !== undefined && options.sandbox !== undefined) {
+    throw new Error(`Constellation ${action}() cannot specify both environment and sandbox options.`);
+  }
+  if (options.systemPrompt !== undefined) {
+    throw new Error(`Constellation ${action}() cannot rewrite an existing agent's systemPrompt from the SDK adapter yet.`);
+  }
+  if (options.allowedTools !== undefined || options.disallowedTools !== undefined) {
+    throw new Error(`Constellation ${action}() has not wired allowedTools/disallowedTools to the remote device protocol yet.`);
+  }
+  if (options.skillSources !== undefined) {
+    throw new Error(`Constellation ${action}() has not wired skillSources to the remote device protocol yet.`);
+  }
+  if (options.systemInfoReminder !== undefined) {
+    throw new Error(`Constellation ${action}() has not wired systemInfoReminder to the remote device protocol yet.`);
+  }
+  if (options.dreaming?.behavior !== undefined) {
+    throw new Error(`Constellation ${action}() does not yet support dreaming.behavior overrides.`);
+  }
+  if (options.memfsStartup !== undefined) {
+    throw new Error(`Constellation ${action}() does not support memfsStartup.`);
+  }
+  if (options.includePartialMessages !== undefined) {
+    throw new Error(`Constellation ${action}() streams Remote Client deltas directly; includePartialMessages is not a separate toggle.`);
+  }
+}
+
+class CloudEnvironmentSession extends RemoteClientSessionCore {
+  cloudOptions;
+  connectionId = null;
+  removeExternalToolHandler = null;
+  removeControlRequestHandler = null;
+  externalTools = new Map;
+  managedSandbox = null;
+  sandboxRefreshTimer = null;
+  sandboxRefreshInFlight = null;
+  cloudMode;
+  constructor(cloudOptions, mode) {
+    super(mode, {
+      label: "cloud",
+      requestTimeoutMs: cloudOptions.requestTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS
+    });
+    this.cloudOptions = cloudOptions;
+    this.cloudMode = mode;
+    const tools = mode.options.tools;
+    this.externalTools = externalToolsByName(tools);
+  }
+  async initializeRuntimeController() {
+    const resolved = await this.resolveRuntime();
+    const connection = await this.resolveConnectionForRuntime(resolved.runtime);
+    this.connectionId = connection.connectionId;
+    const apiKey = getCloudApiKey(this.cloudOptions);
+    const url = buildCloudStatusWebSocketUrl({
+      apiBaseUrl: this.cloudOptions.apiBaseUrl,
+      connectionId: connection.connectionId,
+      agentId: resolved.runtime.agent_id,
+      conversationId: resolved.runtime.conversation_id,
+      apiKey,
+      authMode: this.cloudOptions.webSocketAuth ?? "header"
+    });
+    const client = createAppServerClient({
+      url,
+      WebSocket: createCloudStatusWebSocketConstructor({
+        cloudOptions: this.cloudOptions,
+        runtime: resolved.runtime
+      }),
+      requestTimeoutMs: this.cloudOptions.requestTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS
+    });
+    this.removeControlRequestHandler = registerAppServerControlRequestHandler({
+      client,
+      getRuntime: () => this.runtime,
+      getOptions: () => this.currentOptions()
+    });
+    if (this.externalTools.size > 0) {
+      this.removeExternalToolHandler = client.onExternalToolCall(createExternalToolCallHandler(this.externalTools));
+    }
+    try {
+      await client.connect();
+      const response = await this.startCloudRuntime(client, resolved.runtime);
+      if (!response.success || !response.runtime) {
+        throw new Error(response.error ?? "Failed to start Cloud status runtime");
+      }
+      const tools = agentToolNames(response.agent);
+      return {
+        controller: new AppServerRuntimeController(client, {
+          requestTimeoutMs: this.cloudOptions.requestTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS
+        }),
+        runtime: response.runtime,
+        model: typeof response.agent?.model === "string" ? response.agent.model : "",
+        modelSettings: response.agent?.model_settings ?? null,
+        ...tools !== undefined ? { tools } : {}
+      };
+    } catch (error) {
+      this.removeExternalToolHandler?.();
+      this.removeExternalToolHandler = null;
+      this.removeControlRequestHandler?.();
+      this.removeControlRequestHandler = null;
+      client.close();
+      await this.cleanupManagedSandbox();
+      throw error;
+    }
+  }
+  async startCloudRuntime(client, runtime) {
+    const options = this.currentOptions();
+    const command = {
+      client_info: {
+        name: SDK_AGENT_ORIGIN,
+        title: "Letta Agent SDK"
+      },
+      agent_id: runtime.agent_id,
+      conversation_id: runtime.conversation_id,
+      recover_approvals: false,
+      force_device_status: true
+    };
+    const mode = mapPermissionMode(options.permissionMode);
+    if (mode)
+      command.mode = mode;
+    if (options.cwd !== undefined)
+      command.cwd = options.cwd;
+    const groups = externalToolGroups(options.tools);
+    if (groups)
+      command.external_tools = groups;
+    return await client.runtimeStart(command);
+  }
+  async afterRuntimeInitialized() {
+    if (!this.controller || !this.runtime)
+      return;
+    this.controller.send({
+      type: "sync",
+      runtime: this.runtime,
+      recover_approvals: true,
+      force_device_status: true
+    });
+  }
+  async beforeTurn() {
+    const sandbox = this.managedSandbox;
+    if (!sandbox)
+      return;
+    await this.refreshManagedSandbox(sandbox);
+  }
+  onCoreClose() {
+    this.removeExternalToolHandler?.();
+    this.removeExternalToolHandler = null;
+    this.removeControlRequestHandler?.();
+    this.removeControlRequestHandler = null;
+    this.cleanupManagedSandbox();
+  }
+  async resolveRuntime() {
+    let agentId = this.cloudMode.agentId;
+    let conversationId = this.cloudMode.conversationId;
+    if (agentId && this.cloudMode.newConversation) {
+      const conversation = await this.createConversation(agentId);
+      conversationId = conversation.id;
+    } else if (agentId && this.cloudMode.defaultConversation) {
+      conversationId = "default";
+    }
+    if (!agentId && conversationId) {
+      const conversation = await this.retrieveConversation(conversationId);
+      if (!conversation.agent_id) {
+        throw new Error(`Cloud conversation ${conversationId} did not include an agent id.`);
+      }
+      agentId = conversation.agent_id;
+    }
+    if (!agentId || !conversationId) {
+      throw new Error("Constellation createSession()/resumeSession() requires an agent id or conversation id.");
+    }
+    return { runtime: { agent_id: agentId, conversation_id: conversationId } };
+  }
+  async createConversation(agentId) {
+    const fetchImpl = getFetch2(this.cloudOptions.fetch);
+    const baseUrl = normalizeCloudApiBaseUrl(this.cloudOptions.apiBaseUrl);
+    const url = new URL(`${baseUrl}/v1/conversations/`);
+    url.searchParams.set("agent_id", agentId);
+    const response = await fetchImpl(url, {
+      method: "POST",
+      headers: cloudHeaders(this.cloudOptions),
+      body: JSON.stringify({})
+    });
+    const body = await parseJsonResponse2(response);
+    assertOkResponse(response, body, "Cloud createSession()");
+    if (!isCloudConversation(body)) {
+      throw new Error("Cloud createSession() response did not include a conversation id.");
+    }
+    return { id: body.id, agent_id: body.agent_id };
+  }
+  async retrieveConversation(conversationId) {
+    const fetchImpl = getFetch2(this.cloudOptions.fetch);
+    const baseUrl = normalizeCloudApiBaseUrl(this.cloudOptions.apiBaseUrl);
+    const response = await fetchImpl(`${baseUrl}/v1/conversations/${encodeURIComponent(conversationId)}`, { headers: cloudHeaders(this.cloudOptions) });
+    const body = await parseJsonResponse2(response);
+    assertOkResponse(response, body, "Cloud resumeSession()");
+    if (!isCloudConversation(body)) {
+      throw new Error(`Cloud resumeSession() could not retrieve conversation ${conversationId}.`);
+    }
+    return { id: body.id, agent_id: body.agent_id };
+  }
+  async resolveConnectionForRuntime(runtime) {
+    const environment = this.effectiveEnvironment();
+    const sandboxOptions = this.effectiveSandboxOptions();
+    if (environment !== undefined) {
+      if (sandboxOptions !== undefined) {
+        throw new Error("Constellation sessions cannot specify both environment and sandbox options.");
+      }
+      return this.resolveExplicitConnection(environment);
+    }
+    return this.createManagedSandboxConnection(runtime);
+  }
+  async resolveExplicitConnection(environment) {
+    const target = environmentToRemoteTarget(environment);
+    const resolved = await this.remoteEnvironmentClient().resolveEnvironment(target);
+    return { connectionId: resolved.connectionId };
+  }
+  async createManagedSandboxConnection(runtime) {
+    const sandbox = await this.createManagedSandbox(runtime.agent_id);
+    this.managedSandbox = sandbox;
+    try {
+      await this.refreshManagedSandbox(sandbox);
+      const connection = await this.waitForManagedSandboxConnection(sandbox);
+      this.startManagedSandboxRefresh(sandbox);
+      return { connectionId: connection.connectionId };
+    } catch (error) {
+      await this.cleanupManagedSandbox();
+      throw error;
+    }
+  }
+  async createManagedSandbox(agentId) {
+    const fetchImpl = getFetch2(this.cloudOptions.fetch);
+    const baseUrl = normalizeCloudApiBaseUrl(this.cloudOptions.apiBaseUrl);
+    const response = await fetchImpl(`${baseUrl}/v1/agents/${encodeURIComponent(agentId)}/sandboxes`, {
+      method: "POST",
+      headers: cloudHeaders(this.cloudOptions),
+      body: JSON.stringify({})
+    });
+    const body = await parseJsonResponse2(response);
+    assertOkResponse(response, body, "Cloud create managed sandbox");
+    if (!isCloudAgentSandbox(body)) {
+      throw new Error("Cloud create managed sandbox response did not include sandbox connection details.");
+    }
+    const sandboxOptions = this.resolvedSandboxOptions();
+    const ttlMinutes = sandboxOptions.ttlMinutes ?? DEFAULT_SANDBOX_TTL_MINUTES;
+    const readyTimeoutMs = sandboxOptions.readyTimeoutMs ?? DEFAULT_SANDBOX_READY_TIMEOUT_MS;
+    const readyPollIntervalMs = sandboxOptions.readyPollIntervalMs ?? DEFAULT_SANDBOX_READY_POLL_INTERVAL_MS;
+    const defaultRefreshIntervalMs = Math.max(1000, Math.floor(ttlMinutes * 60000 * 0.8));
+    return {
+      agentId,
+      sandboxId: body.sandboxId,
+      deviceId: body.deviceId,
+      connectionName: body.connectionName,
+      ttlMinutes,
+      readyTimeoutMs,
+      readyPollIntervalMs,
+      refreshIntervalMs: sandboxOptions.refreshIntervalMs ?? defaultRefreshIntervalMs,
+      terminateOnClose: sandboxOptions.terminateOnClose ?? true
+    };
+  }
+  async refreshManagedSandbox(sandbox) {
+    if (this.sandboxRefreshInFlight) {
+      await this.sandboxRefreshInFlight;
+      return;
+    }
+    this.sandboxRefreshInFlight = this.refreshManagedSandboxOnce(sandbox);
+    try {
+      await this.sandboxRefreshInFlight;
+    } finally {
+      this.sandboxRefreshInFlight = null;
+    }
+  }
+  async refreshManagedSandboxOnce(sandbox) {
+    const fetchImpl = getFetch2(this.cloudOptions.fetch);
+    const baseUrl = normalizeCloudApiBaseUrl(this.cloudOptions.apiBaseUrl);
+    const response = await fetchImpl(`${baseUrl}/v1/agents/${encodeURIComponent(sandbox.agentId)}/sandboxes/refresh`, {
+      method: "POST",
+      headers: cloudHeaders(this.cloudOptions),
+      body: JSON.stringify({ ttlMinutes: sandbox.ttlMinutes })
+    });
+    const body = await parseJsonResponse2(response);
+    assertOkResponse(response, body, "Cloud refresh managed sandbox");
+    if (!isCloudAgentSandboxRefresh(body) || !body.success) {
+      throw new Error("Cloud refresh managed sandbox response did not confirm refresh.");
+    }
+    if (body.sandboxId !== sandbox.sandboxId) {
+      throw new CloudManagedSandboxOwnershipError(`Cloud managed sandbox ownership changed for agent ${sandbox.agentId}: expected ${sandbox.sandboxId}, got ${body.sandboxId}.`);
+    }
+  }
+  async terminateManagedSandbox(sandbox) {
+    await this.refreshManagedSandbox(sandbox);
+    const fetchImpl = getFetch2(this.cloudOptions.fetch);
+    const baseUrl = normalizeCloudApiBaseUrl(this.cloudOptions.apiBaseUrl);
+    const response = await fetchImpl(`${baseUrl}/v1/agents/${encodeURIComponent(sandbox.agentId)}/sandboxes`, {
+      method: "DELETE",
+      headers: cloudHeaders(this.cloudOptions)
+    });
+    const body = await parseJsonResponse2(response);
+    if (response.status === 404)
+      return;
+    assertOkResponse(response, body, "Cloud terminate managed sandbox");
+  }
+  async waitForManagedSandboxConnection(sandbox) {
+    const deadline = Date.now() + sandbox.readyTimeoutMs;
+    let lastError;
+    while (true) {
+      try {
+        const resolved = await this.remoteEnvironmentClient().resolveEnvironment({
+          deviceId: sandbox.deviceId
+        });
+        return { connectionId: resolved.connectionId };
+      } catch (error) {
+        lastError = error;
+        if (!isRetryableManagedSandboxResolveError(error) || Date.now() >= deadline) {
+          break;
+        }
+        const remainingMs = Math.max(0, deadline - Date.now());
+        await sleep(Math.min(sandbox.readyPollIntervalMs, remainingMs));
+      }
+    }
+    const detail = lastError instanceof Error ? lastError.message : String(lastError);
+    throw new Error(`Cloud managed sandbox ${sandbox.sandboxId} did not come online within ${sandbox.readyTimeoutMs}ms: ${detail}`);
+  }
+  startManagedSandboxRefresh(sandbox) {
+    this.stopManagedSandboxRefresh();
+    this.sandboxRefreshTimer = setInterval(() => {
+      this.refreshManagedSandbox(sandbox).catch((error) => {
+        if (error instanceof CloudManagedSandboxOwnershipError) {
+          this.stopManagedSandboxRefresh();
+        }
+      });
+    }, sandbox.refreshIntervalMs);
+    this.sandboxRefreshTimer.unref?.();
+  }
+  stopManagedSandboxRefresh() {
+    if (!this.sandboxRefreshTimer)
+      return;
+    clearInterval(this.sandboxRefreshTimer);
+    this.sandboxRefreshTimer = null;
+  }
+  async cleanupManagedSandbox() {
+    this.stopManagedSandboxRefresh();
+    const sandbox = this.managedSandbox;
+    this.managedSandbox = null;
+    if (!sandbox || !sandbox.terminateOnClose)
+      return;
+    try {
+      await this.terminateManagedSandbox(sandbox);
+    } catch {}
+  }
+  remoteEnvironmentClient() {
+    return new RemoteEnvironmentClient({
+      baseUrl: this.cloudOptions.apiBaseUrl,
+      apiKey: getCloudApiKey(this.cloudOptions),
+      headers: this.cloudOptions.headers,
+      fetch: this.cloudOptions.fetch
+    });
+  }
+  effectiveEnvironment() {
+    const modeEnvironment = this.mode.kind === "session" ? this.mode.options.environment : undefined;
+    return modeEnvironment ?? this.cloudOptions.environment;
+  }
+  effectiveSandboxOptions() {
+    const modeSandbox = this.mode.kind === "session" ? this.mode.options.sandbox : undefined;
+    return modeSandbox ?? this.cloudOptions.sandbox;
+  }
+  resolvedSandboxOptions() {
+    return this.effectiveSandboxOptions() ?? {};
+  }
+}
+
+// src/validation.ts
+var VALID_SKILL_SOURCES = [
+  "bundled",
+  "global",
+  "agent",
+  "project"
+];
+var VALID_REASONING_EFFORTS = [
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh"
+];
+function getBlockLabels(memory) {
+  return memory.map((item) => {
+    if (typeof item === "string")
+      return item;
+    if ("label" in item)
+      return item.label;
+    return null;
+  }).filter((label) => label !== null);
+}
+function validateApprovalRecoveryOptions(options) {
+  if (options.maxApprovalRecoveryAttempts !== undefined && (!Number.isInteger(options.maxApprovalRecoveryAttempts) || options.maxApprovalRecoveryAttempts < 0)) {
+    throw new Error("Invalid maxApprovalRecoveryAttempts. Expected a non-negative integer.");
+  }
+  if (options.approvalRecoveryTimeoutMs !== undefined && (!Number.isInteger(options.approvalRecoveryTimeoutMs) || options.approvalRecoveryTimeoutMs <= 0)) {
+    throw new Error("Invalid approvalRecoveryTimeoutMs. Expected a positive integer.");
+  }
+}
+function validateRemovedSessionOptions(options) {
+  if (options.memfsStartup !== undefined) {
+    throw new Error("memfsStartup is not supported by the SDK.");
+  }
+}
+function validateSystemPromptPreset(preset) {
+  const validPresets = [
+    "default",
+    "letta-claude",
+    "letta-codex",
+    "letta-gemini",
+    "claude",
+    "codex",
+    "gemini"
+  ];
+  if (!validPresets.includes(preset)) {
+    throw new Error(`Invalid system prompt preset '${preset}'. ` + `Valid presets: ${validPresets.join(", ")}`);
+  }
+}
+function validateSkillSources(sources) {
+  if (sources === undefined) {
+    return;
+  }
+  for (const source of sources) {
+    if (!VALID_SKILL_SOURCES.includes(source)) {
+      throw new Error(`Invalid skill source '${source}'. Valid values: ${VALID_SKILL_SOURCES.join(", ")}`);
+    }
+  }
+}
+function validateDreamingOptions(dreaming) {
+  if (dreaming === undefined) {
+    return;
+  }
+  if (dreaming.trigger !== undefined && !["off", "step-count", "compaction-event"].includes(dreaming.trigger)) {
+    throw new Error(`Invalid dreaming.trigger '${String(dreaming.trigger)}'. Valid values: off, step-count, compaction-event`);
+  }
+  if (dreaming.behavior !== undefined && !["reminder", "auto-launch"].includes(dreaming.behavior)) {
+    throw new Error(`Invalid dreaming.behavior '${String(dreaming.behavior)}'. Valid values: reminder, auto-launch`);
+  }
+  if (dreaming.stepCount !== undefined && (!Number.isInteger(dreaming.stepCount) || dreaming.stepCount <= 0)) {
+    throw new Error("Invalid dreaming.stepCount. Expected a positive integer.");
+  }
+}
+function validateReasoningEffort(value) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "string" || !VALID_REASONING_EFFORTS.includes(value)) {
+    throw new Error(`Invalid reasoningEffort '${String(value)}'. Valid values: ${VALID_REASONING_EFFORTS.join(", ")}`);
+  }
+}
+function validateCreateSessionOptions(options) {
+  if (options.systemPrompt !== undefined) {
+    validateSystemPromptPreset(options.systemPrompt);
+  }
+  validateSkillSources(options.skillSources);
+  validateReasoningEffort(options.reasoningEffort);
+  validateDreamingOptions(options.dreaming);
+  validateApprovalRecoveryOptions(options);
+  validateRemovedSessionOptions(options);
+}
+function validateCreateAgentOptions(options) {
+  if (options.memory !== undefined) {
+    const blockLabels = getBlockLabels(options.memory);
+    if (options.persona !== undefined && !blockLabels.includes("persona")) {
+      throw new Error("Cannot set 'persona' value - block not included in 'memory'. " + "Either add 'persona' to memory array or remove the persona option.");
+    }
+    if (options.human !== undefined && !blockLabels.includes("human")) {
+      throw new Error("Cannot set 'human' value - block not included in 'memory'. " + "Either add 'human' to memory array or remove the human option.");
+    }
+  }
+  if (options.systemPrompt !== undefined && typeof options.systemPrompt === "object") {
+    validateSystemPromptPreset(options.systemPrompt.preset);
+  } else if (options.systemPrompt !== undefined && typeof options.systemPrompt === "string") {
+    const validPresets = [
+      "default",
+      "letta-claude",
+      "letta-codex",
+      "letta-gemini",
+      "claude",
+      "codex",
+      "gemini"
+    ];
+    if (validPresets.includes(options.systemPrompt)) {
+      validateSystemPromptPreset(options.systemPrompt);
+    }
+  }
+  validateSkillSources(options.skillSources);
+  validateDreamingOptions(options.dreaming);
+}
+
+// src/client.ts
+var VALID_BACKENDS = new Set([
+  "local",
+  "remote",
+  "cloud"
+]);
+function isLettaCodeBackend(value) {
+  return VALID_BACKENDS.has(value);
+}
+function getOptionsEnvironment(options) {
+  if ("environment" in options) {
+    return options.environment;
+  }
+  return;
+}
+function stripCloudExecutionOptions(options) {
+  const sessionOptions = { ...options };
+  delete sessionOptions.environment;
+  delete sessionOptions.sandbox;
+  return sessionOptions;
+}
+function hasCreateAgentEnvironment(options) {
+  return "environment" in options;
+}
+function looksLikeConversationId(id) {
+  return id.startsWith("conv-") || id.startsWith("local-conv-");
+}
+
+class LettaCodeClient {
+  backend;
+  environment;
+  options;
+  constructor(options = {}) {
+    const backend = options.backend ?? "local";
+    if (!isLettaCodeBackend(backend)) {
+      throw new Error(`Invalid Letta Code backend '${String(backend)}'. Valid values: local, remote, cloud.`);
+    }
+    this.backend = backend;
+    this.environment = getOptionsEnvironment(options);
+    this.options = options;
+    if (this.backend === "local" && this.environment !== undefined) {
+      throw new Error('LettaCodeClient environment is only valid with backend: "cloud".');
+    }
+    if (this.backend === "remote" && this.environment !== undefined) {
+      throw new Error('LettaCodeClient environment is only valid with backend: "cloud"; remote url selects the app-server runtime.');
+    }
+    if (this.backend !== "cloud" && options.sandbox !== undefined) {
+      throw new Error('LettaCodeClient sandbox options are only valid with backend: "cloud".');
+    }
+    if (this.backend === "local") {
+      const localOptions = options;
+      if (localOptions.transport !== undefined && localOptions.transport !== "app-server" && localOptions.transport !== "stdio") {
+        throw new Error("Invalid local transport. Valid values: app-server, stdio.");
+      }
+      const requestTimeoutMs = localOptions.appServer?.requestTimeoutMs;
+      if (requestTimeoutMs !== undefined && (!Number.isInteger(requestTimeoutMs) || requestTimeoutMs <= 0)) {
+        throw new Error("Invalid appServer.requestTimeoutMs. Expected a positive integer.");
+      }
+      const startupTimeoutMs = localOptions.appServer?.startupTimeoutMs;
+      if (startupTimeoutMs !== undefined && (!Number.isInteger(startupTimeoutMs) || startupTimeoutMs <= 0)) {
+        throw new Error("Invalid appServer.startupTimeoutMs. Expected a positive integer.");
+      }
+    }
+    if (this.backend === "remote") {
+      if (!("url" in options) || typeof options.url !== "string" || options.url.length === 0) {
+        throw new Error("LettaCodeClient remote backend requires a non-empty url.");
+      }
+      if (options.requestTimeoutMs !== undefined && (!Number.isInteger(options.requestTimeoutMs) || options.requestTimeoutMs <= 0)) {
+        throw new Error("Invalid requestTimeoutMs. Expected a positive integer.");
+      }
+    }
+    if (this.backend === "cloud") {
+      validateCloudClientOptions(options);
+    }
+  }
+  async createAgent(options = {}) {
+    if (hasCreateAgentEnvironment(options)) {
+      throw new Error("createAgent() does not accept environment. Set a client default or pass environment to resumeSession()/createSession().");
+    }
+    validateCreateAgentOptions(options);
+    if (this.backend === "remote") {
+      const session2 = new AppServerSession(this.remoteOptions(), {
+        kind: "create-agent",
+        options
+      });
+      const initMsg2 = await session2.initialize();
+      session2.close();
+      return initMsg2.agentId;
+    }
+    if (this.backend === "cloud") {
+      return createCloudAgent(this.cloudOptions(), options);
+    }
+    this.assertLocalBackend("createAgent");
+    if (!this.useLegacyLocalStdio()) {
+      const session2 = new AppServerSession(this.localAppServerOptions(), {
+        kind: "create-agent",
+        options
+      });
+      const initMsg2 = await session2.initialize();
+      session2.close();
+      return initMsg2.agentId;
+    }
+    const session = new Session({ ...options, createOnly: true });
+    const initMsg = await session.initialize();
+    session.close();
+    return initMsg.agentId;
+  }
+  createSession(agentIdOrOptions, options = {}) {
+    const agentId = typeof agentIdOrOptions === "string" ? agentIdOrOptions : undefined;
+    const resolvedOptions = typeof agentIdOrOptions === "string" ? options : agentIdOrOptions ?? {};
+    this.assertSessionBackend("createSession", resolvedOptions);
+    const sessionOptions = stripCloudExecutionOptions(resolvedOptions);
+    validateCreateSessionOptions(sessionOptions);
+    if (this.backend === "remote") {
+      if (!agentId) {
+        throw new Error("App-server createSession() requires an agent id. Call createAgent() first or pass an agent id.");
+      }
+      return new AppServerSession(this.remoteOptions(), {
+        kind: "session",
+        agentId,
+        newConversation: true,
+        options: resolvedOptions
+      });
+    }
+    if (this.backend === "cloud") {
+      if (!agentId) {
+        throw new Error("Constellation createSession() requires an agent id. Call createAgent() first or pass an agent id.");
+      }
+      return new CloudEnvironmentSession(this.cloudOptions(), {
+        kind: "session",
+        agentId,
+        newConversation: true,
+        options: resolvedOptions
+      });
+    }
+    if (!this.useLegacyLocalStdio() && agentId) {
+      return new AppServerSession(this.localAppServerOptions(), {
+        kind: "session",
+        agentId,
+        newConversation: true,
+        options: resolvedOptions
+      });
+    }
+    if (agentId) {
+      return new Session({ ...sessionOptions, agentId, newConversation: true });
+    }
+    return new Session({ ...sessionOptions, newConversation: true });
+  }
+  resumeSession(id, options = {}) {
+    this.assertSessionBackend("resumeSession", options);
+    const sessionOptions = stripCloudExecutionOptions(options);
+    validateCreateSessionOptions(sessionOptions);
+    if (this.backend === "remote") {
+      if (looksLikeConversationId(id)) {
+        return new AppServerSession(this.remoteOptions(), {
+          kind: "session",
+          conversationId: id,
+          options
+        });
+      }
+      return new AppServerSession(this.remoteOptions(), {
+        kind: "session",
+        agentId: id,
+        defaultConversation: true,
+        options
+      });
+    }
+    if (this.backend === "cloud") {
+      if (looksLikeConversationId(id)) {
+        return new CloudEnvironmentSession(this.cloudOptions(), {
+          kind: "session",
+          conversationId: id,
+          options
+        });
+      }
+      return new CloudEnvironmentSession(this.cloudOptions(), {
+        kind: "session",
+        agentId: id,
+        defaultConversation: true,
+        options
+      });
+    }
+    if (!this.useLegacyLocalStdio()) {
+      if (looksLikeConversationId(id)) {
+        return new AppServerSession(this.localAppServerOptions(), {
+          kind: "session",
+          conversationId: id,
+          options
+        });
+      }
+      return new AppServerSession(this.localAppServerOptions(), {
+        kind: "session",
+        agentId: id,
+        defaultConversation: true,
+        options
+      });
+    }
+    if (looksLikeConversationId(id)) {
+      return new Session({ ...sessionOptions, conversationId: id });
+    }
+    return new Session({
+      ...sessionOptions,
+      agentId: id,
+      defaultConversation: true
+    });
+  }
+  async prompt(message, agentId, options = {}) {
+    const session = agentId ? this.createSession(agentId, options) : this.createSession(options);
+    try {
+      return await session.runTurn(message);
+    } finally {
+      session.close();
+    }
+  }
+  assertLocalBackend(action) {
+    if (this.backend === "local") {
+      return;
+    }
+    throw new Error(`LettaCodeClient backend '${this.backend}' is not implemented yet. ${action} currently supports backend 'local' only.`);
+  }
+  assertSessionBackend(action, options) {
+    const effectiveEnvironment = options.environment ?? this.environment;
+    if (this.backend === "local") {
+      if (effectiveEnvironment !== undefined) {
+        throw new Error(`${action}() environment overrides are only valid with backend: "cloud".`);
+      }
+      if (options.sandbox !== undefined) {
+        throw new Error(`${action}() sandbox options are only valid with backend: "cloud".`);
+      }
+      if (!this.useLegacyLocalStdio()) {
+        assertRemoteSessionOptionsSupported(action, options);
+      }
+      return;
+    }
+    if (this.backend === "remote") {
+      if (options.environment !== undefined) {
+        throw new Error(`${action}() environment overrides are only valid with backend: "cloud"; remote url selects the app-server runtime.`);
+      }
+      if (options.sandbox !== undefined) {
+        throw new Error(`${action}() sandbox options are only valid with backend: "cloud"; remote url selects the app-server runtime.`);
+      }
+      assertRemoteSessionOptionsSupported(action, options);
+      return;
+    }
+    if (this.backend === "cloud") {
+      const cloudOptions = this.cloudOptions();
+      if (cloudOptions.environment !== undefined && options.sandbox !== undefined) {
+        throw new Error(`Constellation ${action}() cannot specify sandbox options when the client has a default environment.`);
+      }
+      if (cloudOptions.sandbox !== undefined && options.environment !== undefined) {
+        throw new Error(`Constellation ${action}() cannot specify an environment when the client has default sandbox options.`);
+      }
+      assertCloudSessionOptionsSupported(action, options);
+      return;
+    }
+    throw new Error(`LettaCodeClient backend '${this.backend}' is not implemented yet. ${action} currently supports backend 'local' only.`);
+  }
+  useLegacyLocalStdio() {
+    return this.options.transport === "stdio";
+  }
+  localAppServerOptions() {
+    const localOptions = this.options;
+    const appServer = localOptions.appServer;
+    return {
+      local: appServer?.url === undefined,
+      ...appServer?.url !== undefined ? { url: appServer.url } : {},
+      ...appServer?.WebSocket !== undefined ? { WebSocket: appServer.WebSocket } : {},
+      ...appServer?.requestTimeoutMs !== undefined ? { requestTimeoutMs: appServer.requestTimeoutMs } : {},
+      ...appServer?.listen !== undefined ? { localListen: appServer.listen } : {},
+      ...appServer?.startupTimeoutMs !== undefined ? { localStartupTimeoutMs: appServer.startupTimeoutMs } : {}
+    };
+  }
+  remoteOptions() {
+    if (this.backend !== "remote") {
+      throw new Error("Remote options requested for non-remote backend.");
+    }
+    return this.options;
+  }
+  cloudOptions() {
+    if (this.backend !== "cloud") {
+      throw new Error('Constellation options requested for non-"cloud" backend.');
+    }
+    return this.options;
+  }
+}
+// src/stream-events.ts
+function extractTextFromContent2(content) {
+  if (typeof content === "string") {
+    return content;
+  }
+  if (Array.isArray(content)) {
+    const pieces = [];
+    for (const part of content) {
+      if (typeof part === "string") {
+        pieces.push(part);
+        continue;
+      }
+      if (!part || typeof part !== "object") {
+        continue;
+      }
+      const rec = part;
+      if (typeof rec.text === "string") {
+        pieces.push(rec.text);
+      }
+    }
+    const joined = pieces.join("");
+    return joined.length > 0 ? joined : null;
+  }
+  if (content && typeof content === "object") {
+    const rec = content;
+    if (typeof rec.text === "string") {
+      return rec.text;
+    }
+  }
+  return null;
+}
+function extractStreamTextDelta(event) {
+  if (!event || typeof event !== "object") {
+    return null;
+  }
+  const rec = event;
+  const maybeDelta = rec.delta;
+  if (maybeDelta && typeof maybeDelta === "object") {
+    const delta = maybeDelta;
+    if (typeof delta.reasoning === "string" && delta.reasoning.length > 0) {
+      return { kind: "reasoning", text: delta.reasoning };
+    }
+    if (typeof delta.text === "string" && delta.text.length > 0) {
+      return { kind: "assistant", text: delta.text };
+    }
+  }
+  const messageType = rec.message_type;
+  if (messageType === "reasoning_message") {
+    const reasoningText = typeof rec.reasoning === "string" ? rec.reasoning : extractTextFromContent2(rec.content);
+    if (reasoningText && reasoningText.length > 0) {
+      return { kind: "reasoning", text: reasoningText };
+    }
+  }
+  if (messageType === "assistant_message") {
+    const assistantText = extractTextFromContent2(rec.content);
+    if (assistantText && assistantText.length > 0) {
+      return { kind: "assistant", text: assistantText };
+    }
+  }
+  return null;
+}
+// src/tool-helpers.ts
+function jsonResult(payload) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(payload, null, 2)
+      }
+    ],
+    details: payload
+  };
+}
+function readStringParam(params, key, options = {}) {
+  const { required = false, trim = true, label = key, allowEmpty = false } = options;
+  const raw = params[key];
+  if (typeof raw !== "string") {
+    if (required)
+      throw new Error(`${label} required`);
+    return;
+  }
+  const value = trim ? raw.trim() : raw;
+  if (!value && !allowEmpty) {
+    if (required)
+      throw new Error(`${label} required`);
+    return;
+  }
+  return value;
+}
+function readNumberParam(params, key, options = {}) {
+  const { required = false, label = key, integer = false } = options;
+  const raw = params[key];
+  let value;
+  if (typeof raw === "number" && Number.isFinite(raw)) {
+    value = raw;
+  } else if (typeof raw === "string") {
+    const trimmed = raw.trim();
+    if (trimmed) {
+      const parsed = Number.parseFloat(trimmed);
+      if (Number.isFinite(parsed))
+        value = parsed;
+    }
+  }
+  if (value === undefined) {
+    if (required)
+      throw new Error(`${label} required`);
+    return;
+  }
+  return integer ? Math.trunc(value) : value;
+}
+function readBooleanParam(params, key, options = {}) {
+  const { required = false, label = key } = options;
+  const raw = params[key];
+  if (typeof raw === "boolean") {
+    return raw;
+  }
+  if (typeof raw === "string") {
+    const lower = raw.toLowerCase().trim();
+    if (lower === "true" || lower === "1" || lower === "yes")
+      return true;
+    if (lower === "false" || lower === "0" || lower === "no")
+      return false;
+  }
+  if (required)
+    throw new Error(`${label} required`);
+  return;
+}
+function readStringArrayParam(params, key, options = {}) {
+  const { required = false, label = key } = options;
+  const raw = params[key];
+  if (Array.isArray(raw)) {
+    const values = raw.filter((entry) => typeof entry === "string").map((entry) => entry.trim()).filter(Boolean);
+    if (values.length === 0) {
+      if (required)
+        throw new Error(`${label} required`);
+      return;
+    }
+    return values;
+  }
+  if (typeof raw === "string") {
+    const value = raw.trim();
+    if (!value) {
+      if (required)
+        throw new Error(`${label} required`);
+      return;
+    }
+    return [value];
+  }
+  if (required)
+    throw new Error(`${label} required`);
+  return;
+}
+
+// src/index.ts
+import { readFileSync } from "node:fs";
+async function createAgent(options = {}) {
+  validateCreateAgentOptions(options);
+  return new LettaCodeClient().createAgent(options);
+}
+function createSession(agentId, options = {}) {
+  validateCreateSessionOptions(options);
+  if (agentId) {
+    return new LettaCodeClient().createSession(agentId, options);
+  }
+  return new LettaCodeClient({ backend: "local", transport: "stdio" }).createSession(options);
+}
+function resumeSession(id, options = {}) {
+  validateCreateSessionOptions(options);
+  return new LettaCodeClient().resumeSession(id, options);
+}
+async function prompt(message, agentId) {
+  const session = agentId ? createSession(agentId) : createSession();
+  try {
+    return await session.runTurn(message);
+  } finally {
+    session.close();
+  }
+}
+async function listMessagesDirect(agentId, options = {}) {
+  const session = new LettaCodeClient().resumeSession(agentId, {
+    permissionMode: "bypassPermissions"
+  });
+  await session.initialize();
+  try {
+    return await session.listMessages(options);
+  } finally {
+    session.close();
+  }
+}
+function imageFromFile(filePath) {
+  const data = readFileSync(filePath).toString("base64");
+  const ext = filePath.toLowerCase();
+  const media_type = ext.endsWith(".png") ? "image/png" : ext.endsWith(".gif") ? "image/gif" : ext.endsWith(".webp") ? "image/webp" : "image/jpeg";
+  return {
+    type: "image",
+    source: { type: "base64", media_type, data }
+  };
+}
+function imageFromBase64(data, media_type = "image/png") {
+  return {
+    type: "image",
+    source: { type: "base64", media_type, data }
+  };
+}
+async function imageFromURL(url) {
+  const response = await fetch(url);
+  const buffer = await response.arrayBuffer();
+  const data = Buffer.from(buffer).toString("base64");
+  const contentType = response.headers.get("content-type");
+  let media_type = "image/png";
+  if (contentType?.includes("jpeg") || contentType?.includes("jpg") || url.match(/\.jpe?g$/i)) {
+    media_type = "image/jpeg";
+  } else if (contentType?.includes("gif") || url.endsWith(".gif")) {
+    media_type = "image/gif";
+  } else if (contentType?.includes("webp") || url.endsWith(".webp")) {
+    media_type = "image/webp";
+  }
+  return {
+    type: "image",
+    source: { type: "base64", media_type, data }
+  };
+}
+export {
+  resumeSession,
+  readStringParam,
+  readStringArrayParam,
+  readNumberParam,
+  readBooleanParam,
+  prompt,
+  listMessagesDirect,
+  jsonResult,
+  imageFromURL,
+  imageFromFile,
+  imageFromBase64,
+  extractStreamTextDelta,
+  createSession,
+  createAgent,
+  Session,
+  LettaCodeClient
+};
+
+//# debugId=386FEEB02928954D64756E2164756E21