@poe-platform/safe-js 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Poe Platform
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+# SafeJS
+
+Run a JavaScript subset with explicit host capabilities, execution budgets, and resumable checkpoints.
+
+## Quickstart
+
+Install the public package (Node.js 18.18+ and ESM):
+
+```sh
+npm install @poe-platform/safe-js
+```
+
+Save this as `example.mjs`, then run `node example.mjs`:
+
+```js
+import { Budget, run } from "@poe-platform/safe-js";
+
+const result = await run("return prices.map(price => price * 2);", {
+  bindings: { prices: [3, 5, 8] },
+  budget: new Budget({ maxSteps: 10_000, maxCallDepth: 100 })
+});
+
+if (!result.ok) throw result.error;
+console.log(result.returnValue);
+// [6, 10, 16]
+```
+
+`run()` takes source text, not a file path. Success returns `ok`, `returnValue`, `snapshot`, and `stats`. Handle both an `ok: false` result and a rejected promise: parsing, budget exhaustion, cancellation, and some execution failures can reject. Top-level `await` in this example lets rejections reach Node.
+
+`@poe-platform/safe-js/core` exposes `run`, `lint`, `Budget`, and replayable-random helpers. The shared filesystem is available from `@poe-platform/safe-js/fs`, with a browser-safe `fs/core` entry. Existing `poe-code/safe-js` imports remain available through the CLI package.
+
+## Supported features
+
+- **JavaScript control flow:** functions and closures, async/await, loops, destructuring, spread, templates, exceptions, and synchronous generators.
+- **Data processing:** arrays, objects, strings, numbers, JSON, Math, Map, Set, Float32Array, promises, and a bounded regular-expression subset. These are selected APIs, not complete ECMAScript implementations.
+- **Explicit capabilities:** named, default, and namespace imports resolve against host-supplied modules. Optional helpers cover agents, MCP tools, files, environment reads, time, logging, and metrics.
+- **Execution controls:** step, call-depth, string, array, and retained-data budgets; an absolute deadline; host cancellation; console and telemetry sinks.
+- **Checkpoints:** capture execution state, restore compatible source, and reconcile pending host operations. Changed programs can use explicit continuation migration.
+- **Authoring tools:** lint diagnostics and fixes, source-positioned errors, Markdown harnesses, and paired Markdown/script files. `run()` does not lint automatically; harness runners do.
+
+Scripts have no ambient `process`, `require`, `fetch`, or filesystem access. Host functions still execute with the host's privileges. Register only the capabilities the script needs; this is not OS or process isolation.
+
+## Add a host capability
+
+Expose a small module rather than an entire application client:
+
+```js
+import { Budget, lint, run } from "@poe-platform/safe-js";
+
+const source = `
+  import { lookup } from "catalog";
+  const item = await lookup("pencil");
+  return item.price;
+`;
+
+const diagnostics = lint(source, { modules: { catalog: ["lookup"] } });
+if (diagnostics.some(diagnostic => diagnostic.severity === "error")) {
+  throw new Error(JSON.stringify(diagnostics));
+}
+
+const result = await run(source, {
+  modules: {
+    catalog: {
+      lookup: async name => {
+        if (name !== "pencil") throw new Error("Unknown item");
+        return { price: 2 };
+      }
+    }
+  },
+  budget: new Budget({ maxSteps: 10_000, maxCallDepth: 100 })
+});
+
+if (!result.ok) throw result.error;
+console.log(result.returnValue);
+// 2
+```
+
+The lint registry describes exports; the runtime registry supplies their values. Both accept records or Maps. Module names are host-defined identifiers, not file paths or npm packages. Validate arguments and enforce permissions inside each host operation. Adding a function does not make its effects safe to replay.
+
+## Options
+
+### Execution
+
+`run(source, options?)` accepts:
+
+| Option | Purpose / default |
+| --- | --- |
+| `bindings` | Global input values and host functions; none by default. |
+| `modules` | Module names mapped to export records or Maps; none by default. |
+| `budget` | A `Budget` instance. Without one, only the default call-depth limit of 1,000 is configured. |
+| `signal` | Host `AbortSignal` for cancellation. |
+| `filename` | Diagnostic filename; defaults to `<input>`. |
+| `entryPointArgs` | Arguments for invoking the default-exported function. Omit for top-level execution only. |
+| `importMeta` | Host-supplied fields exposed through `import.meta`. |
+| `sink` | Console destination with `log(...args)` and `error(...args)`; defaults to the host console. |
+| `otelSink` | Telemetry with `startSpan` and `recordException`; spans implement `setAttribute`, `addEvent`, and `end`. Optional; `noopOtelSink` is available. |
+| `randomSeed`, `random` | Seed for built-in `Math.random`, or a custom `{ next, seed, snapshot }` generator. `random` takes precedence. |
+| `clock` | Clock-state provider with `snapshot()` returning `{ next }` or `undefined`; not a replacement for host time. |
+| `snapshot` | Previously captured state to resume. |
+| `snapshotPath`, `snapshotBackend` | Checkpoint output file or custom backend (`read`, `write`, `remove`); backend takes precedence. Neither automatically loads state into `snapshot`. |
+| `snapshotIntervalMs` | Periodic checkpoint interval when persistence is configured: 30,000 ms; `0` disables periodic writes. Capture happens at interpreter yield points. |
+| `hostCallResumeProvider` | Reconciles pending external operations on restore; returns a matching `HostCallResumeProof`. |
+
+`new Budget(options?)` accepts optional limits. A custom budget replaces the default, so include `maxCallDepth` if you want that guard.
+
+| Option | Limit |
+| --- | --- |
+| `maxSteps` | Interpreter work counter. |
+| `deadline` | Absolute epoch milliseconds or a `Date`, not a duration. |
+| `maxCallDepth` | Nested interpreter calls. |
+| `stringLength`, `arrayLength` | Individual string and array lengths. |
+| `dataSize` | Retained sandbox data units, not bytes of process memory. |
+
+There are no runtime environment variables to set. `makeEnvModule({ allow, values? })` grants reads of names in `allow`; `values` supplies an explicit string map instead of reading the host's `process.env`. Disallowed reads throw `EnvAccessError`; allowed but unset names return `undefined`. Agent and MCP integrations may require their own credentials.
+
+<details>
+<summary>Linting, parsing, and value conversion</summary>
+
+`lint(source, options?)` returns diagnostics with severity, code, message, filename, line, column, span, and optional fix/hint. With `fix: true`, it returns `{ diagnostics, fixed, fixes }` instead.
+
+| Option | Purpose |
+| --- | --- |
+| `filename`, `allowedGlobals` | Diagnostic filename and additional permitted global names. |
+| `modules` | Export-name lists, or `{ exports, filename?, source? }` descriptions. Typed `exports` map names to type strings or `{ type?, async? }`; source descriptions enable import-cycle checks. |
+| `allowedExportNames` | Permitted named exports. |
+| `defaultExport` | Expected entry point: `{ parameters?: string[], required?: boolean }`. |
+| `frontmatterFields` | Fields to check for unused harness configuration. |
+| `largeLiteralThreshold` | Threshold for large-literal diagnostics. |
+| `fix`, `fixRanges` | Apply available fixes, optionally restricted to source ranges. |
+
+`parse(source, filename?)` parses a single statement/expression; `parseModule(source, filename?)` parses a module. `formatInterpreterError(error, { source?, filename?, hostCallName?, maxMessageLength? })` formats an error; `(source, diagnostic)` is also supported.
+
+`deepCopyToSandbox(value)` and `deepCopyFromSandbox(value, { wrapClosure? })` convert supported values. `wrapClosure` lets the host choose how to represent an exported sandbox function. Not every native JavaScript object is convertible.
+
+</details>
+
+<details>
+<summary>Optional host modules</summary>
+
+Factories return exports to register in `modules`; calling a factory alone does not grant access.
+
+| Factory | Configuration and capabilities |
+| --- | --- |
+| `makeAgentModule(spawnAgent, options?)` | Inject the agent runner. Options: `defaultRetry`, `onEvent`, `otelSink`. Exposes `spawn`, `spawn.retry`, and `spawn.parallel`; call options follow this table. |
+| `makeMcpModule(options)` | Required `servers` map: stdio `{ command, args?, cwd?, env? }` or HTTP `{ url, headers? }`. Options: `requestTimeoutMs` (30,000), `closeTimeoutMs` (1,000), `maxToolPages` (100), `signal`, and injected `fetch`/`spawn`. Named clients expose `tools`, `tool`, `toolBatch`, and `close`; close managed clients when finished. A custom connector function is also accepted. |
+| `makeFsModule(options?)` | Node-backed `{ root?, fs? }`, or shared-filesystem `{ adapter, root?, cwd?, signal? }`; do not combine `fs` and `adapter`. Node access without `root` is unconfined. With an adapter, `root` confines access and `cwd` selects the virtual relative-path base; without `root`, explicit `cwd` also confines access. Omitting both uses virtual `/`. Read text with `readFile(path, "utf8")`; see the [module methods](src/modules/fs.ts) and [filesystem package](../safe-fs/README.md). |
+| `makeEnvModule(namesOrOptions)` | Allowed-name array or `{ allow, values? }`; exposes `get(name)`. `parseEnvConfig(json)` accepts the object form. |
+| `makeTimeModule(options?)` | `now`, `random`, `seed`, `signal`; exposes `now`, `random`, `sleep`, `uuid`. Defaults to host time/randomness; `seed` makes the random generator deterministic, and explicit `random` takes precedence. |
+| `makeLogModule(sink)` | Sends timestamped `info`, `error`, and `event` entries to your callback. |
+| `makeMetricModule(npmRunner)` | Runs `metric:<name>` through your callback; reads the final nonempty stdout line as a finite numeric score. |
+| `makeHarnessModule(frontmatter, meta)` | `meta` is `{ kind, version, filepath }`. Exposes `tasks`, `agents`, `meta`, and `applyConstraints`; prompt constraints come from frontmatter `principles` and `constraints`. |
+| `makeFailModule()` | Exposes a default function that throws a harness failure. No options. |
+
+**Agent calls.** A definition is a name or `{ agent, prompt?, model?, mode?, cwd?, mcp? }`. `spawn(definition, options)` requires `prompt` and accepts `check` (default `false`), `label`, `model`, `mode`, `cwd`, `mcp`, `otelSink`, `timeoutMs`, and `signal`. Modes are `read`, `edit`, `auto`, and `yolo`, subject to provider support. `mcp` maps server names to `{ command, args?, env?, timeout? }`.
+
+`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? }`; `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`. Signals and injected functions are SDK options, not JSON fields.
+
+</details>
+
+<details>
+<summary>Checkpoints and recovery</summary>
+
+- `dump(resultOrRunningPromise, { mode?, onFailure? })` returns checkpoint JSON. `mode` is `capture` or `replay`; `onFailure` is `throw` or `checkpoint`.
+- `restore(snapshot, { source })` validates state for compatible source; pass it as `run`'s `snapshot` option. It does not run the program.
+- `new FileSnapshotBackend(path, { writeMaxAttempts?, writeRetryDelayMs? })` defaults to 3 write attempts and a 100 ms retry delay.
+- `createReplayableRandom({ seed?, snapshot? })` supplies `next`, `seed`, `snapshot`, and `restore` for reproducible random sequences.
+- `declareHostOperation(fn, policy, { onReplay? })` declares `re-issue` or `read-side-effect` recovery policy. `registerPendingHostCallPolicy({ moduleId, operation, policy })` registers it by name. Only mark operations re-issuable when repeating them is acceptable; a declaration does not implement deduplication or external recovery.
+- `inspectSnapshotMigration(snapshot, { source })` inspects outstanding work. `migrateSnapshot(snapshot, { source, targetSource, state, reconciliation })` creates a continuation checkpoint. Reconciliation supplies `checkpointDigest`, `quiescent`, and `calls`; each call has `callId` and disposition `not-performed`, `fulfilled` with `value`, or `rejected` with `reason`.
+- `migrateSnapshotFile(options)` accepts `snapshotPath`, `sourcePath`, `targetSourcePath`, `planPath`, `outputPath`, `inspect`, `dryRun`, and `cwd`. Inspect mode needs the checkpoint and original source; migration also needs the target, plan, and new output path. See [continuation migration](MIGRATION.md) before changing a checkpointed program.
+
+</details>
+
+<details>
+<summary>Harness files and command line</summary>
+
+`runHarness(filepath, options)` reads `.safejs`, `.ajs`, or Markdown executable blocks. Required `modulesFor(frontmatter, { filepath, kind, version })` supplies capabilities. Optional fields: `budget`, `otelSink`, `signal`, `snapshotBackend`, `snapshotIntervalMs`, `snapshotPath`.
+
+`runHarnessPair(filepath, options)` uses the same options for a Markdown/`.ajs` pair. The script exports a default arrow function accepting `frontmatter`; Markdown body and metadata are available through `import.meta`. Loader helpers are `splitFrontmatter(markdown)`, `extractBlock(markdown, startLine?)`, and `findExportedConstInitializer(module, name)`.
+
+The bundled runner is `npx poe-safe-js <script.md|script.safejs|script.ajs>` (`poe-safejs` is an alias). It lints before execution and uses **stub agents and metrics**, not real agent runs. Try the [pipeline](examples/pipeline.md), [superintendent](examples/superintendent.md), or [experiment](examples/experiment.md) shapes; use your own host modules or `poe-code harness run` for real integrations.
+
+| Flag | Purpose |
+| --- | --- |
+| `--fix` | Write available lint fixes before running. |
+| `--fs`, `--fs-root <path>` | Enable real filesystem access, rooted at the script directory by default. `--fs-root` requires `--fs`. |
+| `--fs-config <path>` | Filesystem JSON config; cannot be repeated or combined with `--fs`/`--fs-root`. |
+| `--env-config <path>`, `--mcp-config <path>` | Explicit environment/MCP JSON grants. These integrations are real, not stubs. |
+| `--snapshot <path>`, `--restore <path>` | Save state or load a checkpoint; interrupt capture is best-effort. |
+| `--max-steps <n>`, `--data-size <n>` | Interpreter budget limits. |
+| `-h`, `--help` | Usage and exit codes. |
+
+`migrate` takes a checkpoint path plus `--from`, and either `--inspect` or `--to`, `--plan`, `--output`, with optional `--dry-run`.
+
+For embedding, `runCli(argv, options?)` comes from `@poe-platform/safe-js/cli`. Options: `cwd`, `env`, `mcp`, `modulesFor`, `process`, `readFile`, `stat`, `stdout`, `stderr`, `writeFile`. Its `modulesFor` callback also receives `{ stdout, stderr }`. Do not combine SDK `env`/`mcp` options with their config-file flags.
+
+</details>
+
+## Meaningful limitations
+
+- **Not a full JavaScript engine.** No user-defined classes/prototype chains, async generators, dynamic imports, or automatic multi-file/npm resolution. No browser build, DOM, general Node API, `eval`, or `Function` constructor. Built-in coverage is selective; lint success is not a runtime compatibility guarantee.
+- **Some familiar syntax differs.** Binary `in` is unsupported; use `Object.hasOwn(object, key)` for own-property checks. Regex supports `g`, `i`, `m`, and `s`, but not lookaround, backreferences, named groups, Unicode property escapes, or other flags. Compilation and matching have fixed limits in addition to configured budgets.
+- **Budgets are not hard resource isolation.** Limits govern interpreter work, not arbitrary host functions or total process memory. Deadlines are checked cooperatively; cancellation cannot forcibly stop a blocking host call or undo its effects. Add host-operation timeouts and external isolation where required.
+- **Recovery is not exactly-once delivery.** Replay can repeat work and consumes budget again. Pending side effects need external reconciliation; opaque host handles and native iterator frames are not portable checkpoint state. Keep compatible source for ordinary restore or explicitly migrate. Checkpoints can contain input data and host results: store them as sensitive data.
+- **Filesystem access is a grant, not an OS sandbox.** The helper is a subset of `node:fs/promises`, with text-oriented results and no file handles, streams, or Buffer API. Root checks do not isolate the process from concurrent filesystem changes. Prefer narrow host operations when a script only needs a few files.

package/dist/agent-defs/agents/claude-code.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from "../types.js";
+export declare const claudeCodeAgent: AgentDefinition;

package/dist/agent-defs/agents/claude-desktop.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from "../types.js";
+export declare const claudeDesktopAgent: AgentDefinition;

package/dist/agent-defs/agents/codex.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from "../types.js";
+export declare const codexAgent: AgentDefinition;

package/dist/agent-defs/agents/cursor.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from "../types.js";
+export declare const cursorAgent: AgentDefinition;

package/dist/agent-defs/agents/gemini-cli.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from "../types.js";
+export declare const geminiCliAgent: AgentDefinition;

package/dist/agent-defs/agents/goose.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from "../types.js";
+export declare const gooseAgent: AgentDefinition;

package/dist/agent-defs/agents/index.d.ts

@@ -0,0 +1,10 @@
+export { claudeCodeAgent } from "./claude-code.js";
+export { claudeDesktopAgent } from "./claude-desktop.js";
+export { codexAgent } from "./codex.js";
+export { cursorAgent } from "./cursor.js";
+export { geminiCliAgent } from "./gemini-cli.js";
+export { openCodeAgent } from "./opencode.js";
+export { kimiAgent } from "./kimi.js";
+export { gooseAgent } from "./goose.js";
+export { piAgent } from "./pi.js";
+export { poeAgentAgent } from "./poe-agent.js";

package/dist/agent-defs/agents/kimi.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from "../types.js";
+export declare const kimiAgent: AgentDefinition;

package/dist/agent-defs/agents/opencode.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from "../types.js";
+export declare const openCodeAgent: AgentDefinition;

package/dist/agent-defs/agents/pi.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from "../types.js";
+export declare const piAgent: AgentDefinition;

package/dist/agent-defs/agents/poe-agent.d.ts

@@ -0,0 +1,2 @@
+import type { AgentDefinition } from "../types.js";
+export declare const poeAgentAgent: AgentDefinition;

package/dist/agent-defs/capabilities.d.ts

@@ -0,0 +1,14 @@
+import type { AgentCapability } from "./types.js";
+export declare function listAgentsWithCapability(capability: AgentCapability, options?: {
+    includeAliases?: boolean;
+}): readonly string[];
+export declare function agentSupportsCapability(input: string, capability: AgentCapability): boolean;
+/**
+ * The single message for every agent argument that misses. It distinguishes a
+ * typo (unknown id, plus a did-you-mean) from a real capability gap ("pi
+ * supports: spawn"), and always names the agents the command does accept.
+ */
+export declare function formatAgentCapabilityError(input: {
+    agent: string;
+    capability: AgentCapability;
+}): string;

package/dist/agent-defs/index.d.ts

@@ -0,0 +1,6 @@
+export type { AgentCapability, AgentDefinition, ApiShapeId, OtelCaptureDefinition } from "./types.js";
+export type { AgentSpecifier } from "./specifier.js";
+export { claudeCodeAgent, claudeDesktopAgent, codexAgent, cursorAgent, geminiCliAgent, openCodeAgent, kimiAgent, gooseAgent, piAgent, poeAgentAgent } from "./agents/index.js";
+export { allAgents, resolveAgentId } from "./registry.js";
+export { agentSupportsCapability, formatAgentCapabilityError, listAgentsWithCapability } from "./capabilities.js";
+export { parseAgentSpecifier, formatAgentSpecifier, normalizeAgentId } from "./specifier.js";

package/dist/agent-defs/registry.d.ts

@@ -0,0 +1,3 @@
+import type { AgentDefinition } from "./types.js";
+export declare const allAgents: readonly AgentDefinition[];
+export declare function resolveAgentId(input: string): string | undefined;

package/dist/agent-defs/specifier.d.ts

@@ -0,0 +1,7 @@
+export interface AgentSpecifier {
+    agent: string;
+    model?: string;
+}
+export declare function parseAgentSpecifier(input: string): AgentSpecifier;
+export declare function formatAgentSpecifier(specifier: AgentSpecifier): string;
+export declare function normalizeAgentId(input: string): string;

package/dist/agent-defs/types.d.ts

@@ -0,0 +1,35 @@
+export type ApiShapeId = "openai-chat-completions" | "openai-responses" | "anthropic-messages" | "google-generations";
+/**
+ * The poe-code surfaces an agent can be used with. This is the single
+ * published source for each command's allow-list; `agent-capability-matrix.test.ts`
+ * pins every value to the registry that implements it, so the sets cannot drift.
+ */
+export type AgentCapability = "spawn" | "configure" | "install" | "test" | "skill" | "mcp";
+export interface OtelCaptureDefinition {
+    env?: Record<string, string>;
+    args?: (endpoint: string, content: boolean) => string[];
+}
+export interface AgentDefinition {
+    id: string;
+    name: string;
+    label: string;
+    summary: string;
+    aliases?: string[];
+    /** Binary name for CLI agents. Optional for GUI-only apps like Claude Desktop. */
+    binaryName?: string;
+    readonly capabilities?: readonly AgentCapability[];
+    readonly apiShapes?: readonly ApiShapeId[];
+    readonly otelCapture?: OtelCaptureDefinition;
+    configPath?: string;
+    readonly configPaths?: {
+        readonly darwin: string;
+        readonly linux: string;
+        readonly win32: string;
+    };
+    branding: {
+        colors: {
+            dark: string;
+            light: string;
+        };
+    };
+}

package/dist/agent-harness-tools/binary-exists.d.ts

@@ -0,0 +1,10 @@
+export interface BinaryExistsDetectorResult {
+    exitCode: number;
+    stdout: string;
+}
+export interface BinaryExistsDetector {
+    command: string;
+    args: string[];
+    validate(result: BinaryExistsDetectorResult): boolean;
+}
+export declare function createBinaryExistsDetectors(binaryName: string): BinaryExistsDetector[];

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

@@ -0,0 +1,108 @@
+import type { RunnerScope, RuntimeConfig } from "../poe-code-config/index.js";
+import type { RunHandle, Runner, RunSpec } from "../process-runner/index.js";
+import type { StateManager } from "../poe-code-config/index.js";
+export type { RuntimeConfig } from "../poe-code-config/index.js";
+export type { RunHandle, RunSpec } from "../process-runner/index.js";
+export type ExecutionEnvType = "host" | "docker";
+export type JobStatus = "running" | "exited" | "killed" | "lost";
+export interface ExecutionEnvFactory {
+    readonly type: ExecutionEnvType;
+    readonly supportsDetach?: boolean;
+    /** Whether uploadWorkspace/downloadWorkspace move real files, i.e. whether runner.sync means anything. */
+    readonly supportsWorkspaceTransfer?: boolean;
+    open(spec: OpenSpec): Promise<OpenedEnv>;
+    attach(envId: string, context?: AttachedJobContext): Promise<OpenedEnv>;
+}
+export interface OpenSpec {
+    cwd: string;
+    runtimeCwd?: string;
+    runtime: RuntimeConfig;
+    runner?: RunnerScope;
+    state?: StateManager;
+    hostRunner?: Runner;
+    env: Record<string, string>;
+    uploadIgnoreFiles: string[];
+    jobLabel: {
+        tool: string;
+        argv: string[];
+        displayArgv?: string[];
+    };
+    execution?: {
+        wrapForLogTee?: boolean;
+        stdin?: RunSpec["stdin"];
+        stdout?: RunSpec["stdout"];
+        stderr?: RunSpec["stderr"];
+        env?: RunSpec["env"];
+        tty?: boolean;
+        input?: string | Buffer;
+        captureOutput?: boolean;
+        activityTimeoutMs?: number;
+        activityTimeoutSource?: "all" | "stdout";
+        onStdout?(chunk: string): void;
+        onStderr?(chunk: string): void;
+    };
+    shellSpec?: RunSpec;
+}
+export interface UploadResult {
+    files: number;
+    bytes: number;
+    skipped: {
+        path: string;
+        bytes: number;
+        reason: "max_size";
+    }[];
+}
+export interface DownloadResult {
+    files: number;
+    bytes: number;
+    conflicts: {
+        path: string;
+        reason: "local_modified";
+    }[];
+}
+export interface LogChunk {
+    byteOffset: number;
+    data: string;
+}
+export interface AttachedJobContext {
+    jobId: string;
+    tool: string;
+    argv: string[];
+    cwd: string;
+    reattachContext?: Record<string, unknown>;
+}
+export interface OpenedEnv {
+    readonly id: string;
+    readonly job: JobHandle | null;
+    readonly reattachContext?: Record<string, unknown>;
+    uploadWorkspace(): Promise<UploadResult>;
+    downloadWorkspace(opts: {
+        conflictPolicy: "refuse" | "overwrite";
+    }): Promise<DownloadResult>;
+    exec(spec: RunSpec): RunHandle;
+    detach(): Promise<JobHandle>;
+    shell(): RunHandle;
+    close(): Promise<void>;
+}
+export interface JobHandle {
+    readonly id: string;
+    readonly envId: string;
+    readonly tool: string;
+    readonly argv: string[];
+    status(opts?: {
+        signal?: AbortSignal;
+    }): Promise<JobStatus>;
+    stream(opts?: {
+        sinceByte?: number;
+        since?: Date;
+        follow?: boolean;
+        signal?: AbortSignal;
+    }): AsyncIterable<LogChunk>;
+    wait(): Promise<{
+        exitCode: number;
+    }>;
+    kill(signal?: NodeJS.Signals): Promise<void>;
+}
+export declare function registerExecutionEnvFactory(factory: ExecutionEnvFactory): void;
+export declare function selectExecutionEnv(runtime: RuntimeConfig): ExecutionEnvFactory;
+export declare function selectExecutionEnvFactory(type: ExecutionEnvType): ExecutionEnvFactory;

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

@@ -0,0 +1,30 @@
+import { type WorkflowParticipant } from "./participant.js";
+export type WorkflowMode = "read" | "edit" | "auto" | "yolo";
+export interface RunAgentHooks {
+    from: string;
+    strategy?: "auto" | "symlink" | "transform";
+    scope?: "project" | "user" | "merged";
+}
+export interface WorkflowHook {
+    participant?: string;
+    mode?: WorkflowMode;
+    prompt: string;
+}
+export interface RunAgentInput {
+    agent: string;
+    prompt: string;
+    mode?: WorkflowMode;
+    cwd: string;
+    model?: string;
+    skills?: string[];
+    hooks?: RunAgentHooks;
+    signal?: AbortSignal;
+}
+export type RunAgentFn = (input: RunAgentInput) => Promise<unknown>;
+export interface HookContext {
+    cwd: string;
+    participants: Record<string, WorkflowParticipant>;
+    runAgent: RunAgentFn;
+    signal?: AbortSignal;
+}
+export declare function runWorkflowHook(hook: WorkflowHook, context: HookContext): Promise<void>;

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

@@ -0,0 +1,18 @@
+export { discoverWorkflowDocs, resolveWorkflowPath, type DiscoverDocsOptions } from "./paths.js";
+export { archivePlan, discoverPlans, openPlanList, parsePlanReadiness } from "./plans.js";
+export { comparePlanReadiness, formatPlanReadinessLabel } from "./plan-readiness.js";
+export type { ArchivePlanOptions, DiscoverPlansOptions, OpenPlanListOptions, PlanReadiness, PlanRef } from "./plans.js";
+export { normalizeParticipantConfig, selectParticipantAgent, type WorkflowParticipant } from "./participant.js";
+export { resolveLoopAgent, type ResolveLoopAgentInput } from "./select-agent.js";
+export { runWorkflowHook, type HookContext, type RunAgentFn, type RunAgentHooks, type RunAgentInput, type WorkflowHook, type WorkflowMode } from "./hooks.js";
+export { runWorkflowStage, type StageContext, type WorkflowStage } from "./stage.js";
+export { runDocumentWorkflow, type DocumentWorkflowOptions, type IterationResult, type WorkflowFileStat, type WorkflowFileSystem } from "./runner.js";
+export { runDocumentWorkflowSequence, type DocumentWorkflowSequenceOptions } from "./sequence.js";
+export { ensureSafeRunLogDir, makeRunLogFileName, resolveRunLogDir, slugifyPlanPath, type RunLogFileSystem, type ResolveRunLogDirOptions } from "./run-logs.js";
+export { streamLogFile, waitForExit, wrapForLogTee, type LogStreamEnv, type LogStreamFs } from "./log-stream.js";
+export { createPoeCommandSession, runPoeCommand, type PoeCommandSession } from "./run-poe-command.js";
+export { createBinaryExistsDetectors, type BinaryExistsDetector, type BinaryExistsDetectorResult } from "./binary-exists.js";
+export { applyRuntimeOverrides, resolvePoeCommandExecution, UnsupportedRuntimeCapabilityError, type RuntimeOverrideOptions } from "./poe-command-execution.js";
+export { skillPlanConfigSection } from "./skill-config.js";
+export * from "./execution-env.js";
+export * from "./workspace-transfer.js";

package/dist/agent-harness-tools/log-stream.d.ts

@@ -0,0 +1,28 @@
+import type { FSWatcher } from "node:fs";
+import type { LogChunk } from "./execution-env.js";
+export interface LogStreamEnv {
+    fs?: LogStreamFs;
+}
+export interface LogStreamFs {
+    promises: {
+        readFile(path: string): Promise<Buffer | string>;
+        stat?(path: string): Promise<{
+            mtimeMs: number;
+        }>;
+        lstat?(path: string): Promise<{
+            isSymbolicLink(): boolean;
+        }>;
+    };
+    watch?: (path: string, listener: () => void) => FSWatcher;
+}
+export declare function wrapForLogTee(argv: string[], jobId: string): string[];
+export declare function streamLogFile(env: LogStreamEnv, jobId: string, opts: {
+    sinceByte?: number;
+    since?: Date;
+    follow?: boolean;
+}): AsyncIterable<LogChunk>;
+export declare function waitForExit(env: LogStreamEnv, jobId: string, opts?: {
+    signal?: AbortSignal;
+}): Promise<{
+    exitCode: number;
+}>;

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

@@ -0,0 +1,10 @@
+import type { WorkflowMode } from "./hooks.js";
+export interface WorkflowParticipant {
+    id: string;
+    agent: string | string[];
+    mode?: WorkflowMode;
+    model?: string;
+    prompt?: string;
+}
+export declare function normalizeParticipantConfig(id: string, value: unknown): WorkflowParticipant;
+export declare function selectParticipantAgent(participant: WorkflowParticipant, iteration: number): string;

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

@@ -0,0 +1,14 @@
+export declare function resolveWorkflowPath(inputPath: string, cwd: string, homeDir: string): string;
+export interface DiscoverDocsOptions {
+    cwd: string;
+    homeDir: string;
+    subDirectory: string;
+    glob?: string;
+    fs: {
+        lstat: (path: string) => Promise<{
+            isSymbolicLink(): boolean;
+        }>;
+        readdir: (path: string) => Promise<string[]>;
+    };
+}
+export declare function discoverWorkflowDocs(options: DiscoverDocsOptions): Promise<string[]>;

package/dist/agent-harness-tools/plan-readiness.d.ts

@@ -0,0 +1,7 @@
+import type { PlanReadiness } from "./plans.js";
+export declare function formatPlanReadinessLabel(label: string, readiness: PlanReadiness): string;
+export declare function comparePlanReadiness(left: {
+    readiness: PlanReadiness;
+}, right: {
+    readiness: PlanReadiness;
+}): number;

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

@@ -0,0 +1,35 @@
+import { type TaskList, type TaskListFs } from "../task-list/index.js";
+export interface PlanRef {
+    id: string;
+    absolutePath: string;
+    displayPath: string;
+    kind: string;
+    name: string;
+    readiness: PlanReadiness;
+}
+export type PlanReadiness = "draft" | "ready";
+export interface DiscoverPlansOptions {
+    cwd: string;
+    homeDir: string;
+    planDirectory: string;
+    kinds?: readonly string[];
+    fs?: TaskListFs;
+}
+export interface ArchivePlanOptions {
+    cwd: string;
+    homeDir: string;
+    planDirectory: string;
+    id: string;
+    fs?: TaskListFs;
+    metadataPatch?: Record<string, unknown>;
+}
+export interface OpenPlanListOptions {
+    cwd: string;
+    homeDir: string;
+    planDirectory: string;
+    fs?: TaskListFs;
+}
+export declare function parsePlanReadiness(value: unknown): PlanReadiness;
+export declare function discoverPlans(options: DiscoverPlansOptions): Promise<PlanRef[]>;
+export declare const archivePlan: (options: ArchivePlanOptions) => Promise<void>;
+export declare function openPlanList(options: OpenPlanListOptions): Promise<TaskList>;