@poe-platform/safe-js 0.1.0

package/dist/safe-js/interp/values.d.ts

@@ -0,0 +1,136 @@
+import type { Budget, CompileTicket } from "./budget.js";
+import { CompileScope } from "./regex/compile-guard.js";
+import type { GeneratorChannel } from "./generator.js";
+import { type RegexPattern } from "./regex/parse.js";
+export { createSandboxArguments, isSandboxArguments } from "./arguments.js";
+declare const sandboxClosureBrand: unique symbol;
+declare const sandboxGeneratorBrand: unique symbol;
+declare const sandboxMapBrand: unique symbol;
+declare const sandboxPromiseBrand: unique symbol;
+declare const sandboxRegexBrand: unique symbol;
+declare const sandboxRegexPattern: unique symbol;
+declare const sandboxSetBrand: unique symbol;
+declare const sandboxRetainedValues: unique symbol;
+export type SandboxPrimitive = string | number | boolean | null | undefined;
+export type SandboxValue = SandboxPrimitive | Float32Array | SandboxObject | SandboxArray | SandboxClosure | SandboxGenerator | SandboxMap | SandboxSet | SandboxPromise | SandboxRegex;
+export type SandboxObject = {
+    [key: string]: SandboxValue;
+};
+export type SandboxArray = SandboxValue[];
+export type SandboxMap = {
+    readonly kind: "map";
+    readonly entries: Map<SandboxValue, SandboxValue>;
+    readonly [sandboxMapBrand]: true;
+};
+export type SandboxSet = {
+    readonly kind: "set";
+    readonly values: Set<SandboxValue>;
+    readonly [sandboxSetBrand]: true;
+};
+export type SandboxRegex = {
+    readonly kind: "regex";
+    readonly source: string;
+    readonly flags: string;
+    lastIndex: number;
+    readonly [sandboxRegexBrand]: true;
+    readonly [sandboxRegexPattern]: RegexPattern;
+};
+export type SandboxCallContext = {
+    readonly compilation?: CompileScope;
+    readonly span?: {
+        readonly end: {
+            readonly column: number;
+            readonly line: number;
+            readonly offset: number;
+        };
+        readonly start: {
+            readonly column: number;
+            readonly line: number;
+            readonly offset: number;
+        };
+    };
+    readonly stack: readonly string[];
+    readonly thisValue: SandboxValue;
+    readonly invokeClosure?: (closure: SandboxClosure, args: readonly SandboxValue[], thisValue: SandboxValue) => Promise<SandboxValue>;
+};
+export type SandboxClosure = {
+    readonly async?: true;
+    readonly sandbox?: true;
+    readonly boundTarget?: SandboxClosure;
+    readonly cancellationSignal?: AbortSignal;
+    readonly kind: "fn";
+    readonly length?: number;
+    readonly name?: string;
+    readonly properties?: SandboxObject;
+    readonly call: (args: readonly SandboxValue[], context?: SandboxCallContext) => SandboxValue | Promise<SandboxValue>;
+    readonly construct?: (args: readonly SandboxValue[], context?: SandboxCallContext) => SandboxValue | Promise<SandboxValue>;
+    readonly [sandboxClosureBrand]: true;
+    readonly [sandboxRetainedValues]?: () => Iterable<SandboxValue>;
+};
+export type SandboxPromise = {
+    readonly kind: "promise";
+    readonly synchronousPrefix?: Promise<void>;
+    readonly promise: Promise<SandboxValue>;
+    readonly hostCall?: import("./host-call.js").HostCallRecord;
+    readonly hostCallJournal?: import("./host-call.js").HostCallJournal;
+    readonly span?: SandboxCallContext["span"];
+    readonly [sandboxPromiseBrand]: true;
+};
+export type SandboxGenerator = {
+    readonly kind: "generator";
+    state: "start" | "running" | "suspended" | "done";
+    readonly channel: GeneratorChannel;
+    readonly astNodeId?: number;
+    readonly capturedScopeId?: number | string;
+    readonly [sandboxGeneratorBrand]: true;
+};
+type CopyFromSandboxOptions = {
+    wrapClosure?: (value: SandboxClosure) => unknown;
+    compilation?: CompileScope;
+};
+export declare function createSandboxClosure(input: {
+    async?: boolean;
+    sandbox?: boolean;
+    boundTarget?: SandboxClosure;
+    cancellationSignal?: AbortSignal;
+    call: (args: readonly SandboxValue[], context?: SandboxCallContext) => SandboxValue | Promise<SandboxValue>;
+    construct?: (args: readonly SandboxValue[], context?: SandboxCallContext) => SandboxValue | Promise<SandboxValue>;
+    name?: string;
+    length?: number;
+    properties?: SandboxObject | ((closure: SandboxClosure) => SandboxObject);
+    retainedValues?: () => Iterable<SandboxValue>;
+}): SandboxClosure;
+export declare function createSandboxPromise(promise: Promise<SandboxValue>, metadata?: {
+    trackReplay?: boolean;
+    synchronousPrefix?: Promise<void>;
+    hostCall?: import("./host-call.js").HostCallRecord;
+    hostCallJournal?: import("./host-call.js").HostCallJournal;
+    span?: SandboxCallContext["span"];
+}): SandboxPromise;
+export declare function createSandboxGenerator(channel: GeneratorChannel, metadata?: {
+    astNodeId: number;
+    capturedScopeId: number | string;
+} | undefined): SandboxGenerator;
+export declare function createSandboxMap(entries?: Iterable<readonly [SandboxValue, SandboxValue]>): SandboxMap;
+export declare function createSandboxSet(values?: Iterable<SandboxValue>): SandboxSet;
+export declare function createSandboxRegex(source: string, flags?: string, lastIndex?: number, compilation?: CompileScope): SandboxRegex;
+export declare function getSandboxRegexPattern(regex: SandboxRegex): RegexPattern;
+export declare function isSandboxClosure(value: unknown): value is SandboxClosure;
+export declare function isSandboxMap(value: unknown): value is SandboxMap;
+export declare function isSandboxPromise(value: unknown): value is SandboxPromise;
+export declare function isSandboxSet(value: unknown): value is SandboxSet;
+export declare function isSandboxGenerator(value: unknown): value is SandboxGenerator;
+export declare function isSandboxRegex(value: unknown): value is SandboxRegex;
+export declare function deepCopyToSandbox(value: unknown): SandboxValue;
+export declare function cloneSandboxValue(value: SandboxValue): SandboxValue;
+export declare function allocateProducedSandboxValue(value: SandboxValue, budget: Budget): SandboxValue;
+export declare function measureSandboxData(values: Iterable<unknown>, options?: {
+    ignoreClosures?: boolean;
+    ignoreClosureCaptures?: boolean;
+    compileTickets?: Set<CompileTicket>;
+}): number;
+export declare function reconcileCompiledValues(budget: Budget, values: Iterable<unknown>, compilation?: CompileScope, parent?: CompileScope, escaping?: Iterable<unknown>): void;
+export declare function deepCopyFromSandbox(value: SandboxPromise, options?: CopyFromSandboxOptions): Promise<unknown>;
+export declare function deepCopyFromSandbox(value: SandboxValue, options?: CopyFromSandboxOptions): unknown;
+export declare function defineOwnDataProperty(target: object, key: string, value: unknown): void;
+export declare function isArrayIndexKey(value: string): boolean;

package/dist/safe-js/lint/index.d.ts

@@ -0,0 +1,38 @@
+import type { DefaultExportSignature } from "./rules/AS-export-import-meta.js";
+import { type SourceSpan } from "../parse/parser.js";
+import type { Modules } from "./rules/module-registry.js";
+export type Diagnostic = {
+    code: string;
+    severity: "error" | "info" | "warning";
+    message: string;
+    filename: string;
+    line: number;
+    column: number;
+    span: SourceSpan;
+    fix?: Fix;
+    hint?: string;
+};
+export type Fix = {
+    range: readonly [number, number];
+    replacement: string;
+};
+export type LintOptions = {
+    allowedExportNames?: readonly string[];
+    allowedGlobals?: readonly string[];
+    defaultExport?: DefaultExportSignature;
+    fix?: boolean;
+    fixRanges?: readonly Fix["range"][];
+    filename?: string;
+    largeLiteralThreshold?: number;
+    frontmatterFields?: readonly string[];
+    modules?: Modules;
+};
+export type LintFixResult = {
+    diagnostics: Diagnostic[];
+    fixed: string;
+    fixes: Fix[];
+};
+export declare function lint(source: string, options: LintOptions & {
+    fix: true;
+}): LintFixResult;
+export declare function lint(source: string, options?: LintOptions): Diagnostic[];

package/dist/safe-js/lint/rules/AS-export-import-meta.d.ts

@@ -0,0 +1,21 @@
+import { type SourceSpan } from "../../parse/parser.js";
+type DiagnosticCode = "AS-EXPORT-DEFAULT-MISSING" | "AS-EXPORT-DEFAULT-MULTIPLE" | "AS-EXPORT-DEFAULT-NOT-ARROW" | "AS-EXPORT-DEFAULT-SIGNATURE" | "AS-EXPORT-UNKNOWN" | "AS-IMPORT-META-ASSIGN" | "AS-RETURN-AT-TOP";
+export type Diagnostic = {
+    code: DiagnosticCode;
+    severity: "error" | "warning";
+    message: string;
+    filename: string;
+    line: number;
+    column: number;
+    span: SourceSpan;
+};
+export type DefaultExportSignature = {
+    parameters?: readonly string[];
+    required?: boolean;
+};
+export declare function AS_EXPORT_IMPORT_META(source: string, options?: {
+    allowedExportNames?: readonly string[];
+    defaultExport?: DefaultExportSignature;
+    filename?: string;
+}): Diagnostic[];
+export {};

package/dist/safe-js/lint/rules/module-registry.d.ts

@@ -0,0 +1,33 @@
+import { type ImportDeclaration } from "../../parse/parser.js";
+export type ModuleRegistration = readonly string[] | {
+    exports?: readonly string[] | LintModuleExports;
+    filename?: string;
+    source?: string;
+};
+export type Modules = ReadonlyMap<string, ModuleRegistration> | Record<string, ModuleRegistration>;
+export type LintModuleExport = string | {
+    async?: boolean;
+    type?: string;
+};
+export type LintModuleExports = ReadonlyMap<string, LintModuleExport> | Record<string, LintModuleExport>;
+export type ModuleExportTypes = LintModuleExports;
+export type NormalizedModuleRegistration = {
+    asyncExports: ReadonlySet<string>;
+    exports: string[];
+    exportTypes: ReadonlyMap<string, string>;
+    filename?: string;
+    source?: string;
+};
+export type SafeJSSourceModule = {
+    moduleName: string;
+    exports: readonly string[];
+    filename: string;
+    source: string;
+};
+export declare function collectImportDeclarations(source: string, filename: string): ImportDeclaration[];
+export declare function createUnknownModuleMessage(moduleName: string, moduleNames: readonly string[]): string;
+export declare function createUnknownExportMessage(moduleName: string, exportName: string, availableExports: readonly string[]): string;
+export declare function normalizeModules(modules: Modules | undefined): Map<string, string[]>;
+export declare function normalizeModuleRegistrations(modules: Modules | undefined): Map<string, NormalizedModuleRegistration>;
+export declare function collectSafeJSSourceModules(modules: Modules | undefined): Map<string, SafeJSSourceModule>;
+export declare function hasTypedModuleRegistrations(modules: Modules | undefined): boolean;

package/dist/safe-js/lint.d.ts

@@ -0,0 +1 @@
+export { lint, type Diagnostic, type Fix, type LintFixResult, type LintOptions } from "./lint/index.js";

package/dist/safe-js/loader/extract-block.d.ts

@@ -0,0 +1,10 @@
+export interface ExtractBlockResult {
+    endOffset: number;
+    source: string;
+    lineOffset: number;
+    startOffset: number;
+    ranges: readonly (readonly [number, number])[];
+}
+export declare function extractBlock(markdown: string, startLine?: number): ExtractBlockResult;
+export declare function maskSource(source: string): string;
+export declare function countLineBreaks(markdown: string, start?: number, end?: number): number;

package/dist/safe-js/loader/find-exported.d.ts

@@ -0,0 +1,2 @@
+import type { Expression, Module } from "../parse/parser.js";
+export declare function findExportedConstInitializer(module: Module, name: string): Expression | undefined;

package/dist/safe-js/loader/frontmatter.d.ts

@@ -0,0 +1,5 @@
+export interface SplitFrontmatterResult {
+    frontmatter: Record<string, unknown>;
+    body: string;
+}
+export declare function splitFrontmatter(markdown: string): SplitFrontmatterResult;

package/dist/safe-js/migrate.d.ts

@@ -0,0 +1,33 @@
+import type { SafeJSSnapshot } from "./restore.js";
+import { type SnapshotMigration, type SnapshotMigrationReconciliation } from "./snapshot/migration.js";
+export type { SnapshotMigration, SnapshotMigrationReconciliation, SnapshotMigrationResolution } from "./snapshot/migration.js";
+export type SnapshotMigrationOptions = {
+    source: string;
+    targetSource: string;
+    state: unknown;
+    reconciliation: SnapshotMigrationReconciliation;
+};
+export declare function inspectSnapshotMigration(snapshot: SafeJSSnapshot, options: {
+    source: string;
+}): {
+    checkpointDigest: string;
+    sourceHash: string;
+    executionSemantics: string;
+    calls: (Omit<import("./index.js").HostCallRecord, "outcome" | "asynchronous"> & {
+        asynchronous: boolean;
+        outcome?: {
+            status: "fulfilled" | "rejected";
+            data: import("./snapshot/replay-data.js").ReplayData;
+        };
+    })[];
+    unresolvedCalls: (Omit<import("./index.js").HostCallRecord, "outcome" | "asynchronous"> & {
+        asynchronous: boolean;
+        outcome?: {
+            status: "fulfilled" | "rejected";
+            data: import("./snapshot/replay-data.js").ReplayData;
+        };
+    })[];
+};
+export declare function migrateSnapshot(snapshot: SafeJSSnapshot, options: SnapshotMigrationOptions): SafeJSSnapshot & {
+    migration: SnapshotMigration;
+};

package/dist/safe-js/migration-file.d.ts

@@ -0,0 +1,55 @@
+export type SnapshotMigrationFileOptions = {
+    snapshotPath: string;
+    sourcePath: string;
+    targetSourcePath?: string;
+    planPath?: string;
+    outputPath?: string;
+    inspect?: boolean;
+    dryRun?: boolean;
+    cwd?: string;
+};
+export declare function migrateSnapshotFile(options: SnapshotMigrationFileOptions): Promise<{
+    inspection: {
+        checkpointDigest: string;
+        sourceHash: string;
+        executionSemantics: string;
+        calls: (Omit<import("./index.js").HostCallRecord, "outcome" | "asynchronous"> & {
+            asynchronous: boolean;
+            outcome?: {
+                status: "fulfilled" | "rejected";
+                data: import("./snapshot/replay-data.js").ReplayData;
+            };
+        })[];
+        unresolvedCalls: (Omit<import("./index.js").HostCallRecord, "outcome" | "asynchronous"> & {
+            asynchronous: boolean;
+            outcome?: {
+                status: "fulfilled" | "rejected";
+                data: import("./snapshot/replay-data.js").ReplayData;
+            };
+        })[];
+    };
+    outputPath?: undefined;
+    dryRun?: undefined;
+} | {
+    inspection: {
+        checkpointDigest: string;
+        sourceHash: string;
+        executionSemantics: string;
+        calls: (Omit<import("./index.js").HostCallRecord, "outcome" | "asynchronous"> & {
+            asynchronous: boolean;
+            outcome?: {
+                status: "fulfilled" | "rejected";
+                data: import("./snapshot/replay-data.js").ReplayData;
+            };
+        })[];
+        unresolvedCalls: (Omit<import("./index.js").HostCallRecord, "outcome" | "asynchronous"> & {
+            asynchronous: boolean;
+            outcome?: {
+                status: "fulfilled" | "rejected";
+                data: import("./snapshot/replay-data.js").ReplayData;
+            };
+        })[];
+    };
+    outputPath: string | undefined;
+    dryRun: boolean;
+}>;

package/dist/safe-js/modules/agent.d.ts

@@ -0,0 +1,132 @@
+import { type SpawnParallelOptions } from "../../agent-spawn/parallel.js";
+import { type SpawnUsage } from "../../agent-spawn/types.js";
+import { type OtelSink } from "../observability/otel.js";
+export type AgentSpawnMode = "read" | "edit" | "auto" | "yolo";
+export type AgentModuleMcpServer = {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    timeout?: number;
+};
+export type AgentModuleMcpConfig = Record<string, AgentModuleMcpServer>;
+export type AgentModuleDefinition = string | {
+    agent: string;
+    prompt?: string;
+    model?: string;
+    mode?: AgentSpawnMode;
+    cwd?: string;
+    mcp?: AgentModuleMcpConfig;
+};
+export type AgentModuleSpawnOptions = {
+    prompt: string;
+    check?: boolean;
+    label?: string;
+    mcp?: AgentModuleMcpConfig;
+    model?: string;
+    mode?: AgentSpawnMode;
+    cwd?: string;
+    otelSink?: OtelSink;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+};
+export type SpawnAgentInput = Omit<AgentModuleSpawnOptions, "label" | "check"> & {
+    agent: string;
+};
+export type SpawnAgentResult = {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    summary: string;
+    durationMs: number;
+    usage?: SpawnUsage;
+};
+export type SpawnAgent = (input: SpawnAgentInput) => Promise<SpawnAgentResult>;
+export declare class AgentSpawnError extends Error {
+    readonly result: SpawnAgentResult;
+    constructor(result: SpawnAgentResult);
+}
+export type AgentModuleOptions = {
+    defaultRetry?: AgentModuleRetryOptions;
+    onEvent?: (event: AgentSpawnEvent) => void | Promise<void>;
+    otelSink?: OtelSink;
+};
+export type AgentSpawnEvent = {
+    type: "spawn.started";
+    spawnId: number;
+    agent: string;
+    task: string;
+    attempt: number;
+    maxAttempts: number;
+} | {
+    type: "spawn.retry";
+    spawnId: number;
+    agent: string;
+    task: string;
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+    error: string;
+} | {
+    type: "spawn.succeeded";
+    spawnId: number;
+    agent: string;
+    task: string;
+    attempt: number;
+    maxAttempts: number;
+    durationMs: number;
+} | {
+    type: "spawn.failed";
+    checked: boolean;
+    spawnId: number;
+    agent: string;
+    task: string;
+    attempt: number;
+    maxAttempts: number;
+    durationMs: number;
+    error: string;
+} | {
+    type: "spawn.cancelled";
+    spawnId: number;
+    agent: string;
+    task: string;
+    attempt: number;
+    maxAttempts: number;
+    durationMs: number;
+    reason: string;
+};
+export type SpawnUsageTotal = {
+    inputTokens: number;
+    outputTokens: number;
+    cachedTokens: number;
+    costUsd?: number;
+    spawnCount: number;
+    attemptCount?: number;
+};
+export type SpawnUsageAccumulator = {
+    beginAttempt?(): void;
+    beginSpawn?(): void;
+    record(usage: SpawnUsage | undefined): void;
+    reset(): void;
+    snapshot(): SpawnUsageTotal;
+};
+export declare function createSpawnUsageAccumulator(): SpawnUsageAccumulator;
+export declare function runWithSpawnUsageAccumulator<TResult>(accumulator: SpawnUsageAccumulator, operation: () => Promise<TResult>): Promise<TResult>;
+export type AgentModuleRetryOptions = {
+    maxAttempts: number;
+    backoffMs: number;
+    isErrorRetryable?: (error: unknown) => boolean;
+    isRetryable?: (result: SpawnAgentResult) => boolean;
+};
+export type AgentModuleParallelCall = readonly [agentDef: AgentModuleDefinition, options: AgentModuleSpawnOptions] | ((signal?: AbortSignal) => {
+    events: AsyncIterable<never>;
+    result: Promise<SpawnAgentResult>;
+});
+type AgentModuleSpawn = {
+    (agentDef: AgentModuleDefinition, options: AgentModuleSpawnOptions): Promise<SpawnAgentResult>;
+    retry(agentDef: AgentModuleDefinition, options: AgentModuleSpawnOptions, retryOptions: AgentModuleRetryOptions): Promise<SpawnAgentResult>;
+    parallel(calls: AgentModuleParallelCall[], options?: SpawnParallelOptions): Promise<SpawnAgentResult[]>;
+};
+export declare function makeAgentModule(spawnAgent: SpawnAgent, moduleOptions?: AgentModuleOptions): {
+    spawn: AgentModuleSpawn;
+};
+export {};

package/dist/safe-js/modules/env.d.ts

@@ -0,0 +1,14 @@
+export type EnvModuleOptions = {
+    allow: readonly string[];
+    values?: Readonly<Record<string, string | undefined>>;
+};
+export type EnvModule = {
+    get(name: string): string | undefined;
+};
+export declare class EnvAccessError extends Error {
+    readonly code = "ENV_ACCESS_DENIED";
+    readonly variable: string;
+    constructor(variable: string);
+}
+export declare function makeEnvModule(input: readonly string[] | EnvModuleOptions): EnvModule;
+export declare function parseEnvConfig(json: string): EnvModuleOptions;

package/dist/safe-js/modules/fail.d.ts

@@ -0,0 +1,6 @@
+export declare class HarnessFailure extends Error {
+    constructor(message: string);
+}
+export declare function makeFailModule(): {
+    default: (message: string) => never;
+};

package/dist/safe-js/modules/fs-config.d.ts

@@ -0,0 +1,12 @@
+import { type FileSystemAdapterRegistry, type FileSystemConfig } from "../../safe-fs/index.js";
+import type { FsModuleOptions } from "./fs.js";
+export type FsConfig = {
+    readonly adapter: FileSystemConfig;
+    readonly root?: string;
+    readonly cwd?: string;
+};
+export type ResolveFsConfigOptions = {
+    readonly registry?: FileSystemAdapterRegistry;
+};
+export declare function parseFsConfig(json: string): FsConfig;
+export declare function resolveFsConfig(config: FsConfig, options?: ResolveFsConfigOptions): Promise<Required<Pick<FsModuleOptions, "adapter">> & Pick<FsModuleOptions, "root" | "cwd">>;

package/dist/safe-js/modules/fs.d.ts

@@ -0,0 +1,82 @@
+import { type PathLike } from "node:fs";
+import * as nodeFsPromises from "node:fs/promises";
+import { type FileSystem } from "../../safe-fs/index.js";
+type FsOperationName = "access" | "appendFile" | "chmod" | "copyFile" | "cp" | "link" | "lstat" | "mkdir" | "mkdtemp" | "readFile" | "readdir" | "readlink" | "realpath" | "rename" | "rm" | "rmdir" | "stat" | "symlink" | "truncate" | "utimes" | "writeFile";
+type FsPassthroughName = Exclude<FsOperationName, "lstat" | "mkdtemp" | "readFile" | "readdir" | "readlink" | "realpath" | "stat">;
+declare const REFUSED_OPTION_REASONS: {
+    readonly signal: "the sandbox has no AbortController, and cancelling a run is the host's to request rather than the script's";
+    readonly throwIfNoEntry: "only node's synchronous stat reads it and fs/promises rejects a missing path whatever it says, so catch the ENOENT rejection instead";
+    readonly filter: "a closure is dropped from the digest that identifies a host call across a snapshot, so a resumed run could reconcile against a copy that took a different set of files, and under a root it would read the rewritten host paths rather than the ones the script wrote — walk the tree with readdir and copy the entries you want instead";
+};
+type FsOptionSurface = {
+    readonly argument: number;
+    readonly honoured: readonly string[];
+    readonly refused: readonly (keyof typeof REFUSED_OPTION_REASONS)[];
+};
+export declare const FS_OPTION_SURFACE: Record<"appendFile" | "cp" | "lstat" | "mkdir" | "mkdtemp" | "readFile" | "readdir" | "readlink" | "realpath" | "rm" | "rmdir" | "stat" | "writeFile", FsOptionSurface>;
+declare const STAT_NUMBER_FIELDS: readonly ["dev", "mode", "nlink", "uid", "gid", "rdev", "blksize", "ino", "size", "blocks", "atimeMs", "mtimeMs", "ctimeMs", "birthtimeMs"];
+declare const FILE_TYPE_PREDICATES: readonly ["isFile", "isDirectory", "isSymbolicLink", "isBlockDevice", "isCharacterDevice", "isFIFO", "isSocket"];
+export type FsImplementation = Pick<typeof nodeFsPromises, FsOperationName>;
+type FileTypePredicates = {
+    readonly [Name in (typeof FILE_TYPE_PREDICATES)[number]]: () => boolean;
+};
+export type SandboxStats = {
+    readonly [Name in (typeof STAT_NUMBER_FIELDS)[number]]: number;
+} & FileTypePredicates;
+export type SandboxDirent = {
+    readonly name: string;
+    readonly parentPath: string;
+} & FileTypePredicates;
+type StringEncoding = NodeJS.BufferEncoding;
+type EncodingOptions = StringEncoding | {
+    encoding: StringEncoding;
+};
+type ReadFileOptions = StringEncoding | {
+    encoding: StringEncoding;
+    flag?: string;
+};
+type ReaddirOptions = {
+    encoding?: StringEncoding;
+    recursive?: boolean;
+};
+type StatOptions = {
+    bigint?: false;
+};
+export type FsModuleOptions = {
+    root?: string;
+    fs?: FsImplementation;
+    adapter?: never;
+    cwd?: never;
+    signal?: never;
+} | {
+    adapter: FileSystem;
+    root?: string;
+    cwd?: string;
+    signal?: AbortSignal;
+    fs?: never;
+};
+export type FsModule = Pick<FsImplementation, FsPassthroughName> & {
+    readFile(path: PathLike, options: ReadFileOptions): Promise<string>;
+    readlink(path: PathLike, options?: EncodingOptions): Promise<string>;
+    realpath(path: PathLike, options?: EncodingOptions): Promise<string>;
+    mkdtemp(prefix: string, options?: EncodingOptions): Promise<string>;
+    readdir: {
+        (path: PathLike, options: ReaddirOptions & {
+            withFileTypes: true;
+        }): Promise<SandboxDirent[]>;
+        (path: PathLike, options?: StringEncoding | (ReaddirOptions & {
+            withFileTypes?: false;
+        })): Promise<string[]>;
+    };
+    stat(path: PathLike, options?: StatOptions): Promise<SandboxStats>;
+    lstat(path: PathLike, options?: StatOptions): Promise<SandboxStats>;
+    constants: {
+        F_OK: number;
+        R_OK: number;
+        W_OK: number;
+        X_OK: number;
+        COPYFILE_EXCL: number;
+    };
+};
+export declare function makeFsModule(options?: FsModuleOptions): FsModule;
+export {};

package/dist/safe-js/modules/harness.d.ts

@@ -0,0 +1,19 @@
+import { type SandboxValue } from "../interp/values.js";
+export type HarnessFrontmatter = Record<string, SandboxValue>;
+export type HarnessModuleMeta = {
+    kind: SandboxValue;
+    version: SandboxValue;
+    filepath: string;
+    frontmatter: HarnessFrontmatter;
+};
+export type HarnessModule = {
+    tasks: SandboxValue;
+    agents: SandboxValue;
+    meta: HarnessModuleMeta;
+    applyConstraints: (prompt: string) => string;
+};
+export declare function makeHarnessModule(frontmatter: Record<string, unknown>, meta: {
+    kind: unknown;
+    version: unknown;
+    filepath: string;
+}): HarnessModule;

package/dist/safe-js/modules/log.d.ts

@@ -0,0 +1,16 @@
+export type LogModuleEntry = {
+    ts: string;
+    type: "info" | "error";
+    args: unknown[];
+} | {
+    ts: string;
+    type: "event";
+    name: string;
+    payload: unknown;
+};
+export type LogModuleSink = (entry: LogModuleEntry) => void;
+export declare function makeLogModule(sink?: LogModuleSink): {
+    info: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    event: (name: string, payload: unknown) => void;
+};

package/dist/safe-js/modules/mcp-transport.d.ts

@@ -0,0 +1,26 @@
+import { McpClient, type HttpTransportFetch, type StdioSpawn } from "../../tiny-mcp-client/index.js";
+export type McpServerConfig = {
+    command: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+} | {
+    url: string;
+    headers?: Record<string, string>;
+};
+export type McpModuleOptions = {
+    servers: Record<string, McpServerConfig>;
+    requestTimeoutMs?: number;
+    closeTimeoutMs?: number;
+    maxToolPages?: number;
+    signal?: AbortSignal;
+    fetch?: HttpTransportFetch;
+    spawn?: StdioSpawn;
+};
+export type ManagedMcpConnection = {
+    ready: Promise<McpClient>;
+    close(): Promise<void>;
+};
+export declare function parseMcpConfig(source: string, directory: string): McpModuleOptions;
+export declare function normalizeMcpOptions(value: unknown, keys?: string[]): McpModuleOptions;
+export declare function connectMcpTransport(server: McpServerConfig, options: McpModuleOptions, signal?: AbortSignal): ManagedMcpConnection;