stitchkit 0.69.0 → 0.70.0

package/dist/index-xbtcszs7.js

@@ -0,0 +1,202 @@
+// src/agent-runtime/contained-files.ts
+import { constants } from "node:fs";
+import { open, readdir, realpath } from "node:fs/promises";
+import path from "node:path";
+function descriptorPath(handle) {
+  if (process.platform === "linux")
+    return `/proc/self/fd/${handle.fd}`;
+  if (process.platform === "darwin" || process.platform === "freebsd") {
+    return `/dev/fd/${handle.fd}`;
+  }
+  throw new Error("Contained filesystem operations require descriptor paths on this platform");
+}
+async function openPinnedDirectory(absolute) {
+  const expected = await realpath(absolute);
+  const handle = await open(expected, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+  try {
+    if (await realpath(descriptorPath(handle)) !== expected) {
+      throw new Error("Contained directory identity changed while opening");
+    }
+    return handle;
+  } catch (error) {
+    await handle.close();
+    throw error;
+  }
+}
+function safeSegments(relative) {
+  if (path.isAbsolute(relative))
+    throw new Error("Contained paths must be relative");
+  const segments = relative.split(/[\\/]/u);
+  if (segments.length === 0 || segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+    throw new Error("Contained path has invalid segments");
+  }
+  return segments;
+}
+async function openContainedParent(root, relative) {
+  const segments = safeSegments(relative);
+  const basename = segments.pop();
+  if (!basename)
+    throw new Error("Contained path is missing a basename");
+  let current = await openPinnedDirectory(root);
+  try {
+    for (const segment of segments) {
+      const next = await open(path.join(descriptorPath(current), segment), constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+      const metadata = await next.stat();
+      if (!metadata.isDirectory()) {
+        await next.close();
+        throw new Error("Contained ancestor is not a directory");
+      }
+      await current.close();
+      current = next;
+    }
+    return { handle: current, path: descriptorPath(current), basename };
+  } catch (error) {
+    await current.close();
+    throw error;
+  }
+}
+async function openContainedFile(root, relative) {
+  const parent = await openContainedParent(root, relative);
+  try {
+    const handle = await open(path.join(parent.path, parent.basename), constants.O_RDONLY | constants.O_NOFOLLOW);
+    const metadata = await handle.stat();
+    if (!metadata.isFile()) {
+      await handle.close();
+      throw new Error("Contained path is not a regular file");
+    }
+    return handle;
+  } finally {
+    await parent.handle.close();
+  }
+}
+function sameIdentity(left, right) {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+async function assertContainedFileCurrent(root, relative, expected) {
+  const current = await openContainedFile(root, relative);
+  try {
+    if (!sameIdentity(await expected.stat(), await current.stat())) {
+      throw new Error("Contained file identity changed during authorization");
+    }
+  } finally {
+    await current.close();
+  }
+}
+async function assertContainedParentCurrent(root, relative, expected) {
+  const current = await openContainedParent(root, relative);
+  try {
+    if (!sameIdentity(await expected.stat(), await current.handle.stat())) {
+      throw new Error("Contained parent identity changed during authorization");
+    }
+  } finally {
+    await current.handle.close();
+  }
+}
+async function readContainedUtf8Handle(handle, maxBytes) {
+  const metadata = await handle.stat();
+  if (!metadata.isFile())
+    throw new Error("Contained path is not a regular file");
+  if (metadata.size > maxBytes)
+    throw new Error("Contained file exceeds byte budget");
+  const buffer = Buffer.alloc(metadata.size);
+  let offset = 0;
+  while (offset < buffer.byteLength) {
+    const { bytesRead } = await handle.read(buffer, offset, buffer.byteLength - offset, offset);
+    if (bytesRead === 0)
+      break;
+    offset += bytesRead;
+  }
+  if (offset !== metadata.size)
+    throw new Error("Contained file changed while being read");
+  return {
+    text: new TextDecoder("utf-8", { fatal: true }).decode(buffer),
+    bytes: offset,
+    mode: metadata.mode
+  };
+}
+async function walkContainedFiles(input) {
+  const scan = await scanContainedFiles({ ...input, symlinks: "refuse" });
+  if (scan.truncated)
+    throw new Error("Contained file traversal exceeded its bounds");
+  return scan.files;
+}
+async function scanContainedFiles(input) {
+  const files = [];
+  let truncated = false;
+  let skippedDirectories = 0;
+  let skippedSymlinks = 0;
+  const root = await openPinnedDirectory(input.root);
+  const visit = async (directory, relativeDirectory, depth) => {
+    if (truncated)
+      return;
+    if (depth > input.maxDepth) {
+      truncated = true;
+      return;
+    }
+    const entries = await readdir(descriptorPath(directory), { withFileTypes: true });
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+      const relative = relativeDirectory ? path.join(relativeDirectory, entry.name) : entry.name;
+      const anchored = path.join(descriptorPath(directory), entry.name);
+      if (entry.isSymbolicLink()) {
+        if (input.symlinks === "refuse") {
+          throw new Error(`Contained file traversal refuses symlink: ${relative}`);
+        }
+        skippedSymlinks += 1;
+        continue;
+      }
+      if (entry.isDirectory()) {
+        if (input.excludeDirectory?.(relative)) {
+          skippedDirectories += 1;
+          continue;
+        }
+        let child;
+        try {
+          child = await open(anchored, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+        } catch (error) {
+          if (input.symlinks === "skip") {
+            skippedSymlinks += 1;
+            continue;
+          }
+          throw error;
+        }
+        try {
+          await visit(child, relative, depth + 1);
+        } finally {
+          await child.close();
+        }
+        continue;
+      }
+      if (!entry.isFile())
+        continue;
+      if (files.length >= input.maxFiles) {
+        truncated = true;
+        return;
+      }
+      let content;
+      if (input.readMaxBytes !== undefined) {
+        try {
+          const handle = await open(anchored, constants.O_RDONLY | constants.O_NOFOLLOW);
+          try {
+            content = await readContainedUtf8Handle(handle, input.readMaxBytes);
+          } finally {
+            await handle.close();
+          }
+        } catch (error) {
+          if (input.skipUnreadable)
+            continue;
+          throw error;
+        }
+      }
+      files.push({ absolute: relative, relative, ...content && { content } });
+    }
+  };
+  try {
+    await visit(root, "", 0);
+  } finally {
+    await root.close();
+  }
+  return { files, truncated, skippedDirectories, skippedSymlinks };
+}
+
+export { openContainedParent, openContainedFile, assertContainedFileCurrent, assertContainedParentCurrent, readContainedUtf8Handle, walkContainedFiles, scanContainedFiles };

package/dist/{index-gqdfpv4n.js → index-y3w12g8d.js}

@@ -1,10 +1,10 @@
 import {
   collectTools,
   createToolRunner
-} from "./index-kg9xx84n.js";
+} from "./index-7rey2b8s.js";
 import {
   toolErrorFromResult
-} from "./index-h8vn1jcr.js";
+} from "./index-qzbg46b6.js";
 import {
   assertUniqueToolName
 } from "./index-22by16v6.js";

package/dist/node.js

@@ -5,7 +5,7 @@ import {
   createHandler,
   createSocketIOServer,
   createUnixClientTransport
-} from "./index-444747ww.js";
+} from "./index-38hs3a58.js";
 import {
   createImplement,
   createImplementRegistry,
@@ -14,8 +14,8 @@ import {
   createScopedImplementRegistry,
   implement,
   implementRegistry
-} from "./index-d1jsvkyk.js";
-import"./index-p1be103g.js";
+} from "./index-vbf2p6me.js";
+import"./index-ktsps64f.js";
 import"./index-7b188kmz.js";
 import {
   ShutdownOptionsSchema,
@@ -24,7 +24,8 @@ import {
   ShutdownStatusSchema,
   createServerLifecycle
 } from "./index-dk6e56g0.js";
-import"./index-x18ndp4p.js";
+import"./index-bd17ytae.js";
+import"./index-vj3vvpaa.js";
 import {
   AppError,
   appError,

package/dist/observability/index.js

@@ -10,7 +10,7 @@ import {
   redact,
   sanitizePayload,
   truncatePreview
-} from "../index-zh459sfj.js";
+} from "../index-aczggrty.js";
 import {
   getRequestContext,
   getTraceId,
@@ -21,7 +21,7 @@ import {
   setRequestError,
   setRequestUser,
   wrapInRequestContext
-} from "../index-p1be103g.js";
+} from "../index-ktsps64f.js";
 import {
   childSpan,
   createTraceContext,
@@ -30,7 +30,8 @@ import {
   recordedErrorMessage,
   resolvePropagationContext,
   resolveTraceContext
-} from "../index-x18ndp4p.js";
+} from "../index-bd17ytae.js";
+import"../index-vj3vvpaa.js";
 import"../index-0w9abg87.js";
 import {
   isRecord

package/dist/remote.js

@@ -1,11 +1,12 @@
 import {
   ApiError,
   createClient
-} from "./index-kxxyvkka.js";
-import"./index-t4dpby6e.js";
+} from "./index-wc80at9n.js";
+import"./index-0yphgata.js";
+import"./index-bd17ytae.js";
 import {
   mergeMeta
-} from "./index-x18ndp4p.js";
+} from "./index-vj3vvpaa.js";
 import {
   AppError
 } from "./index-0w9abg87.js";

package/dist/server/index.js

@@ -13,7 +13,7 @@ import {
   sseRoute,
   streamingRoute,
   webSocketLane
-} from "../index-444747ww.js";
+} from "../index-38hs3a58.js";
 import {
   composeAuthHooks,
   createAuthHook,
@@ -26,7 +26,7 @@ import {
   signJwt,
   verifyJwt,
   verifyPkce
-} from "../index-q7gdep2c.js";
+} from "../index-da1aqnhb.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS,
   DEFAULT_CORS_EXPOSE_HEADERS,
@@ -40,7 +40,7 @@ import {
   defineMultipartStream,
   implement,
   implementRegistry
-} from "../index-d1jsvkyk.js";
+} from "../index-vbf2p6me.js";
 import {
   extractIp,
   generateTraceId,
@@ -48,7 +48,7 @@ import {
   getTraceId,
   resolveSocketIp,
   resolveTraceId
-} from "../index-p1be103g.js";
+} from "../index-ktsps64f.js";
 import {
   isWithinDir,
   realPathWithinDir
@@ -69,16 +69,18 @@ import {
   inputIsQuery,
   parseSSE,
   streamSSE
-} from "../index-t4dpby6e.js";
+} from "../index-0yphgata.js";
 import {
-  DEFAULT_CONTRACT_STREAM_FRAME_BYTES,
   errorCode,
   formatZodError,
-  joinRoutePath,
   normalizeError,
-  parseTrailingWildcard,
   zodIssues
-} from "../index-x18ndp4p.js";
+} from "../index-bd17ytae.js";
+import {
+  DEFAULT_CONTRACT_STREAM_FRAME_BYTES,
+  joinRoutePath,
+  parseTrailingWildcard
+} from "../index-vj3vvpaa.js";
 import {
   AppError,
   STITCH_ERROR_STATUS,

package/dist/testing.js

@@ -24,11 +24,12 @@ import {
 import {
   createClient,
   createClients
-} from "./index-kxxyvkka.js";
-import"./index-t4dpby6e.js";
+} from "./index-wc80at9n.js";
+import"./index-0yphgata.js";
+import"./index-bd17ytae.js";
 import {
   joinRoutePath
-} from "./index-x18ndp4p.js";
+} from "./index-vj3vvpaa.js";
 import"./index-0w9abg87.js";
 import {
   isRecord

package/dist/tool-invoker.js

@@ -1,12 +1,13 @@
 import {
   createToolInvoker
-} from "./index-gqdfpv4n.js";
-import"./index-kg9xx84n.js";
-import"./index-h8vn1jcr.js";
-import"./index-p1be103g.js";
+} from "./index-y3w12g8d.js";
+import"./index-7rey2b8s.js";
+import"./index-qzbg46b6.js";
+import"./index-ktsps64f.js";
 import"./index-22by16v6.js";
 import"./index-cby4ar3v.js";
-import"./index-x18ndp4p.js";
+import"./index-bd17ytae.js";
+import"./index-vj3vvpaa.js";
 import"./index-0w9abg87.js";
 import"./index-qyrqwr4c.js";
 import"./index-6k1937bx.js";

package/dist/tools/agent-tool-error.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A mounted tool failed with a model-safe, transport-shaped error envelope.
+ *
+ * The AI SDK must observe a throw so it emits `tool-error`; returning this
+ * envelope would incorrectly mark the call successful. The original cause is
+ * retained for local observability while `message` contains only the safe
+ * envelope that may be sent to the model provider.
+ */
+export declare class AgentToolError extends Error {
+    readonly output: Record<string, unknown>;
+    constructor(output: Record<string, unknown>, cause?: unknown);
+}
+export declare function isAgentToolError(value: unknown): value is AgentToolError;
+//# sourceMappingURL=agent-tool-error.d.ts.map

package/dist/tools/agent-tool-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-tool-error.d.ts","sourceRoot":"","sources":["../../src/tools/agent-tool-error.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAgB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEhD,YAAY,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,EAAE,OAAO,EAW3D;CACF;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE"}

package/dist/tools/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/tools/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAwB,OAAO,EAAE,MAAM,IAAI,CAAC;AAGxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EACL,KAAK,WAAW,EAEhB,KAAK,aAAa,EAClB,KAAK,aAAa,EAEnB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAqC,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAG5D,MAAM,WAAW,YAAY;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,qCAAqC;IACrC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mEAAmE;IACnE,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC5D,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,gEAAgE;IAChE,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACjD;AAED,wBAAgB,UAAU,CACxB,QAAQ,EAAE,UAAU,GAAG,UAAU,EAAE,EACnC,MAAM,GAAE,gBAAqB,GAC5B,OAAO,CAyET"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/tools/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAwB,OAAO,EAAE,MAAM,IAAI,CAAC;AAGxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,OAAO,EACL,KAAK,WAAW,EAEhB,KAAK,aAAa,EAClB,KAAK,aAAa,EAEnB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAqC,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAG5D,MAAM,WAAW,YAAY;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,qCAAqC;IACrC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mEAAmE;IACnE,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC5D,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,gEAAgE;IAChE,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACjD;AAED,wBAAgB,UAAU,CACxB,QAAQ,EAAE,UAAU,GAAG,UAAU,EAAE,EACnC,MAAM,GAAE,gBAAqB,GAC5B,OAAO,CA4ET"}

package/dist/tools.js

@@ -1,14 +1,15 @@
 import {
   redact
-} from "./index-zh459sfj.js";
+} from "./index-aczggrty.js";
 import {
   buildToolManifest,
   mountAgent
-} from "./index-h7ctj1kp.js";
+} from "./index-s8nt8c22.js";
+import"./index-3xnq72rz.js";
 import {
   signJwt,
   verifyPkce
-} from "./index-q7gdep2c.js";
+} from "./index-da1aqnhb.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS,
   DEFAULT_PROCESS_SIGNALS,
@@ -16,10 +17,10 @@ import {
   defaultSignalSource,
   guardSignalCallback,
   reportSignalError
-} from "./index-d1jsvkyk.js";
+} from "./index-vbf2p6me.js";
 import {
   createToolInvoker
-} from "./index-gqdfpv4n.js";
+} from "./index-y3w12g8d.js";
 import {
   WaitTimeoutError,
   createCli,
@@ -28,10 +29,10 @@ import {
   fetchPinnedDocument,
   readCapped,
   runWaitOperation
-} from "./index-mbxds404.js";
+} from "./index-mjx0wt4c.js";
 import {
   collectToolSurface
-} from "./index-xxsq3ca1.js";
+} from "./index-vc498pst.js";
 import {
   createRuntimeToolFactory,
   defineRuntimeTool
@@ -40,19 +41,19 @@ import {
   collectTools,
   createToolRunner,
   formatToolError
-} from "./index-kg9xx84n.js";
+} from "./index-7rey2b8s.js";
 import {
   ToolExecutionControlError,
   coerceJsonArgs,
   executeToolMethod,
   isToolExecutionControlError,
   toolResultFromError
-} from "./index-h8vn1jcr.js";
+} from "./index-qzbg46b6.js";
 import {
   getRequestContext,
   getTraceId,
   runWithRequestContext
-} from "./index-p1be103g.js";
+} from "./index-ktsps64f.js";
 import {
   ManagedFileError
 } from "./index-bfcpjw20.js";
@@ -70,10 +71,12 @@ import {
 } from "./index-22by16v6.js";
 import"./index-cby4ar3v.js";
 import {
-  defineContract,
   normalizeError,
   resolvePropagationContext
-} from "./index-x18ndp4p.js";
+} from "./index-bd17ytae.js";
+import {
+  defineContract
+} from "./index-vj3vvpaa.js";
 import {
   AppError,
   STITCH_ERROR_STATUS

package/llms-full.txt

@@ -59,15 +59,15 @@ own, recorded as an ADR.
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the store and managed-resource conformance kits |
 | `stitchkit/declaration` | build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser | stable | `createCursorQuery`, `createCacheBridge` |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 10 of the 14 minors since 0.56.2, most recently 0.69.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 10 of the 15 minors since 0.56.2, most recently 0.69.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
 | `stitchkit/agent-runtime/coding-tools` | server (Bun or Node) | evolving | bounded host-authorized direct file and shell tools; a root boundary, not an OS sandbox |
 | `stitchkit/agent-runtime/openrouter` | server | evolving | isolated OpenRouter language-model adapter |
 | `stitchkit/agent-runtime/browser` | browser + server | evolving | canonical agent records, events and reconnect cursor without execution or sinks |
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
-| `@stitchkit/tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | server | evolving<br>_redefined in 3 of the 14 minors since 0.56.2, most recently 0.67.0_ | managed resource graph, readiness, admission, schedules and bounded shutdown |
+| `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
+| `stitchkit/application` | server | evolving<br>_redefined in 3 of the 15 minors since 0.56.2, most recently 0.67.0_ | managed resource graph, readiness, admission, schedules and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | isolated grammY polling and webhook lifecycle adapters |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 
@@ -224,7 +224,7 @@ set `OPENROUTER_API_KEY`, then run `bun run dev` and choose a live tool-capable
 model with `/model`. The provider catalog owns the exact model id and context window and presents
 weekly popularity separately from sourced benchmark observations; `OPENROUTER_MODEL` is only an
 optional preferred row. That profile is a thin `stitchkit.agent.ts` composition over the official
-`@stitchkit/tui` package and canonical headless harness:
+`stitchkit-tui` package and canonical headless harness:
 durable SQLite history, lazy skills, direct coding tools, approval continuations
 and recovery stay framework-owned primitives, while model choice, permissions,
 executables and OS isolation remain application policy.
@@ -4066,8 +4066,13 @@ cross-crash exactly-once guarantee remain application concerns.
 `stitchkit/agent-runtime/coding-tools` returns ordinary direct runtime tools named `read_file`,
 `write_file`, `search_files`, `apply_patch`, `run_command` and optional `read_output`. Every call passes a
 required host authorization callback. File paths are relative, bounded and contained after
-realpath resolution; writes/edits reject symlink targets, content is strict UTF-8 and retained
-bytes are finite. Shell accepts a finite alias mapped by the host to an absolute executable plus an
+descriptor-relative resolution: each ancestor is opened without following symlinks and remains
+pinned through authorization and the filesystem effect. Reads revalidate the pinned file identity;
+writes and patches revalidate the pinned parent identity; search and resource discovery descend
+only through opened directories. Linux uses `/proc/self/fd`; macOS and FreeBSD use `/dev/fd`.
+Other platforms fail these filesystem operations closed because Node exposes no equivalent
+portable directory-handle-relative API. Writes/edits reject symlink targets, content is strict
+UTF-8 and retained bytes are finite. Shell accepts a finite alias mapped by the host to an absolute executable plus an
 argument array — never a shell command string — and uses only the explicitly supplied environment.
 Arguments, output and time are bounded, while cancellation terminates the child. The configured
 root and cwd are path boundaries, not a security sandbox: isolate the process when an executable
@@ -4080,9 +4085,19 @@ multi-file atomicity. With an optional `AgentCodingArtifactStore`, shell output
 preview continues into an opaque bounded artifact and `read_output` reads slices without
 exposing a host path. Without a store, the previous finite output-limit behavior is unchanged.
 
+`run_command` treats every invocation as finite. `shellTimeoutMs` bounds normal execution and
+`shellTerminationGraceMs` bounds settlement after timeout, caller cancellation, output overflow or
+parent exit. POSIX hosts launch a dedicated process group and kill every descendant remaining in
+that group; a process that deliberately escapes the group is outside the guarantee. Node's
+portable Windows child-process API cannot kill a complete descendant tree without invoking a
+second host executable, so Windows kills the direct child, destroys retained pipes at the grace
+deadline and makes no descendant-cleanup claim. A signal already aborted before execution returns
+`cancelled` without spawning.
+
 One `createAgentHarnessFileResources` instance represents one immutable discovery generation:
 concurrent and repeated `load()` calls share it, so a direct resource read cannot cross into a
-new catalog unexpectedly. Construct a new loader to refresh after filesystem changes.
+new catalog unexpectedly. Discovery uses the same descriptor-anchored traversal as coding search;
+construct a new loader to refresh after filesystem changes.
 
 Runtime events preserve reasoning/text/tool lifecycle order. Durable admission,
 checkpoint, run-state and terminal events carry stable identities; transient
@@ -4509,7 +4524,9 @@ or silently accept an unknown future version.
 - `assistant-checkpoint` follows a successful checkpoint CAS;
 - `run-state` follows durable queue/acquire/interrupt transitions;
 - `tool-status` is transient lifecycle presentation with JSON-safe input on
-  start and output on completion; internal tool failures remain generic;
+  start and output on completion. A mounted typed failure carries the same safe
+  `{ error, details?, _hint? }` envelope as the durable result; an unknown
+  internal cause remains generic and stays in local observability only;
 - `terminal` follows the winning terminal CAS.
 
 These are post-commit notifications, not a transactional outbox: a process can
@@ -4625,6 +4642,14 @@ before a managed side effect and again before accepting its result. Fence loss
 uses an internal control signal: it stops the old loop and is not sent to the
 model as a tool error.
 
+`mountAgent` sends failed runner outcomes through the AI SDK's tool-error
+channel. AgentRuntime persists them with `outcome: 'error'`, publishes the same
+safe envelope, and replays them as an error result on later turns. Classification
+comes from the execution channel, never from inspecting output fields: a valid
+successful result such as `{ error: 'domain value' }` remains successful. Typed
+`AppError` codes and safe details may reach the model; arbitrary thrown causes
+are retained for local hooks and reduced to `INTERNAL_SERVER_ERROR` outside.
+
 The framework cannot undo an already-started non-cooperative external effect.
 Pass the stable call/run idempotency identity into business mutations when the
 effect must be replay-safe.
@@ -8869,6 +8894,21 @@ additive** — adopting it changes nothing in your code. (See
 So upgrading is: read the `### ⚠️ Breaking changes` of every version *above* your
 current one *up to* your target, and apply each snippet.
 
+## Released migration: 0.70.0
+
+### Descriptor-backed Agent filesystem containment
+
+Built-in coding file/search tools and `createAgentHarnessFileResources` now require a runtime
+that can address an opened directory descriptor: Linux `/proc/self/fd`, or macOS/FreeBSD
+`/dev/fd`. This is what keeps a mutable parent rename or outside-symlink replacement from changing
+the authorized target between validation and the actual effect.
+
+No call-site change is needed on those platforms. On Windows or another platform without that
+boundary, move the built-in filesystem operations to a supported worker or replace them with
+application-owned tools backed by an equivalent native handle API. They fail closed rather than
+falling back to path spelling. `run_command` remains separately available under its explicit
+executable alias and authorization policy; this change does not claim an executable sandbox.
+
 ## Released migration: 0.69.0
 
 ### Direct coding-tool operation names
@@ -12204,17 +12244,19 @@ artifact store is supplied, `read_output`.
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `createAgentCodingTools` | function | construct direct host-authorized bounded file, search, guarded patch, shell and artifact runtime-tool definitions |
+| `createAgentCodingTools` | function | construct direct host-authorized bounded file, search, guarded patch, shell and artifact runtime-tool definitions; filesystem operations require Linux `/proc/self/fd` or macOS/FreeBSD `/dev/fd` descriptor paths and otherwise fail closed |
 | `AgentCodingToolDefinition` | _type_ | peer-free structural direct-tool shape accepted by the canonical runtime-tool surface |
 | `AgentCodingToolConfig` | _type_ | absolute root, required authorization callback, finite executable alias map, exact child environment and optional limits |
 | `AgentCodingToolAuthorizationSchema` / `AgentCodingToolAuthorization` | schema / _type_ | discriminated read/write/search/patch/shell/artifact decision presented to host policy before effect |
-| `AgentCodingToolLimitsSchema` / `AgentCodingToolLimits` | schema / _type_ | explicit path/read/write/argument-count/argument-byte/output/artifact/timeout ceilings |
+| `AgentCodingToolLimitsSchema` / `AgentCodingToolLimits` | schema / _type_ | explicit path/read/write/argument-count/argument-byte/output/artifact/timeout/termination-grace ceilings |
 | `AgentCodingArtifactStore` | _type_ | host-owned opaque artifact write and bounded read boundary |
 | `FileReadInputSchema` / `FileReadOutputSchema` | schema | bounded strict-UTF-8 byte slice; offsets must align with UTF-8 code-point boundaries |
 | `FileWriteInputSchema` / `FileWriteOutputSchema` | schema | create-only by default or explicit atomic replacement; symlink targets fail closed |
 | `createShellInputSchema` / `ShellOutputSchema` | schema | enumerated executable alias plus arguments and concrete relative cwd; explicit exited/timeout/output-limit/cancelled outcome |
 
-The default ceilings are 4,096 path bytes, 256 KiB read/write/output, 128 shell arguments, 64 KiB
+File/search operations pin directory descriptors across authorization and the actual effect;
+resource discovery uses the same ancestor-safe traversal. This closes parent rename/symlink races
+without claiming an executable sandbox. The default ceilings are 4,096 path bytes, 256 KiB read/write/output, 128 shell arguments, 64 KiB
 of aggregate argument text, 4 MiB per artifact and 30 seconds. The root is a path-resolution
 boundary, not an OS sandbox; executable behavior, process
 isolation, credentials and external-effect idempotency remain host responsibilities.
@@ -12263,7 +12305,7 @@ loaded by the neutral, browser or Node runtime surfaces.
 
 ---
 
-## `@stitchkit/tui`
+## `stitchkit-tui`
 
 Separate optional evolving Bun/OpenTUI package over a caller-composed headless harness.
 
@@ -12290,7 +12332,7 @@ The slash palette owns its highlighted selection: Up/Down move it, Tab completes
 the exact command and Escape dismisses it. Partial input is never submitted while the palette is
 active; unknown slash text with no match remains an ordinary model prompt.
 
-### `@stitchkit/tui/core`
+### `stitchkit-tui/core`
 
 Renderer-neutral state only. This entrypoint imports neither React/OpenTUI nor the agent runtime.
 
@@ -12415,7 +12457,7 @@ payload.
 | `bindStdioProcessSignals` | function | explicitly bind OS signals to one close-only stdio handle — [guide](../guide/testing-and-deployment.md#stdio-process-signals) |
 | `buildMcpServer` | function | build an `McpServer` from contract/runtime surfaces; no-auth configs omit the second argument |
 | `mountMcp` | function | add contract tools to an existing `McpServer` — [guide](../guide/mcp-and-agents.md#mountmcp) |
-| `mountAgent` | function | a Vercel AI SDK `ToolSet` from a service — [guide](../guide/mcp-and-agents.md#ai-agents--mountagent) |
+| `mountAgent` | function | a Vercel AI SDK `ToolSet` from a service; failed executions reject through the SDK tool-error channel with a safe typed envelope, while successful output is never classified by field name — [guide](../guide/mcp-and-agents.md#ai-agents--mountagent) |
 | `defineRuntimeTool` | function | define one validated pathless operation for explicit MCP, Agent and/or CLI surfaces — [guide](../guide/mcp-and-agents.md#pathless-runtime-tools-and-multimodal-results) |
 | `createRuntimeToolFactory` | function | bind shared identity and Zod-validated per-call context for runtime tools — [guide](../guide/mcp-and-agents.md#pathless-runtime-tools-and-multimodal-results) |
 | `createToolInvoker` | function | compile an exposure-aware in-process dispatcher over the canonical tool runner; use peer-free `stitchkit/tools/invoker`, or the full `stitchkit/tools` adapter barrel — [guide](../guide/mcp-and-agents.md#in-process-calls--createtoolinvoker) |