@anthropic-ai/sdk 0.95.2 → 0.97.0

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/version.ts

@@ -1 +1 @@
-export const VERSION = '0.95.2'; // x-release-please-version
+export const VERSION = '0.97.0'; // x-release-please-version

package/streaming.d.mts

@@ -1,2 +1,3 @@
+/** @deprecated Import from ./core/streaming instead */
 export * from "./core/streaming.mjs";
 //# sourceMappingURL=streaming.d.mts.map

package/streaming.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"streaming.d.mts","sourceRoot":"","sources":["src/streaming.ts"],"names":[],"mappings":""}
+{"version":3,"file":"streaming.d.mts","sourceRoot":"","sources":["src/streaming.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,qCAAiC"}

package/streaming.d.ts

@@ -1,2 +1,3 @@
+/** @deprecated Import from ./core/streaming instead */
 export * from "./core/streaming.js";
 //# sourceMappingURL=streaming.d.ts.map

package/streaming.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["src/streaming.ts"],"names":[],"mappings":""}
+{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["src/streaming.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,oCAAiC"}

package/streaming.mjs

@@ -1,2 +1,3 @@
+/** @deprecated Import from ./core/streaming instead */
 export * from "./core/streaming.mjs";
 //# sourceMappingURL=streaming.mjs.map

package/streaming.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"streaming.mjs","sourceRoot":"","sources":["src/streaming.ts"],"names":[],"mappings":""}
+{"version":3,"file":"streaming.mjs","sourceRoot":"","sources":["src/streaming.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,qCAAiC"}

package/tools/agent-toolset/fs-util.d.mts

@@ -0,0 +1,49 @@
+/**
+ * Shared, Node-only filesystem helpers for the agent toolset's file tools:
+ * path confinement (symlink-aware), an atomic write, and language-independent
+ * error messages. Kept out of `node.ts` so the tool implementations stay focused
+ * and these helpers can be reused by every file tool.
+ */
+/** Mode for directories the file tools create — not world-writable under a 0 umask. */
+export declare const DIR_CREATE_MODE = 493;
+/** Mode for files the file tools create. */
+export declare const FILE_CREATE_MODE = 420;
+/**
+ * Fully resolve `abs`: `realpath` the longest existing ancestor and re-append
+ * the rest, but never re-append a component that is itself a symlink — read the
+ * link and continue from its target instead. This handles paths being created
+ * (write/edit) without letting a symlink leaf (e.g. a dangling one pointing
+ * outside a confinement root) slip through unresolved.
+ */
+export declare function canonicalize(abs: string): Promise<string>;
+/**
+ * Resolve `p` and confine it to `root`.
+ *
+ * Unless `allowOutside` is set, absolute inputs are rejected and the
+ * **canonical** path is returned — every symlink in `p` (including the leaf,
+ * even a dangling one) is resolved before the confinement check, and the
+ * resolved path is what the caller then operates on, so a symlink inside `root`
+ * that points outside it can neither pass the check nor be followed afterwards.
+ *
+ * Residual TOCTOU: a component could still be swapped for a symlink between this
+ * call and the eventual `fs` operation. Closing that fully needs per-component
+ * `O_NOFOLLOW`/`openat`, which Node does not expose ergonomically; this is why a
+ * sandbox is still recommended for the toolset as a whole.
+ */
+export declare function confineToRoot(root: string, p: string, opts?: {
+    allowOutside?: boolean;
+}): Promise<string>;
+/**
+ * Atomically write `content` to `targetPath`: write a sibling temp file, fsync
+ * it, then rename over the target. The rename is atomic on most filesystems, so
+ * a crash mid-write never leaves the target half-written.
+ */
+export declare function atomicWriteFile(targetPath: string, content: string): Promise<void>;
+/**
+ * Map a thrown filesystem error to a consistent, language-independent message,
+ * so the model sees the same wording regardless of the runtime (Node's raw
+ * `ENOENT: no such file...` text would otherwise leak through). Falls back to
+ * the raw error message for codes we don't special-case.
+ */
+export declare function fsErrorMessage(err: unknown, file: string): string;
+//# sourceMappingURL=fs-util.d.mts.map

package/tools/agent-toolset/fs-util.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-util.d.mts","sourceRoot":"","sources":["../../src/tools/agent-toolset/fs-util.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,uFAAuF;AACvF,eAAO,MAAM,eAAe,MAAQ,CAAC;AACrC,4CAA4C;AAC5C,eAAO,MAAM,gBAAgB,MAAQ,CAAC;AAWtC;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA4B/D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,CAAC,EAAE,MAAM,EACT,IAAI,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,GAChC,OAAO,CAAC,MAAM,CAAC,CAiBjB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBxF;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAwBjE"}

package/tools/agent-toolset/fs-util.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared, Node-only filesystem helpers for the agent toolset's file tools:
+ * path confinement (symlink-aware), an atomic write, and language-independent
+ * error messages. Kept out of `node.ts` so the tool implementations stay focused
+ * and these helpers can be reused by every file tool.
+ */
+/** Mode for directories the file tools create — not world-writable under a 0 umask. */
+export declare const DIR_CREATE_MODE = 493;
+/** Mode for files the file tools create. */
+export declare const FILE_CREATE_MODE = 420;
+/**
+ * Fully resolve `abs`: `realpath` the longest existing ancestor and re-append
+ * the rest, but never re-append a component that is itself a symlink — read the
+ * link and continue from its target instead. This handles paths being created
+ * (write/edit) without letting a symlink leaf (e.g. a dangling one pointing
+ * outside a confinement root) slip through unresolved.
+ */
+export declare function canonicalize(abs: string): Promise<string>;
+/**
+ * Resolve `p` and confine it to `root`.
+ *
+ * Unless `allowOutside` is set, absolute inputs are rejected and the
+ * **canonical** path is returned — every symlink in `p` (including the leaf,
+ * even a dangling one) is resolved before the confinement check, and the
+ * resolved path is what the caller then operates on, so a symlink inside `root`
+ * that points outside it can neither pass the check nor be followed afterwards.
+ *
+ * Residual TOCTOU: a component could still be swapped for a symlink between this
+ * call and the eventual `fs` operation. Closing that fully needs per-component
+ * `O_NOFOLLOW`/`openat`, which Node does not expose ergonomically; this is why a
+ * sandbox is still recommended for the toolset as a whole.
+ */
+export declare function confineToRoot(root: string, p: string, opts?: {
+    allowOutside?: boolean;
+}): Promise<string>;
+/**
+ * Atomically write `content` to `targetPath`: write a sibling temp file, fsync
+ * it, then rename over the target. The rename is atomic on most filesystems, so
+ * a crash mid-write never leaves the target half-written.
+ */
+export declare function atomicWriteFile(targetPath: string, content: string): Promise<void>;
+/**
+ * Map a thrown filesystem error to a consistent, language-independent message,
+ * so the model sees the same wording regardless of the runtime (Node's raw
+ * `ENOENT: no such file...` text would otherwise leak through). Falls back to
+ * the raw error message for codes we don't special-case.
+ */
+export declare function fsErrorMessage(err: unknown, file: string): string;
+//# sourceMappingURL=fs-util.d.ts.map

package/tools/agent-toolset/fs-util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-util.d.ts","sourceRoot":"","sources":["../../src/tools/agent-toolset/fs-util.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,uFAAuF;AACvF,eAAO,MAAM,eAAe,MAAQ,CAAC;AACrC,4CAA4C;AAC5C,eAAO,MAAM,gBAAgB,MAAQ,CAAC;AAWtC;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA4B/D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,CAAC,EAAE,MAAM,EACT,IAAI,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,GAChC,OAAO,CAAC,MAAM,CAAC,CAiBjB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBxF;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAwBjE"}

package/tools/agent-toolset/fs-util.js

@@ -0,0 +1,159 @@
+"use strict";
+/**
+ * Shared, Node-only filesystem helpers for the agent toolset's file tools:
+ * path confinement (symlink-aware), an atomic write, and language-independent
+ * error messages. Kept out of `node.ts` so the tool implementations stay focused
+ * and these helpers can be reused by every file tool.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FILE_CREATE_MODE = exports.DIR_CREATE_MODE = void 0;
+exports.canonicalize = canonicalize;
+exports.confineToRoot = confineToRoot;
+exports.atomicWriteFile = atomicWriteFile;
+exports.fsErrorMessage = fsErrorMessage;
+const tslib_1 = require("../../internal/tslib.js");
+const fs = tslib_1.__importStar(require("node:fs/promises"));
+const path = tslib_1.__importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const ToolError_1 = require("../../lib/tools/ToolError.js");
+/** Mode for directories the file tools create — not world-writable under a 0 umask. */
+exports.DIR_CREATE_MODE = 0o755;
+/** Mode for files the file tools create. */
+exports.FILE_CREATE_MODE = 0o644;
+/** `realpath` `p`, or return `p` unchanged when it cannot be resolved. */
+async function realpathOrSelf(p) {
+    try {
+        return await fs.realpath(p);
+    }
+    catch {
+        return p;
+    }
+}
+/**
+ * Fully resolve `abs`: `realpath` the longest existing ancestor and re-append
+ * the rest, but never re-append a component that is itself a symlink — read the
+ * link and continue from its target instead. This handles paths being created
+ * (write/edit) without letting a symlink leaf (e.g. a dangling one pointing
+ * outside a confinement root) slip through unresolved.
+ */
+async function canonicalize(abs) {
+    const tail = [];
+    let prefix = abs;
+    for (;;) {
+        let real;
+        try {
+            real = await fs.realpath(prefix);
+        }
+        catch {
+            let isLink = false;
+            try {
+                isLink = (await fs.lstat(prefix)).isSymbolicLink();
+            }
+            catch {
+                /* prefix truly doesn't exist (ENOENT) — fall through and walk up */
+            }
+            if (isLink) {
+                // Resolve the symlink ourselves and retry; `tail` (the part below it)
+                // still applies to the link's target.
+                prefix = path.resolve(path.dirname(prefix), await fs.readlink(prefix));
+                continue;
+            }
+            const parent = path.dirname(prefix);
+            if (parent === prefix)
+                return abs; // walked past the FS root without a hit
+            tail.push(path.basename(prefix));
+            prefix = parent;
+            continue;
+        }
+        return tail.length ? path.join(real, ...tail.reverse()) : real;
+    }
+}
+/**
+ * Resolve `p` and confine it to `root`.
+ *
+ * Unless `allowOutside` is set, absolute inputs are rejected and the
+ * **canonical** path is returned — every symlink in `p` (including the leaf,
+ * even a dangling one) is resolved before the confinement check, and the
+ * resolved path is what the caller then operates on, so a symlink inside `root`
+ * that points outside it can neither pass the check nor be followed afterwards.
+ *
+ * Residual TOCTOU: a component could still be swapped for a symlink between this
+ * call and the eventual `fs` operation. Closing that fully needs per-component
+ * `O_NOFOLLOW`/`openat`, which Node does not expose ergonomically; this is why a
+ * sandbox is still recommended for the toolset as a whole.
+ */
+async function confineToRoot(root, p, opts) {
+    const allowOutside = opts?.allowOutside ?? false;
+    if (path.isAbsolute(p)) {
+        if (!allowOutside) {
+            throw new ToolError_1.ToolError(`absolute path ${JSON.stringify(p)} not permitted`);
+        }
+        return path.resolve(p);
+    }
+    const realRoot = await realpathOrSelf(path.resolve(root));
+    const abs = path.resolve(realRoot, p);
+    if (allowOutside)
+        return abs;
+    const real = await canonicalize(abs);
+    const rootSep = realRoot.endsWith(path.sep) ? realRoot : realRoot + path.sep;
+    if (real !== realRoot && !real.startsWith(rootSep)) {
+        throw new ToolError_1.ToolError(`path ${JSON.stringify(p)} escapes workdir`);
+    }
+    return real;
+}
+/**
+ * Atomically write `content` to `targetPath`: write a sibling temp file, fsync
+ * it, then rename over the target. The rename is atomic on most filesystems, so
+ * a crash mid-write never leaves the target half-written.
+ */
+async function atomicWriteFile(targetPath, content) {
+    const dir = path.dirname(targetPath);
+    const tempPath = path.join(dir, `.tmp-${process.pid}-${(0, node_crypto_1.randomUUID)()}`);
+    let handle;
+    try {
+        handle = await fs.open(tempPath, 'wx', exports.FILE_CREATE_MODE);
+        await handle.writeFile(content, 'utf-8');
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await fs.rename(tempPath, targetPath);
+    }
+    catch (err) {
+        if (handle)
+            await handle.close().catch(() => { });
+        await fs.unlink(tempPath).catch(() => { });
+        throw err;
+    }
+}
+/**
+ * Map a thrown filesystem error to a consistent, language-independent message,
+ * so the model sees the same wording regardless of the runtime (Node's raw
+ * `ENOENT: no such file...` text would otherwise leak through). Falls back to
+ * the raw error message for codes we don't special-case.
+ */
+function fsErrorMessage(err, file) {
+    const code = err?.code;
+    switch (code) {
+        case 'ENOENT':
+            return `${file}: no such file or directory`;
+        case 'EACCES':
+        case 'EPERM':
+            return `${file}: permission denied`;
+        case 'ENOTDIR':
+            return `${file}: not a directory`;
+        case 'EISDIR':
+            return `${file}: is a directory`;
+        case 'ELOOP':
+            return `${file}: too many levels of symbolic links`;
+        case 'ENAMETOOLONG':
+            return `${file}: file name too long`;
+        case 'ENOSPC':
+            return `${file}: no space left on device`;
+        case 'EMFILE':
+        case 'ENFILE':
+            return `${file}: too many open files`;
+        default:
+            return `${file}: ${err instanceof Error ? err.message : String(err)}`;
+    }
+}
+//# sourceMappingURL=fs-util.js.map

package/tools/agent-toolset/fs-util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-util.js","sourceRoot":"","sources":["../../src/tools/agent-toolset/fs-util.ts"],"names":[],"mappings":"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"}