stitchkit 0.70.0 → 0.70.1

package/llms-full.txt

@@ -953,21 +953,26 @@ const server = createServer({ services, socket })
 
 const result = await server.shutdown({
   gracePeriodMs: 30_000,
+  realtimeCloseTimeoutMs: 1_000,
   forceTimeoutMs: 5_000,
   retryAfterSeconds: 5,
   signal: shutdownController.signal,
 })
 ```
 
-The first call closes HTTP and Socket.IO admission, then gives the complete
-graceful request/realtime/runtime chain one `gracePeriodMs` budget. If that
-budget or the external signal forces destructive teardown, `forceTimeoutMs`
-bounds physical completion separately. Repeated calls return the same Promise;
+The first call closes HTTP and Socket.IO admission, then gives admitted HTTP/application work the
+full `gracePeriodMs` budget. Once that work drains, `realtimeCloseTimeoutMs` (default `1_000`)
+bounds WebSocket close handshakes inside the same outer deadline. Any upgraded sockets still open
+at that boundary are terminated without shortening HTTP grace, and graceful runtime shutdown
+continues. If the outer grace budget or external signal forces destructive teardown,
+`forceTimeoutMs` bounds physical completion separately. Repeated calls return the same Promise;
 the first options win. New
 ordinary HTTP work receives `503`, `Retry-After` and `Connection: close` outside
 `wrapFetch`. `result.outcome` is `clean` or `forced`; a forced result preserves
 the pending snapshot and reason while final pending counters describe the
-post-close transport state. A graceful phase error still runs forced cleanup and
+post-close transport state. `forcedWebSockets` counts both sockets terminated at the dedicated
+realtime bound and sockets terminated by outer force; `pendingWebSocketsAtForce` is only the latter
+snapshot, so a clean result can truthfully report a bounded realtime termination. A graceful phase error still runs forced cleanup and
 then rejects with the original error; a forced transport that cannot confirm
 completion before `forceTimeoutMs` rejects instead of reporting a false zero.
 `runtime` is a diagnostics escape hatch, not a second canonical stop path.
@@ -4069,7 +4074,9 @@ required host authorization callback. File paths are relative, bounded and conta
 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`.
+only through opened directories. Linux traverses `/proc/self/fd`; macOS uses the package's
+architecture-specific Node-API `openat` backend. Unsupported platforms, including FreeBSD until a
+real backend is qualified, fail closed. The package needs no install-time compiler or script.
 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
@@ -8899,11 +8906,13 @@ current one *up to* your target, and apply each snippet.
 ### 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
+that can address an opened directory descriptor: Linux `/proc/self/fd`, or the packaged macOS
+Node-API backend added in 0.70.1. 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
+No call-site change is needed on those platforms. The 0.70.0 notes incorrectly inferred macOS and
+FreeBSD support from `/dev/fd`; macOS is restored by 0.70.1 and FreeBSD remains unsupported. 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
@@ -11697,9 +11706,9 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `UnixListenConfig` | _type_ | unix listener — a socket path, or `{ path, mode }` to tighten the file mode after listen |
 | `BunServerHandle` | _type_ | managed Bun handle (`url`, `port`, `runtime`, `status`, `shutdown`) |
 | `ManagedServerHandle` | _type_ | shared lifecycle shape generic over the runtime escape hatch |
-| `ShutdownOptionsSchema` / `ShutdownOptions` | schema / _type_ | one graceful budget, bounded forced-completion timeout, retry hint and optional external abort signal |
+| `ShutdownOptionsSchema` / `ShutdownOptions` | schema / _type_ | HTTP/application grace, a separate WebSocket close-handshake bound, bounded forced-completion timeout, retry hint and optional external abort signal |
 | `ShutdownStatusSchema` / `ShutdownStatus` | schema / _type_ | live state and request/WebSocket counters |
-| `ShutdownResultSchema` / `ShutdownResult` | schema / _type_ | clean/forced result with final counters and at-force snapshots |
+| `ShutdownResultSchema` / `ShutdownResult` | schema / _type_ | clean/forced result with final counters, outer-force snapshots and `forcedWebSockets` including bounded realtime terminations |
 | `ShutdownStateSchema` / `ShutdownState` | schema / _type_ | managed lifecycle state machine |
 | `ServiceDef` | _type_ | the result of `implement` |
 | `MethodDef` | _type_ | one resolved endpoint inside a service |
@@ -11887,7 +11896,7 @@ cutovers are covered by the executable
 | `ManagedResourceDependency` | _type_ | a dependency named by id or given as the resource itself — the second form is what `context.use(...)` can type |
 | `ManagedResourcePublished` | _type_ | the value type `context.use(resource)` returns, recovered from that resource's own `start` |
 | `ManagedResourcePublishesNoValue` | _type_ | what `context.use(...)` returns for a resource that publishes nothing — a branded refusal rather than `never`, so reading it does not silently compile |
-| `ManagedServerResourceConfig` | _type_ | the server or a sync/async factory receiving `ManagedResourceContext`, plus stable ID, dependencies and shutdown policy for `managedServerResource` |
+| `ManagedServerResourceConfig` | _type_ | the server or a sync/async factory receiving `ManagedResourceContext`, plus stable ID, dependencies and server shutdown policy (`retryAfterSeconds`, `realtimeCloseTimeoutMs`) |
 | `ManagedServerResource` | _type_ | the resource `managedServerResource` returns, whose `start` publishes the `ManagedServerHandle` |
 | `ApplicationHealthHandlerOptions` / `ApplicationHealthHandlerOptionsSchema` | _type_ / schema | liveness/readiness selection and sanitized `Retry-After` policy |
 | `ApplicationOperationalHandlers` / `ApplicationOperationalHandlersOptions` / `ApplicationOperationalHandlersOptionsSchema` | _type_ / schema | conventional status/readiness/liveness route surface and shared retry policy |
@@ -12244,7 +12253,7 @@ 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; filesystem operations require Linux `/proc/self/fd` or macOS/FreeBSD `/dev/fd` descriptor paths and otherwise fail closed |
+| `createAgentCodingTools` | function | construct direct host-authorized bounded file, search, guarded patch, shell and artifact runtime-tool definitions; filesystem operations use Linux `/proc/self/fd` or the packaged macOS Node-API backend 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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.70.0",
+  "version": "0.70.1",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",
@@ -38,6 +38,7 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "native/*.node",
     "llms.txt",
     "llms-full.txt",
     "README.md",
@@ -141,6 +142,7 @@
     "access": "public"
   },
   "scripts": {
+    "build:native-contained-files": "node scripts/build-contained-files-native.mjs",
     "check": "bun x tsc --noEmit",
     "build:browser": "bun build src/index.ts src/react.ts src/contract/index.ts src/declaration.ts src/agent-runtime-browser.ts --outdir dist --target node --packages external --splitting --root src",
     "build:server": "bun build src/server/index.ts src/node.ts src/tools.ts src/tool-invoker.ts src/cli.ts src/remote.ts src/files.ts src/testing.ts src/observability/index.ts src/agent-runtime.ts src/agent-runtime-harness.ts src/agent-runtime-coding-tools.ts src/agent-runtime-openrouter.ts src/agent-runtime-sqlite-bun.ts src/agent-runtime-sqlite-node.ts src/application.ts src/application-grammy.ts src/application-opentelemetry.ts --outdir dist --target node --packages external --splitting --root src",

package/dist/index-xbtcszs7.js

@@ -1,202 +0,0 @@
-// 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 };