@letta-ai/letta-agent-sdk 0.8.77 → 0.8.79

package/dist/client-base.d.ts

@@ -15,7 +15,8 @@ import type { CreateAgentOptions, LettaCodeBackend, LettaCodeClientOptions, Lett
  * protocol.
  * `remote` connects to a user-managed Letta Code app-server websocket endpoint.
  * `cloud` uses agents hosted on Letta Cloud, with an explicit remote
- * environment or SDK-managed sandbox.
+ * environment or SDK-managed sandbox. With `registerComputer`, the SDK also
+ * starts a local app-server that registers this machine as that computer.
  */
 export declare class LettaAgentClientBase implements AsyncDisposable {
     readonly backend: LettaCodeBackend;
@@ -72,6 +73,14 @@ export declare class LettaAgentClientBase implements AsyncDisposable {
     query(params: QueryParams): Query;
     private createQuerySession;
     private assertSessionBackend;
+    /**
+     * Build a Cloud session. Sessions that run on the computer this client
+     * registers start the local app-server first and wait for it to come online.
+     */
+    private createCloudSession;
+    private connectRegisteredComputer;
+    /** Start the app-server that registers this machine; overridden by the Node client. */
+    protected startRegisteredComputer(): Promise<void>;
     protected createLocalAgent(_options: CreateAgentOptions): Promise<string>;
     /**
      * Node-only skill seeding support (directory loading, memory-repo git
@@ -99,7 +108,10 @@ export declare class LettaAgentClientBase implements AsyncDisposable {
      * prompts, with or without an open session.
      */
     registerTools(options: RegisterToolsOptions): Promise<ToolRegistration>;
-    /** How the local backend reaches its App Server; overridden by the Node client. */
+    /**
+     * How the local backend, or a Cloud client's registered computer, reaches
+     * its App Server; overridden by the Node client.
+     */
     protected localAppServerConnection(): AppServerSessionOptions;
     /**
      * Release resources owned directly by this client, including its pooled

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

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

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,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AACrF,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;AAChC,mBAAmB,kBAAkB,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;CAWrD;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,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AACrF,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;AAChC,mBAAmB,kBAAkB,CAAC"}

package/dist/client-entry.js

@@ -13518,6 +13518,7 @@ class RemoteTurnCoordinator {
       active.observedTurnEvidence = true;
       if (runId)
         active.runIds.add(runId);
+      this.armTurnTimeout(active);
     }
     const sdkMessage = this.transformStreamDelta(delta);
     if (sdkMessage)
@@ -13583,12 +13584,17 @@ class RemoteTurnCoordinator {
     this.activeTurn = turn;
     turn.startedAt = Date.now();
     this._activeTurnStartedAt = turn.startedAt;
-    if (this.requestTimeoutMs !== undefined) {
-      turn.timeout = setTimeout(() => {
-        this.failTurn(turn, `Timed out waiting for ${this.label} turn`);
-      }, this.requestTimeoutMs);
-      turn.timeout.unref?.();
-    }
+    this.armTurnTimeout(turn);
+  }
+  armTurnTimeout(turn) {
+    if (this.requestTimeoutMs === undefined)
+      return;
+    if (turn.timeout)
+      clearTimeout(turn.timeout);
+    turn.timeout = setTimeout(() => {
+      this.failTurn(turn, `Timed out waiting for ${this.label} turn`);
+    }, this.requestTimeoutMs);
+    turn.timeout.unref?.();
   }
   activateNextTurnFromProtocol() {
     if (this.activeTurn)
@@ -15943,6 +15949,19 @@ function validateCloudClientOptions(options) {
     const field = options.computer !== undefined ? "computer" : "environment";
     throw new Error(`Letta Cloud sessions cannot specify both ${field} and sandbox options.`);
   }
+  if (options.registerComputer !== undefined) {
+    const name = options.registerComputer?.name;
+    if (typeof name !== "string" || !name.trim()) {
+      throw new Error("Invalid registerComputer.name. Expected a non-empty string.");
+    }
+    if (options.computer !== undefined || options.environment !== undefined) {
+      const field = options.computer !== undefined ? "computer" : "environment";
+      throw new Error(`Letta Cloud clients cannot specify both ${field} and registerComputer. Use computer for a machine that is already connected, or registerComputer to connect this one.`);
+    }
+    if (options.sandbox !== undefined) {
+      throw new Error("Letta Cloud clients cannot specify both registerComputer and sandbox options.");
+    }
+  }
   if (options.webSocketAuth !== undefined && options.webSocketAuth !== "header" && options.webSocketAuth !== "query") {
     throw new Error("Invalid webSocketAuth. Valid values: header, query.");
   }
@@ -16036,6 +16055,7 @@ function assertCloudSessionOptionsSupported(action, options) {
 class CloudEnvironmentSession extends RemoteClientSessionCore {
   cloudOptions;
   apiClient;
+  connectRegisteredComputer;
   sandbox;
   connectionId = null;
   removeExternalToolHandler = null;
@@ -16051,13 +16071,14 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
   repositoryIdsRequiringCleanupRecompile = new Set;
   repositoryManagement;
   cloudMode;
-  constructor(cloudOptions, mode, apiClient = createCloudClient(cloudOptions)) {
+  constructor(cloudOptions, mode, apiClient = createCloudClient(cloudOptions), connectRegisteredComputer) {
     super(mode, {
       label: "cloud",
       requestTimeoutMs: cloudOptions.requestTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS
     });
     this.cloudOptions = cloudOptions;
     this.apiClient = apiClient;
+    this.connectRegisteredComputer = connectRegisteredComputer;
     this.cloudMode = mode;
     this.repositoryManagement = new CloudManagementTransport(apiClient);
     this.sandbox = this.effectiveEnvironment() === undefined ? {
@@ -16460,6 +16481,8 @@ class CloudEnvironmentSession extends RemoteClientSessionCore {
     return this.createManagedSandboxConnection(runtime);
   }
   async resolveExplicitConnection(environment) {
+    if (this.connectRegisteredComputer)
+      return this.connectRegisteredComputer();
     const target = environmentToRemoteTarget(environment);
     const resolved = await this.remoteEnvironmentClient().resolveEnvironment(target);
     return { connectionId: resolved.connectionId };
@@ -17259,6 +17282,15 @@ function stripCloudExecutionOptions(options) {
   delete sessionOptions.filesystemConfinement;
   return sessionOptions;
 }
+var REGISTERED_COMPUTER_READY_TIMEOUT_MS = 30000;
+var REGISTERED_COMPUTER_POLL_INTERVAL_MS = 500;
+function registeredComputerName(options) {
+  return options.backend === "cloud" ? options.registerComputer?.name : undefined;
+}
+function isRegisteredComputerPending(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.startsWith("Computer not found") || message.startsWith("Computer is offline");
+}
 function hasRepositoryResources(options) {
   return options.resources !== undefined && options.resources.length > 0;
 }
@@ -17317,7 +17349,8 @@ class LettaAgentClientBase {
       throw new Error(`Invalid Letta Code backend '${String(backend)}'. Valid values: local, remote, cloud.`);
     }
     this.backend = backend;
-    this.computer = getOptionsComputer(options);
+    const registeredName = registeredComputerName(options);
+    this.computer = getOptionsComputer(options) ?? (registeredName !== undefined ? { name: registeredName } : undefined);
     this.environment = this.computer;
     this.options = options;
     this.agents = createAgentsClient(() => this.getManagementTransport(), () => this.getAgentRepositoriesClient());
@@ -17413,12 +17446,12 @@ class LettaAgentClientBase {
       });
     }
     if (this.backend === "cloud") {
-      return new CloudEnvironmentSession(this.cloudOptions(), {
+      return this.createCloudSession({
         kind: "session",
         agentId,
         newConversation: true,
         options
-      }, this.getCloudClient());
+      });
     }
     return this.createLocalSession(agentId, options);
   }
@@ -17444,19 +17477,7 @@ class LettaAgentClientBase {
       return session2;
     }
     if (this.backend === "cloud") {
-      if (looksLikeConversationId(id)) {
-        return new CloudEnvironmentSession(this.cloudOptions(), {
-          kind: "session",
-          conversationId: id,
-          options
-        }, this.getCloudClient());
-      }
-      return new CloudEnvironmentSession(this.cloudOptions(), {
-        kind: "session",
-        agentId: id,
-        defaultConversation: true,
-        options
-      }, this.getCloudClient());
+      return this.createCloudSession(looksLikeConversationId(id) ? { kind: "session", conversationId: id, options } : { kind: "session", agentId: id, defaultConversation: true, options });
     }
     const session = this.resumeLocalSession(id, options);
     if (inherited && session instanceof AppServerSession)
@@ -17522,11 +17543,11 @@ class LettaAgentClientBase {
       if (!conversation || typeof conversation !== "object" || typeof conversation.id !== "string") {
         throw new Error("Cloud query conversation response did not include a conversation id.");
       }
-      return new CloudEnvironmentSession(this.cloudOptions(), {
+      return this.createCloudSession({
         kind: "conversation",
         conversationId: conversation.id,
         options: sessionOptions
-      }, this.getCloudClient());
+      });
     }
     return this.createLocalQuerySession(options, sessionOptions);
   }
@@ -17591,6 +17612,29 @@ class LettaAgentClientBase {
     }
     throw new Error(`LettaAgentClient backend '${this.backend}' is not implemented yet. ${action} currently supports backend 'local' only.`);
   }
+  createCloudSession(mode) {
+    const name = registeredComputerName(this.options);
+    const sessionComputer = mode.options.computer ?? mode.options.environment;
+    return new CloudEnvironmentSession(this.cloudOptions(), mode, this.getCloudClient(), name !== undefined && sessionComputer === undefined ? () => this.connectRegisteredComputer(name) : undefined);
+  }
+  async connectRegisteredComputer(name) {
+    await this.startRegisteredComputer();
+    const deadline = Date.now() + REGISTERED_COMPUTER_READY_TIMEOUT_MS;
+    while (true) {
+      try {
+        const resolved = await this.getComputersClient().resolve({ name });
+        return { connectionId: resolved.connectionId };
+      } catch (error) {
+        if (!isRegisteredComputerPending(error) || Date.now() >= deadline) {
+          throw error;
+        }
+        await new Promise((resolve) => setTimeout(resolve, REGISTERED_COMPUTER_POLL_INTERVAL_MS));
+      }
+    }
+  }
+  startRegisteredComputer() {
+    return Promise.reject(this.localBackendUnavailableError());
+  }
   createLocalAgent(_options) {
     throw this.localBackendUnavailableError();
   }
@@ -17671,8 +17715,8 @@ class LettaAgentClientBase {
   }
   registerTools(options) {
     this.assertOpen();
-    if (this.backend === "cloud") {
-      return Promise.reject(new Error('registerTools() requires backend: "local" or "remote". Cloud sessions register tools through the tools session option.'));
+    if (this.backend === "cloud" && registeredComputerName(this.options) === undefined) {
+      return Promise.reject(new Error('registerTools() requires backend: "local" or "remote", or backend: "cloud" with registerComputer. Other Cloud sessions register tools through the tools session option.'));
     }
     this.toolRegistry ??= new ToolRegistry(this.backend === "remote" ? this.remoteOptions() : this.localAppServerConnection());
     return this.toolRegistry.register(options);
@@ -17703,7 +17747,8 @@ class LettaAgentClientBase {
     if (this.backend !== "cloud") {
       throw new Error('Letta Cloud options requested for non-"cloud" backend.');
     }
-    return this.options;
+    const options = this.options;
+    return options.registerComputer !== undefined ? { ...options, computer: { name: options.registerComputer.name } } : options;
   }
 }
 // src/stream-events.ts
@@ -18218,6 +18263,9 @@ class LettaAgentClient extends LettaAgentClientBase {
     if (this.backend === "local") {
       throw this.localBackendUnavailableError();
     }
+    if (options.backend === "cloud" && options.registerComputer !== undefined) {
+      throw new Error('registerComputer starts a local Letta Code app-server. Import from "@letta-ai/letta-agent-sdk" in Node.js to use it.');
+    }
   }
 }
 export {
@@ -18230,4 +18278,4 @@ export {
   CloudManagedSandboxExpiredError
 };
 
-//# debugId=214DC938EA1FA61564756E2164756E21
+//# debugId=6F04BC66F4049A5B64756E2164756E21