@letta-ai/letta-code-sdk 0.0.5 → 0.0.6

package/dist/index.js

@@ -20,6 +20,10 @@ 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);
+}
 
 class SubprocessTransport {
   options;
@@ -29,21 +33,25 @@ class SubprocessTransport {
   messageResolvers = [];
   closed = false;
   agentId;
+  wireMessageCount = 0;
+  lastMessageAt = 0;
   constructor(options = {}) {
     this.options = options;
   }
   async connect() {
     const args = this.buildArgs();
     const cliPath = await this.findCli();
-    if (process.env.DEBUG) {
-      console.log("[letta-code-sdk] Using CLI:", cliPath);
-      console.log("[letta-code-sdk] Args:", args.join(" "));
-    }
+    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");
     }
@@ -57,7 +65,9 @@ class SubprocessTransport {
       try {
         const msg = JSON.parse(line);
         this.handleMessage(msg);
-      } catch {}
+      } catch {
+        sdkLog("stdout", `[non-JSON] ${line.slice(0, 500)}`);
+      }
     });
     if (this.process.stderr) {
       this.process.stderr.on("data", (data) => {
@@ -67,11 +77,16 @@ class SubprocessTransport {
         }
       });
     }
-    this.process.on("close", (code) => {
-      this.closed = true;
+    this.process.on("close", (code, signal) => {
       if (code !== 0 && code !== null) {
         console.error(`[letta-code-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-code-sdk] CLI process error:", err);
@@ -80,8 +95,12 @@ class SubprocessTransport {
   }
   async write(data) {
     if (!this.process?.stdin || this.closed) {
-      throw new Error("Transport not connected");
+      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) + `
 `);
   }
@@ -90,8 +109,10 @@ class SubprocessTransport {
       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);
     });
@@ -99,12 +120,15 @@ class SubprocessTransport {
   async* messages() {
     while (true) {
       const msg = await this.read();
-      if (msg === null)
+      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();
@@ -120,8 +144,22 @@ class SubprocessTransport {
     return this.closed;
   }
   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();
@@ -146,7 +184,7 @@ class SubprocessTransport {
       } else if (this.options.defaultConversation) {
         args.push("--default");
       }
-    } else if (this.options.promptMode) {} else if (this.options.createOnly) {
+    } else if (this.options.createOnly) {
       args.push("--new-agent");
     } else if (this.options.newConversation) {
       args.push("--new");
@@ -154,6 +192,9 @@ class SubprocessTransport {
     if (this.options.model) {
       args.push("-m", this.options.model);
     }
+    if (this.options.embedding) {
+      args.push("--embedding", this.options.embedding);
+    }
     if (this.options.systemPrompt !== undefined) {
       if (typeof this.options.systemPrompt === "string") {
         const validPresets = [
@@ -212,12 +253,15 @@ class SubprocessTransport {
     }
     if (this.options.permissionMode === "bypassPermissions") {
       args.push("--yolo");
-    } else if (this.options.permissionMode === "acceptEdits") {
-      args.push("--accept-edits");
+    } else if (this.options.permissionMode && this.options.permissionMode !== "default") {
+      args.push("--permission-mode", this.options.permissionMode);
     }
     if (this.options.allowedTools) {
       args.push("--allowedTools", this.options.allowedTools.join(","));
     }
+    if (this.options.disallowedTools) {
+      args.push("--disallowedTools", this.options.disallowedTools.join(","));
+    }
     return args;
   }
   async findCli() {
@@ -251,7 +295,27 @@ class SubprocessTransport {
   }
 }
 
+// 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);
+}
+
 class Session {
   options;
   transport;
@@ -259,77 +323,216 @@ class Session {
   _sessionId = null;
   _conversationId = null;
   initialized = false;
+  externalTools = new Map;
   constructor(options = {}) {
     this.options = options;
     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 === "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;
+        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: initMsg.tools
+          tools: allTools
         };
       }
     }
+    sessionLog("init", "ERROR: transport closed before init message received");
     throw new Error("Failed to initialize session - no init message received");
   }
   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 ? "..." : ""}`);
     await this.transport.write({
       type: "user",
       message: { role: "user", content: message }
     });
+    sessionLog("send", "message written to transport");
   }
   async* stream() {
+    const streamStart = Date.now();
+    let yieldCount = 0;
+    let dropCount = 0;
+    let gotResult = false;
+    sessionLog("stream", `starting stream (agent=${this._agentId}, conversation=${this._conversationId})`);
     for await (const wireMsg of this.transport.messages()) {
       if (wireMsg.type === "control_request") {
         const controlReq = wireMsg;
-        if (controlReq.request.subtype === "can_use_tool") {
+        const subtype = controlReq.request.subtype;
+        sessionLog("stream", `control_request: subtype=${subtype} tool=${controlReq.request.tool_name || "N/A"}`);
+        if (subtype === "can_use_tool") {
           await this.handleCanUseTool(controlReq.request_id, controlReq.request);
           continue;
         }
+        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
+          });
+          continue;
+        }
       }
       const sdkMsg = this.transformMessage(wireMsg);
       if (sdkMsg) {
+        yieldCount++;
+        sessionLog("stream", `yield #${yieldCount}: type=${sdkMsg.type}${sdkMsg.type === "result" ? ` success=${sdkMsg.success} error=${sdkMsg.error || "none"}` : ""}`);
         yield sdkMsg;
         if (sdkMsg.type === "result") {
+          gotResult = true;
           break;
         }
+      } else {
+        dropCount++;
+        const wireMsgAny = wireMsg;
+        sessionLog("stream", `DROPPED wire message #${dropCount}: type=${wireMsg.type} message_type=${wireMsgAny.message_type || "N/A"} subtype=${wireMsgAny.subtype || "N/A"}`);
+      }
+    }
+    const elapsed = Date.now() - streamStart;
+    sessionLog("stream", `stream ended: duration=${elapsed}ms yielded=${yieldCount} dropped=${dropCount} gotResult=${gotResult}`);
+    if (!gotResult) {
+      sessionLog("stream", `WARNING: stream ended WITHOUT a result message -- transport may have closed unexpectedly`);
+    }
+  }
+  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;
-    if (this.options.permissionMode === "bypassPermissions") {
+    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 (this.options.canUseTool) {
+    } else if (hasCallback) {
       try {
-        const result = await this.options.canUseTool(req.tool_name, req.input);
+        const result = await this.options.canUseTool(toolName, req.input);
         if (result.behavior === "allow") {
           response = {
             behavior: "allow",
@@ -350,6 +553,13 @@ class Session {
           interrupt: false
         };
       }
+    } else if (autoAllowWithoutCallback) {
+      sessionLog("canUseTool", `AUTO-ALLOW ${toolName} (default behavior)`);
+      response = {
+        behavior: "allow",
+        updatedInput: null,
+        updatedPermissions: []
+      };
     } else {
       response = {
         behavior: "deny",
@@ -357,6 +567,8 @@ class Session {
         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: {
@@ -365,8 +577,10 @@ class Session {
         response
       }
     });
+    sessionLog("canUseTool", `response sent for ${toolName}`);
   }
   async abort() {
+    sessionLog("abort", `aborting session (agent=${this._agentId})`);
     await this.transport.write({
       type: "control_request",
       request_id: `interrupt-${Date.now()}`,
@@ -374,6 +588,7 @@ class Session {
     });
   }
   close() {
+    sessionLog("close", `closing session (agent=${this._agentId}, conversation=${this._conversationId})`);
     this.transport.close();
   }
   get agentId() {
@@ -459,6 +674,7 @@ class Session {
         success: msg.subtype === "success",
         result: msg.result,
         error: msg.subtype !== "success" ? msg.subtype : undefined,
+        stopReason: msg.stop_reason,
         durationMs: msg.duration_ms,
         totalCostUsd: msg.total_cost_usd,
         conversationId: msg.conversation_id
@@ -524,6 +740,97 @@ function validateCreateAgentOptions(options) {
     }
   }
 }
+// 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";
@@ -551,7 +858,7 @@ function resumeSession(id, options = {}) {
   }
 }
 async function prompt(message, agentId) {
-  const session = agentId ? createSession(agentId) : new Session({ promptMode: true });
+  const session = agentId ? createSession(agentId) : createSession();
   try {
     await session.send(message);
     let result = null;
@@ -610,7 +917,12 @@ async function imageFromURL(url) {
 }
 export {
   resumeSession,
+  readStringParam,
+  readStringArrayParam,
+  readNumberParam,
+  readBooleanParam,
   prompt,
+  jsonResult,
   imageFromURL,
   imageFromFile,
   imageFromBase64,
@@ -619,4 +931,4 @@ export {
   Session
 };
 
-//# debugId=D4FF4806F62B360664756E2164756E21
+//# debugId=63415FA0837719DA64756E2164756E21