@brian-agent/codemode 0.0.0-stage → 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,246 @@
+import type { CodemodeWasmModule } from "./wasm.ts";
+export interface CodemodeToolContext {
+    /**
+     * Aborted when the script finishes (including unawaited calls), the
+     * execution times out, the caller aborts, or the sandbox is closed.
+     */
+    signal: AbortSignal;
+}
+/** A JSON Schema document. Only used to render declarations; values are not validated against it. */
+export type CodemodeJsonSchema = {
+    [key: string]: unknown;
+} | boolean;
+export interface CodemodeTool {
+    /**
+     * The script calls tools as `tools.<id>(args)`, where `<id>` is the name with characters that
+     * are not valid in identifiers replaced by `_` (see `toCodemodeIdentifier`), and also as
+     * `tools["<name>"](args)`. Globals are called as `<name>(args)` and must be identifiers, or
+     * `<namespace>.<member>`, which groups them into a frozen namespace object.
+     */
+    name: string;
+    /** Shown as a doc comment in {@link renderDeclarations}, and listed in `ALL_TOOLS` for tools. */
+    description?: string;
+    /** Schema of the single argument. Rendered as the parameter type; `unknown` when omitted. */
+    inputSchema?: CodemodeJsonSchema;
+    /** Schema of the resolved value. Rendered as the promise type; `unknown` when omitted. */
+    outputSchema?: CodemodeJsonSchema;
+    /** Globals only: `execute` receives all call arguments as an array instead of the first one. */
+    spread?: boolean;
+    /**
+     * Globals only: TypeScript parameter list and return type for {@link renderDeclarations}, for
+     * example `(type: string, id?: string): Promise<Model[]>`. Replaces the rendering from the schemas.
+     */
+    signature?: string;
+    /**
+     * `args` is whatever the script passed, after a JSON round trip. The return
+     * value must be JSON-serializable; a thrown error surfaces in the script as
+     * an `Error` with the same message.
+     */
+    execute(args: unknown, context: CodemodeToolContext): Promise<unknown> | unknown;
+}
+/**
+ * One item of the script's output, in the order the script produced it: `text()` and `console.*`
+ * produce text items, with `console: true` for `console.*`, and `image()` image items. `data` is base64.
+ */
+export type CodemodeOutputItem = {
+    type: "text";
+    text: string;
+    console?: true;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+export type CodemodeCallStatus = "ok" | "error" | "cancelled";
+export interface CodemodeCall {
+    name: string;
+    status: CodemodeCallStatus;
+    durationMs: number;
+}
+export type CodemodeErrorKind = 
+/** The script threw or failed to parse. `name` and `stack` come from the script's error. */
+"script"
+/**
+ * The overall deadline expired, or a VM on the calling thread used up its interrupt budget.
+ * The execution ended and the VM was asked to stop; a worker or remote VM may still be computing.
+ */
+ | "timeout"
+/** The caller's signal fired or the sandbox was closed. The execution ended and the VM was asked to stop. */
+ | "aborted"
+/**
+ * The VM or its transport failed outside the script's control (for example a wasm trap, a missing
+ * worker file, or a remote sandbox that failed).
+ */
+ | "sandbox";
+export interface CodemodeError {
+    kind: CodemodeErrorKind;
+    name?: string;
+    message: string;
+    stack?: string;
+}
+/** Keys the script changed with `store()`. Only successful executions report writes. */
+export interface CodemodeStoreWrites {
+    set: Record<string, unknown>;
+    /** Keys stored as `undefined`. */
+    delete: string[];
+}
+/**
+ * `output` is kept for failed executions too, up to the failure. `exit()` completes with `value: undefined`.
+ * `during`: in a {@link CodemodeSandboxBase.start} run that the script itself ended (it returned, threw, or exited),
+ * the result being processed when it did.
+ */
+export type CodemodeResult = {
+    ok: true;
+    value: unknown;
+    output: CodemodeOutputItem[];
+    calls: CodemodeCall[];
+    storeWrites: CodemodeStoreWrites;
+    during?: CodemodeDuring;
+} | {
+    ok: false;
+    error: CodemodeError;
+    output: CodemodeOutputItem[];
+    calls: CodemodeCall[];
+    during?: CodemodeDuring;
+};
+/** Options every sandbox accepts, wherever its VM runs. */
+export interface CodemodeSandboxBaseOptions {
+    tools?: CodemodeTool[];
+    /**
+     * Functions exposed as top-level identifiers instead of on `tools`, for host helpers such as
+     * attaching an image to the result. They behave like tools (JSON round trip, promise result)
+     * but are not recorded in `result.calls`. Names must be identifiers and may not shadow the
+     * built-in globals (`tools`, `ALL_TOOLS`, `console`, `text`, `image`, `exit`, `store`, `load`).
+     */
+    globals?: CodemodeTool[];
+    /**
+     * Overall deadline per execution, including time spent in tools. `Infinity` disables the
+     * deadline; the execution then only ends when the script settles or is aborted.
+     * Default: 300000.
+     */
+    timeoutMs?: number;
+    /**
+     * Maximum memory the QuickJS VM may allocate. Allocations beyond it fail inside the script as
+     * `InternalError: out of memory`. Default: no limit beyond wasm32's 4 GiB address space.
+     */
+    memoryLimitBytes?: number;
+}
+/** Options of `CodemodeSandbox`, which runs each VM in a Node or Bun worker thread. */
+export interface CodemodeSandboxOptions extends CodemodeSandboxBaseOptions {
+    /**
+     * Compiled `quickjs-wasi/quickjs.wasm`, usually from {@link loadQuickJSWasm}. Default:
+     * `loadQuickJSWasm()`, the file in the installed `quickjs-wasi` package. Pass it when that file
+     * is not on disk, for example in a Bun compiled executable.
+     */
+    wasm?: CodemodeWasmModule | Promise<CodemodeWasmModule>;
+    /**
+     * Worker entry that imports `@brian-agent/codemode/worker`. Default: this package's own
+     * worker file. Pass it when this package is bundled, since the default is resolved relative to
+     * the module that creates the sandbox. Bun compiled executables require the relative string
+     * specifier of an embedded build entrypoint; other hosts usually use a URL.
+     */
+    workerUrl?: string | URL;
+    /**
+     * Synchronously reserves capacity immediately before creating each worker, after loading wasm.
+     * Throw to deny admission without starting a worker. Return a release callback, called once if
+     * worker construction fails or when the worker actually exits, not when the result settles.
+     * The release callback must not throw. Reservations can be shared across sandbox instances.
+     */
+    acquireWorker?(): () => void;
+    /**
+     * Called once for each worker started by execute() or start(). `exited` resolves when that worker
+     * actually exits, which may be after the result and close() settle: on Bun a non-interruptible
+     * built-in can delay termination. Use it to keep the worker counted against host concurrency
+     * limits until it exits. A thrown callback error fails the execution and requests worker termination.
+     */
+    onWorkerStarted?(exited: Promise<void>): void;
+}
+/** A call the script made in a {@link CodemodeSandboxBase.start} run, answered with `CodemodeRun.deliver()`. */
+export interface CodemodeHostCall {
+    /** The VM's own number for the call, `1`, `2`, ... in the order the script made its calls (tools and globals). */
+    id: number;
+    target: "tool" | "global";
+    name: string;
+    /** What the script passed, after a JSON round trip; for spread globals the argument list. */
+    args: unknown;
+}
+/** A tool as a {@link CodemodeSandboxBase.start} run's script sees it: `tools.<name>` and its `ALL_TOOLS` entry. */
+export interface CodemodeDeclaredTool {
+    name: string;
+    /**
+     * The identifier the script uses, `tools.<jsName>`. Default: `toCodemodeIdentifier(name)`. A host that replays a run
+     * passes the one the run started with, so a changed mapping cannot rename a tool under a resumed script.
+     */
+    jsName?: string;
+    description?: string;
+}
+/** A global as a {@link CodemodeSandboxBase.start} run's script sees it; the same names as `globals` allow. */
+export interface CodemodeDeclaredGlobal {
+    name: string;
+    spread?: boolean;
+}
+/**
+ * A call's answer. A rejection becomes an `Error` with `message` in the script, carrying the own properties of
+ * `properties` (JSON values; `name`, `message`, and `stack` are ignored), for example `{ structuredOutput }`.
+ */
+export type CodemodeOutcome = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    message: string;
+    properties?: Record<string, unknown>;
+};
+/** In a {@link CodemodeSandboxBase.start} run: the result the VM was processing when the script finished, 0 for its first run, and the calls issued by then. */
+export interface CodemodeDuring {
+    seq: number;
+    issued: number;
+}
+export interface CodemodeRunOptions {
+    /** The VM clock's start, in ms since the epoch: `Date.now()` until the first result arrives. */
+    startedAt: number;
+    /** Seeds `Math.random()` and the VM's other randomness. A 32-bit unsigned integer. */
+    seed: number;
+    tools?: CodemodeDeclaredTool[];
+    globals?: CodemodeDeclaredGlobal[];
+    store?: Readonly<Record<string, unknown>>;
+    signal?: AbortSignal;
+    /** Deadline of this run in ms. Default: none (not the sandbox's default). */
+    timeoutMs?: number;
+    /** The VM's fingerprint, before the script runs and before any of its calls. */
+    onStarted?(fingerprint: string): void;
+    /** The script made a call. Answer it with `CodemodeRun.deliver()`, now or later. */
+    onCall(call: CodemodeHostCall): void;
+    /**
+     * The VM processed result `seq` (`0`: the script's first run, before any result) and waits again, having issued
+     * `issued` calls in total.
+     */
+    onIdle?(seq: number, issued: number): void;
+}
+/** A running {@link CodemodeSandboxBase.start} execution. */
+export interface CodemodeRun {
+    readonly result: Promise<CodemodeResult>;
+    /**
+     * Whether the run has its outcome: the script ended, timed out, or failed, or the run was aborted. Set when that is
+     * decided, before `result` settles; calls can no longer be answered. It does not mean the VM has exited.
+     */
+    readonly finished: boolean;
+    /**
+     * Answer call `id` as result number `seq`. Results are numbered 1, 2, ... without gaps, and the VM applies them
+     * strictly in that order, whatever order they arrive in: after a gap it waits for the missing number. While it
+     * processes this one, its clock reads `now` (ms since the epoch), or the previous value if `now` is earlier.
+     * Throws for a call that is not waiting for an answer, a `seq` used before, or a `now` that is not finite.
+     */
+    deliver(seq: number, now: number, id: number, outcome: CodemodeOutcome): void;
+}
+export interface CodemodeExecuteOptions {
+    signal?: AbortSignal;
+    /** Overrides the sandbox default for this execution. */
+    timeoutMs?: number;
+    /**
+     * Values the script reads with `load(key)`. Must be JSON-serializable. The script's own
+     * `store()` calls come back as `result.storeWrites`; persisting them is up to the caller.
+     */
+    store?: Readonly<Record<string, unknown>>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { CodemodeWasmModule } from \"./wasm.ts\";\n\nexport interface CodemodeToolContext {\n\t/**\n\t * Aborted when the script finishes (including unawaited calls), the\n\t * execution times out, the caller aborts, or the sandbox is closed.\n\t */\n\tsignal: AbortSignal;\n}\n\n/** A JSON Schema document. Only used to render declarations; values are not validated against it. */\nexport type CodemodeJsonSchema = { [key: string]: unknown } | boolean;\n\nexport interface CodemodeTool {\n\t/**\n\t * The script calls tools as `tools.<id>(args)`, where `<id>` is the name with characters that\n\t * are not valid in identifiers replaced by `_` (see `toCodemodeIdentifier`), and also as\n\t * `tools[\"<name>\"](args)`. Globals are called as `<name>(args)` and must be identifiers, or\n\t * `<namespace>.<member>`, which groups them into a frozen namespace object.\n\t */\n\tname: string;\n\t/** Shown as a doc comment in {@link renderDeclarations}, and listed in `ALL_TOOLS` for tools. */\n\tdescription?: string;\n\t/** Schema of the single argument. Rendered as the parameter type; `unknown` when omitted. */\n\tinputSchema?: CodemodeJsonSchema;\n\t/** Schema of the resolved value. Rendered as the promise type; `unknown` when omitted. */\n\toutputSchema?: CodemodeJsonSchema;\n\t/** Globals only: `execute` receives all call arguments as an array instead of the first one. */\n\tspread?: boolean;\n\t/**\n\t * Globals only: TypeScript parameter list and return type for {@link renderDeclarations}, for\n\t * example `(type: string, id?: string): Promise<Model[]>`. Replaces the rendering from the schemas.\n\t */\n\tsignature?: string;\n\t/**\n\t * `args` is whatever the script passed, after a JSON round trip. The return\n\t * value must be JSON-serializable; a thrown error surfaces in the script as\n\t * an `Error` with the same message.\n\t */\n\texecute(args: unknown, context: CodemodeToolContext): Promise<unknown> | unknown;\n}\n\n/**\n * One item of the script's output, in the order the script produced it: `text()` and `console.*`\n * produce text items, with `console: true` for `console.*`, and `image()` image items. `data` is base64.\n */\nexport type CodemodeOutputItem =\n\t| { type: \"text\"; text: string; console?: true }\n\t| { type: \"image\"; data: string; mimeType: string };\n\nexport type CodemodeCallStatus = \"ok\" | \"error\" | \"cancelled\";\n\nexport interface CodemodeCall {\n\tname: string;\n\tstatus: CodemodeCallStatus;\n\tdurationMs: number;\n}\n\nexport type CodemodeErrorKind =\n\t/** The script threw or failed to parse. `name` and `stack` come from the script's error. */\n\t| \"script\"\n\t/**\n\t * The overall deadline expired, or a VM on the calling thread used up its interrupt budget.\n\t * The execution ended and the VM was asked to stop; a worker or remote VM may still be computing.\n\t */\n\t| \"timeout\"\n\t/** The caller's signal fired or the sandbox was closed. The execution ended and the VM was asked to stop. */\n\t| \"aborted\"\n\t/**\n\t * The VM or its transport failed outside the script's control (for example a wasm trap, a missing\n\t * worker file, or a remote sandbox that failed).\n\t */\n\t| \"sandbox\";\n\nexport interface CodemodeError {\n\tkind: CodemodeErrorKind;\n\tname?: string;\n\tmessage: string;\n\tstack?: string;\n}\n\n/** Keys the script changed with `store()`. Only successful executions report writes. */\nexport interface CodemodeStoreWrites {\n\tset: Record<string, unknown>;\n\t/** Keys stored as `undefined`. */\n\tdelete: string[];\n}\n\n/**\n * `output` is kept for failed executions too, up to the failure. `exit()` completes with `value: undefined`.\n * `during`: in a {@link CodemodeSandboxBase.start} run that the script itself ended (it returned, threw, or exited),\n * the result being processed when it did.\n */\nexport type CodemodeResult =\n\t| {\n\t\t\tok: true;\n\t\t\tvalue: unknown;\n\t\t\toutput: CodemodeOutputItem[];\n\t\t\tcalls: CodemodeCall[];\n\t\t\tstoreWrites: CodemodeStoreWrites;\n\t\t\tduring?: CodemodeDuring;\n\t  }\n\t| {\n\t\t\tok: false;\n\t\t\terror: CodemodeError;\n\t\t\toutput: CodemodeOutputItem[];\n\t\t\tcalls: CodemodeCall[];\n\t\t\tduring?: CodemodeDuring;\n\t  };\n\n/** Options every sandbox accepts, wherever its VM runs. */\nexport interface CodemodeSandboxBaseOptions {\n\ttools?: CodemodeTool[];\n\t/**\n\t * Functions exposed as top-level identifiers instead of on `tools`, for host helpers such as\n\t * attaching an image to the result. They behave like tools (JSON round trip, promise result)\n\t * but are not recorded in `result.calls`. Names must be identifiers and may not shadow the\n\t * built-in globals (`tools`, `ALL_TOOLS`, `console`, `text`, `image`, `exit`, `store`, `load`).\n\t */\n\tglobals?: CodemodeTool[];\n\t/**\n\t * Overall deadline per execution, including time spent in tools. `Infinity` disables the\n\t * deadline; the execution then only ends when the script settles or is aborted.\n\t * Default: 300000.\n\t */\n\ttimeoutMs?: number;\n\t/**\n\t * Maximum memory the QuickJS VM may allocate. Allocations beyond it fail inside the script as\n\t * `InternalError: out of memory`. Default: no limit beyond wasm32's 4 GiB address space.\n\t */\n\tmemoryLimitBytes?: number;\n}\n\n/** Options of `CodemodeSandbox`, which runs each VM in a Node or Bun worker thread. */\nexport interface CodemodeSandboxOptions extends CodemodeSandboxBaseOptions {\n\t/**\n\t * Compiled `quickjs-wasi/quickjs.wasm`, usually from {@link loadQuickJSWasm}. Default:\n\t * `loadQuickJSWasm()`, the file in the installed `quickjs-wasi` package. Pass it when that file\n\t * is not on disk, for example in a Bun compiled executable.\n\t */\n\twasm?: CodemodeWasmModule | Promise<CodemodeWasmModule>;\n\t/**\n\t * Worker entry that imports `@brian-agent/codemode/worker`. Default: this package's own\n\t * worker file. Pass it when this package is bundled, since the default is resolved relative to\n\t * the module that creates the sandbox. Bun compiled executables require the relative string\n\t * specifier of an embedded build entrypoint; other hosts usually use a URL.\n\t */\n\tworkerUrl?: string | URL;\n\t/**\n\t * Synchronously reserves capacity immediately before creating each worker, after loading wasm.\n\t * Throw to deny admission without starting a worker. Return a release callback, called once if\n\t * worker construction fails or when the worker actually exits, not when the result settles.\n\t * The release callback must not throw. Reservations can be shared across sandbox instances.\n\t */\n\tacquireWorker?(): () => void;\n\t/**\n\t * Called once for each worker started by execute() or start(). `exited` resolves when that worker\n\t * actually exits, which may be after the result and close() settle: on Bun a non-interruptible\n\t * built-in can delay termination. Use it to keep the worker counted against host concurrency\n\t * limits until it exits. A thrown callback error fails the execution and requests worker termination.\n\t */\n\tonWorkerStarted?(exited: Promise<void>): void;\n}\n\n/** A call the script made in a {@link CodemodeSandboxBase.start} run, answered with `CodemodeRun.deliver()`. */\nexport interface CodemodeHostCall {\n\t/** The VM's own number for the call, `1`, `2`, ... in the order the script made its calls (tools and globals). */\n\tid: number;\n\ttarget: \"tool\" | \"global\";\n\tname: string;\n\t/** What the script passed, after a JSON round trip; for spread globals the argument list. */\n\targs: unknown;\n}\n\n/** A tool as a {@link CodemodeSandboxBase.start} run's script sees it: `tools.<name>` and its `ALL_TOOLS` entry. */\nexport interface CodemodeDeclaredTool {\n\tname: string;\n\t/**\n\t * The identifier the script uses, `tools.<jsName>`. Default: `toCodemodeIdentifier(name)`. A host that replays a run\n\t * passes the one the run started with, so a changed mapping cannot rename a tool under a resumed script.\n\t */\n\tjsName?: string;\n\tdescription?: string;\n}\n\n/** A global as a {@link CodemodeSandboxBase.start} run's script sees it; the same names as `globals` allow. */\nexport interface CodemodeDeclaredGlobal {\n\tname: string;\n\tspread?: boolean;\n}\n\n/**\n * A call's answer. A rejection becomes an `Error` with `message` in the script, carrying the own properties of\n * `properties` (JSON values; `name`, `message`, and `stack` are ignored), for example `{ structuredOutput }`.\n */\nexport type CodemodeOutcome =\n\t| { ok: true; value: unknown }\n\t| { ok: false; message: string; properties?: Record<string, unknown> };\n\n/** In a {@link CodemodeSandboxBase.start} run: the result the VM was processing when the script finished, 0 for its first run, and the calls issued by then. */\nexport interface CodemodeDuring {\n\tseq: number;\n\tissued: number;\n}\n\nexport interface CodemodeRunOptions {\n\t/** The VM clock's start, in ms since the epoch: `Date.now()` until the first result arrives. */\n\tstartedAt: number;\n\t/** Seeds `Math.random()` and the VM's other randomness. A 32-bit unsigned integer. */\n\tseed: number;\n\ttools?: CodemodeDeclaredTool[];\n\tglobals?: CodemodeDeclaredGlobal[];\n\tstore?: Readonly<Record<string, unknown>>;\n\tsignal?: AbortSignal;\n\t/** Deadline of this run in ms. Default: none (not the sandbox's default). */\n\ttimeoutMs?: number;\n\t/** The VM's fingerprint, before the script runs and before any of its calls. */\n\tonStarted?(fingerprint: string): void;\n\t/** The script made a call. Answer it with `CodemodeRun.deliver()`, now or later. */\n\tonCall(call: CodemodeHostCall): void;\n\t/**\n\t * The VM processed result `seq` (`0`: the script's first run, before any result) and waits again, having issued\n\t * `issued` calls in total.\n\t */\n\tonIdle?(seq: number, issued: number): void;\n}\n\n/** A running {@link CodemodeSandboxBase.start} execution. */\nexport interface CodemodeRun {\n\treadonly result: Promise<CodemodeResult>;\n\t/**\n\t * Whether the run has its outcome: the script ended, timed out, or failed, or the run was aborted. Set when that is\n\t * decided, before `result` settles; calls can no longer be answered. It does not mean the VM has exited.\n\t */\n\treadonly finished: boolean;\n\t/**\n\t * Answer call `id` as result number `seq`. Results are numbered 1, 2, ... without gaps, and the VM applies them\n\t * strictly in that order, whatever order they arrive in: after a gap it waits for the missing number. While it\n\t * processes this one, its clock reads `now` (ms since the epoch), or the previous value if `now` is earlier.\n\t * Throws for a call that is not waiting for an answer, a `seq` used before, or a `now` that is not finite.\n\t */\n\tdeliver(seq: number, now: number, id: number, outcome: CodemodeOutcome): void;\n}\n\nexport interface CodemodeExecuteOptions {\n\tsignal?: AbortSignal;\n\t/** Overrides the sandbox default for this execution. */\n\ttimeoutMs?: number;\n\t/**\n\t * Values the script reads with `load(key)`. Must be JSON-serializable. The script's own\n\t * `store()` calls come back as `result.storeWrites`; persisting them is up to the caller.\n\t */\n\tstore?: Readonly<Record<string, unknown>>;\n}\n"]}

package/dist/wasm.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A compiled `WebAssembly.Module` of `quickjs-wasi/quickjs.wasm`. Typed opaquely because the Node
+ * type definitions do not declare the WebAssembly globals (they live in the DOM lib).
+ */
+export type CodemodeWasmModule = object;
+/**
+ * Read and compile the QuickJS wasm once per path. `path` defaults to the file in the installed
+ * `quickjs-wasi` package; pass it when that file lives elsewhere, for example embedded in a Bun
+ * compiled executable. A failed load is retried on the next call.
+ */
+export declare function loadQuickJSWasm(path?: string): Promise<CodemodeWasmModule>;
+//# sourceMappingURL=wasm.d.ts.map

package/dist/wasm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm.d.ts","sourceRoot":"","sources":["../src/wasm.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAQxC;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAc1E"}

package/dist/wasm.js

@@ -0,0 +1,24 @@
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+const modules = new Map();
+/**
+ * Read and compile the QuickJS wasm once per path. `path` defaults to the file in the installed
+ * `quickjs-wasi` package; pass it when that file lives elsewhere, for example embedded in a Bun
+ * compiled executable. A failed load is retried on the next call.
+ */
+export function loadQuickJSWasm(path) {
+    const resolved = path ?? createRequire(import.meta.url).resolve("quickjs-wasi/quickjs.wasm");
+    let module = modules.get(resolved);
+    if (!module) {
+        const { WebAssembly } = globalThis;
+        module = readFile(resolved)
+            .then((bytes) => WebAssembly.compile(bytes))
+            .catch((error) => {
+            modules.delete(resolved);
+            throw error;
+        });
+        modules.set(resolved, module);
+    }
+    return module;
+}
+//# sourceMappingURL=wasm.js.map

package/dist/wasm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm.js","sourceRoot":"","sources":["../src/wasm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAY5C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAuC,CAAC;AAE/D;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,IAAa;IAC5C,MAAM,QAAQ,GAAG,IAAI,IAAI,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAC7F,IAAI,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACnC,IAAI,CAAC,MAAM,EAAE,CAAC;QACb,MAAM,EAAE,WAAW,EAAE,GAAG,UAA2D,CAAC;QACpF,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC;aACzB,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;aAC3C,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YACzB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YACzB,MAAM,KAAK,CAAC;QACb,CAAC,CAAC,CAAC;QACJ,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,MAAM,CAAC;AACf,CAAC","sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { createRequire } from \"node:module\";\n\n/**\n * A compiled `WebAssembly.Module` of `quickjs-wasi/quickjs.wasm`. Typed opaquely because the Node\n * type definitions do not declare the WebAssembly globals (they live in the DOM lib).\n */\nexport type CodemodeWasmModule = object;\n\ninterface WebAssemblyGlobal {\n\tcompile(bytes: Uint8Array): Promise<CodemodeWasmModule>;\n}\n\nconst modules = new Map<string, Promise<CodemodeWasmModule>>();\n\n/**\n * Read and compile the QuickJS wasm once per path. `path` defaults to the file in the installed\n * `quickjs-wasi` package; pass it when that file lives elsewhere, for example embedded in a Bun\n * compiled executable. A failed load is retried on the next call.\n */\nexport function loadQuickJSWasm(path?: string): Promise<CodemodeWasmModule> {\n\tconst resolved = path ?? createRequire(import.meta.url).resolve(\"quickjs-wasi/quickjs.wasm\");\n\tlet module = modules.get(resolved);\n\tif (!module) {\n\t\tconst { WebAssembly } = globalThis as unknown as { WebAssembly: WebAssemblyGlobal };\n\t\tmodule = readFile(resolved)\n\t\t\t.then((bytes) => WebAssembly.compile(bytes))\n\t\t\t.catch((error: unknown) => {\n\t\t\t\tmodules.delete(resolved);\n\t\t\t\tthrow error;\n\t\t\t});\n\t\tmodules.set(resolved, module);\n\t}\n\treturn module;\n}\n"]}

package/package.json

@@ -1,6 +1,76 @@
 {
-  "name": "@brian-agent/codemode",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@brian-agent/codemode",
+	"version": "0.1.0",
+	"description": "Sandboxed JavaScript execution where the only capability is calling injected tools",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"source": "./src/index.ts",
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./declarations": {
+			"source": "./src/declarations.ts",
+			"types": "./dist/declarations.d.ts",
+			"import": "./dist/declarations.js"
+		},
+		"./source": {
+			"source": "./src/source.ts",
+			"types": "./dist/source.d.ts",
+			"import": "./dist/source.js"
+		},
+		"./portable": {
+			"source": "./src/portable.ts",
+			"types": "./dist/portable.d.ts",
+			"import": "./dist/portable.js"
+		},
+		"./cloudflare": {
+			"source": "./src/cloudflare.ts",
+			"types": "./dist/cloudflare.d.ts",
+			"import": "./dist/cloudflare.js"
+		},
+		"./worker": {
+			"source": "./src/runtime/worker.ts",
+			"types": "./dist/runtime/worker.d.ts",
+			"import": "./dist/runtime/worker.js"
+		}
+	},
+	"files": [
+		"dist",
+		"README.md"
+	],
+	"scripts": {
+		"clean": "shx rm -rf dist",
+		"build": "tsc -p tsconfig.build.json",
+		"test": "vitest --run",
+		"prepublishOnly": "npm run clean && npm run build"
+	},
+	"keywords": [
+		"brian",
+		"codemode",
+		"sandbox",
+		"quickjs",
+		"wasm",
+		"cloudflare",
+		"durable-objects"
+	],
+	"author": "Earendil Works",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/embeputer/brian.git",
+		"directory": "packages/codemode"
+	},
+	"engines": {
+		"node": ">=22.19.0"
+	},
+	"dependencies": {
+		"quickjs-wasi": "3.6.2"
+	},
+	"devDependencies": {
+		"shx": "0.3.4",
+		"vitest": "5.0.0"
+	}
+}