@letta-ai/letta-agent-sdk 0.8.0 → 0.8.2

package/src/app-server-session.ts

@@ -657,8 +657,16 @@ export class AppServerSession extends RemoteClientSessionCore {
           clientToolset,
         ),
         runtime: response.runtime,
-        model: typeof response.agent?.model === "string" ? response.agent.model : "",
-        modelSettings: objectRecord(response.agent?.model_settings) ?? null,
+        model:
+          typeof response.agent?.model === "string"
+            ? response.agent.model
+            : typeof response.conversation?.model === "string"
+              ? response.conversation.model
+              : "",
+        modelSettings:
+          objectRecord(response.agent?.model_settings) ??
+          objectRecord(response.conversation?.model_settings) ??
+          null,
         ...(availableTools !== undefined ? { tools: availableTools } : {}),
         ...(skillSources !== undefined ? { skillSources: [...skillSources] } : {}),
       };
@@ -763,6 +771,31 @@ export class AppServerSession extends RemoteClientSessionCore {
       return command as RuntimeStartCommand;
     }
 
+    if (this.mode.kind === "agent-free") {
+      if (this.mode.createConversation) {
+        const create = this.mode.createConversation;
+        command.create_conversation = {
+          body: {
+            model: create.model,
+            system: create.system,
+            ...(create.modelSettings !== undefined
+              ? { model_settings: create.modelSettings }
+              : {}),
+            ...(create.contextWindowLimit !== undefined
+              ? { context_window_limit: create.contextWindowLimit }
+              : {}),
+          },
+        };
+      } else if (this.mode.conversationId) {
+        command.conversation_id = this.mode.conversationId;
+      } else {
+        throw new Error(
+          "Agent-free sessions require a conversation to create or resume.",
+        );
+      }
+      return command as RuntimeStartCommand;
+    }
+
     if (this.mode.agentId) {
       command.agent_id = this.mode.agentId;
       if (this.mode.newConversation) {

package/src/client-base.ts

@@ -1,5 +1,6 @@
 import type Letta from "@letta-ai/letta-client";
 import { RepositoriesClient } from "./repositories.js";
+import { resolveSkillItems, type SkillNodeSupport } from "./skill-loading.js";
 import { createAgentRepositoriesClient } from "./agent-repositories.js";
 import { AppServerManagementTransport } from "./app-server-management.js";
 import {
@@ -31,6 +32,12 @@ import type {
   ConversationsClient,
   ModelsClient,
 } from "./management-types.js";
+import { createQuery } from "./query.js";
+import type {
+  AgentFreeQueryOptions,
+  Query,
+  QueryParams,
+} from "./query-types.js";
 import type {
   CreateAgentOptions,
   CreateSessionOptions,
@@ -93,6 +100,28 @@ function looksLikeConversationId(id: string): boolean {
   return id.startsWith("conv-") || id.startsWith("local-conv-");
 }
 
+function agentFreeSessionOptions(
+  options: AgentFreeQueryOptions,
+): LettaCodeClientSessionOptions {
+  const {
+    system: _system,
+    modelSettings: _modelSettings,
+    contextWindowLimit: _contextWindowLimit,
+    ...sessionOptions
+  } = options;
+  return sessionOptions;
+}
+
+function validateAgentFreeQueryOptions(options: AgentFreeQueryOptions): void {
+  if (typeof options.model !== "string" || options.model.length === 0) {
+    throw new Error("query() requires a non-empty model.");
+  }
+  if (typeof options.system !== "string") {
+    throw new Error("query() requires a system prompt.");
+  }
+  validateCreateSessionOptions(agentFreeSessionOptions(options));
+}
+
 type OneShotSession = LettaCodeSession & {
   sendAndWaitForResult(message: SendMessage): Promise<SDKResultMessage>;
 };
@@ -227,6 +256,18 @@ export class LettaAgentClientBase {
 
     validateCreateAgentOptions(options);
 
+    // Resolve skill directory paths to inline skills up front so every
+    // backend receives the same shape. Directory loading is Node-only; the
+    // portable client resolves inline skills and rejects paths.
+    if (options.skills !== undefined && options.skills.length > 0) {
+      const nodeSupport = this.skillNodeSupport();
+      const skills = await resolveSkillItems(
+        options.skills,
+        nodeSupport?.loadSkillDirectory,
+      );
+      options = { ...options, skills };
+    }
+
     if (this.backend === "remote") {
       const session = new AppServerSession(this.appServerSessionOptions(), {
         kind: "create-agent",
@@ -234,10 +275,17 @@ export class LettaAgentClientBase {
       });
       const initMsg = await session.initialize();
       session.close();
+      if (!initMsg.agentId) {
+        throw new Error("App Server agent creation did not return an agent id.");
+      }
       return initMsg.agentId;
     }
     if (this.backend === "cloud") {
-      return createCloudAgent(this.getCloudClient(), options);
+      return createCloudAgent(
+        this.getCloudClient(),
+        options,
+        this.skillNodeSupport()?.pushSkillSupportFiles,
+      );
     }
     return this.createLocalAgent(options);
   }
@@ -354,6 +402,79 @@ export class LettaAgentClientBase {
     }
   }
 
+  /** Run one prompt in a new agent-free ephemeral conversation. */
+  query(params: QueryParams): Query {
+    validateAgentFreeQueryOptions(params.options);
+    return createQuery((options) => this.createAgentFreeSession(options), params);
+  }
+
+  private async createAgentFreeSession(
+    options: AgentFreeQueryOptions,
+  ): Promise<LettaCodeSession> {
+    validateAgentFreeQueryOptions(options);
+    const sessionOptions = agentFreeSessionOptions(options);
+    this.assertSessionBackend("query", sessionOptions);
+
+    if (this.backend === "remote") {
+      return new AppServerSession(this.appServerSessionOptions(), {
+        kind: "agent-free",
+        createConversation: {
+          model: options.model,
+          system: options.system,
+          ...(options.modelSettings !== undefined
+            ? { modelSettings: options.modelSettings }
+            : {}),
+          ...(options.contextWindowLimit !== undefined
+            ? { contextWindowLimit: options.contextWindowLimit }
+            : {}),
+        },
+        options: sessionOptions,
+      });
+    }
+    if (this.backend === "cloud") {
+      const computer = options.computer ?? options.environment ?? this.computer;
+      if (computer === undefined) {
+        throw new Error(
+          "Cloud query() requires an explicit computer; managed sandboxes are agent-scoped.",
+        );
+      }
+      const conversation = await this.getCloudClient().post<unknown>(
+        "/v1/conversations/ephemeral",
+        {
+          body: {
+            model: options.model,
+            system: options.system,
+            ...(options.modelSettings !== undefined
+              ? { model_settings: options.modelSettings }
+              : {}),
+            ...(options.contextWindowLimit !== undefined
+              ? { context_window_limit: options.contextWindowLimit }
+              : {}),
+          },
+        },
+      );
+      if (
+        !conversation ||
+        typeof conversation !== "object" ||
+        typeof (conversation as { id?: unknown }).id !== "string"
+      ) {
+        throw new Error(
+          "Cloud ephemeral conversation response did not include a conversation id.",
+        );
+      }
+      return new CloudEnvironmentSession(
+        this.cloudOptions(),
+        {
+          kind: "agent-free",
+          conversationId: (conversation as { id: string }).id,
+          options: sessionOptions,
+        },
+        this.getCloudClient(),
+      );
+    }
+    return this.createLocalAgentFreeSession(options, sessionOptions);
+  }
+
   private assertSessionBackend(
     action: string,
     options: LettaCodeClientSessionOptions,
@@ -451,6 +572,15 @@ export class LettaAgentClientBase {
     throw this.localBackendUnavailableError();
   }
 
+  /**
+   * Node-only skill seeding support (directory loading, memory-repo git
+   * push). The Node client overrides this; the portable client returns
+   * undefined, which limits skills to inline SKILL.md-only objects.
+   */
+  protected skillNodeSupport(): SkillNodeSupport | undefined {
+    return undefined;
+  }
+
   protected createLocalSession(
     _agentId: string,
     _options: LettaCodeClientSessionOptions,
@@ -458,6 +588,13 @@ export class LettaAgentClientBase {
     throw this.localBackendUnavailableError();
   }
 
+  protected createLocalAgentFreeSession(
+    _queryOptions: AgentFreeQueryOptions,
+    _sessionOptions: LettaCodeClientSessionOptions,
+  ): LettaCodeSession {
+    throw this.localBackendUnavailableError();
+  }
+
   protected resumeLocalSession(
     _id: string,
     _options: LettaCodeClientSessionOptions,

package/src/client-entry.ts

@@ -54,3 +54,4 @@ export type {
 } from "./transcript-accumulator.js";
 export { createReactNativeWebSocketConstructor } from "./websocket.js";
 export type * from "./types.js";
+export type * from "./query-types.js";

package/src/client.ts

@@ -3,6 +3,9 @@ import { AppServerManagementTransport } from "./app-server-management.js";
 import type { ManagementTransport } from "./management.js";
 import { createLocalAppServerSession } from "./local-app-server-session.js";
 import { startLocalAppServer } from "./local-app-server.js";
+import type { AgentFreeQueryOptions } from "./query-types.js";
+import type { SkillNodeSupport } from "./skill-loading.js";
+import { loadSkillDirectory, pushSkillSupportFiles } from "./skill-node.js";
 import type {
   CreateAgentOptions,
   LettaCodeClientSessionOptions,
@@ -11,6 +14,10 @@ import type {
 } from "./types.js";
 
 export class LettaAgentClient extends LettaAgentClientBase {
+  protected override skillNodeSupport(): SkillNodeSupport {
+    return { loadSkillDirectory, pushSkillSupportFiles };
+  }
+
   protected override createLocalManagementTransport(): ManagementTransport {
     const localOptions = (
       this.options as LettaCodeLocalClientOptions
@@ -48,6 +55,9 @@ export class LettaAgentClient extends LettaAgentClientBase {
     );
     const initMsg = await session.initialize();
     session.close();
+    if (!initMsg.agentId) {
+      throw new Error("Local App Server agent creation did not return an agent id.");
+    }
     return initMsg.agentId;
   }
 
@@ -67,6 +77,35 @@ export class LettaAgentClient extends LettaAgentClientBase {
     );
   }
 
+  protected override createLocalAgentFreeSession(
+    queryOptions: AgentFreeQueryOptions,
+    sessionOptions: LettaCodeClientSessionOptions,
+  ): LettaCodeSession {
+    const localOptions = this.options as LettaCodeLocalClientOptions;
+    if (
+      localOptions.appServer?.url === undefined &&
+      (localOptions.appServer?.harnessBackend ?? "local") === "local"
+    ) {
+      throw new Error(
+        'query() requires the API-backed App Server. Set appServer.harnessBackend to "api" or connect to an API-backed remote App Server.',
+      );
+    }
+    return createLocalAppServerSession(localOptions.appServer, {
+      kind: "agent-free",
+      createConversation: {
+        model: queryOptions.model,
+        system: queryOptions.system,
+        ...(queryOptions.modelSettings !== undefined
+          ? { modelSettings: queryOptions.modelSettings }
+          : {}),
+        ...(queryOptions.contextWindowLimit !== undefined
+          ? { contextWindowLimit: queryOptions.contextWindowLimit }
+          : {}),
+      },
+      options: sessionOptions,
+    });
+  }
+
   protected override resumeLocalSession(
     id: string,
     options: LettaCodeClientSessionOptions,

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,
@@ -325,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/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;