toolcraft 0.0.749 → 0.0.750

package/node_modules/@noble/hashes/webcrypto.d.ts

@@ -0,0 +1,121 @@
+import { type Pbkdf2Opt } from './pbkdf2.ts';
+import { type KDFInput, type TArg, type TRet } from './utils.ts';
+/** Callable WebCrypto hash function descriptor. */
+export type WebHash = {
+    /**
+     * Hashes one message with the selected WebCrypto digest.
+     * @param msg - message bytes to hash
+     * @returns Promise resolving to digest bytes.
+     */
+    (msg: TArg<Uint8Array>): Promise<TRet<Uint8Array>>;
+    /** WebCrypto algorithm name passed to `crypto.subtle`. */
+    webCryptoName: string;
+    /** Digest size in bytes. */
+    outputLen: number;
+    /** Input block size in bytes. */
+    blockLen: number;
+};
+/** WebCrypto SHA1 (RFC 3174) legacy hash function. It was cryptographically broken. */
+/**
+ * WebCrypto SHA2-256 hash function from RFC 6234.
+ * @param msg - message bytes to hash
+ * @returns Promise resolving to digest bytes.
+ * @example
+ * Hash a message with WebCrypto SHA2-256.
+ * ```ts
+ * await sha256(new Uint8Array([97, 98, 99]));
+ * ```
+ */
+export declare const sha256: TRet<WebHash>;
+/**
+ * WebCrypto SHA2-384 hash function from RFC 6234.
+ * @param msg - message bytes to hash
+ * @returns Promise resolving to digest bytes.
+ * @example
+ * Hash a message with WebCrypto SHA2-384.
+ * ```ts
+ * await sha384(new Uint8Array([97, 98, 99]));
+ * ```
+ */
+export declare const sha384: TRet<WebHash>;
+/**
+ * WebCrypto SHA2-512 hash function from RFC 6234.
+ * @param msg - message bytes to hash
+ * @returns Promise resolving to digest bytes.
+ * @example
+ * Hash a message with WebCrypto SHA2-512.
+ * ```ts
+ * await sha512(new Uint8Array([97, 98, 99]));
+ * ```
+ */
+export declare const sha512: TRet<WebHash>;
+/** WebCrypto HMAC function type. See {@link hmac} for usage. */
+type WebHmacFn = {
+    (hash: TArg<WebHash>, key: TArg<Uint8Array>, message: TArg<Uint8Array>): Promise<TRet<Uint8Array>>;
+    create(hash: TArg<WebHash>, key: TArg<Uint8Array>): any;
+};
+/**
+ * WebCrypto HMAC: RFC2104 message authentication code.
+ * @param hash - function that would be used e.g. sha256. Webcrypto version.
+ * @param key - authentication key bytes
+ * @param message - message bytes to authenticate
+ * @returns Promise resolving to authentication tag bytes.
+ * `.create()` exists only to mirror the synchronous API surface
+ * and always throws `not implemented`.
+ * @example
+ * Compute an RFC 2104 HMAC with WebCrypto.
+ * ```ts
+ * import { hmac, sha256 } from '@noble/hashes/webcrypto.js';
+ * const key = new Uint8Array([1, 2, 3]);
+ * const message = new Uint8Array([4, 5, 6]);
+ * const mac = await hmac(sha256, key, message);
+ * ```
+ */
+export declare const hmac: TRet<WebHmacFn>;
+/**
+ * WebCrypto HKDF (RFC 5869): derive keys from an initial input.
+ * Combines hkdf_extract + hkdf_expand in one step
+ * @param hash - hash function that would be used (e.g. sha256). Webcrypto version.
+ * @param ikm - input keying material, the initial key
+ * @param salt - optional salt value (a non-secret random value)
+ * @param info - optional context and application specific information bytes
+ * @param length - length of output keying material in bytes.
+ *   RFC 5869 §2.3 allows `0..255*HashLen`, so `0` requests an empty OKM.
+ * @returns Promise resolving to derived key bytes.
+ * The RFC `L <= 255 * HashLen` bound is enforced before calling WebCrypto.
+ * @throws If the current runtime does not provide `crypto.subtle`. {@link Error}
+ * @example
+ * WebCrypto HKDF (RFC 5869): derive keys from an initial input.
+ * ```ts
+ * import { hkdf, sha256 } from '@noble/hashes/webcrypto.js';
+ * import { randomBytes, utf8ToBytes } from '@noble/hashes/utils.js';
+ * const inputKey = randomBytes(32);
+ * const salt = randomBytes(32);
+ * const info = utf8ToBytes('application-key');
+ * const okm = await hkdf(sha256, inputKey, salt, info, 32);
+ * ```
+ */
+export declare function hkdf(hash: TArg<WebHash>, ikm: TArg<Uint8Array>, salt: TArg<Uint8Array | undefined>, info: TArg<Uint8Array | undefined>, length: number): Promise<TRet<Uint8Array>>;
+/**
+ * WebCrypto PBKDF2-HMAC: RFC 8018 key derivation function.
+ * @param hash - hash function that would be used e.g. sha256. Webcrypto version.
+ * @param password - password from which a derived key is generated; string
+ *   inputs are normalized through `kdfInputToBytes()`, i.e. UTF-8
+ * @param salt - cryptographic salt; string inputs are normalized through
+ *   `kdfInputToBytes()`, i.e. UTF-8
+ * @param opts - PBKDF2 work factor and output settings. `dkLen`, if provided,
+ *   must be `>= 1` per RFC 8018 §5.2. See {@link Pbkdf2Opt}.
+ * @returns Promise resolving to derived key bytes.
+ * Positive-iteration enforcement is currently delegated to backend
+ * `deriveBits()` rejection (for example `c = 0`), not a dedicated
+ * library-side guard. Values above the signed 32-bit backend range are rejected locally.
+ * @throws If the current runtime does not provide `crypto.subtle`. {@link Error}
+ * @example
+ * WebCrypto PBKDF2-HMAC: RFC 2898 key derivation function.
+ * ```ts
+ * import { pbkdf2, sha256 } from '@noble/hashes/webcrypto.js';
+ * const key = await pbkdf2(sha256, 'password', 'salt', { dkLen: 32, c: Math.pow(2, 18) });
+ * ```
+ */
+export declare function pbkdf2(hash: TArg<WebHash>, password: TArg<KDFInput>, salt: TArg<KDFInput>, opts: Pbkdf2Opt): Promise<TRet<Uint8Array>>;
+export {};

package/node_modules/@noble/hashes/webcrypto.js

@@ -0,0 +1,228 @@
+import {} from "./pbkdf2.js";
+import { abytes, ahash, anumber, checkOpts, clean, copyBytes, kdfInputToBytes, } from "./utils.js";
+function _subtle() {
+    const cr = typeof globalThis === 'object' ? globalThis.crypto : null;
+    const sb = cr?.subtle;
+    if (typeof sb === 'object' && sb != null)
+        return sb;
+    throw new Error('crypto.subtle must be defined');
+}
+function createWebHash(name, blockLen, outputLen) {
+    const hashC = async (msg) => {
+        abytes(msg);
+        const crypto = _subtle();
+        return new Uint8Array(await crypto.digest(name, msg));
+    };
+    hashC.webCryptoName = name; // make sure it won't interfere with function name
+    hashC.outputLen = outputLen;
+    hashC.blockLen = blockLen;
+    hashC.create = () => {
+        // Present only so this async wrapper satisfies the shared
+        // hash-wrapper shape checked by `ahashWeb()`.
+        throw new Error('not implemented');
+    };
+    // Later WebCrypto HMAC/HKDF/PBKDF2 calls read descriptor metadata directly, so freezing prevents
+    // callers from retargeting a `sha256` wrapper into a different backend digest by mutation.
+    return Object.freeze(hashC);
+}
+function ahashWeb(hash) {
+    ahash(hash);
+    const name = hash.webCryptoName;
+    if (typeof name !== 'string')
+        throw new Error('non-web hash');
+    return name;
+}
+/** WebCrypto SHA1 (RFC 3174) legacy hash function. It was cryptographically broken. */
+// export const sha1: WebHash = createHash('SHA-1', 64, 20);
+/**
+ * WebCrypto SHA2-256 hash function from RFC 6234.
+ * @param msg - message bytes to hash
+ * @returns Promise resolving to digest bytes.
+ * @example
+ * Hash a message with WebCrypto SHA2-256.
+ * ```ts
+ * await sha256(new Uint8Array([97, 98, 99]));
+ * ```
+ */
+export const sha256 = /* @__PURE__ */ createWebHash('SHA-256', 64, 32);
+/**
+ * WebCrypto SHA2-384 hash function from RFC 6234.
+ * @param msg - message bytes to hash
+ * @returns Promise resolving to digest bytes.
+ * @example
+ * Hash a message with WebCrypto SHA2-384.
+ * ```ts
+ * await sha384(new Uint8Array([97, 98, 99]));
+ * ```
+ */
+export const sha384 = /* @__PURE__ */ createWebHash('SHA-384', 128, 48);
+/**
+ * WebCrypto SHA2-512 hash function from RFC 6234.
+ * @param msg - message bytes to hash
+ * @returns Promise resolving to digest bytes.
+ * @example
+ * Hash a message with WebCrypto SHA2-512.
+ * ```ts
+ * await sha512(new Uint8Array([97, 98, 99]));
+ * ```
+ */
+export const sha512 = /* @__PURE__ */ createWebHash('SHA-512', 128, 64);
+/**
+ * WebCrypto HMAC: RFC2104 message authentication code.
+ * @param hash - function that would be used e.g. sha256. Webcrypto version.
+ * @param key - authentication key bytes
+ * @param message - message bytes to authenticate
+ * @returns Promise resolving to authentication tag bytes.
+ * `.create()` exists only to mirror the synchronous API surface
+ * and always throws `not implemented`.
+ * @example
+ * Compute an RFC 2104 HMAC with WebCrypto.
+ * ```ts
+ * import { hmac, sha256 } from '@noble/hashes/webcrypto.js';
+ * const key = new Uint8Array([1, 2, 3]);
+ * const message = new Uint8Array([4, 5, 6]);
+ * const mac = await hmac(sha256, key, message);
+ * ```
+ */
+export const hmac = /* @__PURE__ */ (() => {
+    const hmac_ = async (hash, key, message) => {
+        const crypto = _subtle();
+        abytes(key, undefined, 'key');
+        abytes(message, undefined, 'message');
+        const hashName = ahashWeb(hash);
+        // importKey() snapshots key synchronously, but message is not passed to sign() until after
+        // importKey() resolves. Keep the wrapper's inputs stable across that await.
+        const _message = copyBytes(message);
+        try {
+            // WebCrypto keys can't be zeroized
+            // prettier-ignore
+            const wkey = await crypto.importKey('raw', key, { name: 'HMAC', hash: hashName }, false, ['sign']);
+            return new Uint8Array(await crypto.sign('HMAC', wkey, _message));
+        }
+        finally {
+            clean(_message);
+        }
+    };
+    hmac_.create = (_hash, _key) => {
+        throw new Error('not implemented');
+    };
+    return hmac_;
+})();
+/**
+ * WebCrypto HKDF (RFC 5869): derive keys from an initial input.
+ * Combines hkdf_extract + hkdf_expand in one step
+ * @param hash - hash function that would be used (e.g. sha256). Webcrypto version.
+ * @param ikm - input keying material, the initial key
+ * @param salt - optional salt value (a non-secret random value)
+ * @param info - optional context and application specific information bytes
+ * @param length - length of output keying material in bytes.
+ *   RFC 5869 §2.3 allows `0..255*HashLen`, so `0` requests an empty OKM.
+ * @returns Promise resolving to derived key bytes.
+ * The RFC `L <= 255 * HashLen` bound is enforced before calling WebCrypto.
+ * @throws If the current runtime does not provide `crypto.subtle`. {@link Error}
+ * @example
+ * WebCrypto HKDF (RFC 5869): derive keys from an initial input.
+ * ```ts
+ * import { hkdf, sha256 } from '@noble/hashes/webcrypto.js';
+ * import { randomBytes, utf8ToBytes } from '@noble/hashes/utils.js';
+ * const inputKey = randomBytes(32);
+ * const salt = randomBytes(32);
+ * const info = utf8ToBytes('application-key');
+ * const okm = await hkdf(sha256, inputKey, salt, info, 32);
+ * ```
+ */
+export async function hkdf(hash, ikm, salt, info, length) {
+    const crypto = _subtle();
+    const hashName = ahashWeb(hash);
+    const hashOutputLen = hash.outputLen;
+    abytes(ikm, undefined, 'ikm');
+    anumber(length, 'length');
+    if (length > 255 * hashOutputLen)
+        throw new Error('Length must be <= 255*HashLen');
+    if (salt !== undefined)
+        abytes(salt, undefined, 'salt');
+    if (info !== undefined)
+        abytes(info, undefined, 'info');
+    // salt and info reach deriveBits() only after importKey() resolves, so snapshot them now.
+    const _salt = salt === undefined ? new Uint8Array(0) : copyBytes(salt);
+    const _info = info === undefined ? new Uint8Array(0) : copyBytes(info);
+    try {
+        const wkey = await crypto.importKey('raw', ikm, 'HKDF', false, ['deriveBits']);
+        const opts = { name: 'HKDF', hash: hashName, salt: _salt, info: _info };
+        const out = new Uint8Array(await crypto.deriveBits(opts, wkey, 8 * length));
+        if (out.length !== length) {
+            clean(out);
+            throw new Error('WebCrypto returned an invalid derived key length');
+        }
+        return out;
+    }
+    finally {
+        clean(_salt, _info);
+    }
+}
+/**
+ * WebCrypto PBKDF2-HMAC: RFC 8018 key derivation function.
+ * @param hash - hash function that would be used e.g. sha256. Webcrypto version.
+ * @param password - password from which a derived key is generated; string
+ *   inputs are normalized through `kdfInputToBytes()`, i.e. UTF-8
+ * @param salt - cryptographic salt; string inputs are normalized through
+ *   `kdfInputToBytes()`, i.e. UTF-8
+ * @param opts - PBKDF2 work factor and output settings. `dkLen`, if provided,
+ *   must be `>= 1` per RFC 8018 §5.2. See {@link Pbkdf2Opt}.
+ * @returns Promise resolving to derived key bytes.
+ * Positive-iteration enforcement is currently delegated to backend
+ * `deriveBits()` rejection (for example `c = 0`), not a dedicated
+ * library-side guard. Values above the signed 32-bit backend range are rejected locally.
+ * @throws If the current runtime does not provide `crypto.subtle`. {@link Error}
+ * @example
+ * WebCrypto PBKDF2-HMAC: RFC 2898 key derivation function.
+ * ```ts
+ * import { pbkdf2, sha256 } from '@noble/hashes/webcrypto.js';
+ * const key = await pbkdf2(sha256, 'password', 'salt', { dkLen: 32, c: Math.pow(2, 18) });
+ * ```
+ */
+export async function pbkdf2(hash, password, salt, opts) {
+    const crypto = _subtle();
+    const hashName = ahashWeb(hash);
+    const _opts = checkOpts({ dkLen: 32 }, opts);
+    const { c, dkLen } = _opts;
+    anumber(c, 'c');
+    anumber(dkLen, 'dkLen');
+    // Node's native WebCrypto PBKDF2 binding accepts only a signed 32-bit iteration count and aborts
+    // the process on larger values instead of returning a rejected promise.
+    if (c > 0x7fffffff)
+        throw new Error('"c" exceeds WebCrypto backend limit');
+    // RFC 8018 §5.2 defines dkLen as a positive integer.
+    if (dkLen < 1)
+        throw new Error('"dkLen" must be >= 1');
+    // SubtleCrypto.deriveBits() accepts an unsigned-long bit count. Byte lengths at or above
+    // 2^29 would wrap after multiplication by eight instead of requesting the intended length.
+    if (dkLen >= 2 ** 29)
+        throw new Error('derived key too long');
+    const _password = kdfInputToBytes(password, 'password');
+    try {
+        const saltBytes = kdfInputToBytes(salt, 'salt');
+        // String conversion already returns an owned array. Caller-owned byte salts need a snapshot
+        // because deriveBits() does not receive them until after importKey() resolves.
+        const _salt = typeof salt === 'string' ? saltBytes : copyBytes(saltBytes);
+        try {
+            const key = await crypto.importKey('raw', _password, 'PBKDF2', false, [
+                'deriveBits',
+            ]);
+            const deriveOpts = { name: 'PBKDF2', salt: _salt, iterations: c, hash: hashName };
+            const out = new Uint8Array(await crypto.deriveBits(deriveOpts, key, 8 * dkLen));
+            if (out.length !== dkLen) {
+                clean(out);
+                throw new Error('WebCrypto returned an invalid derived key length');
+            }
+            return out;
+        }
+        finally {
+            clean(_salt);
+        }
+    }
+    finally {
+        if (typeof password === 'string')
+            clean(_password);
+    }
+}

package/node_modules/@poe-code/agent-mcp-config/dist/apply.js

@@ -1,11 +1,7 @@
-import path from "node:path";
-import { isDeepStrictEqual } from "node:util";
+import { dirname } from "@poe-code/safe-fs/contracts";
 import { runMutations, configMutation, fileMutation } from "@poe-code/config-mutations";
 import { getAgentConfig, resolveConfigPath, isSupported } from "./configs.js";
 import { getShapeTransformer } from "./shapes.js";
-function getConfigDirectory(configPath) {
-    return path.dirname(configPath);
-}
 export class UnsupportedAgentError extends Error {
     constructor(agentId) {
         super(`Unsupported agent: ${agentId}`);
@@ -69,7 +65,7 @@ export async function configure(agentId, server, options) {
         await unconfigure(agentId, enabledServer, options);
         return;
     }
-    const configDir = getConfigDirectory(configPath);
+    const configDir = dirname(configPath);
     await runMutations([
         fileMutation.ensureDirectory({
             path: configDir,
@@ -87,12 +83,12 @@ export async function configure(agentId, server, options) {
                     : undefined;
                 const shapedServer = shaped;
                 const enabledShapedServer = enabledShaped;
-                if (existingServer !== undefined && isDeepStrictEqual(existingServer, shapedServer)) {
+                if (existingServer !== undefined && sameConfiguration(existingServer, shapedServer)) {
                     return { changed: false, content: document };
                 }
                 if (existingServer !== undefined &&
                     (enabledShapedServer === undefined ||
-                        !isDeepStrictEqual(existingServer, enabledShapedServer))) {
+                        !sameConfiguration(existingServer, enabledShapedServer))) {
                     throw new Error(`MCP server "${server.name}" already exists with different configuration in ${configPath}.`);
                 }
                 const newServers = {
@@ -131,7 +127,7 @@ export async function unconfigure(agentId, server, options) {
                     return { changed: false, content: document };
                 }
                 if (expectedServer !== undefined &&
-                    !isDeepStrictEqual(servers[serverName], expectedServer)) {
+                    !sameConfiguration(servers[serverName], expectedServer)) {
                     return { changed: false, content: document };
                 }
                 const newServers = { ...servers };
@@ -155,3 +151,21 @@ export async function unconfigure(agentId, server, options) {
         observers: options.observers
     });
 }
+function sameConfiguration(left, right) {
+    if (Object.is(left, right))
+        return true;
+    if (left === null || right === null || typeof left !== "object" || typeof right !== "object") {
+        return false;
+    }
+    if (Array.isArray(left) !== Array.isArray(right))
+        return false;
+    if (left instanceof Date || right instanceof Date) {
+        return left instanceof Date && right instanceof Date && Object.is(left.getTime(), right.getTime());
+    }
+    if (Array.isArray(left) && Array.isArray(right) && left.length !== right.length)
+        return false;
+    const keys = Object.keys(left);
+    if (keys.length !== Object.keys(right).length)
+        return false;
+    return keys.every(key => Object.hasOwn(right, key) && sameConfiguration(left[key], right[key]));
+}

package/node_modules/@poe-code/config-mutations/README.md

@@ -2,6 +2,8 @@
 
 Composable file and config mutation engine.
 
+The runtime works without Node built-ins: paths default to portable POSIX semantics, atomic writes use Web Crypto IDs, and filesystem access is injected. The testing filesystem returns `Uint8Array` bytes when no encoding is requested.
+
 This package applies ordered filesystem, JSON, TOML, YAML, and template
 mutations with dry-run support and observer hooks. Callers inject the filesystem
 so tests can use in-memory adapters and production flows can use

package/node_modules/@poe-code/config-mutations/dist/execution/apply-mutation.js

@@ -1,6 +1,5 @@
-import { randomUUID } from "node:crypto";
-import nativePath from "node:path";
-import { renderTemplate } from "toolcraft-design";
+import { posixPath as defaultPath } from "@poe-code/safe-fs/contracts";
+import { renderTemplate } from "toolcraft-design/components/template";
 import { isConfigObject } from "../types.js";
 import { getConfigFormat, detectFormat } from "../formats/index.js";
 import { cloneConfigObject, setConfigEntry } from "../formats/object.js";
@@ -47,7 +46,7 @@ async function assertRegularWriteTarget(context, targetPath) {
     // plant one to redirect a credential/config write outside it. Symlinks at or
     // above home are legitimate system links (e.g. /tmp -> /private/tmp on macOS,
     // /var -> /private/var) and must not block writes, so bound the walk at home.
-    const path = context.paths ?? nativePath;
+    const path = context.paths ?? defaultPath;
     const boundary = path.dirname(path.resolve(context.homeDir));
     let currentPath = path.resolve(targetPath);
     while (currentPath !== boundary) {
@@ -71,7 +70,7 @@ async function assertRegularWriteTarget(context, targetPath) {
 async function writeAtomically(context, targetPath, content) {
     await assertRegularWriteTarget(context, targetPath);
     for (let attempt = 0; attempt < 10; attempt += 1) {
-        const tempPath = `${targetPath}.mutation-tmp-${process.pid}-${randomUUID()}`;
+        const tempPath = `${targetPath}.mutation-tmp-${globalThis.crypto.randomUUID()}`;
         let tempCreated = false;
         try {
             await assertRegularWriteTarget(context, tempPath);

package/node_modules/@poe-code/config-mutations/dist/execution/path-utils.d.ts

@@ -1,9 +1,8 @@
-import nativePath from "node:path";
-import type { PathMapper } from "../types.js";
+import type { MutationContext, PathMapper } from "../types.js";
 /**
  * Expand ~ shortcut to the provided home directory.
  */
-export declare function expandHome(targetPath: string, homeDir: string, path?: typeof nativePath): string;
+export declare function expandHome(targetPath: string, homeDir: string, path?: NonNullable<MutationContext["paths"]>): string;
 /**
  * Validate that a path is home-relative (starts with ~).
  * Throws if the path is not home-relative.
@@ -15,4 +14,4 @@ export declare function validateHomePath(targetPath: string): void;
  * 2. Expands ~ to home directory
  * 3. If pathMapper is provided, maps the directory portion and reconstructs the path
  */
-export declare function resolvePath(rawPath: string, homeDir: string, pathMapper?: PathMapper, path?: typeof nativePath): string;
+export declare function resolvePath(rawPath: string, homeDir: string, pathMapper?: PathMapper, path?: NonNullable<MutationContext["paths"]>): string;

package/node_modules/@poe-code/config-mutations/dist/execution/path-utils.js

@@ -1,8 +1,8 @@
-import nativePath from "node:path";
+import { posixPath as defaultPath } from "@poe-code/safe-fs/contracts";
 /**
  * Expand ~ shortcut to the provided home directory.
  */
-export function expandHome(targetPath, homeDir, path = nativePath) {
+export function expandHome(targetPath, homeDir, path = defaultPath) {
     if (!targetPath?.startsWith("~")) {
         return targetPath;
     }
@@ -42,7 +42,7 @@ export function validateHomePath(targetPath) {
  * 2. Expands ~ to home directory
  * 3. If pathMapper is provided, maps the directory portion and reconstructs the path
  */
-export function resolvePath(rawPath, homeDir, pathMapper, path = nativePath) {
+export function resolvePath(rawPath, homeDir, pathMapper, path = defaultPath) {
     validateHomePath(rawPath);
     const expanded = expandHome(rawPath, homeDir, path);
     const canonicalHome = path.resolve(homeDir);

package/node_modules/@poe-code/config-mutations/dist/template/render.js

@@ -1,4 +1,4 @@
-import { renderTemplate as renderDesignTemplate } from "toolcraft-design";
+import { renderTemplate as renderDesignTemplate } from "toolcraft-design/components/template";
 /**
  * Render a mustache template with the given variables.
  * HTML escaping is disabled.

package/node_modules/@poe-code/config-mutations/dist/testing/mock-fs.d.ts

@@ -9,8 +9,8 @@ export interface MockFileSystem extends FileSystem {
     /** Get file content or undefined if not found */
     getContent(path: string): string | undefined;
     /** Read file with encoding overloads for compatibility */
-    readFile(path: string, encoding: BufferEncoding): Promise<string>;
-    readFile(path: string): Promise<Buffer>;
+    readFile(path: string, encoding: "utf8"): Promise<string>;
+    readFile(path: string): Promise<Uint8Array>;
 }
 export interface MockFsOptions {
     /** Initial files - paths can use ~ which will be expanded to homeDir */

package/node_modules/@poe-code/config-mutations/dist/testing/mock-fs.js

@@ -1,4 +1,4 @@
-import path from "node:path";
+import { posixPath as path } from "@poe-code/safe-fs/contracts";
 const DEFAULT_HOME_DIR = "/home/test";
 /**
  * Create an in-memory mock filesystem for testing mutations.
@@ -43,7 +43,7 @@ export function createMockFs(initialFiles, homeDir = DEFAULT_HOME_DIR) {
             if (encoding) {
                 return content;
             }
-            return Buffer.from(content, "utf8");
+            return new TextEncoder().encode(content);
         },
         async writeFile(filePath, content, options) {
             const absolutePath = expandPath(filePath, homeDir);
@@ -62,11 +62,8 @@ export function createMockFs(initialFiles, homeDir = DEFAULT_HOME_DIR) {
             if (typeof content === "string") {
                 files[absolutePath] = content;
             }
-            else if (Buffer.isBuffer(content)) {
-                files[absolutePath] = content.toString("utf8");
-            }
             else {
-                files[absolutePath] = Buffer.from(content.buffer, content.byteOffset, content.byteLength).toString("utf8");
+                files[absolutePath] = new TextDecoder().decode(new Uint8Array(content.buffer, content.byteOffset, content.byteLength));
             }
         },
         async mkdir(dirPath, options) {

package/node_modules/@poe-code/config-mutations/dist/types.d.ts

@@ -52,8 +52,10 @@ export interface PathMapper {
     }): string;
 }
 export interface MutationContext {
-    /** Path operations for the filesystem namespace; defaults to native host paths. */
-    paths?: typeof import("node:path");
+    /** Path operations for the filesystem namespace; defaults to portable POSIX paths. */
+    paths?: Pick<typeof import("@poe-code/safe-fs/contracts").posixPath, "join" | "resolve" | "relative" | "isAbsolute" | "dirname" | "basename"> & {
+        readonly sep: string;
+    };
     /** Filesystem interface - required */
     fs: FileSystem;
     /** Home directory for ~ expansion - required */

package/node_modules/@poe-code/process-runner/README.md

@@ -4,7 +4,6 @@ Low-level process execution abstraction. Single interface for launching processe
 
 ## Overview
 
-- No external dependencies
 - Consumed by `@poe-code/agent-spawn`
 - Consumed by `process-launcher`
 
@@ -40,4 +39,6 @@ This package exposes no environment variables.
 
 This package currently exposes no package-level configuration options.
 
+Import `uploadWorkspace` and `downloadWorkspace` from `@poe-code/process-runner/workspace-transfer` for portable transfers. Pass SafeFS `FileSystem` instances as `fs` and `remoteFs` in Workers; the host filesystem remains the default in Node.
+
 Workspace transfer validates a positive finite upload limit and applies gitignore traversal rules: an ignored parent must be unignored before its children can be included. Docker template hashing honors `.dockerignore`. Docker port mappings, wait output, and detached completion markers are validated before use.

package/node_modules/@poe-code/process-runner/dist/transfer-filesystem.d.ts

@@ -0,0 +1 @@
+export { createHostFileSystem as createDefaultFileSystem } from "@poe-code/safe-fs/node";

package/node_modules/@poe-code/process-runner/dist/transfer-filesystem.js

@@ -0,0 +1 @@
+export { createHostFileSystem as createDefaultFileSystem } from "@poe-code/safe-fs/node";

package/node_modules/@poe-code/process-runner/dist/transfer-filesystem.workerd.d.ts

@@ -0,0 +1,2 @@
+import type { FileSystem } from "@poe-code/safe-fs/contracts";
+export declare function createDefaultFileSystem(): FileSystem;

package/node_modules/@poe-code/process-runner/dist/transfer-filesystem.workerd.js

@@ -0,0 +1 @@
+export function createDefaultFileSystem() { throw new Error("Workspace transfer requires an injected filesystem in Workers."); }

package/node_modules/@poe-code/process-runner/dist/types.d.ts

@@ -59,7 +59,7 @@ export interface OpenSpec {
         stderr?: RunSpec["stderr"];
         env?: RunSpec["env"];
         tty?: boolean;
-        input?: string | Buffer;
+        input?: string | Uint8Array;
         captureOutput?: boolean;
         /** Keep stdout callbacks and draining, without retaining its full text when false. */
         captureStdout?: boolean;

package/node_modules/@poe-code/process-runner/dist/workspace-transfer.d.ts

@@ -1,3 +1,4 @@
+import type { FileSystem } from "@poe-code/safe-fs/contracts";
 import type { DownloadResult, UploadResult } from "./types.js";
 export type { DownloadResult, UploadResult } from "./types.js";
 export interface WorkspaceTransferDirent {
@@ -19,9 +20,9 @@ export interface WorkspaceTransferFileSystem {
     readdir(path: string, options: {
         withFileTypes: true;
     }): Promise<WorkspaceTransferDirent[]>;
-    readFile(path: string): Promise<Buffer>;
-    readFile(path: string, encoding: BufferEncoding): Promise<string>;
-    writeFile(path: string, data: string | Buffer, options?: {
+    readFile(path: string): Promise<Uint8Array>;
+    readFile(path: string, encoding: "utf8"): Promise<string>;
+    writeFile(path: string, data: string | Uint8Array, options?: {
         flag?: string;
         mode?: number;
     }): Promise<void>;
@@ -39,8 +40,8 @@ export interface WorkspaceTransferEnv {
     cwd: string;
     uploadDir: string;
     workspaceDir?: string;
-    fs?: WorkspaceTransferFileSystem;
-    remoteFs?: WorkspaceTransferFileSystem;
+    fs?: WorkspaceTransferFileSystem | FileSystem;
+    remoteFs?: WorkspaceTransferFileSystem | FileSystem;
 }
 export interface WorkspaceTransferOptions {
     runner?: WorkspaceTransferRunnerOptions;