@tetral-ai/sdk 0.110.0-alpha.1

package/src/tools/agent-toolset/skills.ts

@@ -0,0 +1,256 @@
+/**
+ * Node-only skill plumbing for the agent toolset: downloading a session
+ * agent's skills into the workdir and extracting the archives. Kept in its own
+ * file because it is a distinct concern from the tool implementations in
+ * `node.ts` — distinct enough, and large enough, to review on its own.
+ */
+
+import * as fs from 'node:fs/promises';
+import * as fssync from 'node:fs';
+import * as path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import type { Anthropic } from '../../client';
+import { AnthropicError } from '../../core/error';
+import { loggerFor } from '../../internal/utils/log';
+import { DIR_CREATE_MODE } from './fs-util';
+import type { AgentToolContext } from './node';
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Download the session agent's skills into `{ctx.workdir}/skills/<name>/`.
+ *
+ * No-op (returns a no-op cleanup) unless both `ctx.client` and `ctx.sessionId`
+ * are set. Looks up the session's resolved agent and, for each skill, fetches
+ * its files via `client.beta.skills.versions.download` and extracts the archive
+ * (a zip or tar.* archive) into a directory named after the skill. A failure on
+ * one skill is logged and does not block the others. Call this before starting
+ * the session tool runner (e.g. right after the bash session / workdir is
+ * ready).
+ *
+ * Returns a cleanup function that removes the skill directories this call
+ * created — call it once the work item is done so downloaded skills do not
+ * accumulate in the workdir across sessions.
+ */
+export async function setupSkills(ctx: AgentToolContext): Promise<() => Promise<void>> {
+  const { client, sessionId } = ctx;
+  if (!client || !sessionId) return async () => {};
+  const log = loggerFor(client);
+  const session = await client.beta.sessions.retrieve(sessionId);
+  const skillsRoot = path.resolve(ctx.workdir, 'skills');
+  const created: string[] = [];
+  for (const skill of session.agent.skills) {
+    try {
+      const versionId = await resolveSkillVersion(client, skill.skill_id, skill.version);
+      const version = await client.beta.skills.versions.retrieve(versionId, { skill_id: skill.skill_id });
+      // The directory is the skill's name, reduced to a single safe path
+      // component so a hostile name can't escape `skillsRoot`.
+      let dirname = path.basename(version.name.trim());
+      if (dirname === '' || dirname === '.' || dirname === '..') dirname = skill.skill_id;
+      const dest = path.resolve(skillsRoot, dirname);
+      if (dest !== skillsRoot && !dest.startsWith(skillsRoot + path.sep)) {
+        log.warn('skill name escapes the skills dir; skipping', {
+          component: 'agent-tool-context',
+          name: version.name,
+        });
+        continue;
+      }
+      const resp = await client.beta.skills.versions.download(versionId, { skill_id: skill.skill_id });
+      await fs.rm(dest, { recursive: true, force: true });
+      await fs.mkdir(dest, { recursive: true, mode: DIR_CREATE_MODE });
+      created.push(dest);
+      await extractSkillArchive(resp, dest);
+      log.info('downloaded skill', {
+        component: 'agent-tool-context',
+        skill_id: skill.skill_id,
+        version: versionId,
+        dest,
+      });
+    } catch (e) {
+      log.warn('failed to download skill', {
+        component: 'agent-tool-context',
+        skill_id: skill.skill_id,
+        error: String(e),
+      });
+    }
+  }
+  return async () => {
+    for (const dest of created) {
+      await fs.rm(dest, { recursive: true, force: true }).catch((e) => {
+        log.warn('failed to clean up skill', { component: 'agent-tool-context', dest, error: String(e) });
+      });
+    }
+  };
+}
+
+/**
+ * Resolve `version` to the concrete numeric timestamp the
+ * `/v1/skills/{id}/versions/{version}` endpoints require — `session.agent.skills[].version`
+ * can be an alias such as `"latest"`, which those endpoints reject. Numeric
+ * versions pass through unchanged.
+ */
+export async function resolveSkillVersion(
+  client: Anthropic,
+  skillId: string,
+  version: string,
+): Promise<string> {
+  if (/^\d+$/.test(version)) return version;
+  let newest: string | undefined;
+  for await (const v of client.beta.skills.versions.list(skillId)) {
+    if (/^\d+$/.test(v.version) && (newest === undefined || BigInt(v.version) > BigInt(newest))) {
+      newest = v.version;
+    }
+  }
+  if (newest === undefined) {
+    throw new AnthropicError(
+      `skill ${JSON.stringify(skillId)} has no concrete version to resolve ${JSON.stringify(
+        version,
+      )} against`,
+    );
+  }
+  return newest;
+}
+
+/** Reject archive members that are absolute or contain a `..` component. */
+function assertSafeMemberNames(names: string): void {
+  for (const raw of names.split('\n')) {
+    const entry = raw.trim();
+    if (!entry) continue;
+    if (path.isAbsolute(entry) || entry.split(/[\\/]/).includes('..')) {
+      throw new AnthropicError(`refusing to extract unsafe archive member: ${entry}`);
+    }
+  }
+}
+
+/**
+ * Reject archives that contain anything other than regular files and
+ * directories. The type char is the first byte of each `ls`-style line emitted
+ * by `tar -tvf` / `unzip -Z`: `-` file, `d` dir, `l` symlink, `h` hardlink,
+ * `b`/`c` device, `p` fifo, `s` socket. A symlink/hardlink member is how an
+ * archive escapes its extraction dir even when no name contains `..`.
+ */
+function assertNoSpecialMembers(verboseListing: string): void {
+  for (const line of verboseListing.split('\n')) {
+    const type = line.trimStart()[0];
+    if (type === 'l' || type === 'h' || type === 'b' || type === 'c' || type === 'p' || type === 's') {
+      throw new AnthropicError('refusing to extract archive with symlink/hardlink/device member');
+    }
+  }
+}
+
+/**
+ * Run an archive CLI (`unzip` for zip archives, `tar` for everything else),
+ * returning its stdout. Both binaries must be on `PATH`; a missing one would
+ * otherwise surface as an opaque `ENOENT` spawn failure, so it is turned into a
+ * clear, specific error naming the missing command.
+ */
+async function runArchiveTool(cmd: 'unzip' | 'tar', args: string[]): Promise<string> {
+  try {
+    const { stdout } = await execFileAsync(cmd, args);
+    return stdout;
+  } catch (e) {
+    if (e != null && typeof e === 'object' && (e as { code?: unknown }).code === 'ENOENT') {
+      throw new AnthropicError(
+        `skill extraction requires the \`${cmd}\` command, but it was not found on PATH`,
+      );
+    }
+    throw e;
+  }
+}
+
+/**
+ * The single top-level directory shared by every entry in a newline-separated
+ * archive listing, or `''` if entries don't all live under one common
+ * directory. Skill bundles are packaged wrapped in one directory named after
+ * the skill (e.g. `pdf/SKILL.md`, `pdf/scripts/...`); the extractor strips it
+ * so contents land directly in the skill's dir instead of a redundant nested
+ * `<skill>/<skill>/` level. A flat or multi-root archive yields `''`.
+ */
+function archiveTopDir(listing: string): string {
+  let top: string | undefined;
+  let nested = false;
+  for (const raw of listing.split('\n')) {
+    // Drop `.` / empty segments so a `./pdf/...`-style listing (e.g. from
+    // `tar -C dir .`) is treated the same as `pdf/...`.
+    const parts = raw
+      .trim()
+      .split('/')
+      .filter((p) => p !== '' && p !== '.');
+    if (parts.length === 0) continue;
+    const first = parts[0]!;
+    if (top === undefined) top = first;
+    else if (first !== top) return '';
+    if (parts.length > 1) nested = true;
+  }
+  return top !== undefined && nested ? top : '';
+}
+
+/**
+ * Extract a skill download (a zip or tar.* archive) into `dest`. Streams the
+ * response body straight to a temp file beside `dest` (so the whole archive is
+ * never buffered in memory — skills can contain large binaries), then shells out
+ * to `unzip`/`tar` — consistent with the rest of the toolset, which already
+ * invokes `bash` and `rg`. Both `unzip` and `tar` must be available on `PATH`; a
+ * missing binary surfaces as a clear error (see {@link runArchiveTool}). Refuses
+ * any member that would escape `dest` (zip-slip / tar-slip), including
+ * symlink/hardlink members: skill archives come from the API, but skills can be
+ * third-party.
+ *
+ * The skill bundle's single wrapper directory is stripped: the archive is
+ * extracted into a staging dir and the wrapper's contents are promoted into
+ * `dest`, so files land at `dest/SKILL.md` rather than a doubled
+ * `dest/<skill>/SKILL.md` (`unzip` has no `--strip-components`, so this is
+ * done uniformly by staging + promote rather than per-tool flags).
+ */
+export async function extractSkillArchive(resp: Response, dest: string): Promise<void> {
+  const tmp = path.join(dest, `.skill-archive-${process.pid}-${Date.now()}`);
+  if (!resp.body) {
+    throw new AnthropicError('skill download response had no body');
+  }
+  await pipeline(
+    Readable.fromWeb(resp.body as Parameters<typeof Readable.fromWeb>[0]),
+    fssync.createWriteStream(tmp),
+  );
+  const stage = path.join(path.dirname(dest), `.skill-stage-${process.pid}-${Date.now()}`);
+  try {
+    // Sniff the first bytes: zip archives start with "PK\x03\x04"; treat
+    // anything else as a tar.* archive (`tar -xf` autodetects gzip/bzip2/xz).
+    const head = await readHead(tmp, 4);
+    const isZip =
+      head.length >= 4 && head[0] === 0x50 && head[1] === 0x4b && head[2] === 0x03 && head[3] === 0x04;
+    const archiveCmd = isZip ? 'unzip' : 'tar';
+    // List first, validate, then extract — `tar`/`unzip` will happily write a
+    // `../` member (or follow a symlink member) outside `-C`/`-d` otherwise.
+    const listing = await runArchiveTool(archiveCmd, isZip ? ['-Z1', tmp] : ['-tf', tmp]);
+    assertSafeMemberNames(listing);
+    assertNoSpecialMembers(await runArchiveTool(archiveCmd, isZip ? ['-Z', tmp] : ['-tvf', tmp]));
+    const top = archiveTopDir(listing);
+    await fs.mkdir(stage, { recursive: true, mode: DIR_CREATE_MODE });
+    await runArchiveTool(archiveCmd, isZip ? ['-oq', tmp, '-d', stage] : ['-xf', tmp, '-C', stage]);
+    // Promote the wrapper's contents (or the staged tree itself, if the
+    // archive wasn't wrapped) into the already-created empty `dest`. `stage`
+    // is a sibling of `dest`, so each rename stays on one filesystem.
+    const srcRoot = top ? path.join(stage, top) : stage;
+    for (const entry of await fs.readdir(srcRoot)) {
+      await fs.rename(path.join(srcRoot, entry), path.join(dest, entry));
+    }
+  } finally {
+    await fs.rm(tmp, { force: true });
+    await fs.rm(stage, { recursive: true, force: true });
+  }
+}
+
+/** Read the first `n` bytes of `file`. */
+async function readHead(file: string, n: number): Promise<Buffer> {
+  const handle = await fs.open(file, 'r');
+  try {
+    const buf = Buffer.alloc(n);
+    const { bytesRead } = await handle.read(buf, 0, n, 0);
+    return buf.subarray(0, bytesRead);
+  } finally {
+    await handle.close();
+  }
+}

package/src/tools/memory/node.browser.ts

@@ -0,0 +1,64 @@
+/**
+ * Browser stub for `tools/memory/node`.
+ *
+ * The real module's {@link BetaLocalFilesystemMemoryTool} is implemented on top
+ * of Node built-ins (`fs/promises`, `path`, `crypto`), which browser bundlers
+ * cannot resolve. The `browser` field in `package.json` substitutes this stub
+ * in browser builds; Node runtimes and node-target bundles ignore the mapping
+ * and load the real implementation.
+ *
+ * `betaMemoryTool` is runtime-agnostic and is re-exported for real here; only
+ * the filesystem-backed handlers throw.
+ */
+
+export { betaMemoryTool } from '../../helpers/beta/memory';
+export type { MemoryToolHandlers } from '../../helpers/beta/memory';
+
+import { AnthropicError } from '../../core/error';
+import type { MemoryToolHandlers } from '../../helpers/beta/memory';
+import type {
+  BetaMemoryTool20250818CreateCommand,
+  BetaMemoryTool20250818DeleteCommand,
+  BetaMemoryTool20250818InsertCommand,
+  BetaMemoryTool20250818RenameCommand,
+  BetaMemoryTool20250818StrReplaceCommand,
+  BetaMemoryTool20250818ViewCommand,
+} from '../../resources/beta';
+
+function nodeOnly(name: string): never {
+  throw new AnthropicError(`${name} requires Node.js or a Node-compatible runtime`);
+}
+
+export class BetaLocalFilesystemMemoryTool implements MemoryToolHandlers {
+  constructor(_basePath: string = './memory') {
+    nodeOnly('BetaLocalFilesystemMemoryTool');
+  }
+
+  static init(_basePath: string = './memory'): Promise<BetaLocalFilesystemMemoryTool> {
+    return nodeOnly('BetaLocalFilesystemMemoryTool.init');
+  }
+
+  view(_command: BetaMemoryTool20250818ViewCommand): Promise<string> {
+    return nodeOnly('BetaLocalFilesystemMemoryTool');
+  }
+
+  create(_command: BetaMemoryTool20250818CreateCommand): Promise<string> {
+    return nodeOnly('BetaLocalFilesystemMemoryTool');
+  }
+
+  str_replace(_command: BetaMemoryTool20250818StrReplaceCommand): Promise<string> {
+    return nodeOnly('BetaLocalFilesystemMemoryTool');
+  }
+
+  insert(_command: BetaMemoryTool20250818InsertCommand): Promise<string> {
+    return nodeOnly('BetaLocalFilesystemMemoryTool');
+  }
+
+  delete(_command: BetaMemoryTool20250818DeleteCommand): Promise<string> {
+    return nodeOnly('BetaLocalFilesystemMemoryTool');
+  }
+
+  rename(_command: BetaMemoryTool20250818RenameCommand): Promise<string> {
+    return nodeOnly('BetaLocalFilesystemMemoryTool');
+  }
+}