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

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;
+}

package/src/skill-loading.ts

@@ -0,0 +1,194 @@
+/**
+ * Skill seeding for createAgent({ skills }) — portable core.
+ *
+ * A skill's canonical shape is a directory: `SKILL.md` plus optional support
+ * files (scripts/, references/, ...). Callers pass either a path to such a
+ * directory or an inline {@link AgentSkill} object.
+ *
+ * The platform stores `skills/{name}/SKILL.md` as a memory block labeled
+ * `skills/{name}` (see letta-cloud `blockMarkdownPath.ts` /
+ * `path_mapping.py`), so SKILL.md instructions ride the create-agent request
+ * as a memory block. Support files have no block representation; they are
+ * pushed to the agent's memory git repo after creation.
+ *
+ * This module is part of the portable client graph and must stay free of
+ * Node imports. Directory loading and the git push live in `skill-node.ts`,
+ * behind the package root, and are injected by the Node client.
+ */
+
+/**
+ * A skill to seed into a new agent's memory filesystem at creation.
+ *
+ * The instructions become `skills/{name}/SKILL.md` in the agent's memory
+ * repo (stored as the memory block labeled `skills/{name}`), so the agent
+ * owns and can edit the skill like any other memory. Support `files` land
+ * beside it (`skills/{name}/{path}`); they require the Cloud backend from
+ * Node.
+ */
+export interface AgentSkill {
+  /** Directory name: lowercase letters, digits, ".", "_", "-". */
+  name: string;
+  /**
+   * Trigger text: when the agent should load this skill. Rendered as the
+   * SKILL.md frontmatter description and always visible to the agent.
+   */
+  description: string;
+  /** SKILL.md body (markdown, without frontmatter). */
+  instructions: string;
+  /**
+   * Optional support files, keyed by path relative to the skill directory
+   * (e.g. "scripts/convert.sh"). Cloud backend from Node only.
+   */
+  files?: Record<string, Uint8Array>;
+}
+
+/**
+ * Skill item for createAgent(): a path to a skill directory containing
+ * SKILL.md (Node runtimes only), or an inline {@link AgentSkill}.
+ */
+export type SkillItem = string | AgentSkill;
+
+/** Loads a skill directory from disk. Node-only; see skill-node.ts. */
+export type SkillDirectoryLoader = (dirPath: string) => Promise<AgentSkill>;
+
+/** Pushes skill support files to an agent's memory git repo. Node-only. */
+export type SkillFilesPusher = (
+  target: { apiBaseUrl: string; apiKey: string; agentId: string },
+  skills: AgentSkill[],
+) => Promise<void>;
+
+/** Node-only skill capabilities injected by the package-root client. */
+export interface SkillNodeSupport {
+  loadSkillDirectory: SkillDirectoryLoader;
+  pushSkillSupportFiles: SkillFilesPusher;
+}
+
+/** Skill directory names: lowercase, digits, hyphens (letta-code convention). */
+const SKILL_NAME_RE = /^[a-z0-9][a-z0-9._-]*$/;
+
+export function assertValidSkillName(name: string): void {
+  if (!SKILL_NAME_RE.test(name)) {
+    throw new Error(
+      `Invalid skill name "${name}". Skill names are directory names: ` +
+        `lowercase letters, digits, ".", "_", "-" (e.g. "generating-voice-memos").`,
+    );
+  }
+}
+
+/**
+ * Minimal YAML frontmatter reader for SKILL.md: extracts `name` and
+ * `description` (plain, quoted, or `>`/`>-` folded scalars) and returns the
+ * body without the frontmatter fence. Anything unparsable is left in place.
+ */
+export function parseSkillMarkdown(content: string): {
+  name?: string;
+  description?: string;
+  body: string;
+} {
+  if (!content.startsWith("---\n") && !content.startsWith("---\r\n")) {
+    return { body: content };
+  }
+  const fence = /\r?\n---[ \t]*(\r?\n|$)/.exec(content.slice(3));
+  if (!fence) return { body: content };
+  const yamlStart = content.startsWith("---\r\n") ? 5 : 4;
+  const yamlEnd = 3 + fence.index;
+  const yamlText = content.slice(yamlStart, yamlEnd);
+  const body = content.slice(yamlEnd + fence[0].length);
+
+  const fields: Record<string, string> = {};
+  const lines = yamlText.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line || /^\s/.test(line)) continue;
+    const colon = line.indexOf(":");
+    if (colon <= 0) continue;
+    const key = line.slice(0, colon).trim();
+    let value = line.slice(colon + 1).trim();
+    if (value === ">" || value === ">-" || value === "|" || value === "|-") {
+      const folded: string[] = [];
+      let next = lines[i + 1];
+      while (next !== undefined && (/^\s/.test(next) || next === "")) {
+        i++;
+        folded.push(next.trim());
+        next = lines[i + 1];
+      }
+      value = folded.filter((part) => part.length > 0).join(" ");
+    } else if (
+      (value.startsWith('"') && value.endsWith('"') && value.length >= 2) ||
+      (value.startsWith("'") && value.endsWith("'") && value.length >= 2)
+    ) {
+      value = value.slice(1, -1);
+    }
+    fields[key] = value;
+  }
+
+  return { name: fields["name"], description: fields["description"], body };
+}
+
+/**
+ * Resolve every skill item to an AgentSkill. Directory paths need the
+ * injected Node loader; without one (portable clients) they are rejected.
+ */
+export async function resolveSkillItems(
+  items: SkillItem[] | undefined,
+  loadDirectory?: SkillDirectoryLoader,
+): Promise<AgentSkill[]> {
+  if (!items || items.length === 0) return [];
+  const resolved: AgentSkill[] = [];
+  for (const item of items) {
+    if (typeof item === "string") {
+      if (!loadDirectory) {
+        throw new Error(
+          `Skill directory paths ("${item}") require a Node.js runtime. ` +
+            "Pass an inline skill ({ name, description, instructions }) instead.",
+        );
+      }
+      resolved.push(await loadDirectory(item));
+    } else {
+      assertValidSkillName(item.name);
+      if (!item.instructions || item.instructions.trim().length === 0) {
+        throw new Error(`Skill "${item.name}" has empty instructions.`);
+      }
+      if (!item.description || item.description.trim().length === 0) {
+        throw new Error(
+          `Skill "${item.name}" has no description. ` +
+            `The description is the skill's trigger text; it is required.`,
+        );
+      }
+      resolved.push(item);
+    }
+  }
+  const seen = new Set<string>();
+  for (const skill of resolved) {
+    if (seen.has(skill.name)) {
+      throw new Error(`Duplicate skill name: "${skill.name}".`);
+    }
+    seen.add(skill.name);
+  }
+  return resolved;
+}
+
+/** True when any resolved skill carries support files beyond SKILL.md. */
+export function skillsHaveSupportFiles(skills: AgentSkill[]): boolean {
+  return skills.some(
+    (skill) => skill.files && Object.keys(skill.files).length > 0,
+  );
+}
+
+/** Collect `skills/{name}/{relPath}` entries for every skill support file. */
+export function skillSupportFileEntries(
+  skills: AgentSkill[],
+): Array<{ path: string; data: Uint8Array }> {
+  const entries: Array<{ path: string; data: Uint8Array }> = [];
+  for (const skill of skills) {
+    for (const [relPath, data] of Object.entries(skill.files ?? {})) {
+      if (relPath.split("/").some((part) => part === ".." || part === "")) {
+        throw new Error(
+          `Skill "${skill.name}" file path escapes the skill directory: ${relPath}`,
+        );
+      }
+      entries.push({ path: `skills/${skill.name}/${relPath}`, data });
+    }
+  }
+  return entries;
+}

package/src/skill-node.ts

@@ -0,0 +1,139 @@
+/**
+ * Node-only skill seeding: directory loading and the memory-repo git push.
+ *
+ * `skill-loading.ts` owns the portable core (types, validation, SKILL.md
+ * parsing, block mapping). This module owns everything that touches the
+ * filesystem or spawns git, and stays behind the package root so the
+ * portable `/client` entry never pulls in Node builtins.
+ */
+
+import { readFile, readdir, stat, mkdtemp, rm, mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, relative, sep } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+import {
+  assertValidSkillName,
+  parseSkillMarkdown,
+  skillSupportFileEntries,
+  type AgentSkill,
+} from "./skill-loading.js";
+
+const run = promisify(execFile);
+
+/** Load one skill directory from disk. */
+export async function loadSkillDirectory(dirPath: string): Promise<AgentSkill> {
+  const dirStat = await stat(dirPath).catch(() => null);
+  if (!dirStat?.isDirectory()) {
+    throw new Error(`Skill path is not a directory: ${dirPath}`);
+  }
+
+  const skillMd = await readFile(join(dirPath, "SKILL.md"), "utf-8").catch(
+    () => null,
+  );
+  if (skillMd === null) {
+    throw new Error(`Skill directory has no SKILL.md: ${dirPath}`);
+  }
+
+  const parsed = parseSkillMarkdown(skillMd);
+  const name = parsed.name ?? basename(dirPath);
+  assertValidSkillName(name);
+  if (!parsed.description) {
+    throw new Error(
+      `SKILL.md in ${dirPath} has no frontmatter description. ` +
+        `The description is the skill's trigger text; it is required.`,
+    );
+  }
+
+  // Collect support files (everything except SKILL.md), preserving layout.
+  const files: Record<string, Uint8Array> = {};
+  const walk = async (current: string): Promise<void> => {
+    for (const entry of await readdir(current, { withFileTypes: true })) {
+      const full = join(current, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full);
+      } else if (entry.isFile()) {
+        const rel = relative(dirPath, full).split(sep).join("/");
+        if (rel === "SKILL.md") continue;
+        files[rel] = new Uint8Array(await readFile(full));
+      }
+    }
+  };
+  await walk(dirPath);
+
+  return {
+    name,
+    description: parsed.description,
+    instructions: parsed.body.replace(/^\s+/, ""),
+    ...(Object.keys(files).length > 0 ? { files } : {}),
+  };
+}
+
+export interface SkillFilesPushTarget {
+  apiBaseUrl: string;
+  apiKey: string;
+  agentId: string;
+}
+
+/**
+ * Push skill support files into a new agent's memory git repo.
+ *
+ * SKILL.md rides the create-agent request as a memory block; everything else
+ * in a skill directory (scripts/, references/, ...) has no block
+ * representation and exactly one write channel: the agent's memory git
+ * remote at `{apiBaseUrl}/v1/git/{agentId}/state.git`. This function owns
+ * that one commit: shallow clone, write files, commit, push (with one
+ * pull --rebase retry in case the server committed between clone and push).
+ */
+export async function pushSkillSupportFiles(
+  target: SkillFilesPushTarget,
+  skills: AgentSkill[],
+): Promise<void> {
+  const entries = skillSupportFileEntries(skills);
+  if (entries.length === 0) return;
+
+  const base = target.apiBaseUrl.replace(/\/+$/, "");
+  const remote = `${base}/v1/git/${target.agentId}/state.git`;
+  // Credentials travel via a one-shot Authorization header, not the URL, so
+  // they cannot leak into error messages or the cloned repo's config.
+  const authHeader = `Authorization: Basic ${Buffer.from(`x:${target.apiKey}`).toString("base64")}`;
+  const gitEnv = {
+    ...process.env,
+    GIT_TERMINAL_PROMPT: "0",
+    GIT_AUTHOR_NAME: "letta-agent-sdk",
+    GIT_AUTHOR_EMAIL: "sdk@letta.com",
+    GIT_COMMITTER_NAME: "letta-agent-sdk",
+    GIT_COMMITTER_EMAIL: "sdk@letta.com",
+  };
+  const git = (args: string[], cwd?: string) =>
+    run("git", ["-c", `http.extraHeader=${authHeader}`, ...args], {
+      env: gitEnv,
+      ...(cwd ? { cwd } : {}),
+    });
+
+  const work = await mkdtemp(join(tmpdir(), "letta-skill-seed-"));
+  try {
+    await git(["clone", "--quiet", "--depth", "1", remote, work]);
+    for (const entry of entries) {
+      const filePath = join(work, entry.path);
+      await mkdir(dirname(filePath), { recursive: true });
+      await writeFile(filePath, entry.data);
+    }
+    await git(["add", "-A"], work);
+    await git(["commit", "--quiet", "-m", "feat: seed skill support files"], work);
+    try {
+      await git(["push", "--quiet", "origin", "HEAD"], work);
+    } catch {
+      await git(["pull", "--quiet", "--rebase", "origin", "HEAD"], work);
+      await git(["push", "--quiet", "origin", "HEAD"], work);
+    }
+  } catch (error) {
+    throw new Error(
+      `Agent ${target.agentId} was created, but pushing skill support files ` +
+        `to its memory repo failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  } finally {
+    await rm(work, { recursive: true, force: true });
+  }
+}

package/src/types.ts

@@ -209,6 +209,12 @@ export type MemoryItem =
   | CreateBlock // Custom block: { label, value, description? }
   | BlockReference; // Shared block reference: { blockId }
 
+// Skill seeding types (AgentSkill, SkillItem) live beside their
+// implementation in skill-loading.ts and are re-exported from the package
+// root.
+import type { SkillItem } from "./skill-loading.js";
+export type { AgentSkill, SkillItem } from "./skill-loading.js";
+
 /**
  * Default memory block preset names.
  */
@@ -408,105 +414,28 @@ export type LettaCodeClientOptions =
   | LettaCodeRemoteClientOptions
   | LettaCodeCloudClientOptions;
 
-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;
-}
+// Letta-hosted repository API types live beside their implementation in
+// repository-types.ts and are re-exported here for compatibility.
+import type { RepositoryResource } from "./repository-types.js";
+export type {
+  Repository,
+  CreateRepositoryParams,
+  ListRepositoriesParams,
+  ListRepositoriesResult,
+  RepositoryResource,
+  RepositoryFileEntry,
+  ListRepositoryFilesParams,
+  ListRepositoryFilesResult,
+  CreateRepositoryFileParams,
+  RepositoryFile,
+  UpdateRepositoryFileParams,
+  RepositoryFileMutationResult,
+  DeleteRepositoryFileParams,
+  DeleteRepositoryFileResult,
+  RepositoryVersion,
+  ListRepositoryVersionsParams,
+  GetRepositoryVersionParams,
+} from "./repository-types.js";
 
 // ═══════════════════════════════════════════════════════════════
 // SESSION OPTIONS
@@ -951,6 +880,19 @@ export interface CreateAgentOptions {
    */
   memory?: MemoryItem[];
 
+  /**
+   * Skills to seed into the agent's memory filesystem at creation. Each item
+   * is a path to a skill directory containing SKILL.md (Node runtimes only)
+   * or an inline {@link AgentSkill}.
+   *
+   * SKILL.md instructions ride the create request itself (as the memory
+   * block labeled `skills/{name}`) and are present from the agent's first
+   * turn. Skill support files (scripts, references) are pushed to the
+   * agent's memory repo immediately after creation; that second step
+   * currently requires the Cloud backend. Requires memfs (the default).
+   */
+  skills?: SkillItem[];
+
   /** @deprecated Prefer a personality preset or a system memory file. */
   persona?: string;
 
@@ -1038,7 +980,7 @@ export interface CreateAgentOptions {
  */
 export interface SDKInitMessage {
   type: "init";
-  agentId: string;
+  agentId: string | null;
   sessionId: string;
   conversationId: string;
   model: string;