@letta-ai/letta-agent-sdk 0.7.8 → 0.8.1

package/src/cloud-session.ts

@@ -6,6 +6,11 @@ import {
   type AppServerClient,
 } from "@letta-ai/letta-code/app-server-client";
 import { createAgentBody } from "./agent-creation.js";
+import {
+  resolveSkillItems,
+  skillsHaveSupportFiles,
+  type SkillFilesPusher,
+} from "./skill-loading.js";
 import {
   AppServerRuntimeController,
   agentToolNames,
@@ -78,7 +83,12 @@ type CloudRuntimeStartResponse = ProtocolMessage & {
     model?: string | null;
     model_settings?: Record<string, unknown> | null;
   }) | null;
-  conversation: (Record<string, unknown> & { id?: string; agent_id?: string }) | null;
+  conversation: (Record<string, unknown> & {
+    id?: string;
+    agent_id?: string | null;
+    model?: string | null;
+    model_settings?: Record<string, unknown> | null;
+  }) | null;
   error?: string;
 };
 
@@ -143,7 +153,10 @@ export class CloudManagedSandboxExpiredError extends Error {
   }
 }
 
-type CloudSessionMode = Extract<RuntimeSessionMode, { kind: "session" }>;
+type CloudSessionMode = Extract<
+  RuntimeSessionMode,
+  { kind: "session" } | { kind: "agent-free" }
+>;
 
 function getWebSocketConstructor(
   websocketOverride?: LettaCodeSocketConstructor,
@@ -226,7 +239,7 @@ function environmentToRemoteTarget(
 function buildCloudStatusWebSocketUrl(params: {
   apiBaseUrl?: string;
   connectionId: string;
-  agentId: string;
+  agentId: string | null;
   conversationId: string;
   apiKey?: string;
   authMode: "header" | "query";
@@ -240,7 +253,7 @@ function buildCloudStatusWebSocketUrl(params: {
     throw new Error(`Unsupported cloud apiBaseUrl protocol: ${base.protocol}`);
   }
   base.pathname = `/v1/environments/${encodeURIComponent(params.connectionId)}/status/ws`;
-  base.searchParams.set("agentId", params.agentId);
+  if (params.agentId) base.searchParams.set("agentId", params.agentId);
   base.searchParams.set("conversationId", params.conversationId);
   base.searchParams.set("channel", "stream");
   if (params.authMode === "query" && params.apiKey) {
@@ -301,12 +314,38 @@ function externalToolsByName(tools: AnyAgentTool[] | undefined): Map<string, Any
 export async function createCloudAgent(
   client: Letta,
   agentOptions: CreateAgentOptions,
+  pushSkillSupportFiles?: SkillFilesPusher,
 ): Promise<string> {
-  const body = await createAgentBody(agentOptions);
+  // Directory paths were already resolved to inline skills by the client
+  // facade; this validates inline skills passed directly.
+  const skills = await resolveSkillItems(agentOptions.skills);
+  const hasSupportFiles = skillsHaveSupportFiles(skills);
+  if (hasSupportFiles && pushSkillSupportFiles === undefined) {
+    throw new Error(
+      "Skill support files (scripts/, references/) require the Node.js " +
+        "package root; the portable client seeds SKILL.md-only skills.",
+    );
+  }
+  const body = await createAgentBody(agentOptions, skills);
   const agent = await client.agents.create(body as AgentCreateParams);
   if (typeof agent.id !== "string" || agent.id.length === 0) {
     throw new Error("Cloud create agent response did not include an agent id.");
   }
+  // SKILL.md contents rode the create request as memory blocks; support
+  // files (scripts, references) have no block representation and go to the
+  // agent's memory git repo in one follow-up commit.
+  if (hasSupportFiles && pushSkillSupportFiles) {
+    if (typeof client.apiKey !== "string" || client.apiKey.length === 0) {
+      throw new Error(
+        `Agent ${agent.id} was created, but skill support files need an API ` +
+          "key to push to the agent's memory repo and none is configured.",
+      );
+    }
+    await pushSkillSupportFiles(
+      { apiBaseUrl: client.baseURL, apiKey: client.apiKey, agentId: agent.id },
+      skills,
+    );
+  }
   return agent.id;
 }
 
@@ -364,10 +403,12 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
     const resolved = await this.resolveRuntime();
     const connection = await this.resolveConnectionForRuntime(resolved.runtime).catch(
       async (error: unknown) => {
-        await this.cleanupSessionRepositories(
-          resolved.runtime.agent_id,
-          resolved.runtime.conversation_id,
-        );
+        if (resolved.runtime.agent_id) {
+          await this.cleanupSessionRepositories(
+            resolved.runtime.agent_id,
+            resolved.runtime.conversation_id,
+          );
+        }
         throw error;
       },
     );
@@ -393,10 +434,12 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
     } catch (error) {
       await this.closeMcpBridge();
       await this.cleanupManagedSandbox();
-      await this.cleanupSessionRepositories(
-        resolved.runtime.agent_id,
-        resolved.runtime.conversation_id,
-      );
+      if (resolved.runtime.agent_id) {
+        await this.cleanupSessionRepositories(
+          resolved.runtime.agent_id,
+          resolved.runtime.conversation_id,
+        );
+      }
       throw error;
     }
   }
@@ -438,8 +481,16 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
           clientToolset,
         ),
         runtime: response.runtime,
-        model: typeof response.agent?.model === "string" ? response.agent.model : "",
-        modelSettings: response.agent?.model_settings ?? null,
+        model:
+          typeof response.agent?.model === "string"
+            ? response.agent.model
+            : typeof response.conversation?.model === "string"
+              ? response.conversation.model
+              : "",
+        modelSettings:
+          response.agent?.model_settings ??
+          response.conversation?.model_settings ??
+          null,
         ...(availableTools !== undefined ? { tools: availableTools } : {}),
         ...(skillSources !== undefined ? { skillSources: [...skillSources] } : {}),
       };
@@ -590,11 +641,11 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
         name: SDK_AGENT_ORIGIN,
         title: "Letta Agent SDK",
       },
-      agent_id: runtime.agent_id,
       conversation_id: runtime.conversation_id,
       recover_approvals: false,
       force_device_status: true,
     };
+    if (runtime.agent_id) command.agent_id = runtime.agent_id;
 
     const mode = mapPermissionMode(options.permissionMode);
     if (mode) command.mode = mode;
@@ -676,6 +727,18 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
   }
 
   private async resolveRuntime(): Promise<{ runtime: RuntimeScope }> {
+    if (this.cloudMode.kind === "agent-free") {
+      if (!this.cloudMode.conversationId) {
+        throw new Error("Cloud agent-free sessions require a conversation id.");
+      }
+      return {
+        runtime: {
+          agent_id: null,
+          conversation_id: this.cloudMode.conversationId,
+        },
+      };
+    }
+
     let agentId = this.cloudMode.agentId;
     let conversationId = this.cloudMode.conversationId;
 
@@ -890,6 +953,11 @@ export class CloudEnvironmentSession extends RemoteClientSessionCore {
   private async createManagedSandboxConnection(
     runtime: RuntimeScope,
   ): Promise<ResolvedCloudConnection> {
+    if (!runtime.agent_id) {
+      throw new Error(
+        "Agent-free queries require an explicit Cloud computer; managed sandboxes are agent-scoped.",
+      );
+    }
     // Scope the managed sandbox to the conversation when one exists: the
     // server treats create-with-conversationId as create-or-resume, so
     // sessions of the same conversation share one sandbox and sessions of

package/src/index.ts

@@ -39,6 +39,7 @@ import type {
   SDKResultMessage,
   SendMessage,
 } from "./types.js";
+import type { Query, QueryParams } from "./query-types.js";
 import { validateCreateSessionOptions, validateCreateAgentOptions } from "./validation.js";
 
 // Re-export types
@@ -94,6 +95,8 @@ export type {
   SessionDiffHunk,
   SessionDiffPreview,
   SkillSource,
+  SkillItem,
+  AgentSkill,
   DreamingOptions,
   SessionDreamingOptions,
   DreamingTrigger,
@@ -152,6 +155,11 @@ export type {
   McpSseServerConfig,
   McpServers,
 } from "./types.js";
+export type {
+  AgentFreeQueryOptions,
+  Query,
+  QueryParams,
+} from "./query-types.js";
 export type * from "./sandbox-files.js";
 export type {
   AgentRepositoriesClient,
@@ -174,6 +182,8 @@ export type {
   ConversationMessagesResult,
   DetachAgentRepositoryOptions,
   AgentRepositoryPermissions,
+  EnqueueMessageOptions,
+  EnqueueMessageResult,
 } from "./management-types.js";
 
 export { RepositoriesClient } from "./repositories.js";
@@ -323,6 +333,14 @@ export async function prompt(
   }
 }
 
+/** Run an agent-free query in a new ephemeral conversation. */
+export function query(params: QueryParams): Query {
+  return new LettaAgentClient({
+    backend: "local",
+    appServer: { harnessBackend: "api" },
+  }).query(params);
+}
+
 // ═══════════════════════════════════════════════════════════════
 // SESSIONLESS APIs
 // ═══════════════════════════════════════════════════════════════

package/src/local-app-server.ts

@@ -99,7 +99,7 @@ export function buildLocalAppServerArgs(
   return [
     cliPath,
     ...(options.backend !== undefined ? ["--backend", options.backend] : []),
-    "app-server",
+    "server",
     "--listen",
     options.listen ?? DEFAULT_LISTEN_URL,
   ];

package/src/management-types.ts

@@ -12,7 +12,12 @@ import type {
   ConversationUpdateParams,
 } from "@letta-ai/letta-client/resources/conversations/conversations";
 import type { MessageListParams } from "@letta-ai/letta-client/resources/conversations/messages";
-import type { ListMessagesResult, ListModelsResult } from "./types.js";
+import type {
+  ListMessagesResult,
+  ListModelsResult,
+  PermissionMode,
+  SendMessage,
+} from "./types.js";
 
 /** Agent state returned by either the Cloud API or Letta Code app-server. */
 export type LettaAgent = AgentState;
@@ -100,6 +105,34 @@ export interface ConversationMessagesOptions {
 
 export type ConversationMessagesResult = ListMessagesResult;
 
+export interface EnqueueMessageOptions {
+  /**
+   * Required when `conversationId` is `"default"`; identifies the agent whose
+   * default conversation receives the message. Ignored otherwise.
+   */
+  agentId?: string;
+  /**
+   * Correlation id for this message. Reuse the same value when retrying an
+   * enqueue so the listener can deduplicate delivery; the SDK generates one
+   * when omitted. Matches the `otid` contract of `session.send()`.
+   */
+  clientMessageId?: string;
+  /** Permission mode the listener applies before the turn when the runtime is cold. */
+  permissionMode?: PermissionMode;
+  /** Working directory for the runtime; `null` resets to the listener boot cwd. */
+  workingDirectory?: string | null;
+}
+
+/** The Cloud API's 202 acceptance of an enqueued message. */
+export interface EnqueueMessageResult {
+  /** The correlation id the message was accepted under (caller-supplied or SDK-generated). */
+  clientMessageId: string;
+  /** Temporal workflow id of the conversation queue that owns delivery. */
+  workflowId: string;
+  /** Super run id tracking the message from queue through delivery and completion. */
+  superRunId: string;
+}
+
 export type AgentRepositoryPermissions = "read" | "read_write";
 export type AgentRepositoryRecompileTarget = "default" | false;
 
@@ -193,4 +226,28 @@ export interface ConversationsClient {
     conversationId: string,
     options?: ConversationMessagesOptions,
   ): Promise<ConversationMessagesResult>;
+  /**
+   * Hand a user message to the server for delivery instead of sending it over
+   * a session. Cloud backend only.
+   *
+   * The returned promise resolves once the Cloud API has durably accepted the
+   * message (HTTP 202): from that point the server owns delivery. It ensures
+   * or resumes the conversation's sandbox, delivers the message to the
+   * listener with acknowledgement and retries, and tracks the whole lifecycle
+   * as a super run. The caller may exit immediately; the turn runs
+   * server-side. This is the send path chat.letta.com uses.
+   *
+   * Use `enqueue()` when you cannot hold a connection open for the length of
+   * a turn, such as serverless webhook handlers. Use a session's `send()` and
+   * `stream()` when you want to stream the turn's output; a session delivers
+   * input over its open socket and does not survive the caller.
+   *
+   * Pass `"default"` as `conversationId` with `options.agentId` to target an
+   * agent's default conversation.
+   */
+  enqueue(
+    conversationId: string,
+    message: SendMessage,
+    options?: EnqueueMessageOptions,
+  ): Promise<EnqueueMessageResult>;
 }

package/src/management.ts

@@ -15,6 +15,8 @@ import type {
   ConversationsClient,
   ConversationMessagesResult,
   CreateConversationOptions,
+  EnqueueMessageOptions,
+  EnqueueMessageResult,
   ForkConversationOptions,
   LettaAgent,
   LettaConversation,
@@ -25,7 +27,7 @@ import type {
   UpdateConversationOptions,
   ConversationMessagesOptions,
 } from "./management-types.js";
-import type { ListModelsResult } from "./types.js";
+import type { ListModelsResult, SendMessage } from "./types.js";
 
 export interface ManagementTransport {
   listAgents(query: AgentListParams): Promise<LettaAgent[]>;
@@ -57,6 +59,12 @@ export interface ManagementTransport {
     conversationId: string,
     query: MessageListParams,
   ): Promise<ConversationMessagesResult>;
+  /** Cloud only. Non-cloud transports reject with a backend error. */
+  enqueueConversationMessage(
+    conversationId: string,
+    message: SendMessage,
+    options: EnqueueMessageOptions,
+  ): Promise<EnqueueMessageResult>;
 }
 
 type TransportProvider = () => ManagementTransport;
@@ -227,5 +235,24 @@ export function createConversationsClient(
         conversationId,
         conversationMessagesQuery(options),
       ),
+    enqueue: async (conversationId, message, options = {}) => {
+      assertNonEmptyId(conversationId, "conversation id");
+      if (conversationId.trim() === "default" && !options.agentId) {
+        throw new Error(
+          'enqueue("default", ...) requires options.agentId to identify the agent.',
+        );
+      }
+      if (options.agentId !== undefined) {
+        assertNonEmptyId(options.agentId, "agent id");
+      }
+      if (options.clientMessageId !== undefined) {
+        assertNonEmptyId(options.clientMessageId, "client message id");
+      }
+      return await transport().enqueueConversationMessage(
+        conversationId,
+        message,
+        options,
+      );
+    },
   };
 }

package/src/query-types.ts

@@ -0,0 +1,40 @@
+import type {
+  LettaCodeClientSessionOptions,
+  SDKMessage,
+  SendMessage,
+} from "./types.js";
+
+/** Options for an agent-free query backed by an ephemeral conversation. */
+export interface AgentFreeQueryOptions
+  extends Omit<
+    LettaCodeClientSessionOptions,
+    | "model"
+    | "reasoningEffort"
+    | "stateless"
+    | "dreaming"
+    | "resources"
+    | "filesystemConfinement"
+  > {
+  /** Model handle persisted on the ephemeral conversation. */
+  model: string;
+  /** Complete system prompt for the ephemeral conversation. */
+  system: string;
+  /** Provider model settings persisted on the ephemeral conversation. */
+  modelSettings?: Record<string, unknown>;
+  /** Optional context-window limit persisted on the ephemeral conversation. */
+  contextWindowLimit?: number | null;
+}
+
+/** Input accepted by query(). */
+export interface QueryParams {
+  prompt: SendMessage;
+  options: AgentFreeQueryOptions;
+}
+
+/** Stream returned by query(), with controls for long-running execution. */
+export interface Query extends AsyncGenerator<SDKMessage, void, unknown> {
+  /** Interrupt the active turn without closing the query session. */
+  interrupt(): Promise<void>;
+  /** Close the query and release its underlying session. */
+  close(): void;
+}

package/src/query.ts

@@ -0,0 +1,43 @@
+import type { AgentFreeQueryOptions, Query, QueryParams } from "./query-types.js";
+import type { LettaCodeSession, SDKMessage } from "./types.js";
+
+type CreateAgentFreeSession = (
+  options: AgentFreeQueryOptions,
+) => Promise<LettaCodeSession>;
+
+/** Create one agent-free ephemeral conversation and stream its query result. */
+export function createQuery(
+  createSession: CreateAgentFreeSession,
+  params: QueryParams,
+): Query {
+  let session: LettaCodeSession | null = null;
+  let closed = false;
+
+  const iterator = (async function* runQuery(): AsyncGenerator<
+    SDKMessage,
+    void,
+    unknown
+  > {
+    try {
+      session = await createSession(params.options);
+      if (closed) return;
+      await session.send(params.prompt);
+      yield* session.stream();
+    } finally {
+      closed = true;
+      session?.close();
+    }
+  })();
+
+  return Object.assign(iterator, {
+    async interrupt(): Promise<void> {
+      await session?.abort();
+    },
+    close(): void {
+      if (closed) return;
+      closed = true;
+      session?.close();
+      void iterator.return();
+    },
+  });
+}

package/src/remote-client-session-core.ts

@@ -166,7 +166,7 @@ export abstract class RemoteClientSessionCore implements LettaCodeSession {
     this.runtime = init.runtime;
     this._agentId = init.runtime.agent_id;
     this._conversationId = init.runtime.conversation_id;
-    this._sessionId = `${init.runtime.agent_id}:${init.runtime.conversation_id}`;
+    this._sessionId = init.runtime.agent_id ? `${init.runtime.agent_id}:${init.runtime.conversation_id}` : init.runtime.conversation_id;
     this._modelSettings = init.modelSettings ?? null;
     this._model =
       typeof init.model === "string"

package/src/remote-session-protocol.ts

@@ -23,7 +23,7 @@ import type {
 } from "./types.js";
 
 export type RuntimeScope = {
-  agent_id: string;
+  agent_id: string | null;
   conversation_id: string;
 };
 
@@ -35,6 +35,17 @@ export type ProtocolMessage = Record<string, unknown> & {
 
 export type RuntimeSessionMode =
   | { kind: "create-agent"; options: CreateAgentOptions }
+  | {
+      kind: "agent-free";
+      conversationId?: string;
+      createConversation?: {
+        model: string;
+        system: string;
+        modelSettings?: Record<string, unknown>;
+        contextWindowLimit?: number | null;
+      };
+      options: LettaCodeClientSessionOptions;
+    }
   | {
       kind: "session";
       agentId?: string;

package/src/remote-turn-coordinator.ts

@@ -614,12 +614,16 @@ export class RemoteTurnCoordinator {
     const errorCode = approvalConflict
       ? "approval_conflict"
       : (turn.errorCode ?? toSdkErrorCode(stopReason));
+    const publicError =
+      errorCode && errorCode !== "error"
+        ? errorCode
+        : (turn.detail ?? stopReason ?? "error");
 
     return {
       type: "result",
       success,
       result: success ? tracker?.assistantText || undefined : undefined,
-      error: success ? undefined : (errorCode ?? stopReason ?? "error"),
+      error: success ? undefined : publicError,
       errorCode: success ? undefined : (errorCode ?? "error"),
       approvalConflict: approvalConflict || undefined,
       recoverable: approvalConflict

package/src/repository-types.ts

@@ -0,0 +1,105 @@
+/**
+ * Letta-hosted repository API types, used by RepositoriesClient and
+ * AgentRepositoriesClient. Kept beside their implementation
+ * (repositories.ts) and re-exported from types.ts.
+ */
+
+export interface Repository {
+  id: string;
+  name: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CreateRepositoryParams {
+  name: string;
+}
+
+export interface ListRepositoriesParams {
+  limit?: number;
+  offset?: number;
+}
+
+export interface ListRepositoriesResult {
+  repositories: Repository[];
+  hasNextPage: boolean;
+}
+
+export interface RepositoryResource {
+  type: "repository";
+  repositoryId: string;
+  /**
+   * Whether to trigger a system-prompt recompile after attaching (and after
+   * detaching on cleanup) so the session's conversation does not retain
+   * stale repository projections. Defaults to `true`.
+   */
+  recompile?: boolean;
+}
+
+export interface RepositoryFileEntry {
+  path: string;
+  type: "file" | "directory";
+}
+
+export interface ListRepositoryFilesParams {
+  pathPrefix?: string;
+  depth?: number;
+  ref?: string;
+}
+
+export interface ListRepositoryFilesResult {
+  files: RepositoryFileEntry[];
+  ref: string;
+}
+
+export interface CreateRepositoryFileParams {
+  path: string;
+  content: string;
+}
+
+export interface RepositoryFile {
+  path: string;
+  content: string;
+  contentSha256: string;
+  ref?: string;
+}
+
+export interface UpdateRepositoryFileParams {
+  path: string;
+  content?: string;
+  newPath?: string;
+  precondition?: {
+    contentSha256: string;
+  };
+}
+
+export interface RepositoryFileMutationResult {
+  path: string;
+  contentSha256: string;
+  commitSha: string;
+}
+
+export interface DeleteRepositoryFileParams {
+  path: string;
+}
+
+export interface DeleteRepositoryFileResult {
+  success: boolean;
+  commitSha: string;
+}
+
+export interface RepositoryVersion {
+  sha: string;
+  message: string;
+  timestamp: string;
+  author_name: string | null;
+}
+
+export interface ListRepositoryVersionsParams {
+  path?: string;
+  limit?: number;
+}
+
+export interface GetRepositoryVersionParams {
+  path: string;
+}