@poe-platform/safe-js 0.1.805 → 0.1.807

package/README.md

@@ -10,6 +10,20 @@ Complete ECMAScript conformance has not been established; see
 
 Under `workerd` and `browser` conditions, the standalone root and `/core` exports select the portable interpreter with parsing (`parse`, `parseModule`, `parseSourceModule`), checkpoints (`dump`, `restore`), sandbox copy helpers, error classes, `declareHostOperation`, `makeFsModule`, `makeEnvModule`, `makeTimeModule`, `makeFailModule`, `makeMetricModule`, and `makeHarnessModule`. The `/modules/fs` entry is also portable; supply a filesystem adapter for host file access.
 
+Worker hosts must supply trusted data, native built-ins, callbacks, and ordinary native Promises. Do not pass untrusted host Proxies or Promise constructor/species accessors into the interpreter: portable proxy checks recognize interpreter-tracked proxies, and native Promise probes may consult constructor/species properties. Guest code remains interpreted; this host contract does not make arbitrary native JavaScript a sandboxed input.
+
+Without host-provided asynchronous context storage, portable context is stack-scoped. Call `captureHostContext()` inside a host operation before awaiting or scheduling work, then use its returned function around each context-sensitive continuation. Captures keep concurrent operations isolated and preserve disabled-context retirement; they do not automatically propagate through further native `await` expressions. Release captured functions when the operation finishes.
+
+```js
+import { captureHostContext } from "@poe-platform/safe-js";
+
+async function hostOperation(callback) {
+  const resume = captureHostContext();
+  const value = await externalWork();
+  return resume(() => callback(value));
+}
+```
+
 ## Quickstart
 
 Install the public ESM package. Its declared Node.js minimum is 18.18+, but
@@ -551,7 +565,9 @@ Factories return exports to register in `modules`; calling a factory alone does
 
 `spawn.retry(definition, options, retryOptions)` and `defaultRetry` use `{ maxAttempts, backoffMs, isErrorRetryable?, isRetryable? }`. `spawn.parallel(calls, options?)` accepts definition/options tuples or spawn-handle factories; options are `check`, `maxConcurrent`, `failFast`, and `signal`. Usage helpers are `createSpawnUsageAccumulator()` and `runWithSpawnUsageAccumulator(accumulator, operation)`.
 
-**Config files.** `parseMcpConfig(json, directory)` accepts `servers` and the three numeric MCP limits, resolving stdio paths against `directory`. `parseFsConfig(json)` accepts `{ adapter: { type, options }, root?, cwd?, readFileMaxBytes?, hostReadMemoryLimit? }`; `resolveFsConfig(config, { registry? })` constructs the adapter for `makeFsModule`. Built-in types are `memory` and `real`; `real` requires an absolute host `options.root`. Outer `root`/`cwd` are absolute virtual paths. Custom registry descriptors supply `validateOptions` and `create`. `maxSymlinkFollows` optionally bounds dangling-symlink canonicalization for rooted filesystem modules; it defaults to `Infinity` and accepts the same finite values through filesystem JSON configuration. Actual symlink cycles still fail. Signals and injected functions are SDK options, not JSON fields.
+The `./workerd` entrypoint exposes the same SDK exports as the Node entrypoint, including HTTP MCP and snapshot migration. Use an explicit process adapter for stdio MCP on Workers.
+
+**Config files.** `parseMcpConfig(json, directory)` accepts `servers` and the three numeric MCP limits, resolving stdio paths against `directory`. `parseFsConfig(json)` accepts `{ adapter: { type, options }, root?, cwd?, readFileMaxBytes?, hostReadMemoryLimit? }`; `resolveFsConfig(config, { registry? })` constructs the adapter for `makeFsModule`. Node built-in types are `memory` and `real`; `real` requires an absolute host `options.root`. The `./core` and `./workerd` entrypoints also expose these filesystem config helpers. Under Worker conditions, the default registry contains only `memory`; pass other adapters explicitly through `registry`. Outer `root`/`cwd` are absolute virtual paths. Custom registry descriptors supply `validateOptions` and `create`. `maxSymlinkFollows` optionally bounds dangling-symlink canonicalization for rooted filesystem modules; it defaults to `Infinity` and accepts the same finite values through filesystem JSON configuration. Actual symlink cycles still fail. Signals and injected functions are SDK options, not JSON fields.
 
 </details>
 

package/dist/agent-harness-tools/execution-env.d.ts

@@ -34,7 +34,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/dist/agent-harness-tools/harness-dashboard.d.ts

@@ -1,4 +1,4 @@
-import { type dashboard } from "../toolcraft-design/index.js";
+import type { dashboard, Dashboard, DashboardOptions } from "../toolcraft-design/index.js";
 import type { RunQueue } from "./run-queue.js";
 /** One view for an entire harness sequence, including work added while it runs. */
 export declare function createHarnessDashboard(options: {
@@ -8,6 +8,7 @@ export declare function createHarnessDashboard(options: {
     cwd: string;
     queue: RunQueue;
     validatePlan?: (path: string) => Promise<string>;
+    dashboardFactory?: (options: DashboardOptions) => Dashboard;
 }): {
     dashboard: dashboard.Dashboard;
     start(): void;

package/dist/agent-harness-tools/poe-command-execution.d.ts

@@ -1,4 +1,5 @@
-import { type RunnerScope, type ResolvedConfig, type StateManager } from "../poe-code-config/core.js";
+import type { FileSystem } from "@poe-platform/safe-fs/contracts";
+import type { RunnerScope, ResolvedConfig, StateManager } from "../poe-code-config/core.js";
 import { selectExecutionEnv, type OpenSpec } from "./execution-env.js";
 export type RuntimeOverrideOptions = {
     runtime?: "host" | "docker";
@@ -18,14 +19,15 @@ export declare function resolvePoeCommandExecution(input: {
     context?: {
         homeDir?: string;
         state?: StateManager;
+        fs?: Pick<FileSystem, "readFile" | "stat" | "realpath">;
     };
     openSpec?: Partial<Pick<OpenSpec, "execution" | "shellSpec">>;
-}): {
+}): Promise<{
     factory: ReturnType<typeof selectExecutionEnv>;
     openSpec: OpenSpec;
     detach: boolean;
     state: StateManager;
-};
+}>;
 /** Raised when a requested runner capability is not offered by the resolved execution env. */
 export declare class UnsupportedRuntimeCapabilityError extends Error {
     constructor(message: string);

package/dist/agent-harness-tools/runner.d.ts

@@ -5,7 +5,7 @@ export interface WorkflowFileStat {
     mtimeMs: number;
 }
 export interface WorkflowFileSystem {
-    readFile(path: string, encoding: BufferEncoding): Promise<string>;
+    readFile(path: string, encoding: "utf8"): Promise<string>;
     mkdir(path: string, options?: {
         recursive?: boolean;
     }): Promise<void>;

package/dist/agent-harness-tools/workspace-transfer.d.ts

@@ -1,3 +1,3 @@
-export { downloadWorkspace, uploadWorkspace } from "../process-runner/index.js";
-export type { WorkspaceDownloadOptions, WorkspaceTransferDirent, WorkspaceTransferEnv, WorkspaceTransferFileSystem, WorkspaceTransferOptions, WorkspaceTransferRunnerOptions, WorkspaceTransferStats } from "../process-runner/index.js";
+export { downloadWorkspace, uploadWorkspace } from "../process-runner/workspace-transfer.js";
+export type { WorkspaceDownloadOptions, WorkspaceTransferDirent, WorkspaceTransferEnv, WorkspaceTransferFileSystem, WorkspaceTransferOptions, WorkspaceTransferRunnerOptions, WorkspaceTransferStats } from "../process-runner/workspace-transfer.js";
 export type { DownloadResult, UploadResult } from "./execution-env.js";

package/dist/poe-acp-client/acp-transport.d.ts

@@ -1,4 +1,4 @@
-import { type ChildProcessWithoutNullStreams, type SpawnOptionsWithoutStdio } from "node:child_process";
+import type { ChildProcessWithoutNullStreams, SpawnOptionsWithoutStdio } from "node:child_process";
 import { type JsonRpcNotificationHandler, type JsonRpcRequestHandler, type JsonRpcRequestOptions } from "./jsonrpc-message-layer.js";
 import type { AuthenticateRequest, AuthenticateResponse, CancelNotification, CreateTerminalRequest, CreateTerminalResponse, InitializeRequest, InitializeResponse, KillTerminalCommandRequest, KillTerminalCommandResponse, LoadSessionRequest, LoadSessionResponse, NewSessionRequest, NewSessionResponse, PromptRequest, PromptResponse, ReadTextFileRequest, ReadTextFileResponse, ReleaseTerminalRequest, ReleaseTerminalResponse, RequestId, RequestPermissionRequest, RequestPermissionResponse, SessionNotification, SetSessionConfigOptionRequest, SetSessionConfigOptionResponse, SetSessionModeRequest, SetSessionModeResponse, TerminalOutputRequest, TerminalOutputResponse, WaitForTerminalExitRequest, WaitForTerminalExitResponse, WriteTextFileRequest, WriteTextFileResponse } from "./types.js";
 interface AcpRequestShape<TParams, TResult> {

package/dist/poe-code-config/memory.d.ts

@@ -12,3 +12,4 @@ export declare function configuredTimeout(options: MemoryConfigOptions): Promise
 export declare function cacheEnabled(options: MemoryConfigOptions): Promise<boolean>;
 export declare function mcpWritesAllowed(options: MemoryConfigOptions): Promise<boolean>;
 export declare function defaultQueryBudget(options: MemoryConfigOptions): Promise<number>;
+export { readMergedDocumentReadonly } from "./store.js";

package/dist/poe-code-config/runtime.d.ts

@@ -1,3 +1,4 @@
+import { type FileSystem } from "@poe-platform/safe-fs/contracts";
 import type { ResolvedConfig } from "./types.js";
 export interface RuntimeMount {
     source: string;
@@ -38,6 +39,7 @@ export interface RuntimeResolveResult {
     dockerfilePath: string | null;
     buildContext: string | null;
 }
+type RuntimeFileSystem = Pick<FileSystem, "stat" | "realpath">;
 export declare const runtimeConfigScope: {
     scope: string;
     schema: {
@@ -104,10 +106,11 @@ export declare const runtimeConfigScope: {
 };
 export declare function parseRunner(raw: unknown): RunnerScope;
 export declare function parseRuntime(raw: unknown): RuntimeConfig;
-export declare function resolveRuntime({ cwd, config }: {
+export declare function resolveRuntime({ cwd, config, fs }: {
     cwd: string;
     config: Pick<ResolvedConfig, "runtime">;
-}): RuntimeResolveResult;
+    fs?: RuntimeFileSystem;
+}): Promise<RuntimeResolveResult>;
 declare function parseBuildArgs(value: unknown): Record<string, string>;
 declare function parseMounts(value: unknown): RuntimeMount[];
 declare function parseOptionalStringArray(value: unknown, key?: string): string[] | undefined;

package/dist/process-runner/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/dist/process-runner/workspace-transfer.d.ts

@@ -1,3 +1,4 @@
+import type { FileSystem } from "@poe-platform/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;

package/dist/safe-js/chunks/{chunk-KMBCLXER.js → chunk-2IYZK337.js}

@@ -1,6 +1,6 @@
 import {
   hostCwd
-} from "./chunk-VVOPJZRG.js";
+} from "./chunk-H25SH6HQ.js";
 
 // packages/safe-js/src/modules/paths.ts
 import { basename, dirname, extname, isAbsolutePath, joinPath, relativePath, resolvePath } from "@poe-platform/safe-fs/core";

package/dist/safe-js/chunks/{chunk-WNCT5WTP.js → chunk-3W4JJFK6.js}

@@ -1,7 +1,7 @@
 import {
   SnapshotNotReadyError,
   serializeSafeJSSnapshot
-} from "./chunk-JVE54EBX.js";
+} from "./chunk-ROIZEQTS.js";
 import {
   SandboxError
 } from "./chunk-EQUBWQJN.js";

package/dist/safe-js/chunks/{chunk-GJPD4ALZ.js → chunk-425IYA26.js}

@@ -1,6 +1,6 @@
 import {
   isSandboxClosure
-} from "./chunk-JVE54EBX.js";
+} from "./chunk-ROIZEQTS.js";
 
 // packages/safe-js/src/lint/runtime-modules.ts
 var AsyncFunction = (async () => void 0).constructor;

package/dist/safe-js/chunks/{chunk-2LI4AP6C.js → chunk-5FPEN6AM.js}

@@ -7,15 +7,15 @@ import {
 } from "./chunk-ONWFPHUI.js";
 import {
   restore
-} from "./chunk-HR3HSM26.js";
+} from "./chunk-SAYUBVHD.js";
 import {
   hashParsedAst,
   hashSource
-} from "./chunk-AN6Z3R6M.js";
+} from "./chunk-MJH5AYEK.js";
 import {
   attachDumpController,
   createDumpController
-} from "./chunk-WNCT5WTP.js";
+} from "./chunk-3W4JJFK6.js";
 import {
   DUMP_FORMAT_VERSION,
   EXECUTION_SEMANTICS,
@@ -107,7 +107,7 @@ import {
   wrapCallerInjectedBindings,
   wrapCancelableBindings,
   wrapHostConstructor
-} from "./chunk-JVE54EBX.js";
+} from "./chunk-ROIZEQTS.js";
 import {
   Budget,
   CompileScope,
@@ -125,13 +125,13 @@ import {
 } from "./chunk-EQUBWQJN.js";
 import {
   dirname
-} from "./chunk-KMBCLXER.js";
+} from "./chunk-2IYZK337.js";
 import {
   AsyncLocalStorage,
   createHostCallbackContext,
   hostFs,
   types
-} from "./chunk-VVOPJZRG.js";
+} from "./chunk-H25SH6HQ.js";
 
 // packages/safe-js/src/modules/source-graph.ts
 var ambiguous = /* @__PURE__ */ Symbol("ambiguous module export");
@@ -801,6 +801,7 @@ var RealmState = class {
   nestedDepth = 0;
   failure;
   bridgeOptions = () => ({
+    resources: this.resources,
     budget: this.budget,
     compileOwner: this.lease.owner,
     signal: this.controller.signal,
@@ -2339,7 +2340,7 @@ function run(source, options = {}) {
         throw new TypeError("Source resolution requires sourceType: 'module'.");
       if (options.sourceRoot !== void 0) {
         if (options.sourceResolver !== void 0) throw new TypeError("Specify sourceRoot or sourceResolver, not both.");
-        const { createRootedSourceResolver } = await import("./source-files-A2WSOO6G.js");
+        const { createRootedSourceResolver } = await import("./source-files-QT24SQTE.js");
         const { sourceRoot, ...resolved } = options;
         const sourceResolver = await createRootedSourceResolver(sourceRoot);
         return runWithExtensions(source, { ...resolved, filename: await sourceResolver.entryId(options.filename), sourceResolver }, jobs);

package/dist/safe-js/chunks/{chunk-NOS76GMS.js → chunk-5ZVTZBH2.js}

@@ -1,6 +1,6 @@
 import {
   deepCopyToSandbox
-} from "./chunk-JVE54EBX.js";
+} from "./chunk-ROIZEQTS.js";
 
 // packages/safe-js/src/modules/harness.ts
 function makeHarnessModule(frontmatter, meta) {

package/dist/safe-js/chunks/{chunk-N3EL5B4L.js → chunk-7RGEML7S.js}

@@ -2,11 +2,11 @@ import {
   McpError,
   connectMcpTransport,
   normalizeMcpOptions
-} from "./chunk-HFCSCNZN.js";
+} from "./chunk-E7V44LSN.js";
 import {
   declareHostOperation,
   runResources
-} from "./chunk-JVE54EBX.js";
+} from "./chunk-ROIZEQTS.js";
 import {
   hostErrorData
 } from "./chunk-EQUBWQJN.js";
@@ -34,13 +34,14 @@ function makeMcpModule(connectMcp) {
         return current.ready;
       };
       const invoke = async (operation) => {
+        const scope = runResources.getStore();
         try {
           const result = await operation(await connection());
-          runResources.getStore()?.signal.throwIfAborted();
+          scope?.signal.throwIfAborted();
           options.signal?.throwIfAborted();
           return result;
         } catch (error) {
-          runResources.getStore()?.signal.throwIfAborted();
+          scope?.signal.throwIfAborted();
           options.signal?.throwIfAborted();
           if (error instanceof McpError) {
             hostErrorData.set(error, {

package/dist/safe-js/chunks/{chunk-VQKUOXQ2.js → chunk-BEA7FA5M.js}

@@ -1,19 +1,25 @@
 import {
   restore
-} from "./chunk-HR3HSM26.js";
+} from "./chunk-SAYUBVHD.js";
 import {
   createSeededRandom,
   deepCopyFromSandbox
-} from "./chunk-JVE54EBX.js";
+} from "./chunk-ROIZEQTS.js";
 import {
   parse,
   parseModule,
   parseSourceModule
 } from "./chunk-EQUBWQJN.js";
+import {
+  AsyncLocalStorage
+} from "./chunk-H25SH6HQ.js";
 
 // packages/safe-js/src/parse.ts
 var parse2 = parse;
 
+// packages/safe-js/src/host-context.ts
+var captureHostContext = AsyncLocalStorage.snapshot;
+
 // packages/safe-js/src/modules/time.ts
 function makeTimeModule(options = {}) {
   const hasDeterministicRandom = options.random !== void 0 || options.seed !== void 0;
@@ -92,6 +98,7 @@ var restore2 = restore;
 var deepCopyFromSandbox2 = deepCopyFromSandbox;
 
 export {
+  captureHostContext,
   parse2 as parse,
   makeTimeModule,
   parseModule2 as parseModule,

package/dist/safe-js/chunks/{chunk-WZ27FAD3.js → chunk-C5NG3LHQ.js}

@@ -7,7 +7,7 @@ import {
 import {
   declareBudgetedHostOperation,
   declareHostOperation
-} from "./chunk-JVE54EBX.js";
+} from "./chunk-ROIZEQTS.js";
 import {
   basename,
   dirname,
@@ -15,14 +15,14 @@ import {
   relative,
   resolve,
   sep
-} from "./chunk-KMBCLXER.js";
+} from "./chunk-2IYZK337.js";
 import {
   accessDeniedSystemError,
   constants,
   hostFs,
   hostPlatform,
   inspect
-} from "./chunk-VVOPJZRG.js";
+} from "./chunk-H25SH6HQ.js";
 
 // packages/safe-js/src/modules/fs.ts
 import { createFsBridge } from "@poe-platform/safe-fs/core";