stitchkit 0.69.0 → 0.70.1

package/dist/{index-t4dpby6e.js → index-0yphgata.js}

@@ -1,6 +1,6 @@
 import {
   normalizeError
-} from "./index-x18ndp4p.js";
+} from "./index-bd17ytae.js";
 
 // src/internal/bounded-lines.ts
 var DEFAULT_STREAM_LINE_BYTES = 1024 * 1024;

package/dist/index-1z5xxfst.js

@@ -0,0 +1,397 @@
+// src/agent-runtime/contained-files.ts
+import {
+  close as closeDescriptor,
+  constants,
+  existsSync,
+  fchmod,
+  fstat,
+  read as readDescriptor,
+  write as writeDescriptor
+} from "node:fs";
+import { lstat, open, readdir, realpath, rename, unlink, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+var FILE_TYPE_MASK = 61440;
+var FILE_TYPE_DIRECTORY = 16384;
+var FILE_TYPE_REGULAR = 32768;
+var FILE_TYPE_SYMLINK = 40960;
+function modeIs(mode, type) {
+  return (mode & FILE_TYPE_MASK) === type;
+}
+function hasFunctions(value, names) {
+  return typeof value === "object" && value !== null && names.every((name) => typeof Reflect.get(value, name) === "function");
+}
+var darwinBinding;
+function loadDarwinBinding() {
+  if (darwinBinding)
+    return darwinBinding;
+  const directory = path.dirname(fileURLToPath(import.meta.url));
+  const binary = `darwin-${process.arch}.node`;
+  const candidates = [
+    path.resolve(directory, "../native", binary),
+    path.resolve(directory, "../../native", binary)
+  ];
+  const selected = candidates.find((candidate) => existsSync(candidate));
+  if (!selected) {
+    throw new Error(`Contained filesystem operations need the packaged Darwin ${process.arch} backend`);
+  }
+  const loaded = createRequire(import.meta.url)(selected);
+  const methods = [
+    "openDirectoryAt",
+    "openFileAt",
+    "createFileAt",
+    "statAt",
+    "listAt",
+    "renameAt",
+    "unlinkAt"
+  ];
+  if (!hasFunctions(loaded, methods)) {
+    throw new Error("The packaged Darwin contained-files backend has an invalid surface");
+  }
+  darwinBinding = loaded;
+  return darwinBinding;
+}
+
+class NumericFileHandle {
+  fd;
+  constructor(fd) {
+    this.fd = fd;
+  }
+  close() {
+    return new Promise((resolve, reject) => {
+      closeDescriptor(this.fd, (error) => error ? reject(error) : resolve());
+    });
+  }
+  read(buffer, offset, length, position) {
+    return new Promise((resolve, reject) => {
+      readDescriptor(this.fd, buffer, offset, length, position, (error, bytesRead) => error ? reject(error) : resolve({ bytesRead }));
+    });
+  }
+  stat() {
+    return new Promise((resolve, reject) => {
+      fstat(this.fd, (error, metadata) => error ? reject(error) : resolve(metadata));
+    });
+  }
+}
+function descriptorPath(handle) {
+  if (process.platform === "linux")
+    return `/proc/self/fd/${handle.fd}`;
+  throw new Error("Descriptor paths are available only in the Linux contained-files backend");
+}
+function sameIdentity(left, right) {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+async function openPinnedDirectory(absolute) {
+  if (process.platform !== "linux" && process.platform !== "darwin") {
+    throw new Error("Contained filesystem operations support Linux and macOS only");
+  }
+  const expected = await realpath(absolute);
+  const handle = await open(expected, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+  try {
+    const [pathMetadata, handleMetadata] = await Promise.all([lstat(expected), handle.stat()]);
+    if (!pathMetadata.isDirectory() || !sameIdentity(pathMetadata, handleMetadata)) {
+      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 openDirectoryAt(directory, name) {
+  if (process.platform === "darwin") {
+    return new NumericFileHandle(loadDarwinBinding().openDirectoryAt(directory.fd, name));
+  }
+  return open(path.join(descriptorPath(directory), name), constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+}
+async function openFileAt(directory, name) {
+  if (process.platform === "darwin") {
+    return new NumericFileHandle(loadDarwinBinding().openFileAt(directory.fd, name));
+  }
+  return open(path.join(descriptorPath(directory), name), constants.O_RDONLY | constants.O_NOFOLLOW);
+}
+function entryMetadata(mode) {
+  return {
+    mode,
+    isDirectory: () => modeIs(mode, FILE_TYPE_DIRECTORY),
+    isFile: () => modeIs(mode, FILE_TYPE_REGULAR),
+    isSymbolicLink: () => modeIs(mode, FILE_TYPE_SYMLINK)
+  };
+}
+async function statAt(directory, name) {
+  if (process.platform === "darwin") {
+    const metadata = loadDarwinBinding().statAt(directory.fd, name);
+    return metadata ? entryMetadata(metadata.mode) : null;
+  }
+  return lstat(path.join(descriptorPath(directory), name)).catch((error) => {
+    if (error.code === "ENOENT")
+      return null;
+    throw error;
+  });
+}
+async function listAt(directory) {
+  if (process.platform === "darwin") {
+    return loadDarwinBinding().listAt(directory.fd).map(({ name, mode }) => ({ name, ...entryMetadata(mode) }));
+  }
+  return readdir(descriptorPath(directory), { withFileTypes: true });
+}
+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 openDirectoryAt(current, segment);
+      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, basename };
+  } catch (error) {
+    await current.close();
+    throw error;
+  }
+}
+async function openContainedFile(root, relative) {
+  const parent = await openContainedParent(root, relative);
+  try {
+    const handle = await openFileAt(parent.handle, parent.basename);
+    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();
+  }
+}
+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 writeDescriptorFully(descriptor, content) {
+  const bytes = Buffer.from(content);
+  let offset = 0;
+  while (offset < bytes.byteLength) {
+    const written = await new Promise((resolve, reject) => {
+      writeDescriptor(descriptor, bytes, offset, bytes.byteLength - offset, null, (error, bytesWritten) => error ? reject(error) : resolve(bytesWritten));
+    });
+    if (written === 0)
+      throw new Error("Contained file write made no progress");
+    offset += written;
+  }
+}
+async function chmodDescriptor(descriptor, mode) {
+  await new Promise((resolve, reject) => {
+    fchmod(descriptor, mode & 4095, (error) => error ? reject(error) : resolve());
+  });
+}
+async function createDarwinFile(parent, name, content, mode) {
+  const binding = loadDarwinBinding();
+  const descriptor = binding.createFileAt(parent.fd, name, mode & 4095);
+  let failed;
+  try {
+    await writeDescriptorFully(descriptor, content);
+    await chmodDescriptor(descriptor, mode);
+  } catch (error) {
+    failed = error;
+  } finally {
+    try {
+      await new NumericFileHandle(descriptor).close();
+    } catch (error) {
+      failed ??= error;
+    }
+  }
+  if (failed) {
+    binding.unlinkAt(parent.fd, name);
+    throw failed;
+  }
+}
+async function writeContainedFile(input) {
+  const mode = input.mode ?? 438;
+  if (!input.replace) {
+    if (process.platform === "darwin") {
+      await createDarwinFile(input.parent.handle, input.parent.basename, input.content, mode);
+      return;
+    }
+    await writeFile(path.join(descriptorPath(input.parent.handle), input.parent.basename), input.content, { flag: "wx", mode });
+    return;
+  }
+  const temporary = `.${input.parent.basename}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  if (process.platform === "darwin") {
+    const binding = loadDarwinBinding();
+    let created = false;
+    try {
+      await createDarwinFile(input.parent.handle, temporary, input.content, mode);
+      created = true;
+      binding.renameAt(input.parent.handle.fd, temporary, input.parent.basename);
+    } catch (error) {
+      if (created)
+        binding.unlinkAt(input.parent.handle.fd, temporary);
+      throw error;
+    }
+    return;
+  }
+  const directory = descriptorPath(input.parent.handle);
+  const temporaryPath = path.join(directory, temporary);
+  try {
+    await writeFile(temporaryPath, input.content, { flag: "wx", mode });
+    await rename(temporaryPath, path.join(directory, input.parent.basename));
+  } catch (error) {
+    await unlink(temporaryPath).catch(() => {
+      return;
+    });
+    throw error;
+  }
+}
+async function containedEntryMetadata(parent) {
+  return statAt(parent.handle, parent.basename);
+}
+async function openContainedParentFile(parent) {
+  const handle = await openFileAt(parent.handle, parent.basename);
+  if (!(await handle.stat()).isFile()) {
+    await handle.close();
+    throw new Error("Contained path is not a regular file");
+  }
+  return handle;
+}
+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 listAt(directory)];
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+      const relative = relativeDirectory ? path.join(relativeDirectory, entry.name) : 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 openDirectoryAt(directory, entry.name);
+        } 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 openFileAt(directory, entry.name);
+          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, writeContainedFile, containedEntryMetadata, openContainedParentFile, readContainedUtf8Handle, walkContainedFiles, scanContainedFiles };

package/dist/index-3xnq72rz.js

@@ -0,0 +1,21 @@
+// src/tools/agent-tool-error.ts
+var AGENT_TOOL_ERROR_BRAND = Symbol.for("stitchkit.AgentToolError");
+
+class AgentToolError extends Error {
+  output;
+  constructor(output, cause) {
+    let message = "Tool execution failed";
+    try {
+      message = JSON.stringify(output);
+    } catch {}
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = "AgentToolError";
+    this.output = output;
+    Object.defineProperty(this, AGENT_TOOL_ERROR_BRAND, { value: true });
+  }
+}
+function isAgentToolError(value) {
+  return typeof value === "object" && value !== null && AGENT_TOOL_ERROR_BRAND in value;
+}
+
+export { AgentToolError, isAgentToolError };

package/dist/{index-444747ww.js → index-4g196jmf.js}

@@ -7,7 +7,7 @@ import {
   defaultSignalSource,
   guardSignalCallback,
   reportSignalError
-} from "./index-d1jsvkyk.js";
+} from "./index-vbf2p6me.js";
 import {
   extractIp,
   getClientInfo,
@@ -18,23 +18,25 @@ import {
   runWithRequestContext,
   setRequestEndpoint,
   setRequestError
-} from "./index-p1be103g.js";
+} from "./index-ktsps64f.js";
 import {
   ShutdownOptionsSchema
-} from "./index-dk6e56g0.js";
+} from "./index-7wpgrqa8.js";
 import {
-  DEFAULT_CONTRACT_STREAM_FRAME_BYTES,
   errorCode,
-  isUnsafeKey,
-  joinRoutePath,
   normalizeError,
-  parseTrailingWildcard,
   recordedErrorMessage,
   resolveTraceContext,
-  safeJsonParse,
   validateDeclaredOutput,
   zodIssues
-} from "./index-x18ndp4p.js";
+} from "./index-bd17ytae.js";
+import {
+  DEFAULT_CONTRACT_STREAM_FRAME_BYTES,
+  isUnsafeKey,
+  joinRoutePath,
+  parseTrailingWildcard,
+  safeJsonParse
+} from "./index-vj3vvpaa.js";
 import {
   AppError,
   badRequest
@@ -1788,6 +1790,9 @@ function bindProcessSignals(handle, options = {}) {
     ...requested.forceTimeoutMs !== undefined && {
       forceTimeoutMs: validated.forceTimeoutMs
     },
+    ...requested.realtimeCloseTimeoutMs !== undefined && {
+      realtimeCloseTimeoutMs: validated.realtimeCloseTimeoutMs
+    },
     ...requested.retryAfterSeconds !== undefined && {
       retryAfterSeconds: validated.retryAfterSeconds
     }

package/dist/{index-kg9xx84n.js → index-7rey2b8s.js}

@@ -1,6 +1,6 @@
 import {
   executeToolMethod
-} from "./index-h8vn1jcr.js";
+} from "./index-qzbg46b6.js";
 import {
   assertToolExtensionCompatible,
   mergeSchemas,

package/dist/{index-dk6e56g0.js → index-7wpgrqa8.js}

@@ -10,6 +10,7 @@ var ShutdownStateSchema = z.enum([
 ]);
 var ShutdownOptionsSchema = z.object({
   gracePeriodMs: z.number().int().nonnegative().default(30000),
+  realtimeCloseTimeoutMs: z.number().int().nonnegative().default(1000),
   forceTimeoutMs: z.number().int().nonnegative().default(5000),
   retryAfterSeconds: z.number().int().nonnegative().default(5),
   signal: z.custom((value) => typeof value === "object" && value !== null && ("aborted" in value) && ("addEventListener" in value), "Expected an AbortSignal").optional()
@@ -63,6 +64,32 @@ function untilAbort(signal) {
     return Promise.resolve();
   return new Promise((resolve) => signal.addEventListener("abort", () => resolve(), { once: true }));
 }
+function closeRealtimeWithin(adapter, timeoutMs, signal) {
+  if (signal.aborted)
+    return Promise.resolve("aborted");
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (outcome) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      signal.removeEventListener("abort", onAbort);
+      resolve(outcome);
+    };
+    const onAbort = () => finish("aborted");
+    const timer = setTimeout(() => finish("timeout"), timeoutMs);
+    signal.addEventListener("abort", onAbort, { once: true });
+    adapter.closeRealtime().then(() => finish("closed"), (error) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      signal.removeEventListener("abort", onAbort);
+      reject(error);
+    });
+  });
+}
 function withTimeout(promise, timeoutMs, message) {
   return new Promise((resolve, reject) => {
     const timer = setTimeout(() => reject(new Error(message)), timeoutMs);
@@ -119,6 +146,7 @@ function createServerLifecycle(getAdapter) {
       const phaseAbort = new AbortController;
       let forcedReason;
       let phaseError;
+      let forcedWebSockets = 0;
       const force = (reason) => {
         if (forcedReason)
           return;
@@ -139,7 +167,13 @@ function createServerLifecycle(getAdapter) {
           await waitForZero(() => pendingApplicationRequests, phaseAbort.signal);
           if (!forcedReason) {
             state = "closing-realtime";
-            await Promise.race([adapter.closeRealtime(), untilAbort(phaseAbort.signal)]);
+            const realtimeOutcome = await closeRealtimeWithin(adapter, parsed.realtimeCloseTimeoutMs, phaseAbort.signal);
+            if (!forcedReason && realtimeOutcome === "timeout" && adapter.pendingWebSockets() > 0) {
+              forcedWebSockets += await Promise.race([
+                adapter.terminateRealtime(),
+                untilAbort(phaseAbort.signal).then(() => 0)
+              ]);
+            }
           }
           if (!forcedReason) {
             state = "stopping-runtime";
@@ -157,6 +191,7 @@ function createServerLifecycle(getAdapter) {
           state = "stopping-runtime";
           pendingRequestsAtForce = adapter.pendingRequests();
           pendingWebSocketsAtForce = adapter.pendingWebSockets();
+          forcedWebSockets += pendingWebSocketsAtForce;
           let forceError;
           let forceFailed = false;
           try {
@@ -189,7 +224,7 @@ function createServerLifecycle(getAdapter) {
           pendingRequestsAtForce,
           pendingWebSocketsAtForce,
           abortedRequests: pendingRequestsAtForce,
-          forcedWebSockets: pendingWebSocketsAtForce,
+          forcedWebSockets,
           durationMs: performance.now() - startedAt
         }));
       })().catch((error) => {

package/dist/{index-zh459sfj.js → index-aczggrty.js}

@@ -1,6 +1,6 @@
 import {
   isUnsafeKey
-} from "./index-x18ndp4p.js";
+} from "./index-vj3vvpaa.js";
 import {
   isRecord
 } from "./index-qyrqwr4c.js";