feat(listener): add stateless app-server sessions

scripts/source-file-size-baseline.json

@@ -46,6 +46,6 @@
   "src/websocket/listener/file-commands.ts": 1053,
   "src/websocket/listener/lifecycle.ts": 1051,
   "src/websocket/listener/protocol-inbound.ts": 2264,
-  "src/websocket/listener/protocol-outbound.ts": 1085,
+  "src/websocket/listener/protocol-outbound.ts": 1083,
   "src/websocket/listener/turn.ts": 1010
 }

src/runtime-context.ts

@@ -19,6 +19,8 @@ export interface RuntimeContextSnapshot {
   conversationId?: string | null;
   skillsDirectory?: string | null;
   skillSources?: SkillSource[];
+  /** Runtime override for whether tools may project the agent's MemFS. */
+  memfsEnabled?: boolean;
   workingDirectory?: string | null;
   /**
    * Set when the runtime-scoped working directory was found deleted and

src/tools/impl/shell-env.ts

@@ -375,10 +375,11 @@ export function getShellEnv(): NodeJS.ProcessEnv {
       const localBackendEnabled =
         process.env.LETTA_LOCAL_BACKEND_EXPERIMENTAL === "1" ||
         process.env.LETTA_LOCAL_BACKEND_EXPERIMENTAL?.toLowerCase() === "true";
-      if (
-        !localBackendNoMemfs &&
-        (settingsManager.isMemfsEnabled(agentId) || localBackendEnabled)
-      ) {
+      const runtimeMemfsEnabled = getRuntimeContext()?.memfsEnabled;
+      const memfsEnabled =
+        runtimeMemfsEnabled ??
+        (settingsManager.isMemfsEnabled(agentId) || localBackendEnabled);
+      if (!localBackendNoMemfs && memfsEnabled) {
         const memoryDir = resolveScopedMemoryDir({ agentId });
         if (!memoryDir) {
           throw new Error("Unable to resolve memory directory");

src/tools/toolset.ts

@@ -375,6 +375,7 @@ export async function prepareToolExecutionContextForScope(params: {
   modContext?: ModContext;
   modEvents?: ModEvents;
   modAdapters?: ModAdapter[];
+  runtimeContext?: Partial<RuntimeContextSnapshot>;
 }): Promise<PreparedScopeToolContext> {
   const {
     connectionId,
@@ -396,6 +397,7 @@ export async function prepareToolExecutionContextForScope(params: {
     modContext,
     modEvents,
     modAdapters,
+    runtimeContext,
   } = params;
 
   const backend = getBackend();
@@ -462,6 +464,7 @@ export async function prepareToolExecutionContextForScope(params: {
     modAdapters,
     agent: agent as AgentState,
     runtimeContext: {
+      ...runtimeContext,
       connectionId,
       environmentDeviceId,
       agentId,

src/types/protocol_v2.ts

@@ -783,13 +783,11 @@ export interface RuntimeStartCreateConversationOptions {
   /** Body forwarded to the Letta conversations create API. */
   body?: Omit<ConversationCreateParams, "agent_id">;
 }
-
 export interface RuntimeStartClientInfo {
   name: string;
   title?: string;
   version?: string;
 }
-
 export interface RuntimeStartCommand {
   type: "runtime_start";
   /** Echoed back in the response for request correlation. */
@@ -808,6 +806,8 @@ export interface RuntimeStartCommand {
   cwd?: string | null;
   /** Initial permission mode for this runtime scope. */
   mode?: DevicePermissionMode;
+  /** Runtime-only policy that skips local MemFS reads and writes. */
+  stateless?: boolean;
   skill_sources?: readonly ("bundled" | "global" | "agent" | "project")[];
   /** Preserve the current override when skill_sources is omitted. */ preserve_skill_sources?: boolean;
   /** Optional client metadata for diagnostics/future protocol negotiation. */

src/websocket/listener/commands.ts

@@ -6,7 +6,6 @@ import {
   applySetMaxContext,
   formatSetMaxContextResult,
 } from "@/agent/max-context";
-import { getScopedMemoryFilesystemRoot } from "@/agent/memory-filesystem";
 import { REMEMBER_PROMPT } from "@/agent/prompt-assets";
 import type { ConversationMessageCompactBody } from "@/backend";
 import { getBackend } from "@/backend";
@@ -54,6 +53,10 @@ import {
 } from "./protocol-outbound";
 import { flushRemoteSettingsWrites } from "./remote-settings";
 import { clearConversationRuntimeState, emitListenerStatus } from "./runtime";
+import {
+  getConversationMemoryDirectory,
+  isConversationMemfsEnabled,
+} from "./runtime-memory";
 import {
   ensureSecretsHydratedForAgent,
   invalidateSecretsCacheForAgent,
@@ -111,6 +114,15 @@ export async function handleExecuteCommand(
   try {
     let output: string;
 
+    if (
+      conversationRuntime.stateless &&
+      ["doctor", "init", "remember", "reflect"].includes(command.command_id)
+    ) {
+      throw new Error(
+        `/${command.command_id} is unavailable in a stateless runtime because it writes agent memory.`,
+      );
+    }
+
     switch (command.command_id) {
       case "clear":
         output = await handleClearCommand(socket, conversationRuntime, {
@@ -341,7 +353,10 @@ export async function handleReloadCommand(
     );
   }
 
-  await reloadListenerModAdapter(listener, conversationRuntime.agentId);
+  await reloadListenerModAdapter(
+    listener,
+    conversationRuntime.stateless ? undefined : conversationRuntime.agentId,
+  );
 
   if (conversationRuntime.agentId) {
     invalidateSecretsCacheForAgent(listener, conversationRuntime.agentId);
@@ -558,7 +573,7 @@ async function handleCompactCommand(
       );
       if (
         reflectionSettings.trigger === "compaction-event" &&
-        settingsManager.isMemfsEnabled(agentId)
+        isConversationMemfsEnabled(conversationRuntime)
       ) {
         void buildMaybeLaunchReflectionSubagent({
           runtime: conversationRuntime,
@@ -687,9 +702,8 @@ async function handleDoctorCommand(
   }
 
   const { context: gitContext } = gatherInitGitContext();
-  const memoryDir = settingsManager.isMemfsEnabled(agentId)
-    ? getScopedMemoryFilesystemRoot(agentId)
-    : undefined;
+  const memoryDir =
+    getConversationMemoryDirectory(conversationRuntime) ?? undefined;
   const skillNameFrontmatterRepair =
     await repairMissingSkillNameFrontmatter(memoryDir);
   const skillNameFrontmatterRepairReport =
@@ -747,9 +761,8 @@ async function handleInitCommand(
   }
 
   const { context: gitContext } = gatherInitGitContext();
-  const memoryDir = settingsManager.isMemfsEnabled(agentId)
-    ? getScopedMemoryFilesystemRoot(agentId)
-    : undefined;
+  const memoryDir =
+    getConversationMemoryDirectory(conversationRuntime) ?? undefined;
 
   const initMessage = buildInitMessage({ gitContext, memoryDir });
 
@@ -900,7 +913,7 @@ async function handleReflectCommand(
   const result = await launchReflectionSubagent({
     agentId,
     conversationId,
-    memfsEnabled: settingsManager.isMemfsEnabled(agentId),
+    memfsEnabled: isConversationMemfsEnabled(conversationRuntime),
     triggerSource: "manual",
     description: "Reflecting on conversation",
     recompileByConversation: listener.systemPromptRecompileByConversation,

src/websocket/listener/commands/runtime-start-skill-sources.test.ts

@@ -62,6 +62,68 @@ describe("runtime_start skill sources", () => {
     }
   });
 
+  test("keeps stateless policy across idle runtime eviction until reset", async () => {
+    const storageDir = await mkdtemp(join(tmpdir(), "runtime-stateless-"));
+    try {
+      const backend = new LocalBackend({
+        storageDir,
+        executionMode: "deterministic",
+      });
+      __testSetBackend(backend);
+      const agent = await backend.createAgent({
+        name: "Stateless SDK worker",
+        model: "anthropic/claude-sonnet-4-6",
+      } as AgentCreateBody);
+      const listener = createRuntime();
+      const context = {
+        socket: {} as WebSocket,
+        connectionId: "test-connection",
+        runtime: listener,
+        safeSocketSend: () => true,
+        runDetachedListenerTask: () => {},
+        getOrCreateScopedRuntime,
+        replaySyncStateForRuntime: async () => {},
+      };
+
+      await handleRuntimeStartCommand(
+        {
+          type: "runtime_start",
+          request_id: "runtime-stateless",
+          agent_id: agent.id,
+          conversation_id: "default",
+          stateless: true,
+          recover_approvals: false,
+        },
+        context,
+      );
+
+      const scoped = getOrCreateScopedRuntime(listener, agent.id, "default");
+      expect(scoped.stateless).toBe(true);
+      expect(listener.statelessByConversation?.has(scoped.key)).toBe(true);
+      expect(evictConversationRuntimeIfIdle(scoped)).toBe(true);
+      expect(
+        getOrCreateScopedRuntime(listener, agent.id, "default").stateless,
+      ).toBe(true);
+
+      await handleRuntimeStartCommand(
+        {
+          type: "runtime_start",
+          request_id: "runtime-stateful",
+          agent_id: agent.id,
+          conversation_id: "default",
+          recover_approvals: false,
+        },
+        context,
+      );
+      expect(
+        getOrCreateScopedRuntime(listener, agent.id, "default").stateless,
+      ).toBe(false);
+      expect(listener.statelessByConversation?.has(scoped.key)).toBe(false);
+    } finally {
+      await rm(storageDir, { recursive: true, force: true });
+    }
+  });
+
   test("preserves skill sources when a secondary controller updates runtime tools", async () => {
     const storageDir = await mkdtemp(join(tmpdir(), "runtime-skills-"));
     try {

src/websocket/listener/commands/runtime-start.ts

@@ -22,6 +22,7 @@ import {
   persistPermissionModeMapForRuntime,
 } from "@/websocket/listener/permission-mode";
 import { isRuntimeStartCommand } from "@/websocket/listener/protocol-inbound";
+import { setConversationRuntimeStateless } from "@/websocket/listener/runtime-memory";
 import type {
   ConversationRuntime,
   ListenerConnectionId,
@@ -305,6 +306,8 @@ async function applyRuntimeStartState(
     );
   }
 
+  setConversationRuntimeStateless(scopedRuntime, parsed.stateless === true);
+
   if (parsed.mode) {
     const mode = migratePermissionMode(parsed.mode);
     if (!mode) {

src/websocket/listener/lifecycle.ts

@@ -284,7 +284,6 @@ function stampInboundUserMessageOtids(
 }
 
 export function createRuntime(): ListenerRuntime {
-  const bootWorkingDirectory = getCurrentWorkingDirectory();
   return {
     socket: null,
     transport: null,
@@ -312,11 +311,12 @@ export function createRuntime(): ListenerRuntime {
     pendingQueueEmitScope: undefined,
     onWsEvent: undefined,
     reminderState: createSharedReminderState(),
-    bootWorkingDirectory,
+    bootWorkingDirectory: getCurrentWorkingDirectory(),
     workingDirectoryByConversation: loadPersistedCwdMap(),
     worktreeWatcherByConversation: new Map(),
     permissionModeByConversation: loadPersistedPermissionModeMap(),
     skillSourcesByConversation: new Map(),
+    statelessByConversation: new Set(),
     reminderStateByConversation: new Map(),
     contextTrackerByConversation: new Map(),
     systemPromptRecompileByConversation: new Map(),

src/websocket/listener/message-router.ts

@@ -4,7 +4,6 @@ import {
   estimateSystemPromptTokensFromMemoryDir,
   setSystemPromptDoctorState,
 } from "@/cli/helpers/system-prompt-warning";
-import { settingsManager } from "@/settings-manager";
 import type {
   AbortMessageCommand,
   ApprovalResponseBody,
@@ -63,6 +62,7 @@ import {
 } from "./queue";
 import { emitLoopErrorNotice } from "./recoverable-notices";
 import { getActiveRuntime, safeEmitWsEvent } from "./runtime";
+import { isConversationMemfsEnabled } from "./runtime-memory";
 import type { ListenerTransport } from "./transport";
 import { handleIncomingMessage } from "./turn";
 import type {
@@ -761,7 +761,12 @@ export function createListenerMessageHandler(
         // Internal-only: refresh doctor state after recompile (no chat output)
         if (parsed.command_id === "refresh_doctor_state") {
           const agentId = parsed.runtime.agent_id;
-          if (agentId && settingsManager.isMemfsEnabled(agentId)) {
+          const doctorRuntime = getOrCreateScopedRuntime(
+            runtime,
+            agentId,
+            parsed.runtime.conversation_id,
+          );
+          if (agentId && isConversationMemfsEnabled(doctorRuntime)) {
             try {
               const { getScopedMemoryFilesystemRoot } = await import(
                 "@/agent/memory-filesystem"

src/websocket/listener/mod-adapter.ts

@@ -91,6 +91,7 @@ export function createListenerModContext(
         reasoning_effort?: string | null;
       } | null;
     } | null;
+    memfsEnabled?: boolean;
     modelIdentifier?: string | null;
     permissionMode?: string | null;
     toolset?: string | null;
@@ -107,12 +108,21 @@ export function createListenerModContext(
   });
   return {
     ...context,
-    memfs: resolveListenerAgentMemfsContext(context.agent.id),
+    memfs:
+      options.memfsEnabled === false
+        ? { enabled: false, memoryDir: null }
+        : resolveListenerAgentMemfsContext(context.agent.id),
   };
 }
 
-export function createListenerAgentModContext(agentId: string): ModContext {
-  return createListenerModContext({ agent: { id: agentId } });
+export function createListenerAgentModContext(
+  agentId: string,
+  memfsEnabled?: boolean,
+): ModContext {
+  return createListenerModContext({
+    agent: { id: agentId },
+    ...(memfsEnabled !== undefined ? { memfsEnabled } : {}),
+  });
 }
 
 export function createListenerModAdapter(
@@ -235,8 +245,12 @@ export async function ensureListenerAgentModAdapter(
 export async function ensureListenerModAdaptersForAgent(
   runtime: ListenerRuntime,
   agentId: string,
+  options: { includeAgent?: boolean } = {},
 ): Promise<ModAdapter[]> {
   const globalAdapter = ensureListenerModAdapter(runtime);
+  if (options.includeAgent === false) {
+    return [globalAdapter];
+  }
   const agentAdapter = await ensureListenerAgentModAdapter(runtime, agentId);
   return agentAdapter ? [globalAdapter, agentAdapter] : [globalAdapter];
 }

src/websocket/listener/protocol-inbound.test.ts

@@ -109,6 +109,7 @@ describe("agent/conversation management protocol-inbound validators", () => {
       conversation_source_tags: ["channel:slack"],
       cwd: "/tmp/project",
       mode: "acceptEdits",
+      stateless: true,
       skill_sources: [],
       preserve_skill_sources: true,
       client_info: { name: "test", title: "Test", version: "1.0.0" },
@@ -239,6 +240,12 @@ describe("agent/conversation management protocol-inbound validators", () => {
       agent_id: "agent-1",
       mode: "bad",
     },
+    {
+      type: "runtime_start",
+      request_id: "r0",
+      agent_id: "agent-1",
+      stateless: "yes",
+    },
     {
       type: "runtime_start",
       request_id: "r0",

src/websocket/listener/protocol-inbound.ts

@@ -522,7 +522,6 @@ function isRuntimeStartClientInfo(value: unknown): boolean {
     (value.version === undefined || typeof value.version === "string")
   );
 }
-
 export function isRuntimeStartCommand(
   value: unknown,
 ): value is RuntimeStartCommand {
@@ -542,6 +541,7 @@ export function isRuntimeStartCommand(
       isStringArray(c.conversation_source_tags)) &&
     (c.cwd === undefined || c.cwd === null || typeof c.cwd === "string") &&
     (c.mode === undefined || isDevicePermissionMode(c.mode)) &&
+    (c.stateless === undefined || typeof c.stateless === "boolean") &&
     (c.skill_sources === undefined || isSkillSourceArray(c.skill_sources)) &&
     (c.preserve_skill_sources === undefined ||
       typeof c.preserve_skill_sources === "boolean") &&