@letta-ai/letta-agent-sdk 0.7.5 → 0.7.7

package/README.md

@@ -32,6 +32,19 @@ for await (const message of session.stream()) {
 }
 ```
 
+Latency-sensitive applications can initialize the runtime and transport before
+the first user action without fetching transcript history or invoking the model:
+
+```typescript
+const session = client.resumeSession(conversationId);
+await session.ready();
+await session.send(message);
+```
+
+`ready()` is idempotent and safe to call concurrently. `SDKResultMessage.durationMs`
+measures the tracked turn and excludes session initialization; measure `ready()`
+separately when startup latency matters.
+
 Set `LETTA_API_KEY` for the cloud backend. See the [quickstart](https://docs.letta.com/agent-sdk/quickstart) for the local and self-hosted paths.
 
 ## Where your agents run

package/dist/client-entry.d.ts

@@ -13,6 +13,7 @@ export declare class LettaAgentClient extends LettaAgentClientBase {
 export { CloudManagedSandboxExpiredError } from "./cloud-session.js";
 export { ConversationForkHydrationError } from "./management-errors.js";
 export { RepositoriesClient } from "./repositories.js";
+export type * from "./sandbox-files.js";
 export type { Computer, ComputerMetadata, ComputerSelector, ComputersClient, ListComputersOptions, ListComputersResult, ResolvedComputer, } from "./computers.js";
 export type * from "./management-types.js";
 export { extractStreamTextDelta } from "./stream-events.js";

package/dist/client-entry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client-entry.d.ts","sourceRoot":"","sources":["../src/client-entry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EACV,2BAA2B,EAC3B,4BAA4B,EAC7B,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,+BAA+B,GACvC,4BAA4B,GAC5B,2BAA2B,CAAC;AAEhC;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,oBAAoB;gBAC5C,OAAO,EAAE,+BAA+B;CAMrD;AAED,OAAO,EAAE,+BAA+B,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AACxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,YAAY,EACV,QAAQ,EACR,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,mBAAmB,uBAAuB,CAAC;AAC3C,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAC1E,YAAY,EACV,qBAAqB,EACrB,qBAAqB,EACrB,uBAAuB,EACvB,aAAa,EACb,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,qCAAqC,EAAE,MAAM,gBAAgB,CAAC;AACvE,mBAAmB,YAAY,CAAC"}
+{"version":3,"file":"client-entry.d.ts","sourceRoot":"","sources":["../src/client-entry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EACV,2BAA2B,EAC3B,4BAA4B,EAC7B,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,+BAA+B,GACvC,4BAA4B,GAC5B,2BAA2B,CAAC;AAEhC;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,oBAAoB;gBAC5C,OAAO,EAAE,+BAA+B;CAMrD;AAED,OAAO,EAAE,+BAA+B,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AACxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,mBAAmB,oBAAoB,CAAC;AACxC,YAAY,EACV,QAAQ,EACR,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,mBAAmB,uBAAuB,CAAC;AAC3C,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAC1E,YAAY,EACV,qBAAqB,EACrB,qBAAqB,EACrB,uBAAuB,EACvB,aAAa,EACb,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,qCAAqC,EAAE,MAAM,gBAAgB,CAAC;AACvE,mBAAmB,YAAY,CAAC"}

package/dist/client-entry.js

@@ -9337,6 +9337,22 @@ class RemoteClientSessionCore {
     this.initializePromise = memo;
     return memo;
   }
+  async ready() {
+    if (this.closed)
+      throw new Error("Session is closed");
+    if (!this.initialized)
+      await this.initialize();
+    await this.recoverIdleTransportIfNeeded();
+    if (!this._agentId || !this._conversationId) {
+      throw new Error("Session is not initialized");
+    }
+    return {
+      agentId: this._agentId,
+      conversationId: this._conversationId,
+      model: this._model || undefined,
+      ...this.toolNames !== undefined ? { tools: [...this.toolNames] } : {}
+    };
+  }
   async performInitialize() {
     const init = await this.initializeRuntimeController();
     this.controller = init.controller;
@@ -10947,6 +10963,51 @@ function validateCloudSandboxOptions(options, name) {
   }
 }
 
+// src/sandbox-files.ts
+function isUploadedFile(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return false;
+  const file = value;
+  return typeof file.path === "string" && typeof file.name === "string" && typeof file.mimeType === "string" && typeof file.size === "number" && Number.isSafeInteger(file.size) && file.size >= 0;
+}
+function parseUploadResult(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Cloud sandbox file upload returned an invalid response.");
+  }
+  const files = value.files;
+  if (!Array.isArray(files) || !files.every(isUploadedFile)) {
+    throw new Error("Cloud sandbox file upload returned invalid file metadata.");
+  }
+  return { files };
+}
+function uploadForm(files) {
+  if (files.length === 0) {
+    throw new Error("Cloud sandbox file upload requires at least one file.");
+  }
+  const form = new FormData;
+  for (const [index, file] of files.entries()) {
+    if (!file || typeof file.name !== "string" || file.name.trim() === "") {
+      throw new Error(`Invalid Cloud sandbox upload file at index ${index}.`);
+    }
+    form.append("file", file.data, file.name);
+  }
+  return form;
+}
+async function uploadSandboxFiles(apiClient, sandboxId, files) {
+  const response = await apiClient.post(`/v1/sandboxes/${encodeURIComponent(sandboxId)}/files`, { body: uploadForm(files) });
+  return parseUploadResult(response);
+}
+async function downloadSandboxFile(apiClient, sandboxId, path2) {
+  if (typeof path2 !== "string" || path2.trim() === "") {
+    throw new Error("Cloud sandbox file download requires a non-empty path.");
+  }
+  const response = await apiClient.get(`/v1/sandboxes/${encodeURIComponent(sandboxId)}/files`, {
+    query: { path: path2 },
+    __binaryResponse: true
+  });
+  return new Uint8Array(await response.arrayBuffer());
+}
+
 // src/cloud-session.ts
 var DEFAULT_TURN_TIMEOUT_MS = 120000;
 var DEFAULT_PING_INTERVAL_MS = 30000;
@@ -11086,6 +11147,7 @@ function assertCloudSessionOptionsSupported(action, options) {
 class CloudEnvironmentSession extends RemoteClientSessionCore {
   cloudOptions;
   apiClient;
+  sandbox;
   connectionId = null;
   removeExternalToolHandler = null;
   removeControlRequestHandler = null;
@@ -11109,11 +11171,17 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
     this.apiClient = apiClient;
     this.cloudMode = mode;
     this.repositoryManagement = new CloudManagementTransport(apiClient);
+    this.sandbox = this.effectiveEnvironment() === undefined ? {
+      uploadFiles: (files) => this.uploadFilesToManagedSandbox(files),
+      downloadFile: (path2) => this.downloadFileFromManagedSandbox(path2)
+    } : undefined;
     const tools = mode.options.tools;
     this.externalTools = externalToolsByName(tools);
   }
   async initializeRuntimeController() {
     await this.mcpCleanup;
+    if (!this.closed)
+      this.sandboxLifecycleClosing = false;
     const resolved = await this.resolveRuntime();
     const connection = await this.resolveConnectionForRuntime(resolved.runtime).catch(async (error) => {
       await this.cleanupSessionRepositories(resolved.runtime.agent_id, resolved.runtime.conversation_id);
@@ -11272,6 +11340,26 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
       return;
     await this.refreshManagedSandbox(sandbox);
   }
+  async uploadFilesToManagedSandbox(files) {
+    const sandbox = await this.requireManagedSandboxForFileTransfer();
+    return uploadSandboxFiles(this.apiClient, sandbox.sandboxId, files);
+  }
+  async downloadFileFromManagedSandbox(path2) {
+    const sandbox = await this.requireManagedSandboxForFileTransfer();
+    return downloadSandboxFile(this.apiClient, sandbox.sandboxId, path2);
+  }
+  async requireManagedSandboxForFileTransfer() {
+    if (this.effectiveEnvironment() !== undefined) {
+      throw new Error("Sandbox file transfer requires an SDK-managed Cloud sandbox.");
+    }
+    await this.ready();
+    const sandbox = this.managedSandbox;
+    if (!sandbox) {
+      throw new Error("SDK-managed Cloud sandbox is unavailable.");
+    }
+    await this.refreshManagedSandbox(sandbox);
+    return sandbox;
+  }
   onCoreClose() {
     this.cleanupTransportHandlers();
     this.mcpCleanup = this.closeMcpBridge();
@@ -12770,4 +12858,4 @@ export {
   CloudManagedSandboxExpiredError
 };
 
-//# debugId=4189F3F92EE00D0D64756E2164756E21
+//# debugId=4D2DEBF58B35A6BA64756E2164756E21