@letta-ai/letta-code 0.24.2 → 0.24.3

package/letta.js

@@ -3269,7 +3269,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@letta-ai/letta-code",
-    version: "0.24.2",
+    version: "0.24.3",
     description: "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
     type: "module",
     bin: {
@@ -51442,7 +51442,8 @@ var init_readOnlyShell = __esm(() => {
     "sleep"
   ]);
   SAFE_LETTA_COMMANDS = {
-    memfs: new Set(["status", "help", "backups", "export"]),
+    memory: new Set(["status", "help", "backups", "export", "tokens"]),
+    memfs: new Set(["status", "help", "backups", "export", "tokens"]),
     agents: new Set(["list", "help"]),
     messages: new Set(["search", "list", "help"]),
     blocks: new Set(["list", "help"])
@@ -83492,46 +83493,58 @@ var init_memoryReminder = __esm(() => {
   };
 });
 
-// src/cli/helpers/systemPromptWarning.ts
+// src/utils/systemPromptSize.ts
 import { existsSync as existsSync26, readdirSync as readdirSync8, readFileSync as readFileSync19 } from "node:fs";
 import { join as join29 } from "node:path";
 function estimateSystemTokens(text) {
-  return Math.ceil(Buffer.byteLength(text, "utf8") / STARTUP_SYSTEM_PROMPT_ESTIMATED_BYTES_PER_TOKEN);
+  return Math.ceil(Buffer.byteLength(text, "utf8") / SYSTEM_PROMPT_BYTES_PER_TOKEN);
 }
-function estimateSystemPromptTokensFromMemoryDir(memoryDir) {
-  const systemDir = join29(memoryDir, "system");
-  if (!existsSync26(systemDir)) {
-    return 0;
+function normalizePath2(value) {
+  return value.replaceAll("\\", "/");
+}
+function walkMarkdownFiles(dir) {
+  if (!existsSync26(dir)) {
+    return [];
   }
-  const walkMarkdownFiles = (dir) => {
-    if (!existsSync26(dir)) {
-      return [];
+  const out = [];
+  const entries = readdirSync8(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) {
+      continue;
     }
-    const out = [];
-    const entries = readdirSync8(dir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (entry.name.startsWith(".")) {
-        continue;
-      }
-      const full = join29(dir, entry.name);
-      if (entry.isDirectory()) {
-        if (entry.name === ".git") {
-          continue;
-        }
-        out.push(...walkMarkdownFiles(full));
-        continue;
-      }
-      if (entry.isFile() && entry.name.endsWith(".md")) {
-        out.push(full);
-      }
+    const full = join29(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...walkMarkdownFiles(full));
+      continue;
     }
-    return out;
-  };
-  return walkMarkdownFiles(systemDir).sort().reduce((sum, filePath) => {
+    if (entry.isFile() && entry.name.endsWith(".md")) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+function estimateSystemPromptSize(memoryDir) {
+  const systemDir = join29(memoryDir, "system");
+  if (!existsSync26(systemDir)) {
+    return { total: 0, files: [] };
+  }
+  const files = walkMarkdownFiles(systemDir).sort();
+  const rows = [];
+  for (const filePath of files) {
     const text = readFileSync19(filePath, "utf8");
-    return sum + estimateSystemTokens(text);
-  }, 0);
+    const rel = normalizePath2(filePath.slice(memoryDir.length + 1));
+    rows.push({ path: rel, tokens: estimateSystemTokens(text) });
+  }
+  const total = rows.reduce((sum, row) => sum + row.tokens, 0);
+  return { total, files: rows };
+}
+function estimateSystemPromptTokensFromMemoryDir(memoryDir) {
+  return estimateSystemPromptSize(memoryDir).total;
 }
+var SYSTEM_PROMPT_BYTES_PER_TOKEN = 4;
+var init_systemPromptSize = () => {};
+
+// src/cli/helpers/systemPromptWarning.ts
 function setSystemPromptDoctorState(agentId, estimatedTokens) {
   const nextState = {
     estimated_tokens: estimatedTokens,
@@ -83574,11 +83587,12 @@ function buildStartupSystemPromptWarning(agentState) {
   }
   return null;
 }
-var STARTUP_SYSTEM_PROMPT_WARNING_THRESHOLD_TOKENS = 30000, STARTUP_SYSTEM_PROMPT_ESTIMATED_BYTES_PER_TOKEN = 4, systemPromptDoctorStateByAgent;
+var STARTUP_SYSTEM_PROMPT_WARNING_THRESHOLD_TOKENS = 30000, systemPromptDoctorStateByAgent;
 var init_systemPromptWarning = __esm(() => {
   init_memoryFilesystem();
   init_settings_manager();
   init_debug();
+  init_systemPromptSize();
   systemPromptDoctorStateByAgent = new Map;
 });
 
@@ -87183,10 +87197,132 @@ var init_reflectionTranscript = __esm(() => {
   init_directoryLimits();
 });
 
+// src/utils/tuiPerf.ts
+import { appendFileSync as appendFileSync3, mkdirSync as mkdirSync20 } from "node:fs";
+import { dirname as dirname14 } from "node:path";
+function ensureExitHook() {
+  if (tuiPerfExitHookRegistered) {
+    return;
+  }
+  tuiPerfExitHookRegistered = true;
+  process.once("beforeExit", () => {
+    flushTuiPerfTelemetry();
+  });
+}
+function scheduleTuiPerfFlush() {
+  if (tuiPerfFlushTimer) {
+    return;
+  }
+  tuiPerfFlushTimer = setTimeout(() => {
+    tuiPerfFlushTimer = null;
+    flushTuiPerfTelemetry();
+  }, TUI_PERF_FLUSH_INTERVAL_MS);
+  const timerWithUnref = tuiPerfFlushTimer;
+  timerWithUnref.unref?.();
+}
+function recordTuiPerf(key, sample) {
+  if (!TUI_PERF_ENABLED || !TUI_PERF_FILE) {
+    return;
+  }
+  ensureExitHook();
+  if (tuiPerfWindowStartedAt === 0) {
+    tuiPerfWindowStartedAt = Date.now();
+  }
+  const bytes = sample?.bytes ?? 0;
+  const ms = sample?.ms ?? 0;
+  const bucket = tuiPerfBuckets.get(key) ?? {
+    count: 0,
+    bytes: 0,
+    ms: 0,
+    maxBytes: 0,
+    maxMs: 0
+  };
+  bucket.count += 1;
+  bucket.bytes += bytes;
+  bucket.ms += ms;
+  bucket.maxBytes = Math.max(bucket.maxBytes, bytes);
+  bucket.maxMs = Math.max(bucket.maxMs, ms);
+  tuiPerfBuckets.set(key, bucket);
+  scheduleTuiPerfFlush();
+}
+function recordTuiJsonPayload(key, value) {
+  if (!TUI_PERF_ENABLED || !TUI_PERF_FILE) {
+    return;
+  }
+  try {
+    recordTuiPerf(key, { bytes: Buffer.byteLength(JSON.stringify(value)) });
+  } catch {
+    recordTuiPerf(key);
+  }
+}
+function flushTuiPerfTelemetry() {
+  if (tuiPerfBuckets.size === 0) {
+    tuiPerfWindowStartedAt = 0;
+    return;
+  }
+  const filePath = TUI_PERF_FILE;
+  if (!filePath) {
+    tuiPerfBuckets.clear();
+    tuiPerfWindowStartedAt = 0;
+    return;
+  }
+  const windowMs = Math.max(1, Date.now() - tuiPerfWindowStartedAt);
+  const totals = {
+    count: 0,
+    bytes: 0,
+    ms: 0,
+    maxBytes: 0,
+    maxMs: 0
+  };
+  const buckets = {};
+  for (const [key, bucket] of [...tuiPerfBuckets.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    totals.count += bucket.count;
+    totals.bytes += bucket.bytes;
+    totals.ms += bucket.ms;
+    totals.maxBytes = Math.max(totals.maxBytes, bucket.maxBytes);
+    totals.maxMs = Math.max(totals.maxMs, bucket.maxMs);
+    buckets[key] = {
+      ...bucket,
+      avg_bytes: bucket.count > 0 ? bucket.bytes / bucket.count : 0,
+      avg_ms: bucket.count > 0 ? bucket.ms / bucket.count : 0
+    };
+  }
+  try {
+    const dir = dirname14(filePath);
+    if (tuiPerfFileDirEnsured !== dir) {
+      mkdirSync20(dir, { recursive: true });
+      tuiPerfFileDirEnsured = dir;
+    }
+    appendFileSync3(filePath, `${JSON.stringify({
+      ts: new Date().toISOString(),
+      event: "tui_activity",
+      window_ms: windowMs,
+      totals,
+      buckets
+    })}
+`, { encoding: "utf8" });
+  } catch (error) {
+    if (!tuiPerfWarningEmitted) {
+      tuiPerfWarningEmitted = true;
+      console.error(`[TUI Perf] Failed to write LETTA_TUI_PERF_FILE=${filePath}`, error);
+    }
+  } finally {
+    tuiPerfBuckets.clear();
+    tuiPerfWindowStartedAt = 0;
+  }
+}
+var TUI_PERF_FLUSH_INTERVAL_MS = 1000, TUI_PERF_ENV_VALUES, TUI_PERF_ENABLED, TUI_PERF_FILE, tuiPerfBuckets, tuiPerfFlushTimer = null, tuiPerfWindowStartedAt = 0, tuiPerfFileDirEnsured = null, tuiPerfWarningEmitted = false, tuiPerfExitHookRegistered = false;
+var init_tuiPerf = __esm(() => {
+  TUI_PERF_ENV_VALUES = new Set(["1", "true", "yes"]);
+  TUI_PERF_ENABLED = TUI_PERF_ENV_VALUES.has((process.env.LETTA_TUI_PERF ?? "").toLowerCase());
+  TUI_PERF_FILE = process.env.LETTA_TUI_PERF_FILE?.trim() || null;
+  tuiPerfBuckets = new Map;
+});
+
 // src/cli/helpers/chunkLog.ts
 import {
   existsSync as existsSync28,
-  mkdirSync as mkdirSync20,
+  mkdirSync as mkdirSync21,
   readdirSync as readdirSync9,
   unlinkSync as unlinkSync7,
   writeFileSync as writeFileSync16
@@ -87287,7 +87423,7 @@ class ChunkLog {
       return;
     try {
       if (!existsSync28(this.agentDir)) {
-        mkdirSync20(this.agentDir, { recursive: true });
+        mkdirSync21(this.agentDir, { recursive: true });
       }
       this.dirCreated = true;
     } catch (e) {
@@ -87526,6 +87662,7 @@ async function drainStream(stream2, buffers, refresh, abortSignal, onFirstMessag
   }
   try {
     for await (const chunk of stream2) {
+      recordTuiJsonPayload(`stream_chunk:${chunk.message_type ?? "unknown"}`, chunk);
       if ((buffers.abortGeneration || 0) !== startAbortGen) {
         stopReason = "cancelled";
         queueMicrotask(refresh);
@@ -87581,6 +87718,7 @@ async function drainStream(stream2, buffers, refresh, abortSignal, onFirstMessag
         shouldAccumulate = shouldOutputChunk;
       }
       if (shouldAccumulate) {
+        recordTuiJsonPayload(`stream_accumulate:${chunk.message_type ?? "unknown"}`, chunk);
         onChunk(buffers, chunk, contextTracker);
         queueMicrotask(refresh);
       }
@@ -87663,6 +87801,7 @@ async function drainStream(stream2, buffers, refresh, abortSignal, onFirstMessag
 }
 async function drainStreamWithResume(stream2, buffers, refresh, abortSignal, onFirstMessage, onChunkProcessed, contextTracker, seenSeqIdThreshold) {
   const overallStartTime = performance.now();
+  recordTuiPerf("stream_lifecycle:start");
   const streamRequestContext = getStreamRequestContext(stream2);
   const streamOtid = streamRequestContext?.otid ?? null;
   let _client;
@@ -87785,6 +87924,9 @@ async function drainStreamWithResume(stream2, buffers, refresh, abortSignal, onF
     markCurrentLineAsFinished(buffers);
   }
   result.apiDurationMs = performance.now() - overallStartTime;
+  recordTuiPerf(`stream_lifecycle:end:${result.stopReason}`, {
+    ms: result.apiDurationMs
+  });
   return result;
 }
 var FALLBACK_RUN_DISCOVERY_TIMEOUT_MS = 5000;
@@ -87795,6 +87937,7 @@ var init_stream = __esm(async () => {
   init_debug();
   init_streamAbortRelay();
   init_timing();
+  init_tuiPerf();
   init_chunkLog();
   await __promiseAll([
     init_message(),
@@ -88893,22 +89036,12 @@ function emitToolExecutionFinishedEvents(socket, runtime, params) {
 }
 function createToolExecutionOutputEmitter(socket, runtime, params) {
   const outputByToolCallId = new Map;
-  return (toolCallId, chunk, isStderr = false) => {
-    if (!toolCallId || chunk.length === 0) {
+  const emitToolOutput = (toolCallId, outputState) => {
+    if (!outputState.dirty) {
       return;
     }
-    const existing = outputByToolCallId.get(toolCallId);
-    const outputState = existing ?? {
-      messageId: `message-tool-return-stream-${toolCallId}`,
-      stdout: "",
-      stderr: ""
-    };
-    if (isStderr) {
-      outputState.stderr = appendStreamingOutputWithCap(outputState.stderr, chunk);
-    } else {
-      outputState.stdout = appendStreamingOutputWithCap(outputState.stdout, chunk);
-    }
-    outputByToolCallId.set(toolCallId, outputState);
+    outputState.dirty = false;
+    outputState.lastEmittedAt = Date.now();
     const stdout = normalizeStreamingOutputLines(outputState.stdout);
     const stderr = normalizeStreamingOutputLines(outputState.stderr);
     const toolReturn = [stdout?.join(`
@@ -88938,6 +89071,52 @@ function createToolExecutionOutputEmitter(socket, runtime, params) {
       conversation_id: params.conversationId
     });
   };
+  const flushToolOutput = (toolCallId, outputState) => {
+    if (outputState.timer) {
+      clearTimeout(outputState.timer);
+      outputState.timer = null;
+    }
+    emitToolOutput(toolCallId, outputState);
+  };
+  const emitter = (toolCallId, chunk, isStderr = false) => {
+    if (!toolCallId || chunk.length === 0) {
+      return;
+    }
+    const existing = outputByToolCallId.get(toolCallId);
+    const outputState = existing ?? {
+      messageId: `message-tool-return-stream-${toolCallId}`,
+      stdout: "",
+      stderr: "",
+      dirty: false,
+      lastEmittedAt: 0,
+      timer: null
+    };
+    if (isStderr) {
+      outputState.stderr = appendStreamingOutputWithCap(outputState.stderr, chunk);
+    } else {
+      outputState.stdout = appendStreamingOutputWithCap(outputState.stdout, chunk);
+    }
+    outputByToolCallId.set(toolCallId, outputState);
+    outputState.dirty = true;
+    const now = Date.now();
+    const elapsed = now - outputState.lastEmittedAt;
+    if (elapsed >= STREAMING_TOOL_OUTPUT_EMIT_INTERVAL_MS) {
+      flushToolOutput(toolCallId, outputState);
+      return;
+    }
+    if (!outputState.timer) {
+      outputState.timer = setTimeout(() => {
+        outputState.timer = null;
+        emitToolOutput(toolCallId, outputState);
+      }, STREAMING_TOOL_OUTPUT_EMIT_INTERVAL_MS - elapsed);
+    }
+  };
+  emitter.flush = () => {
+    for (const [toolCallId, outputState] of outputByToolCallId.entries()) {
+      flushToolOutput(toolCallId, outputState);
+    }
+  };
+  return emitter;
 }
 function getInterruptApprovalsForEmission(runtime, params) {
   if (params.lastExecutionResults && params.lastExecutionResults.length > 0) {
@@ -89055,7 +89234,7 @@ function stashRecoveredApprovalInterrupts(runtime, recovered) {
   clearRecoveredApprovalState(runtime);
   return true;
 }
-var INTERRUPT_TOOL_RETURN_MAX_CHARS, STREAMING_TOOL_OUTPUT_MAX_CHARS;
+var INTERRUPT_TOOL_RETURN_MAX_CHARS, STREAMING_TOOL_OUTPUT_MAX_CHARS, STREAMING_TOOL_OUTPUT_EMIT_INTERVAL_MS = 100;
 var init_interrupts = __esm(async () => {
   init_approval_result_normalization();
   init_constants();
@@ -89892,16 +90071,21 @@ async function resolveRecoveredApprovalResponse(runtime, socket, response, proce
   runtime.currentToolsetPreference = preparedToolContext.toolsetPreference;
   runtime.currentLoadedTools = preparedToolContext.preparedToolContext.loadedToolNames;
   try {
-    const approvalResults = await executeApprovalBatch(decisions, undefined, {
-      abortSignal: recoveryAbortController.signal,
-      onStreamingOutput: emitToolExecutionOutput,
-      toolContextId: preparedToolContext.preparedToolContext.contextId,
-      workingDirectory,
-      parentScope: recovered.agentId && recovered.conversationId ? {
-        agentId: recovered.agentId,
-        conversationId: recovered.conversationId
-      } : undefined
-    });
+    let approvalResults;
+    try {
+      approvalResults = await executeApprovalBatch(decisions, undefined, {
+        abortSignal: recoveryAbortController.signal,
+        onStreamingOutput: emitToolExecutionOutput,
+        toolContextId: preparedToolContext.preparedToolContext.contextId,
+        workingDirectory,
+        parentScope: recovered.agentId && recovered.conversationId ? {
+          agentId: recovered.agentId,
+          conversationId: recovered.conversationId
+        } : undefined
+      });
+    } finally {
+      emitToolExecutionOutput.flush();
+    }
     emitToolExecutionFinishedEvents(socket, runtime, {
       approvals: approvalResults,
       runId: runtime.activeRunId ?? undefined,
@@ -89915,7 +90099,8 @@ async function resolveRecoveredApprovalResponse(runtime, socket, response, proce
     const continuationMessages = [
       {
         type: "approval",
-        approvals: approvalResults
+        approvals: approvalResults,
+        otid: crypto.randomUUID()
       }
     ];
     let continuationBatchId = `batch-recovered-${crypto.randomUUID()}`;
@@ -90309,6 +90494,18 @@ async function sendApprovalContinuationWithRetry(conversationId, messages, opts,
           retryAfterMs
         });
         transientRetries = attempt;
+        const retryMessage = getRetryStatusMessage(errorDetail);
+        if (retryMessage) {
+          emitRetryDelta(socket, runtime, {
+            message: retryMessage,
+            reason: "error",
+            attempt,
+            maxAttempts: LLM_API_ERROR_MAX_RETRIES,
+            delayMs,
+            agentId: runtime.agentId ?? undefined,
+            conversationId
+          });
+        }
         await new Promise((resolve27) => setTimeout(resolve27, delayMs));
         if (abortSignal?.aborted) {
           throw new Error("Cancelled by user");
@@ -90354,6 +90551,15 @@ async function sendApprovalContinuationWithRetry(conversationId, messages, opts,
           category: "conversation_busy",
           attempt: conversationBusyRetries
         });
+        emitRetryDelta(socket, runtime, {
+          message: "Conversation is busy, waiting and retrying…",
+          reason: "error",
+          attempt: conversationBusyRetries,
+          maxAttempts: MAX_CONVERSATION_BUSY_RETRIES,
+          delayMs: retryDelayMs,
+          agentId: runtime.agentId ?? undefined,
+          conversationId
+        });
         await new Promise((resolve27) => setTimeout(resolve27, retryDelayMs));
         if (abortSignal?.aborted) {
           throw new Error("Cancelled by user");
@@ -92710,14 +92916,19 @@ async function handleApprovalStop(params) {
       }));
     }
   };
-  const executionResults = await executeApprovalBatch(decisions, undefined, {
-    toolContextId: turnToolContextId ?? undefined,
-    abortSignal: abortController.signal,
-    onStreamingOutput: emitToolExecutionOutput,
-    workingDirectory: turnWorkingDirectory,
-    parentScope: agentId && conversationId ? { agentId, conversationId } : undefined,
-    onFileWrite
-  });
+  let executionResults;
+  try {
+    executionResults = await executeApprovalBatch(decisions, undefined, {
+      toolContextId: turnToolContextId ?? undefined,
+      abortSignal: abortController.signal,
+      onStreamingOutput: emitToolExecutionOutput,
+      workingDirectory: turnWorkingDirectory,
+      parentScope: agentId && conversationId ? { agentId, conversationId } : undefined,
+      onFileWrite
+    });
+  } finally {
+    emitToolExecutionOutput.flush();
+  }
   const persistedExecutionResults = normalizeExecutionResultsForInterruptParity(runtime, executionResults, lastExecutingToolCallIds);
   validateApprovalResultIds(decisions.map((decision) => ({
     approval: {
@@ -92738,7 +92949,8 @@ async function handleApprovalStop(params) {
   const nextInput = [
     {
       type: "approval",
-      approvals: persistedExecutionResults
+      approvals: persistedExecutionResults,
+      otid: crypto.randomUUID()
     }
   ];
   let continuationBatchId = dequeuedBatchId;
@@ -93898,7 +94110,115 @@ var init_commands = __esm(async () => {
 });
 
 // src/websocket/listener/protocol-outbound.ts
+import { appendFileSync as appendFileSync4, mkdirSync as mkdirSync22 } from "node:fs";
+import { dirname as dirname15 } from "node:path";
+import { performance as performance2 } from "node:perf_hooks";
 import WebSocket3 from "ws";
+function getProtocolPerfKey(message) {
+  if (message.type === "stream_delta" && "delta" in message) {
+    const delta = message.delta;
+    return `${message.type}:${String(delta.message_type ?? "unknown")}`;
+  }
+  return message.type;
+}
+function scheduleProtocolPerfFlush() {
+  if (protocolPerfFlushTimer) {
+    return;
+  }
+  protocolPerfFlushTimer = setTimeout(() => {
+    protocolPerfFlushTimer = null;
+    flushProtocolPerfTelemetry();
+  }, PROTOCOL_PERF_FLUSH_INTERVAL_MS);
+  const timerWithUnref = protocolPerfFlushTimer;
+  timerWithUnref.unref?.();
+}
+function recordProtocolPerfTelemetry(key, sample) {
+  if (protocolPerfWindowStartedAt === 0) {
+    protocolPerfWindowStartedAt = Date.now();
+  }
+  const bucket = protocolPerfBuckets.get(key) ?? {
+    count: 0,
+    bytes: 0,
+    stringifyMs: 0,
+    sendMs: 0,
+    maxBufferedBefore: 0,
+    maxBufferedAfter: 0
+  };
+  bucket.count += 1;
+  bucket.bytes += sample.bytes;
+  bucket.stringifyMs += sample.stringifyMs;
+  bucket.sendMs += sample.sendMs;
+  bucket.maxBufferedBefore = Math.max(bucket.maxBufferedBefore, sample.bufferedBefore);
+  bucket.maxBufferedAfter = Math.max(bucket.maxBufferedAfter, sample.bufferedAfter);
+  protocolPerfBuckets.set(key, bucket);
+  scheduleProtocolPerfFlush();
+}
+function writeProtocolPerfFile(record, fallbackLine) {
+  const filePath = PROTOCOL_PERF_FILE;
+  if (!filePath) {
+    console.error(fallbackLine);
+    return;
+  }
+  try {
+    const dir = dirname15(filePath);
+    if (protocolPerfFileDirEnsured !== dir) {
+      mkdirSync22(dir, { recursive: true });
+      protocolPerfFileDirEnsured = dir;
+    }
+    appendFileSync4(filePath, `${JSON.stringify(record)}
+`, {
+      encoding: "utf8"
+    });
+  } catch (error) {
+    if (!protocolPerfFileWarningEmitted) {
+      protocolPerfFileWarningEmitted = true;
+      console.error(`[Listen Perf] Failed to write LETTA_LISTENER_PERF_FILE=${filePath}`, error);
+    }
+    console.error(fallbackLine);
+  }
+}
+function flushProtocolPerfTelemetry() {
+  if (protocolPerfBuckets.size === 0) {
+    protocolPerfWindowStartedAt = 0;
+    return;
+  }
+  const windowMs = Math.max(1, Date.now() - protocolPerfWindowStartedAt);
+  const totals = {
+    count: 0,
+    bytes: 0,
+    stringifyMs: 0,
+    sendMs: 0,
+    maxBufferedBefore: 0,
+    maxBufferedAfter: 0
+  };
+  const buckets = {};
+  const parts = [...protocolPerfBuckets.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([key, bucket]) => {
+    totals.count += bucket.count;
+    totals.bytes += bucket.bytes;
+    totals.stringifyMs += bucket.stringifyMs;
+    totals.sendMs += bucket.sendMs;
+    totals.maxBufferedBefore = Math.max(totals.maxBufferedBefore, bucket.maxBufferedBefore);
+    totals.maxBufferedAfter = Math.max(totals.maxBufferedAfter, bucket.maxBufferedAfter);
+    buckets[key] = {
+      ...bucket,
+      avg_bytes: bucket.count > 0 ? bucket.bytes / bucket.count : 0,
+      avg_stringify_ms: bucket.count > 0 ? bucket.stringifyMs / bucket.count : 0,
+      avg_send_ms: bucket.count > 0 ? bucket.sendMs / bucket.count : 0
+    };
+    const stringifyMs = bucket.stringifyMs.toFixed(2);
+    const sendMs = bucket.sendMs.toFixed(2);
+    return `${key}{count=${bucket.count},bytes=${bucket.bytes},stringify_ms=${stringifyMs},send_ms=${sendMs},max_buffered_before=${bucket.maxBufferedBefore},max_buffered_after=${bucket.maxBufferedAfter}}`;
+  });
+  writeProtocolPerfFile({
+    ts: new Date().toISOString(),
+    event: "protocol_emit",
+    window_ms: windowMs,
+    totals,
+    buckets
+  }, `[Listen Perf] protocol_emit window_ms=${windowMs} ${parts.join(" ")}`);
+  protocolPerfBuckets.clear();
+  protocolPerfWindowStartedAt = 0;
+}
 function getCachedDeviceGitContext(cwd2) {
   const now = Date.now();
   const cached = gitContextCache.get(cwd2);
@@ -94105,8 +94425,24 @@ function emitProtocolV2Message(socket, runtime, message, scope) {
     emitted_at: new Date().toISOString(),
     idempotency_key: `${message.type}:${eventSeq}:${crypto.randomUUID()}`
   };
+  const perfEnabled = PROTOCOL_PERF_ENABLED;
+  const stringifyStartedAt = perfEnabled ? performance2.now() : 0;
+  let payload;
   try {
-    socket.send(JSON.stringify(outbound));
+    payload = JSON.stringify(outbound);
+    const stringifyMs = perfEnabled ? performance2.now() - stringifyStartedAt : 0;
+    const bufferedBefore = perfEnabled ? socket.bufferedAmount : 0;
+    const sendStartedAt = perfEnabled ? performance2.now() : 0;
+    socket.send(payload);
+    if (perfEnabled) {
+      recordProtocolPerfTelemetry(getProtocolPerfKey(message), {
+        bytes: Buffer.byteLength(payload),
+        stringifyMs,
+        sendMs: performance2.now() - sendStartedAt,
+        bufferedBefore,
+        bufferedAfter: socket.bufferedAmount
+      });
+    }
   } catch (error) {
     console.error(`[Listen V2] Failed to emit ${message.type} (seq=${eventSeq})`, error);
     safeEmitWsEvent("send", "lifecycle", {
@@ -94340,7 +94676,7 @@ function emitStreamDelta(socket, runtime, delta, scope, subagentId) {
   };
   emitProtocolV2Message(socket, runtime, message, scope);
 }
-var GIT_CONTEXT_CACHE_TTL_MS = 15000, MAX_GIT_CONTEXT_CACHE_ENTRIES = 64, gitContextCache;
+var GIT_CONTEXT_CACHE_TTL_MS = 15000, MAX_GIT_CONTEXT_CACHE_ENTRIES = 64, PROTOCOL_PERF_FLUSH_INTERVAL_MS = 1000, PROTOCOL_PERF_ENV_VALUES, PROTOCOL_PERF_ENABLED, PROTOCOL_PERF_FILE, protocolPerfBuckets, protocolPerfFlushTimer = null, protocolPerfWindowStartedAt = 0, protocolPerfFileDirEnsured = null, protocolPerfFileWarningEmitted = false, gitContextCache;
 var init_protocol_outbound = __esm(async () => {
   init_memoryFilesystem();
   init_gitContext();
@@ -94356,6 +94692,10 @@ var init_protocol_outbound = __esm(async () => {
   init_permissionMode();
   init_runtime4();
   await init_commands();
+  PROTOCOL_PERF_ENV_VALUES = new Set(["1", "true", "yes"]);
+  PROTOCOL_PERF_ENABLED = PROTOCOL_PERF_ENV_VALUES.has((process.env.LETTA_LISTENER_PERF ?? "").toLowerCase());
+  PROTOCOL_PERF_FILE = process.env.LETTA_LISTENER_PERF_FILE?.trim() || null;
+  protocolPerfBuckets = new Map;
   gitContextCache = new Map;
 });
 
@@ -97555,7 +97895,7 @@ async function handleSkillCommand(parsed, socket) {
   const {
     existsSync: existsSync30,
     lstatSync: lstatSync2,
-    mkdirSync: mkdirSync21,
+    mkdirSync: mkdirSync23,
     rmdirSync,
     symlinkSync,
     unlinkSync: unlinkSync8
@@ -97586,7 +97926,7 @@ async function handleSkillCommand(parsed, socket) {
       }
       const linkName = basename13(parsed.skill_path);
       const linkPath = join34(globalSkillsDir, linkName);
-      mkdirSync21(globalSkillsDir, { recursive: true });
+      mkdirSync23(globalSkillsDir, { recursive: true });
       if (existsSync30(linkPath)) {
         const stat7 = lstatSync2(linkPath);
         if (stat7.isSymbolicLink()) {
@@ -99786,9 +100126,9 @@ __export(exports_debug2, {
   debugLog: () => debugLog3
 });
 import {
-  appendFileSync as appendFileSync3,
+  appendFileSync as appendFileSync5,
   existsSync as existsSync31,
-  mkdirSync as mkdirSync22,
+  mkdirSync as mkdirSync24,
   readdirSync as readdirSync11,
   readFileSync as readFileSync22,
   unlinkSync as unlinkSync8
@@ -99809,7 +100149,7 @@ function printDebugLine2(line, level = "log") {
   const debugFile = getDebugFile2();
   if (debugFile) {
     try {
-      appendFileSync3(debugFile, line, { encoding: "utf8" });
+      appendFileSync5(debugFile, line, { encoding: "utf8" });
       return;
     } catch {}
   }
@@ -99835,7 +100175,7 @@ class DebugLogFile2 {
       return;
     this.ensureDir();
     try {
-      appendFileSync3(this.logPath, line, { encoding: "utf8" });
+      appendFileSync5(this.logPath, line, { encoding: "utf8" });
     } catch {}
   }
   getTail(maxLines = DEFAULT_TAIL_LINES2) {
@@ -99858,7 +100198,7 @@ class DebugLogFile2 {
       return;
     try {
       if (!existsSync31(this.agentDir)) {
-        mkdirSync22(this.agentDir, { recursive: true });
+        mkdirSync24(this.agentDir, { recursive: true });
       }
       this.dirCreated = true;
     } catch {}
@@ -99928,10 +100268,10 @@ __export(exports_skills2, {
 });
 import { existsSync as existsSync32 } from "node:fs";
 import { readdir as readdir8, readFile as readFile13, realpath as realpath4, stat as stat7 } from "node:fs/promises";
-import { dirname as dirname14, join as join38 } from "node:path";
+import { dirname as dirname16, join as join38 } from "node:path";
 import { fileURLToPath as fileURLToPath9 } from "node:url";
 function getBundledSkillsPath2() {
-  const thisDir = dirname14(fileURLToPath9(import.meta.url));
+  const thisDir = dirname16(fileURLToPath9(import.meta.url));
   if (thisDir.includes("src/agent") || thisDir.includes("src\\agent")) {
     return join38(thisDir, "../skills/builtin");
   }
@@ -100125,16 +100465,16 @@ import {
   existsSync as existsSync33,
   readFileSync as fsReadFileSync2,
   writeFileSync as fsWriteFileSync2,
-  mkdirSync as mkdirSync23
+  mkdirSync as mkdirSync25
 } from "node:fs";
-import { dirname as dirname15 } from "node:path";
+import { dirname as dirname17 } from "node:path";
 async function readFile14(path26) {
   return fsReadFileSync2(path26, { encoding: "utf-8" });
 }
 async function writeFile12(path26, content) {
-  const dir = dirname15(path26);
+  const dir = dirname17(path26);
   if (!existsSync33(dir)) {
-    mkdirSync23(dir, { recursive: true });
+    mkdirSync25(dir, { recursive: true });
   }
   fsWriteFileSync2(path26, content, { encoding: "utf-8", flush: true });
 }
@@ -100142,7 +100482,7 @@ function exists2(path26) {
   return existsSync33(path26);
 }
 async function mkdir9(path26, options) {
-  mkdirSync23(path26, options);
+  mkdirSync25(path26, options);
 }
 async function readJsonFile(path26) {
   const text = await readFile14(path26);
@@ -100275,7 +100615,7 @@ var exports_bootstrap_tools = {};
 __export(exports_bootstrap_tools, {
   bootstrapBaseToolsIfNeeded: () => bootstrapBaseToolsIfNeeded
 });
-import { existsSync as existsSync34, mkdirSync as mkdirSync24, writeFileSync as writeFileSync17 } from "node:fs";
+import { existsSync as existsSync34, mkdirSync as mkdirSync26, writeFileSync as writeFileSync17 } from "node:fs";
 import { homedir as homedir27 } from "node:os";
 import { join as join39 } from "node:path";
 async function bootstrapBaseToolsIfNeeded() {
@@ -100285,7 +100625,7 @@ async function bootstrapBaseToolsIfNeeded() {
   try {
     const success = await addBaseToolsToServer();
     if (success) {
-      mkdirSync24(join39(homedir27(), ".letta"), { recursive: true });
+      mkdirSync26(join39(homedir27(), ".letta"), { recursive: true });
       writeFileSync17(MARKER_PATH, new Date().toISOString(), "utf-8");
     }
   } catch (err) {
@@ -101989,7 +102329,7 @@ __export(exports_import, {
 });
 import { createReadStream } from "node:fs";
 import { chmod, mkdir as mkdir10, readFile as readFile15, writeFile as writeFile13 } from "node:fs/promises";
-import { dirname as dirname16, resolve as resolve30 } from "node:path";
+import { dirname as dirname18, resolve as resolve30 } from "node:path";
 async function importAgentFromFile(options) {
   const client = await getClient();
   const resolvedPath = resolve30(options.filePath);
@@ -102048,7 +102388,7 @@ async function writeSkillFiles(skillDir, files) {
 }
 async function writeSkillFile(skillDir, filePath, content) {
   const fullPath = resolve30(skillDir, filePath);
-  await mkdir10(dirname16(fullPath), { recursive: true });
+  await mkdir10(dirname18(fullPath), { recursive: true });
   await writeFile13(fullPath, content, "utf-8");
   const isScript = filePath.startsWith("scripts/") || content.trimStart().startsWith("#!");
   if (isScript) {
@@ -124703,7 +125043,7 @@ html.dark .agent-name { color: var(--text-dim); }
 var init_plan_viewer_template = () => {};
 
 // src/web/generate-plan-viewer.ts
-import { chmodSync as chmodSync2, existsSync as existsSync37, mkdirSync as mkdirSync27, writeFileSync as writeFileSync20 } from "node:fs";
+import { chmodSync as chmodSync2, existsSync as existsSync37, mkdirSync as mkdirSync29, writeFileSync as writeFileSync20 } from "node:fs";
 import { homedir as homedir31 } from "node:os";
 import { join as join44 } from "node:path";
 async function generateAndOpenPlanViewer(planContent, planFilePath, options) {
@@ -124716,7 +125056,7 @@ async function generateAndOpenPlanViewer(planContent, planFilePath, options) {
   const jsonPayload = JSON.stringify(data).replace(/</g, "\\u003c");
   const html = plan_viewer_template_default.replace("<!--LETTA_PLAN_DATA_PLACEHOLDER-->", () => jsonPayload);
   if (!existsSync37(VIEWERS_DIR)) {
-    mkdirSync27(VIEWERS_DIR, { recursive: true, mode: 448 });
+    mkdirSync29(VIEWERS_DIR, { recursive: true, mode: 448 });
   }
   try {
     chmodSync2(VIEWERS_DIR, 448);
@@ -128026,12 +128366,12 @@ __export(exports_terminalKeybindingInstaller, {
 import {
   copyFileSync,
   existsSync as existsSync39,
-  mkdirSync as mkdirSync28,
+  mkdirSync as mkdirSync30,
   readFileSync as readFileSync25,
   writeFileSync as writeFileSync21
 } from "node:fs";
 import { homedir as homedir32, platform as platform6 } from "node:os";
-import { dirname as dirname17, join as join46 } from "node:path";
+import { dirname as dirname19, join as join46 } from "node:path";
 function detectTerminalType() {
   if (process.env.CURSOR_TRACE_ID || process.env.CURSOR_CHANNEL) {
     return "cursor";
@@ -128122,9 +128462,9 @@ function installKeybinding(keybindingsPath) {
     if (keybindingExists(keybindingsPath)) {
       return { success: true, alreadyExists: true };
     }
-    const parentDir = dirname17(keybindingsPath);
+    const parentDir = dirname19(keybindingsPath);
     if (!existsSync39(parentDir)) {
-      mkdirSync28(parentDir, { recursive: true });
+      mkdirSync30(parentDir, { recursive: true });
     }
     let keybindings = [];
     let backupPath = null;
@@ -128281,9 +128621,9 @@ return config`);
 ${WEZTERM_DELETE_FIX}
 `;
     }
-    const parentDir = dirname17(configPath);
+    const parentDir = dirname19(configPath);
     if (!existsSync39(parentDir)) {
-      mkdirSync28(parentDir, { recursive: true });
+      mkdirSync30(parentDir, { recursive: true });
     }
     writeFileSync21(configPath, content, { encoding: "utf-8" });
     return {
@@ -128881,7 +129221,7 @@ __export(exports_custom, {
 });
 import { existsSync as existsSync40 } from "node:fs";
 import { readdir as readdir10, readFile as readFile16 } from "node:fs/promises";
-import { basename as basename14, dirname as dirname18, join as join47 } from "node:path";
+import { basename as basename14, dirname as dirname20, join as join47 } from "node:path";
 async function getCustomCommands() {
   if (cachedCommands !== null) {
     return cachedCommands;
@@ -128942,7 +129282,7 @@ async function parseCommandFile(filePath, rootPath, source2) {
   const content = await readFile16(filePath, "utf-8");
   const { frontmatter, body } = parseFrontmatter(content);
   const id = basename14(filePath, ".md");
-  const relativePath = dirname18(filePath).slice(rootPath.length);
+  const relativePath = dirname20(filePath).slice(rootPath.length);
   const namespace = relativePath.replace(/^[/\\]/, "") || undefined;
   let description = getStringField(frontmatter, "description");
   if (!description) {
@@ -134102,14 +134442,14 @@ var init_InputRich = __esm(async () => {
 import { execFileSync as execFileSync4 } from "node:child_process";
 import {
   existsSync as existsSync41,
-  mkdirSync as mkdirSync29,
+  mkdirSync as mkdirSync31,
   mkdtempSync,
   readFileSync as readFileSync26,
   rmSync as rmSync4,
   writeFileSync as writeFileSync22
 } from "node:fs";
 import { tmpdir as tmpdir6 } from "node:os";
-import { dirname as dirname19, join as join49 } from "node:path";
+import { dirname as dirname21, join as join49 } from "node:path";
 function runCommand(command, args, cwd2, input) {
   try {
     return execFileSync4(command, args, {
@@ -134356,8 +134696,8 @@ function runGit3(args, cwd2) {
 }
 function writeWorkflow(repoDir, workflowPath, content) {
   const absolutePath = join49(repoDir, workflowPath);
-  if (!existsSync41(dirname19(absolutePath))) {
-    mkdirSync29(dirname19(absolutePath), { recursive: true });
+  if (!existsSync41(dirname21(absolutePath))) {
+    mkdirSync31(dirname21(absolutePath), { recursive: true });
   }
   const next = `${content.trimEnd()}
 `;
@@ -138599,7 +138939,7 @@ __export(exports_generate_memory_viewer, {
   generateAndOpenMemoryViewer: () => generateAndOpenMemoryViewer
 });
 import { execFile as execFileCb3 } from "node:child_process";
-import { chmodSync as chmodSync3, existsSync as existsSync42, mkdirSync as mkdirSync30, writeFileSync as writeFileSync23 } from "node:fs";
+import { chmodSync as chmodSync3, existsSync as existsSync42, mkdirSync as mkdirSync32, writeFileSync as writeFileSync23 } from "node:fs";
 import { homedir as homedir34 } from "node:os";
 import { join as join50 } from "node:path";
 import { promisify as promisify13 } from "node:util";
@@ -138920,7 +139260,7 @@ async function generateAndOpenMemoryViewer(agentId, options) {
   const jsonPayload = JSON.stringify(data).replace(/</g, "\\u003c");
   const html = memory_viewer_template_default.replace("<!--LETTA_DATA_PLACEHOLDER-->", () => jsonPayload);
   if (!existsSync42(VIEWERS_DIR2)) {
-    mkdirSync30(VIEWERS_DIR2, { recursive: true, mode: 448 });
+    mkdirSync32(VIEWERS_DIR2, { recursive: true, mode: 448 });
   }
   try {
     chmodSync3(VIEWERS_DIR2, 448);
@@ -142730,7 +143070,7 @@ function formatDuration3(ms) {
   }
   return `${(ms / 1000).toFixed(1)}s`;
 }
-function formatNumber(n) {
+function formatNumber2(n) {
   return n.toLocaleString();
 }
 function formatUsageStats({
@@ -142752,7 +143092,7 @@ function formatUsageStats({
     const monthlyCredits = Math.round(balance.monthly_credit_balance);
     const purchasedCredits = Math.round(balance.purchased_credit_balance);
     const toDollars = (credits) => (credits / 1000).toFixed(2);
-    outputLines.push(`Plan: [${balance.billing_tier}]`, buildAppUrl("/settings/organization/usage"), "", `Available credits:     ◎${formatNumber(totalCredits)} ($${toDollars(totalCredits)})`, `Monthly credits:       ◎${formatNumber(monthlyCredits)} ($${toDollars(monthlyCredits)})`, `Purchased credits:     ◎${formatNumber(purchasedCredits)} ($${toDollars(purchasedCredits)})`);
+    outputLines.push(`Plan: [${balance.billing_tier}]`, buildAppUrl("/settings/organization/usage"), "", `Available credits:     ◎${formatNumber2(totalCredits)} ($${toDollars(totalCredits)})`, `Monthly credits:       ◎${formatNumber2(monthlyCredits)} ($${toDollars(monthlyCredits)})`, `Purchased credits:     ◎${formatNumber2(purchasedCredits)} ($${toDollars(purchasedCredits)})`);
   }
   return outputLines.join(`
 `);
@@ -150023,6 +150363,7 @@ function App2({
     streamingRefreshTimeoutRef.current = setTimeout(() => {
       streamingRefreshTimeoutRef.current = null;
       if (!buffersRef.current.interrupted) {
+        recordTuiPerf("ui_refresh:tool_output");
         refreshDerived();
       }
     }, 100);
@@ -150035,6 +150376,9 @@ function App2({
     };
   }, []);
   const updateStreamingOutput = import_react104.useCallback((toolCallId, chunk, isStderr = false) => {
+    recordTuiPerf(`tool_output:${isStderr ? "stderr" : "stdout"}`, {
+      bytes: Buffer.byteLength(chunk)
+    });
     const lineId = buffersRef.current.toolCallIdToLineId.get(toolCallId);
     if (!lineId)
       return;
@@ -150055,6 +150399,7 @@ function App2({
       setTimeout(() => {
         buffersRef.current.pendingRefresh = false;
         if (!buffersRef.current.interrupted && (buffersRef.current.commitGeneration || 0) === capturedGeneration) {
+          recordTuiPerf("ui_refresh:stream");
           refreshDerived();
         }
       }, 16);
@@ -157568,6 +157913,7 @@ var init_App2 = __esm(async () => {
   init_telemetry();
   init_toolset_labels();
   init_debug();
+  init_tuiPerf();
   init_version();
   init_mcp();
   init_profile();
@@ -157748,12 +158094,12 @@ __export(exports_terminalKeybindingInstaller2, {
 import {
   copyFileSync as copyFileSync2,
   existsSync as existsSync46,
-  mkdirSync as mkdirSync31,
+  mkdirSync as mkdirSync33,
   readFileSync as readFileSync29,
   writeFileSync as writeFileSync25
 } from "node:fs";
 import { homedir as homedir38, platform as platform7 } from "node:os";
-import { dirname as dirname20, join as join54 } from "node:path";
+import { dirname as dirname22, join as join54 } from "node:path";
 function detectTerminalType2() {
   if (process.env.CURSOR_TRACE_ID || process.env.CURSOR_CHANNEL) {
     return "cursor";
@@ -157844,9 +158190,9 @@ function installKeybinding2(keybindingsPath) {
     if (keybindingExists2(keybindingsPath)) {
       return { success: true, alreadyExists: true };
     }
-    const parentDir = dirname20(keybindingsPath);
+    const parentDir = dirname22(keybindingsPath);
     if (!existsSync46(parentDir)) {
-      mkdirSync31(parentDir, { recursive: true });
+      mkdirSync33(parentDir, { recursive: true });
     }
     let keybindings = [];
     let backupPath = null;
@@ -158003,9 +158349,9 @@ return config`);
 ${WEZTERM_DELETE_FIX2}
 `;
     }
-    const parentDir = dirname20(configPath);
+    const parentDir = dirname22(configPath);
     if (!existsSync46(parentDir)) {
-      mkdirSync31(parentDir, { recursive: true });
+      mkdirSync33(parentDir, { recursive: true });
     }
     writeFileSync25(configPath, content, { encoding: "utf-8" });
     return {
@@ -158573,7 +158919,7 @@ __export(exports_import2, {
 });
 import { createReadStream as createReadStream2 } from "node:fs";
 import { chmod as chmod2, mkdir as mkdir11, readFile as readFile19, writeFile as writeFile14 } from "node:fs/promises";
-import { dirname as dirname21, resolve as resolve35 } from "node:path";
+import { dirname as dirname23, resolve as resolve35 } from "node:path";
 async function importAgentFromFile2(options) {
   const client = await getClient();
   const resolvedPath = resolve35(options.filePath);
@@ -158632,7 +158978,7 @@ async function writeSkillFiles2(skillDir, files) {
 }
 async function writeSkillFile2(skillDir, filePath, content) {
   const fullPath = resolve35(skillDir, filePath);
-  await mkdir11(dirname21(fullPath), { recursive: true });
+  await mkdir11(dirname23(fullPath), { recursive: true });
   await writeFile14(fullPath, content, "utf-8");
   const isScript = filePath.startsWith("scripts/") || content.trimStart().startsWith("#!");
   if (isScript) {
@@ -158742,7 +159088,7 @@ __export(exports_memoryFilesystem2, {
   MEMORY_FS_MEMORY_DIR: () => MEMORY_FS_MEMORY_DIR2,
   MEMORY_FS_AGENTS_DIR: () => MEMORY_FS_AGENTS_DIR2
 });
-import { existsSync as existsSync47, mkdirSync as mkdirSync32 } from "node:fs";
+import { existsSync as existsSync47, mkdirSync as mkdirSync34 } from "node:fs";
 import { homedir as homedir40 } from "node:os";
 import { join as join56, resolve as resolve36 } from "node:path";
 function getMemoryFilesystemRoot2(agentId, homeDir = homedir40()) {
@@ -158778,10 +159124,10 @@ function ensureMemoryFilesystemDirs2(agentId, homeDir = homedir40()) {
   const root = getMemoryFilesystemRoot2(agentId, homeDir);
   const systemDir = getMemorySystemDir2(agentId, homeDir);
   if (!existsSync47(root)) {
-    mkdirSync32(root, { recursive: true });
+    mkdirSync34(root, { recursive: true });
   }
   if (!existsSync47(systemDir)) {
-    mkdirSync32(systemDir, { recursive: true });
+    mkdirSync34(systemDir, { recursive: true });
   }
 }
 async function isMemfsEnabledOnServer2(agentId) {
@@ -164102,51 +164448,141 @@ async function runListenSubcommand(argv) {
   }
 }
 
-// src/cli/subcommands/memfs.ts
+// src/cli/subcommands/memory.ts
 init_memoryGit();
-import { cpSync, existsSync as existsSync30, mkdirSync as mkdirSync21, rmSync as rmSync3, statSync as statSync8 } from "node:fs";
+import { cpSync, existsSync as existsSync30, mkdirSync as mkdirSync23, rmSync as rmSync3, statSync as statSync8 } from "node:fs";
 import { readdir as readdir7 } from "node:fs/promises";
 import { homedir as homedir23 } from "node:os";
 import { join as join34 } from "node:path";
 import { parseArgs as parseArgs8 } from "node:util";
+
+// src/cli/subcommands/memoryTokens.ts
+init_systemPromptSize();
+var DEFAULT_TOP = 20;
+var USAGE_EXIT = 64;
+var IO_EXIT = 65;
+function parsePositiveInt(raw, fallback) {
+  if (raw === undefined)
+    return fallback;
+  if (!/^\d+$/.test(raw))
+    return null;
+  return Number.parseInt(raw, 10);
+}
+function formatNumber(value) {
+  return value.toLocaleString("en-US");
+}
+function printText(total, files, top, quiet) {
+  console.log("System prompt token estimate");
+  console.log(`  Total: ${formatNumber(total)} tokens`);
+  if (quiet || top <= 0 || files.length === 0) {
+    return;
+  }
+  const ranked = [...files].sort((a, b) => b.tokens - a.tokens);
+  const limited = ranked.slice(0, top);
+  console.log("");
+  console.log("Top files:");
+  console.log(`  ${"tokens".padStart(8)}  path`);
+  for (const row of limited) {
+    console.log(`  ${formatNumber(row.tokens).padStart(8)}  ${row.path}`);
+  }
+}
+function printJson(total, files) {
+  console.log(JSON.stringify({
+    total_tokens: total,
+    files
+  }, null, 2));
+}
+function resolveMemoryDir3(options) {
+  if (options.memoryDir)
+    return options.memoryDir;
+  if (process.env.MEMORY_DIR)
+    return process.env.MEMORY_DIR;
+  if (options.agentMemoryDir)
+    return options.agentMemoryDir;
+  return null;
+}
+async function runMemoryTokensAction(options) {
+  const format2 = options.format ?? "text";
+  if (format2 !== "text" && format2 !== "json") {
+    console.error(`Invalid --format: ${format2} (expected text or json)`);
+    return USAGE_EXIT;
+  }
+  const top = parsePositiveInt(options.top, DEFAULT_TOP);
+  if (top === null) {
+    console.error(`Invalid --top: ${options.top} (expected non-negative integer)`);
+    return USAGE_EXIT;
+  }
+  const memoryDir = resolveMemoryDir3(options);
+  if (!memoryDir) {
+    console.error("Missing memory dir. Set --memory-dir, --agent, $MEMORY_DIR, or $LETTA_AGENT_ID.");
+    return USAGE_EXIT;
+  }
+  let estimate;
+  try {
+    estimate = estimateSystemPromptSize(memoryDir);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Failed to read memory dir: ${message}`);
+    return IO_EXIT;
+  }
+  const { total, files } = estimate;
+  if (format2 === "json") {
+    printJson(total, files);
+  } else {
+    printText(total, files, top, options.quiet);
+  }
+  return 0;
+}
+
+// src/cli/subcommands/memory.ts
 function printUsage5() {
   console.log(`
 Usage:
-  letta memfs status [--agent <id>]
-  letta memfs diff [--agent <id>]
-  letta memfs backup [--agent <id>]
-  letta memfs backups [--agent <id>]
-  letta memfs restore --from <backup> --force [--agent <id>]
-  letta memfs export --agent <id> --out <dir>
-  letta memfs pull [--agent <id>]
+  letta memory status [--agent <id>]
+  letta memory diff [--agent <id>]
+  letta memory backup [--agent <id>]
+  letta memory backups [--agent <id>]
+  letta memory restore --from <backup> --force [--agent <id>]
+  letta memory export --agent <id> --out <dir>
+  letta memory pull [--agent <id>]
+  letta memory tokens [--memory-dir <path>] [--agent <id>] [--top <N>]
+                     [--format text|json] [--quiet]
 
 Notes:
-  - Requires agent id via --agent or LETTA_AGENT_ID.
-  - Output is JSON only.
+  - Most actions require agent id via --agent or LETTA_AGENT_ID and output JSON.
+  - \`tokens\` additionally accepts --memory-dir or $MEMORY_DIR; reports the
+    estimated token size of system/. Policy (whether a size is concerning) is
+    up to the caller.
   - Memory is git-backed. Use git commands for commit/push.
 
 Examples:
-  LETTA_AGENT_ID=agent-123 letta memfs status
-  letta memfs pull --agent agent-123
-  letta memfs backup --agent agent-123
-  letta memfs export --agent agent-123 --out /tmp/letta-memfs-agent-123
+  LETTA_AGENT_ID=agent-123 letta memory status
+  letta memory pull --agent agent-123
+  letta memory backup --agent agent-123
+  letta memory export --agent agent-123 --out /tmp/letta-memory-agent-123
+  letta memory tokens
+  letta memory tokens --memory-dir ~/.letta/agents/agent-123/memory --format json
 `.trim());
 }
 function getAgentId5(agentFromArgs, agentIdFromArgs) {
   return agentFromArgs || agentIdFromArgs || process.env.LETTA_AGENT_ID || "";
 }
-var MEMFS_OPTIONS = {
+var MEMORY_OPTIONS = {
   help: { type: "boolean", short: "h" },
   agent: { type: "string" },
   "agent-id": { type: "string" },
   from: { type: "string" },
   force: { type: "boolean" },
-  out: { type: "string" }
+  out: { type: "string" },
+  "memory-dir": { type: "string" },
+  top: { type: "string" },
+  format: { type: "string" },
+  quiet: { type: "boolean" }
 };
-function parseMemfsArgs(argv) {
+function parseMemoryArgs(argv) {
   return parseArgs8({
     args: argv,
-    options: MEMFS_OPTIONS,
+    options: MEMORY_OPTIONS,
     strict: true,
     allowPositionals: true
   });
@@ -164198,10 +164634,10 @@ function resolveBackupPath(agentId, from) {
   }
   return join34(getAgentRoot(agentId), from);
 }
-async function runMemfsSubcommand(argv) {
+async function runMemorySubcommand(argv) {
   let parsed;
   try {
-    parsed = parseMemfsArgs(argv);
+    parsed = parseMemoryArgs(argv);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     console.error(`Error: ${message}`);
@@ -164214,6 +164650,15 @@ async function runMemfsSubcommand(argv) {
     return 0;
   }
   const agentId = getAgentId5(parsed.values.agent, parsed.values["agent-id"]);
+  if (action === "tokens") {
+    return runMemoryTokensAction({
+      memoryDir: parsed.values["memory-dir"],
+      agentMemoryDir: agentId ? getMemoryRoot(agentId) : undefined,
+      top: parsed.values.top,
+      format: parsed.values.format,
+      quiet: Boolean(parsed.values.quiet)
+    });
+  }
   if (!agentId) {
     console.error("Missing agent id. Set LETTA_AGENT_ID or pass --agent/--agent-id.");
     return 1;
@@ -164326,7 +164771,7 @@ async function runMemfsSubcommand(argv) {
           return 1;
         }
       } else {
-        mkdirSync21(out, { recursive: true });
+        mkdirSync23(out, { recursive: true });
       }
       cpSync(root, out, { recursive: true });
       console.log(JSON.stringify({ exportedFrom: root, exportedTo: out, agentId }, null, 2));
@@ -164685,8 +165130,9 @@ async function runSubcommand(argv) {
     return null;
   }
   switch (command) {
+    case "memory":
     case "memfs":
-      return runMemfsSubcommand(rest);
+      return runMemorySubcommand(rest);
     case "agents":
       return runAgentsSubcommand(rest);
     case "messages":
@@ -166855,7 +167301,7 @@ USAGE
 
   # maintenance
   letta update          Manually check for updates and install if available
-  letta memfs ...       Memory filesystem subcommands (JSON-only)
+  letta memory ...      Memory filesystem subcommands
   letta agents ...      Agents subcommands (JSON-only)
   letta messages ...    Messages subcommands (JSON-only)
   letta blocks ...      Blocks subcommands (JSON-only)
@@ -166864,14 +167310,16 @@ USAGE
 OPTIONS
 ${renderCliOptionsHelp()}
 
-SUBCOMMANDS (JSON-only)
-  letta memfs status --agent <id>
-  letta memfs diff --agent <id>
-  letta memfs resolve --agent <id> --resolutions '<JSON>'
-  letta memfs backup --agent <id>
-  letta memfs backups --agent <id>
-  letta memfs restore --agent <id> --from <backup> --force
-  letta memfs export --agent <id> --out <dir>
+SUBCOMMANDS
+  letta memory status --agent <id>
+  letta memory diff --agent <id>
+  letta memory resolve --agent <id> --resolutions '<JSON>'
+  letta memory backup --agent <id>
+  letta memory backups --agent <id>
+  letta memory restore --agent <id> --from <backup> --force
+  letta memory export --agent <id> --out <dir>
+  letta memory pull --agent <id>
+  letta memory tokens [--memory-dir <path>] [--agent <id>] [--format text|json]
   letta agents list [--query <text> | --name <name> | --tags <tags>]
   letta messages search --query <text> [--all-agents]
   letta messages list [--agent <id>]
@@ -168205,4 +168653,4 @@ Error during initialization: ${message}`);
 }
 main();
 
-//# debugId=876580101EC255F264756E2164756E21
+//# debugId=22CE2EBE31776A7764756E2164756E21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.24.2",
+  "version": "0.24.3",
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
   "bin": {

package/skills/migrating-memory/SKILL.md

@@ -30,7 +30,7 @@ This is the recommended flow:
 
 1. **Export the source agent's memfs to a temp directory**
    ```bash
-   letta memfs export --agent <source-agent-id> --out /tmp/letta-memfs-<source-agent-id>
+   letta memory export --agent <source-agent-id> --out /tmp/letta-memory-<source-agent-id>
    ```
 
 2. **Copy the files you want into your own memfs**
@@ -39,13 +39,16 @@ This is the recommended flow:
 
    Example:
    ```bash
-   cp -r /tmp/letta-memfs-agent-abc123/system/project ~/.letta/agents/$LETTA_AGENT_ID/memory/system/
-   cp /tmp/letta-memfs-agent-abc123/notes.md ~/.letta/agents/$LETTA_AGENT_ID/memory/
+   cp -r /tmp/letta-memory-agent-abc123/system/project ~/.letta/agents/$LETTA_AGENT_ID/memory/system/
+   cp /tmp/letta-memory-agent-abc123/notes.md ~/.letta/agents/$LETTA_AGENT_ID/memory/
    ```
 
-3. **Sync to API**
+3. **Commit and push the memory repo**
    ```bash
-   letta memfs sync --agent $LETTA_AGENT_ID
+   cd ~/.letta/agents/$LETTA_AGENT_ID/memory
+   git add system/project notes.md
+   git commit -m "Import memory from source agent"
+   git push
    ```
 
 This gives you full control over what you bring across and keeps everything consistent with memfs.
@@ -107,15 +110,18 @@ Scenario: You're a new agent and want to inherit memory from an existing agent "
 
 2. **Export their memfs:**
    ```bash
-   letta memfs export --agent agent-abc123 --out /tmp/letta-memfs-agent-abc123
+   letta memory export --agent agent-abc123 --out /tmp/letta-memory-agent-abc123
    ```
 
 3. **Copy the relevant files into your memfs:**
    ```bash
-   cp -r /tmp/letta-memfs-agent-abc123/system/project ~/.letta/agents/$LETTA_AGENT_ID/memory/system/
+   cp -r /tmp/letta-memory-agent-abc123/system/project ~/.letta/agents/$LETTA_AGENT_ID/memory/system/
    ```
 
-4. **Sync:**
+4. **Commit and push:**
    ```bash
-   letta memfs sync --agent $LETTA_AGENT_ID
+   cd ~/.letta/agents/$LETTA_AGENT_ID/memory
+   git add system/project
+   git commit -m "Import project memory"
+   git push
    ```