@letta-ai/letta-agent-sdk 0.2.7 → 0.3.1

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm](https://img.shields.io/npm/v/@letta-ai/letta-agent-sdk.svg?style=flat-square)](https://www.npmjs.com/package/@letta-ai/letta-agent-sdk) [![Discord](https://img.shields.io/badge/discord-join-blue?style=flat-square&logo=discord)](https://discord.gg/letta)
 
-The SDK interface to [**Letta Code**](https://github.com/letta-ai/letta-code). Build agents with persistent memory that learn over time. 
+Build applications with stateful agents powered by the [Letta agent harness](https://www.letta.com/agent). The Agent SDK provides one TypeScript interface for managed, local, and self-hosted deployments.
 
 ## Installation
 
@@ -10,399 +10,165 @@ The SDK interface to [**Letta Code**](https://github.com/letta-ai/letta-code). B
 npm install @letta-ai/letta-agent-sdk
 ```
 
-## Quick start
+Local execution requires Node.js 22.19 or newer.
 
-### Client creation
+## Quick start
 
 ```ts
 import { LettaAgentClient } from "@letta-ai/letta-agent-sdk";
 
-// Local: SDK-owned Letta Code app-server over loopback websockets. The SDK
-// spawns/manages the app-server process for you.
-const localClient = new LettaAgentClient({ backend: "local" });
-
-// Remote: connect to a user-managed Letta Code app-server over websockets.
-const remoteClient = new LettaAgentClient({
-  backend: "remote",
-  url: "http://127.0.0.1:4500",
-  // Required when the app-server is bound to a non-loopback interface with
-  // --ws-auth capability-token.
-  authToken: process.env.LETTA_APP_SERVER_TOKEN,
-});
-
-// Constellation: create or resume agents whose state lives in Letta's
-// agent cloud, with an SDK-managed sandbox by default.
 const client = new LettaAgentClient({
   backend: "cloud",
   apiKey: process.env.LETTA_API_KEY,
 });
-```
-
-### Persistent agent with multi-turn conversations
-
-```ts
-import { LettaAgentClient } from "@letta-ai/letta-agent-sdk";
-
-const client = new LettaAgentClient({ backend: "local" });
 
 const agentId = await client.createAgent({
-  persona: "You are a helpful coding assistant for TypeScript projects.",
-});
-
-await using session = client.resumeSession(agentId);
-
-await session.send("Find and fix the bug in auth.ts");
-for await (const msg of session.stream()) {
-  if (msg.type === "assistant") console.log(msg.content);
-}
-
-await session.send("Add a unit test for the fix");
-for await (const msg of session.stream()) {
-  if (msg.type === "assistant") console.log(msg.content);
-}
-```
-
-Cloud, remote, and local agent sessions can accept another `send()` while a
-turn is streaming. The SDK sends the same `input` frame used by Letta Desktop
-and the listener owns queueing; `stream()` may surface `queue_update` events
-before the current turn's `result`.
-
-By default, `resumeSession(agentId)` continues the agent’s default conversation.
-Use `createSession(agentId)` when you want to start a fresh thread.
-
-For Constellation agents, omitting `environment` lets the SDK create and manage
-a sandbox for the session. `environment` is still session-scoped and can
-override the client default when you want to use a specific remote runtime:
-
-```ts
-await using session = client.resumeSession(agentId, {
-  environment: { name: "LettaDevelopers" },
-});
-```
-
-The top-level helpers (`createAgent`, `createSession`, `resumeSession`, and
-`prompt`) remain available. Local helper calls use Letta Code's default agent
-selection when you do not pass an agent ID.
-
-### User-managed app-server backend
-
-Use `backend: "remote"` when you already have a Letta Code app-server running.
-The app-server URL selects the execution environment; the SDK uses the same
-Letta Code websocket protocol for `runtime_start`, `input`, streaming deltas,
-and SDK-defined external tools.
-
-```ts
-const client = new LettaAgentClient({
-  backend: "remote",
-  url: "http://127.0.0.1:4500",
-  authToken: process.env.LETTA_APP_SERVER_TOKEN,
-  requestTimeoutMs: 120_000,
-});
-
-const agentId = await client.createAgent({
-  model: "anthropic/claude-sonnet-4",
-  persona: "You are a helpful coding assistant.",
+  model: "anthropic/claude-opus-4-8",
+  persona: "You are a proactive research assistant.",
+  human: "The user prefers concise summaries with sources and next steps.",
 });
 
 await using session = client.createSession(agentId);
 
-await session.send("Summarize this repository.");
-for await (const msg of session.stream()) {
-  if (msg.type === "assistant") console.log(msg.content);
+await session.send("Research the latest project changes and prepare a brief.");
+for await (const message of session.stream()) {
+  if (message.type === "assistant") {
+    console.log(message.content);
+  }
 }
 ```
 
+An agent is the persistent entity with memory. A conversation is a thread on that agent. A session is the active connection used to send messages, stream events, execute tools, and handle approvals.
 
-### Constellation
+- `createSession(agentId)` starts a new conversation.
+- `resumeSession(conversationId)` resumes a saved conversation.
+- `resumeSession(agentId)` resumes the agent's default conversation.
+- `prompt(message, agentId)` runs a one-shot prompt in a new conversation.
 
-Use `backend: "cloud"` to create or resume agents hosted on Constellation. If
-no `environment` is provided, the SDK creates a managed sandbox, waits for it to
-come online, and refreshes it while the session is active. Non-default
-conversations request a conversation-scoped sandbox from supporting servers;
-the default conversation and legacy servers retain the agent-scoped lifecycle.
-Managed sandboxes are left for TTL cleanup by default so another session for the
-same conversation can reconnect to them.
+Portable sessions also expose the stateful controls needed by interactive
+clients:
 
 ```ts
-const client = new LettaAgentClient({
-  backend: "cloud",
-  apiKey: process.env.LETTA_API_KEY,
-  sandbox: {
-    // Optional: defaults to a 5-minute refresh TTL.
-    ttlMinutes: 5,
-    // Optional: defaults false. Set true only with exclusive ownership.
-    terminateOnClose: false,
-  },
-});
-
-const agentId = await client.createAgent({
-  model: "anthropic/claude-sonnet-4",
-  persona: "You are a helpful coding assistant.",
-});
-
-await using session = client.resumeSession(agentId, {
-  permissionMode: "unrestricted",
+const state = await session.bootstrapState();
+await session.changeDeviceState({
+  cwd: "/workspace/project",
+  permissionMode: "acceptEdits",
 });
 
-await session.send("Summarize this repository.");
-for await (const msg of session.stream()) {
-  if (msg.type === "assistant") console.log(msg.content);
+const removed = await session.removeQueuedMessage(queueItemId);
+if (!removed.removed) {
+  // Reconcile the authoritative queue before offering the action again.
 }
+
+await session.recoverPendingApprovals();
 ```
 
-If you pass `cwd` for a Constellation session, use a path that exists inside the
-selected remote environment or managed sandbox. Local paths such as
-`process.cwd()` are not mapped into managed sandboxes automatically.
+`removeQueuedMessage()` waits for an app-server acknowledgement.
+`changeDeviceState()` currently confirms command transport only because the
+underlying protocol does not acknowledge that mutation.
 
-You can still set a default `environment` on the client or override it per
-session to use an existing remote runtime instead of an SDK-managed sandbox. Use
-the environment name from `letta remote --env-name <name>`:
+The read side of the device state is exposed as a one-shot getter and a
+subscription — enough to restore permission-mode UI and re-surface pending
+approvals when a mobile or web client returns to the foreground:
 
 ```ts
-const client = new LettaAgentClient({
-  backend: "cloud",
-  apiKey: process.env.LETTA_API_KEY,
-  environment: { name: "devbox" },
-});
+const status = await session.getDeviceStatus();
+// status.permissionMode, status.workingDirectory, status.isOnline,
+// status.isProcessing, status.pendingControlRequests, status.raw
 
-await using session = client.resumeSession(agentId, {
-  environment: { name: "devbox" },
+const unsubscribe = session.onDeviceStatus((status) => {
+  // Called for every device-status update pushed by the runtime.
 });
+unsubscribe();
 ```
 
-For advanced cases where you want to target a specific remote connection, pass
-its `connectionId` instead. Connection IDs are assigned when the remote listener
-registers and may change after reconnects:
+`getDeviceStatus()` always sends a lightweight, request-correlated `sync`
+(`recover_approvals: false`, `force_device_status: true`) and resolves only
+after the runtime acknowledges it and replays a fresh status. This makes the
+getter safe for foreground reconciliation instead of returning a snapshot
+cached before the app was backgrounded. Pending approval request IDs are for
+correlation; decisions continue through `recoverPendingApprovals()` and the
+session's `canUseTool` callback.
 
-```ts
-await using session = client.resumeSession(agentId, {
-  environment: { connectionId: "conn-123" },
-});
-```
+## Deployment options
 
-`environment` also accepts `{ id: "env-..." }` for an environment record or
-`{ deviceId: "device-..." }` for a stable device selector.
+| Backend | Agent state | Tool execution |
+| --- | --- | --- |
+| `cloud` | Letta Cloud | Managed cloud sandbox or a selected computer |
+| `local` | Current computer | Current computer through an SDK-managed App Server |
+| `remote` | Configured by the App Server | A user-managed App Server computer |
 
-`environment` and `sandbox` are mutually exclusive. Conversation-scoped
-sandboxes refresh and terminate by sandbox ID. Legacy agent-scoped sandboxes
-retain the latest-active ownership check. Pass `sandbox.terminateOnClose: true`
-to request best-effort eager cleanup, but only when no other session or
-reconnecting client needs the sandbox.
-
-If Cloud reaps a conversation-scoped sandbox before the next refresh,
-`send()` throws `CloudManagedSandboxExpiredError` before transmitting the turn.
-Close the old SDK session and resume the same conversation to create a fresh
-connection, then retry safely:
+### Local
 
 ```ts
-import {
-  CloudManagedSandboxExpiredError,
-  LettaAgentClient,
-} from "@letta-ai/letta-agent-sdk";
+const client = new LettaAgentClient({ backend: "local" });
 
-const client = new LettaAgentClient({
-  backend: "cloud",
-  apiKey: process.env.LETTA_API_KEY,
+await using session = client.createSession(agentId, {
+  cwd: process.cwd(),
 });
-const conversationId = "conv-123";
-let session = client.resumeSession(conversationId);
-
-async function sendWithSandboxRecovery(message: string): Promise<void> {
-  for (let attempt = 0; attempt < 2; attempt += 1) {
-    try {
-      await session.send(message);
-      for await (const event of session.stream()) {
-        if (event.type === "assistant") console.log(event.content);
-      }
-      return;
-    } catch (error) {
-      if (!(error instanceof CloudManagedSandboxExpiredError) || attempt > 0) {
-        throw error;
-      }
-      session.close();
-      session = client.resumeSession(conversationId);
-    }
-  }
-}
 ```
 
-Only retry automatically for this pre-send expiration error. If a connection
-fails after `send()` succeeds, inspect conversation history before retrying
-because the original message may already have reached the runtime.
-
-By default, websocket authentication uses `Authorization` headers. Set
-`webSocketAuth: "query"` for browser-style websocket clients that cannot send
-custom upgrade headers.
-
-## Cloud repositories
-
-Cloud clients can create hosted repositories, manage text files inside them,
-and attach repositories to a session as resources. Repository resources are
-attached before the session starts and detached when the SDK session closes.
+### Remote App Server
 
 ```ts
 const client = new LettaAgentClient({
-  backend: "cloud",
-  apiKey: process.env.LETTA_API_KEY,
-});
-
-const repo = await client.repositories.create({ name: "inputs" });
-
-await client.repositories.files.create(repo.id, {
-  path: "data.csv",
-  content: csvContent,
-});
-
-await using session = client.createSession(agentId, {
-  resources: [
-    { type: "repository", repositoryId: repo.id },
-  ],
+  backend: "remote",
+  url: "http://127.0.0.1:4500",
+  authToken: process.env.LETTA_APP_SERVER_TOKEN,
 });
-
-await session.send("Analyze the files in the attached repository.");
 ```
 
-Repository file helpers are available under `client.repositories.files`, and
-version history helpers are available under `client.repositories.versions`.
+See the [deployment guide](https://docs.letta.com/letta-agent-sdk/deployment) for managed sandboxes, remote computers, App Server setup, and authentication.
 
-## Session configuration
+## Browser and React Native
 
-Session options let you set runtime defaults before a session starts, including
-`model`, `reasoningEffort`, `cwd`, `permissionMode`, and dreaming triggers. For
-remote and Constellation sessions, `cwd` must be a path inside the selected
-runtime environment.
+Use the portable `/client` entry point in browser, Expo, and React Native applications. It supports the `cloud` and `remote` backends without importing Node process-management modules.
 
 ```ts
-import { LettaAgentClient } from "@letta-ai/letta-agent-sdk";
-
-const client = new LettaAgentClient({ backend: "local" });
+import { LettaAgentClient } from "@letta-ai/letta-agent-sdk/client";
 
-const session = client.resumeSession("agent-123", {
-  model: "anthropic/claude-sonnet-4",
-  reasoningEffort: "high",
-  // For local sessions this may be a local path; for remote/Constellation
-  // sessions, use a path inside the selected runtime environment.
-  cwd: "/workspace/project",
-  permissionMode: "unrestricted",
-  dreaming: {
-    trigger: "step-count", // off | step-count | compaction-event
-    stepCount: 8,
-  },
+const client = new LettaAgentClient({
+  backend: "cloud",
+  apiKey: userProvidedApiKey,
+  webSocketAuth: "query",
 });
 ```
 
-You can also inspect and change models after startup:
-
-```ts
-const catalog = await session.listModels();
-await session.updateModel({ model: "sonnet", reasoningEffort: "medium" });
-```
+For authenticated Remote App Servers in React Native, pass the platform WebSocket through `createReactNativeWebSocketConstructor()` so capability-token headers use React Native's third constructor argument.
 
-Call `await session.abort()` to interrupt the current turn without closing the
-session.
+## Management APIs
 
-For advanced protocol access, use `sendCommand()` with raw Letta Code websocket
-protocol commands:
+The client exposes agent, conversation, model, and Cloud repository management alongside active sessions:
 
 ```ts
-await session.sendCommand({
-  type: "change_device_state",
-  runtime: { agent_id: session.agentId!, conversation_id: session.conversationId! },
-  payload: { cwd: "/workspace/project" },
+const agents = await client.agents.list({ tags: ["support"] });
+const conversations = await client.conversations.list({
+  agentId: agents[0].id,
+  orderBy: "lastMessageAt",
+  order: "desc",
 });
 
-const sync = await session.sendCommand(
-  {
-    type: "sync",
-    runtime: { agent_id: session.agentId!, conversation_id: session.conversationId! },
-  },
-  { responseType: "sync_response" },
-);
-```
-
-## Dreaming
+// No open session required — safe for model pickers and settings screens.
+const { entries: models, availableHandles } = await client.models.list();
 
-The dreaming API has three explicit components: collect normalized transcript
-snapshots, initialize a guarded memory filesystem, then run a dream over the
-exact transcript list. Reflection batches edit isolated clones and a final
-aggregation pass synthesizes their diffs into the dream agent's MemFS.
+await client.agents.delete(agents[0].id);
 
-```typescript
-import {
-  LettaAgentClient,
-  collectTranscripts,
-  dream,
-  initDreamAgent,
-} from "@letta-ai/letta-agent-sdk";
-
-const client = new LettaAgentClient({
-  backend: "local",
-  appServer: { harnessBackend: "api" },
-});
-
-// 1. Collect immutable snapshots after an exclusive cutoff. Limits apply per
-// source, so this selects the five newest eligible sessions from each store.
-const transcripts = await collectTranscripts({
-  after: "2026-07-01T00:00:00Z",
-  sources: [
-    { type: "claude", limit: 5 },
-    { type: "codex", limit: 5 },
-  ],
-});
-
-// 2. Initialize the complete starting MemFS. Seeded files may be modified but
-// not deleted. New files and directories are allowed only below skills/.
-const agent = await initDreamAgent(client, {
-  model: "anthropic/claude-opus-4-8",
-  memfs: {
-    directories: ["skills"],
-    files: {
-      "system/project/AGENTS.md":
-        "---\ndescription: Project guidance\n---\n\n# Project guidance\n",
-    },
-  },
-  guard: {
-    allowedNewFilePrefixes: ["skills"],
-  },
+const repository = await client.repositories.create({ name: "inputs" });
+await client.repositories.files.create(repository.id, {
+  path: "brief.md",
+  content: "# Project brief\n",
 });
+```
 
-// 3. Run against the exact snapshots. The optional prompt is appended to each
-// reflection batch, not to the aggregation pass.
-const result = await dream({
-  client,
-  agentId: agent.agentId,
-  transcripts,
-  reflectionPrompt: "Only retain learnings relevant to this project.",
-});
+`client.repositories` is available on the `cloud` backend. See [Cloud repositories](https://docs.letta.com/letta-agent-sdk/repositories) for file operations, version history, and session resources.
 
-if (result.kind === "completed") {
-  console.log(result.success, result.runRoot, result.aggregation.report);
-}
-```
+## Documentation
 
-Available transcript sources include `claude`, `codex`, `openhands`, `letta`,
-and already-normalized `transcript` files. `after` compares against each
-session's end time and is exclusive; `limit` keeps the latest eligible sessions
-for that source spec. Use `planOnly: true` to inspect transcript selection and
-batch packing without running agents.
-
-The pre-commit guard is installed on the canonical MemFS and every reflection
-clone. The SDK also validates every commit and the final working tree after
-each run, so `--no-verify` cannot bypass the policy. For finer control, pass
-`guard.allowedOperations` rules for exact or recursive paths. Every run records
-batch inputs, output clones, diffs, normalized worker trajectories, reports,
-and an immutable final aggregate snapshot under `runRoot`. See
-[`examples/dream.ts`](./examples/dream.ts).
-
-OpenHands conversations retain incremental cursors in the dream agent's SDK
-state; later dreams skip records at or before the last successfully reflected
-timestamp. Claude and Codex sessions are finite snapshots and remain
-cursor-free.
-
-## Links
-
-- Docs: https://docs.letta.com/letta-agent-sdk
-- Examples: [`./examples`](./examples)
+- [Overview](https://docs.letta.com/letta-agent-sdk/overview)
+- [Quickstart](https://docs.letta.com/letta-agent-sdk/quickstart)
+- [Deployment](https://docs.letta.com/letta-agent-sdk/deployment)
+- [SDK reference](https://docs.letta.com/letta-agent-sdk/reference)
+- [Examples](./examples)
 
 ---
 

package/dist/app-server-management.d.ts

@@ -0,0 +1,28 @@
+import type { ManagementQuery, ManagementTransport } from "./management.js";
+import type { ConversationMessagesResult, LettaAgent, LettaConversation } from "./management-types.js";
+import type { LettaCodeRemoteClientOptions, ListModelsResult } from "./types.js";
+type OwnedConnection = {
+    url: string;
+    close(): void;
+};
+export type AppServerManagementOptions = Partial<LettaCodeRemoteClientOptions> & {
+    url?: string;
+    connect?: () => Promise<OwnedConnection>;
+};
+export declare class AppServerManagementTransport implements ManagementTransport {
+    private readonly options;
+    constructor(options: AppServerManagementOptions);
+    listAgents(query: ManagementQuery): Promise<LettaAgent[]>;
+    retrieveAgent(agentId: string): Promise<LettaAgent>;
+    updateAgent(agentId: string, body: Record<string, unknown>): Promise<LettaAgent>;
+    deleteAgent(agentId: string): Promise<void>;
+    listModels(): Promise<ListModelsResult>;
+    listConversations(query: ManagementQuery): Promise<LettaConversation[]>;
+    retrieveConversation(conversationId: string): Promise<LettaConversation>;
+    createConversation(body: Record<string, unknown>): Promise<LettaConversation>;
+    updateConversation(conversationId: string, body: Record<string, unknown>): Promise<LettaConversation>;
+    listConversationMessages(conversationId: string, query: ManagementQuery): Promise<ConversationMessagesResult>;
+    private request;
+}
+export {};
+//# sourceMappingURL=app-server-management.d.ts.map

package/dist/app-server-management.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-server-management.d.ts","sourceRoot":"","sources":["../src/app-server-management.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,eAAe,EACf,mBAAmB,EACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EACV,0BAA0B,EAC1B,UAAU,EACV,iBAAiB,EAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAEV,4BAA4B,EAC5B,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB,KAAK,eAAe,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,IAAI,IAAI,CAAA;CAAE,CAAC;AAkCtD,MAAM,MAAM,0BAA0B,GACpC,OAAO,CAAC,4BAA4B,CAAC,GAAG;IACtC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,CAAC;CAC1C,CAAC;AA8CJ,qBAAa,4BACX,YAAW,mBAAmB;IAElB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,0BAA0B;IAE1D,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAYzD,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAanD,WAAW,CACf,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,UAAU,CAAC;IAahB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW3C,UAAU,IAAI,OAAO,CAAC,gBAAgB,CAAC;IA0BvC,iBAAiB,CACrB,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAYzB,oBAAoB,CACxB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,iBAAiB,CAAC;IAavB,kBAAkB,CACtB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,iBAAiB,CAAC;IAavB,kBAAkB,CACtB,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,iBAAiB,CAAC;IAavB,wBAAwB,CAC5B,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,0BAA0B,CAAC;YAgBxB,OAAO;CA8CtB"}

package/dist/app-server-session.d.ts

@@ -1,27 +1,22 @@
 import { type AppServerClient, type AppServerExternalToolCallHandler } from "@letta-ai/letta-code/app-server-client";
 import { RemoteClientSessionCore, type ProtocolMessage, type RemoteClientRuntimeController, type RuntimeSendTurnOptions, type RuntimeScope, type RuntimeSessionInit, type RuntimeSessionMode } from "./remote-client-session-core.js";
-import type { AnyAgentTool, CanUseToolResponse, CreateAgentOptions, LettaCodeRemoteClientOptions, LettaCodeClientSessionOptions, ListModelsResult, ListMessagesOptions, ListMessagesResult, RecoverPendingApprovalsOptions, RecoverPendingApprovalsResult, SendMessage, UpdateModelResult } from "./types.js";
+import type { AnyAgentTool, CanUseToolContext, CanUseToolResponse, CreateAgentOptions, LettaCodeRemoteClientOptions, LettaCodeClientSessionOptions, ListModelsResult, ListMessagesOptions, ListMessagesResult, RecoverPendingApprovalsOptions, RecoverPendingApprovalsResult, SendMessage, UpdateModelResult } from "./types.js";
 type UpdateModelPayload = {
     model_id?: string;
     model_handle?: string;
 };
 export declare function agentToolNames(agent: Record<string, unknown> | null | undefined): string[] | undefined;
 export type AppServerSessionOptions = Partial<LettaCodeRemoteClientOptions> & {
-    /** Base websocket URL. Remote sessions require this; local sessions may omit
-     * it to spawn an SDK-owned app-server lazily at initialize(). */
+    /** Base websocket URL. */
     url?: string;
-    /** Spawn a local app-server when url is omitted. */
-    local?: boolean;
-    /** Optional backend for SDK-owned local app-server processes. */
-    localBackend?: string;
-    /** Optional local app-server listen URL. Defaults to ws://127.0.0.1:0. */
-    localListen?: string;
-    /** Timeout for local app-server startup. */
-    localStartupTimeoutMs?: number;
-    /** Extra environment variables for SDK-owned local app-server processes. */
-    localEnv?: Record<string, string | undefined>;
-    /** Whether create-agent runtime_start should pin the created agent globally. */
-    pinGlobalAgent?: boolean;
+    /**
+     * Internal lazy connection hook. The Node entry point uses this to start a
+     * local app-server without pulling process-management code into `/client`.
+     */
+    connect?: (sessionEnv?: Record<string, string>) => Promise<{
+        url: string;
+        close(): void;
+    }>;
     /** Whether SDK create-agent payloads should add the origin tag automatically. */
     includeSdkOriginTag?: boolean;
 };
@@ -29,7 +24,7 @@ export type AppServerSessionMode = RuntimeSessionMode;
 export declare function assertRemoteSessionOptionsSupported(action: string, options: LettaCodeClientSessionOptions): void;
 export declare function createAgentBody(options: CreateAgentOptions, settings?: {
     includeSdkOriginTag?: boolean;
-}): Record<string, unknown>;
+}): Promise<Record<string, unknown>>;
 export declare function externalToolGroups(tools: AnyAgentTool[] | undefined): Array<Record<string, unknown>> | undefined;
 export declare function createExternalToolCallHandler(externalTools: Map<string, AnyAgentTool>): AppServerExternalToolCallHandler;
 type AppServerApprovalOptions = LettaCodeClientSessionOptions | CreateAgentOptions;
@@ -42,7 +37,7 @@ type AppServerApprovalResponseDecision = {
     behavior: "deny";
     message: string;
 };
-export declare function resolveAppServerToolApproval(options: AppServerApprovalOptions, toolName: string, toolInput: Record<string, unknown>): Promise<CanUseToolResponse>;
+export declare function resolveAppServerToolApproval(options: AppServerApprovalOptions, toolName: string, toolInput: Record<string, unknown>, context?: CanUseToolContext): Promise<CanUseToolResponse>;
 export declare function toAppServerApprovalDecision(decision: CanUseToolResponse): AppServerApprovalResponseDecision;
 export declare function registerAppServerControlRequestHandler(config: {
     client: AppServerClient;
@@ -70,7 +65,7 @@ export declare class AppServerRuntimeController implements RemoteClientRuntimeCo
 }
 export declare class AppServerSession extends RemoteClientSessionCore {
     private readonly remoteOptions;
-    private ownedAppServer;
+    private ownedConnection;
     private externalTools;
     private removeExternalToolHandler;
     private removeControlRequestHandler;

package/dist/app-server-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-server-session.d.ts","sourceRoot":"","sources":["../src/app-server-session.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"app-server-session.d.ts","sourceRoot":"","sources":["../src/app-server-session.ts"],"names":[],"mappings":"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"}