@agent-native/core 0.211.0 → 0.211.1-nightly-20261020213022

package/dist/collab/bounded-tasks.js

@@ -0,0 +1,439 @@
+import { getWorkerThreads } from "../shared/optional-node-builtins.js";
+import { BOUNDED_TASK_GLOBAL, } from "./bounded-task-source.js";
+export { BOUNDED_TASK_GLOBAL };
+export class BoundedTaskError extends Error {
+    code;
+    task;
+    /** `name` of the error the task threw, for `task_threw`. */
+    taskErrorName;
+    constructor(code, task, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : options);
+        this.name = "BoundedTaskError";
+        this.code = code;
+        this.task = task;
+        if (options.taskErrorName)
+            this.taskErrorName = options.taskErrorName;
+    }
+}
+/**
+ * Size of a structured-clone payload in bytes, or -1 when it holds anything
+ * but plain data (or more than 200,000 values). Stops counting once
+ * `limit` is passed. The worker host evaluates this function's source, so it
+ * must not reference anything outside its own body.
+ */
+export function measureBoundedPayload(value, limit) {
+    const maxNodes = 200_000;
+    let total = 0;
+    let nodes = 0;
+    const seen = new Set();
+    const stack = [value];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        nodes += 1;
+        if (nodes > maxNodes)
+            return -1;
+        if (current === null ||
+            current === undefined ||
+            typeof current === "boolean") {
+            total += 1;
+        }
+        else if (typeof current === "number") {
+            total += 8;
+        }
+        else if (typeof current === "string") {
+            total += current.length * 2;
+        }
+        else if (typeof current === "object") {
+            if (seen.has(current))
+                return -1;
+            seen.add(current);
+            if (ArrayBuffer.isView(current)) {
+                // Structured clone copies a view's whole buffer, and a shared buffer
+                // is not copied at all, so the task would see later writes.
+                if (typeof SharedArrayBuffer !== "undefined" &&
+                    current.buffer instanceof SharedArrayBuffer) {
+                    return -1;
+                }
+                total += current.buffer.byteLength;
+            }
+            else if (Array.isArray(current)) {
+                total += 8;
+                for (let index = 0; index < current.length; index += 1) {
+                    stack.push(current[index]);
+                }
+            }
+            else {
+                const proto = Object.getPrototypeOf(current);
+                if (proto !== Object.prototype && proto !== null)
+                    return -1;
+                for (const key of Object.keys(current)) {
+                    total += key.length * 2;
+                    stack.push(current[key]);
+                }
+            }
+        }
+        else {
+            return -1;
+        }
+        if (total > limit)
+            return total;
+    }
+    return total;
+}
+function hostScript(source) {
+    return `"use strict";
+const { parentPort, workerData } = require("node:worker_threads");
+const measureBoundedPayload = ${measureBoundedPayload.toString()};
+${source.code}
+;(() => {
+  const loaded = typeof ${BOUNDED_TASK_GLOBAL} === "undefined" ? undefined : ${BOUNDED_TASK_GLOBAL};
+  const tasks = loaded && typeof loaded === "object"
+    ? (loaded.tasks || (loaded.default && loaded.default.tasks))
+    : undefined;
+  if (!tasks || typeof tasks !== "object") {
+    throw new Error("Bounded task module ${JSON.stringify(source.name).slice(1, -1)} does not export a tasks object");
+  }
+  const describe = (error) => ({
+    name: error && typeof error.name === "string" ? error.name : "Error",
+    message: String(error && error.message !== undefined ? error.message : error).slice(0, 2000),
+  });
+  parentPort.on("message", async (message) => {
+    const id = message.id;
+    const run = Object.prototype.hasOwnProperty.call(tasks, message.task) ? tasks[message.task] : undefined;
+    if (typeof run !== "function") {
+      parentPort.postMessage({ id, ok: false, code: "task_unknown", name: "Error", message: "Unknown task " + String(message.task) });
+      return;
+    }
+    let output;
+    try {
+      output = await run(message.input);
+    } catch (error) {
+      parentPort.postMessage({ id, ok: false, code: "task_threw", ...describe(error) });
+      return;
+    }
+    const size = measureBoundedPayload(output, workerData.maxOutputBytes);
+    if (size < 0) {
+      parentPort.postMessage({ id, ok: false, code: "invalid_output", name: "Error", message: "Task output is not plain data" });
+      return;
+    }
+    if (size > workerData.maxOutputBytes) {
+      parentPort.postMessage({ id, ok: false, code: "output_too_large", name: "Error", message: "Task output exceeds " + workerData.maxOutputBytes + " bytes" });
+      return;
+    }
+    try {
+      parentPort.postMessage({ id, ok: true, output });
+    } catch (error) {
+      parentPort.postMessage({ id, ok: false, code: "invalid_output", ...describe(error) });
+    }
+  });
+  parentPort.postMessage({ ready: true });
+})();
+`;
+}
+/**
+ * Runs functions from one bundled module in worker threads, each under a
+ * terminable deadline and a heap limit, with a fixed number of workers and a
+ * bounded wait queue. A task that overruns is stopped by terminating its
+ * worker, so synchronous work in the task never blocks the caller's event
+ * loop. Where worker threads do not exist (Cloudflare Workers), every run
+ * fails with `unavailable`; it never falls back to running inline.
+ */
+export function createBoundedTaskRunner(options) {
+    const { source } = options;
+    if (!source ||
+        source.kind !== "bounded-task-source" ||
+        typeof source.code !== "string" ||
+        typeof source.name !== "string") {
+        throw new TypeError("createBoundedTaskRunner needs a BoundedTaskSource from bundleBoundedTaskSource");
+    }
+    const deadlineMs = positive(options.deadlineMs, 2_000, "deadlineMs");
+    const startupTimeoutMs = positive(options.startupTimeoutMs, 10_000, "startupTimeoutMs");
+    const maxWorkers = count(options.maxWorkers, 1, 1, "maxWorkers");
+    const maxQueue = count(options.maxQueue, 8, 0, "maxQueue");
+    const queueTimeoutMs = positive(options.queueTimeoutMs, deadlineMs, "queueTimeoutMs");
+    const maxInputBytes = positive(options.maxInputBytes, 8 * 1024 * 1024, "maxInputBytes");
+    const maxOutputBytes = positive(options.maxOutputBytes, 16 * 1024 * 1024, "maxOutputBytes");
+    const memoryLimitMb = positive(options.memoryLimitMb, 128, "memoryLimitMb");
+    const stackSizeMb = positive(options.stackSizeMb, 4, "stackSizeMb");
+    const idleTimeoutMs = positive(options.idleTimeoutMs, 30_000, "idleTimeoutMs");
+    const script = hostScript(source);
+    const slots = [];
+    // A terminated worker can keep running for a while; it holds its place
+    // under maxWorkers until it has exited.
+    const terminating = new Set();
+    const queue = [];
+    let nextId = 1;
+    let closed = false;
+    const fail = (pending, code, task, message, extra = {}) => pending.reject(new BoundedTaskError(code, task, message, extra));
+    function removeSlot(slot) {
+        if (slot.dead)
+            return;
+        slot.dead = true;
+        if (slot.startupTimer)
+            clearTimeout(slot.startupTimer);
+        if (slot.idleTimer)
+            clearTimeout(slot.idleTimer);
+        const index = slots.indexOf(slot);
+        if (index >= 0)
+            slots.splice(index, 1);
+        const exited = slot.worker
+            .terminate()
+            .then(() => undefined, () => undefined)
+            .then(() => {
+            terminating.delete(exited);
+            if (!closed)
+                drain();
+        });
+        terminating.add(exited);
+    }
+    function killSlot(slot, code, message, cause) {
+        if (slot.dead)
+            return;
+        const current = slot.current;
+        slot.current = undefined;
+        if (current) {
+            clearTimeout(current.deadline);
+            fail(current, code, current.task, message, { cause });
+        }
+        removeSlot(slot);
+        if (code === "startup_failed") {
+            // Respawning would hit the same broken bundle; fail what is waiting.
+            for (const task of queue.splice(0, queue.length)) {
+                if (task.queueTimer)
+                    clearTimeout(task.queueTimer);
+                fail(task, code, task.task, message, { cause });
+            }
+            return;
+        }
+        drain();
+    }
+    function spawn() {
+        const threads = getWorkerThreads();
+        let worker;
+        try {
+            if (!threads?.Worker)
+                throw new Error("node:worker_threads is missing");
+            worker = new threads.Worker(script, {
+                eval: true,
+                workerData: { maxOutputBytes },
+                resourceLimits: {
+                    maxOldGenerationSizeMb: memoryLimitMb,
+                    stackSizeMb,
+                },
+            });
+        }
+        catch (error) {
+            unavailable(error);
+            return null;
+        }
+        worker.unref();
+        const slot = { worker, ready: false, dead: false };
+        slot.startupTimer = setTimeout(() => {
+            killSlot(slot, "startup_failed", `Bounded task module ${source.name} did not start within ${startupTimeoutMs} ms`);
+        }, startupTimeoutMs);
+        slot.startupTimer.unref?.();
+        worker.on("message", (message) => {
+            if (slot.dead)
+                return;
+            if (message?.ready === true) {
+                slot.ready = true;
+                if (slot.startupTimer)
+                    clearTimeout(slot.startupTimer);
+                slot.startupTimer = undefined;
+                drain();
+                armQueueTimers();
+                if (!slot.current)
+                    markIdle(slot);
+                return;
+            }
+            const current = slot.current;
+            if (!current || message?.id !== current.id)
+                return;
+            clearTimeout(current.deadline);
+            slot.current = undefined;
+            if (message.ok === true) {
+                current.resolve(message.output);
+            }
+            else {
+                const code = message.code === "task_unknown" ||
+                    message.code === "invalid_output" ||
+                    message.code === "output_too_large"
+                    ? message.code
+                    : "task_threw";
+                fail(current, code, current.task, `Bounded task ${source.name}.${current.task} failed: ${String(message.message)}`, { taskErrorName: String(message.name ?? "Error") });
+            }
+            markIdle(slot);
+            drain();
+        });
+        worker.on("error", (error) => {
+            const outOfMemory = error?.code === "ERR_WORKER_OUT_OF_MEMORY";
+            // Before ready no task is running, so running out of heap means the
+            // module itself does; a respawn would too, forever.
+            if (!slot.ready) {
+                killSlot(slot, "startup_failed", outOfMemory
+                    ? `Bounded task module ${source.name} exceeded its ${memoryLimitMb} MiB heap while starting`
+                    : `Bounded task module ${source.name} failed to start: ${error?.message}`, error);
+                return;
+            }
+            killSlot(slot, outOfMemory ? "memory_exceeded" : "worker_crashed", outOfMemory
+                ? `Bounded task ${source.name} exceeded its ${memoryLimitMb} MiB heap`
+                : `Bounded task worker for ${source.name} crashed: ${error?.message}`, error);
+        });
+        worker.on("exit", (exitCode) => {
+            killSlot(slot, slot.ready ? "worker_crashed" : "startup_failed", `Bounded task worker for ${source.name} exited with code ${exitCode}`);
+        });
+        slots.push(slot);
+        return slot;
+    }
+    function unavailable(error) {
+        const pending = queue.splice(0, queue.length);
+        for (const task of pending) {
+            if (task.queueTimer)
+                clearTimeout(task.queueTimer);
+            fail(task, "unavailable", task.task, `Worker threads are unavailable here, so bounded task ${source.name}.${task.task} cannot run`, { cause: error });
+        }
+    }
+    function armQueueTimers() {
+        for (const pending of queue) {
+            if (pending.queueTimer)
+                continue;
+            pending.queueTimer = setTimeout(() => {
+                const index = queue.indexOf(pending);
+                if (index < 0)
+                    return;
+                queue.splice(index, 1);
+                fail(pending, "queue_timeout", pending.task, `Bounded task ${source.name}.${pending.task} waited more than ${queueTimeoutMs} ms for a worker`);
+            }, queueTimeoutMs);
+            pending.queueTimer.unref?.();
+        }
+    }
+    function markIdle(slot) {
+        if (slot.idleTimer)
+            clearTimeout(slot.idleTimer);
+        slot.idleTimer = setTimeout(() => {
+            if (!slot.current)
+                removeSlot(slot);
+        }, idleTimeoutMs);
+        slot.idleTimer.unref?.();
+    }
+    function dispatch(slot, task) {
+        if (task.queueTimer)
+            clearTimeout(task.queueTimer);
+        if (slot.idleTimer)
+            clearTimeout(slot.idleTimer);
+        const id = nextId++;
+        const deadline = setTimeout(() => {
+            killSlot(slot, "deadline_exceeded", `Bounded task ${source.name}.${task.task} did not finish within ${deadlineMs} ms`);
+        }, deadlineMs);
+        deadline.unref?.();
+        slot.current = { ...task, id, deadline };
+        try {
+            slot.worker.postMessage({ id, task: task.task, input: task.input });
+        }
+        catch (error) {
+            clearTimeout(deadline);
+            slot.current = undefined;
+            fail(task, "invalid_input", task.task, `Bounded task ${source.name}.${task.task} input cannot be sent to a worker`, { cause: error });
+            markIdle(slot);
+        }
+    }
+    function admit(pending) {
+        const size = measureBoundedPayload(pending.input, maxInputBytes);
+        if (size < 0) {
+            fail(pending, "invalid_input", pending.task, `Bounded task ${source.name}.${pending.task} input is not plain data`);
+            return false;
+        }
+        if (size > maxInputBytes) {
+            fail(pending, "input_too_large", pending.task, `Bounded task ${source.name}.${pending.task} input exceeds ${maxInputBytes} bytes`);
+            return false;
+        }
+        return true;
+    }
+    function drain() {
+        while (queue.length > 0) {
+            const idle = slots.find((slot) => slot.ready && !slot.current);
+            if (!idle)
+                break;
+            const next = queue.shift();
+            if (next.queueTimer)
+                clearTimeout(next.queueTimer);
+            // The caller still holds the input and can grow it while it waits;
+            // postMessage copies it in this same turn, so this check holds.
+            if (!admit(next))
+                continue;
+            dispatch(idle, next);
+        }
+        let needed = queue.length - slots.filter((slot) => !slot.ready).length;
+        while (needed > 0 && slots.length + terminating.size < maxWorkers) {
+            if (!spawn())
+                return;
+            needed -= 1;
+        }
+    }
+    return {
+        name: source.name,
+        run(task, input) {
+            return new Promise((resolve, reject) => {
+                const pending = {
+                    task,
+                    input,
+                    resolve: resolve,
+                    reject,
+                };
+                if (closed) {
+                    fail(pending, "closed", task, `Bounded task runner ${source.name} is closed`);
+                    return;
+                }
+                if (!admit(pending))
+                    return;
+                const running = slots.filter((slot) => slot.current).length;
+                if (running + queue.length >= maxWorkers + maxQueue) {
+                    fail(pending, "queue_full", task, `Bounded task runner ${source.name} already has ${maxQueue} tasks waiting`);
+                    return;
+                }
+                queue.push(pending);
+                drain();
+                // Only a starting worker bounds the wait by itself. With no slot at
+                // all, the task waits on a worker still terminating, which has none.
+                if (slots.length === 0 || slots.some((slot) => slot.ready)) {
+                    armQueueTimers();
+                }
+            });
+        },
+        stats() {
+            return {
+                workers: slots.length + terminating.size,
+                running: slots.filter((slot) => slot.current).length,
+                queued: queue.length,
+            };
+        },
+        async close() {
+            closed = true;
+            for (const task of queue.splice(0, queue.length)) {
+                if (task.queueTimer)
+                    clearTimeout(task.queueTimer);
+                fail(task, "closed", task.task, `Bounded task runner ${source.name} closed`);
+            }
+            for (const slot of slots.slice()) {
+                killSlot(slot, "closed", `Bounded task runner ${source.name} closed`);
+            }
+            await Promise.all(terminating);
+        },
+    };
+}
+function positive(value, fallback, name) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new RangeError(`Bounded task option ${name} must be a positive number`);
+    }
+    return value;
+}
+function count(value, fallback, min, name) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isSafeInteger(value) || value < min) {
+        throw new RangeError(`Bounded task option ${name} must be an integer of at least ${min}`);
+    }
+    return value;
+}

package/dist/collab/index.d.ts

@@ -1,5 +1,8 @@
-export { loadYDocState, saveYDocState, hasCollabState, deleteCollabState, uint8ArrayToBase64, base64ToUint8Array, } from "./storage.js";
-export { CollabBaseVersionConflictError, getDoc, withPreparedYDocMutation, applyUpdate, seedXmlFragmentIfEmpty, applyText, getText, getState, getIncUpdate, seedFromText, releaseDoc, searchAndReplace, applyJson, applyPatchOps, getJson, seedFromJson, type PreparedYDocMutationLease, } from "./ydoc-manager.js";
+export { loadYDocState, loadYDocVersion, hasCollabState, deleteCollabState, uint8ArrayToBase64, base64ToUint8Array, strictBase64ToUint8Array, CollabStateMalformedError, type CollabStateMalformedReason, } from "./storage.js";
+export { createBoundedTaskRunner, measureBoundedPayload, BoundedTaskError, BOUNDED_TASK_GLOBAL, type BoundedTaskErrorCode, type BoundedTaskRunner, type BoundedTaskRunnerOptions, type BoundedTaskRunnerStats, type BoundedTaskSource, } from "./bounded-tasks.js";
+export { bundleBoundedTaskSource, type BundleBoundedTaskSourceOptions, type BundledBoundedTaskSource, } from "./bounded-task-bundle.js";
+export { defineLiveCopy, releaseLiveCopy, LiveCopyError, LIVE_COPY_DEFAULT_FIELD, type LiveCopyBinding, type LiveCopyCommit, type LiveCopyErrorCode, type LiveCopyOptions, type LiveCopyOutcome, type LiveCopyPersistOutcome, } from "./live-copy.js";
+export { CollabBaseVersionConflictError, getDoc, saveYDocState, withPreparedYDocMutation, applyUpdate, seedXmlFragmentIfEmpty, applyText, getText, getState, getIncUpdate, seedFromText, releaseDoc, searchAndReplace, applyJson, applyPatchOps, getJson, seedFromJson, readLiveCopy, mutateLiveCopy, seedLiveCopy, type PreparedYDocMutationLease, type LiveCopyRead, type MutateLiveCopyOptions, type LiveCopyCallChange, type LiveCopyMutationResult, type SeedLiveCopyOptions, type LiveCopySeedResult, } from "./ydoc-manager.js";
 export { searchAndReplaceInYXml, extractTextFromYXml } from "./xml-ops.js";
 export { applyTextToYDoc, initYDocWithText } from "./text-to-yjs.js";
 export { getCollabEmitter, emitCollabUpdate, type CollabEvent, } from "./emitter.js";

package/dist/collab/index.js

@@ -1,5 +1,8 @@
-export { loadYDocState, saveYDocState, hasCollabState, deleteCollabState, uint8ArrayToBase64, base64ToUint8Array, } from "./storage.js";
-export { CollabBaseVersionConflictError, getDoc, withPreparedYDocMutation, applyUpdate, seedXmlFragmentIfEmpty, applyText, getText, getState, getIncUpdate, seedFromText, releaseDoc, searchAndReplace, applyJson, applyPatchOps, getJson, seedFromJson, } from "./ydoc-manager.js";
+export { loadYDocState, loadYDocVersion, hasCollabState, deleteCollabState, uint8ArrayToBase64, base64ToUint8Array, strictBase64ToUint8Array, CollabStateMalformedError, } from "./storage.js";
+export { createBoundedTaskRunner, measureBoundedPayload, BoundedTaskError, BOUNDED_TASK_GLOBAL, } from "./bounded-tasks.js";
+export { bundleBoundedTaskSource, } from "./bounded-task-bundle.js";
+export { defineLiveCopy, releaseLiveCopy, LiveCopyError, LIVE_COPY_DEFAULT_FIELD, } from "./live-copy.js";
+export { CollabBaseVersionConflictError, getDoc, saveYDocState, withPreparedYDocMutation, applyUpdate, seedXmlFragmentIfEmpty, applyText, getText, getState, getIncUpdate, seedFromText, releaseDoc, searchAndReplace, applyJson, applyPatchOps, getJson, seedFromJson, readLiveCopy, mutateLiveCopy, seedLiveCopy, } from "./ydoc-manager.js";
 export { searchAndReplaceInYXml, extractTextFromYXml } from "./xml-ops.js";
 export { applyTextToYDoc, initYDocWithText } from "./text-to-yjs.js";
 export { getCollabEmitter, emitCollabUpdate, } from "./emitter.js";

package/dist/collab/live-copy-tasks.d.ts

@@ -0,0 +1,80 @@
+import * as Y from "yjs";
+export declare const LIVE_COPY_TASK: {
+    readonly read: "liveCopy.read";
+    readonly apply: "liveCopy.apply";
+    readonly seed: "liveCopy.seed";
+    readonly edit: "liveCopy.edit";
+};
+export interface LiveCopyTaskRefusal {
+    kind: "refused";
+    reason: string;
+    detail?: string;
+}
+type MaybePromise<T> = T | Promise<T>;
+export interface LiveCopyTaskHandlers {
+    /**
+     * The body's text. Return a refusal for content the text cannot carry;
+     * never drop it. Must not edit `doc`.
+     */
+    derive(doc: Y.Doc, field: string): MaybePromise<string | LiveCopyTaskRefusal>;
+    /** Writes the first content for `source` into `field` of an empty doc. */
+    seed?(doc: Y.Doc, field: string, source: string): MaybePromise<void | LiveCopyTaskRefusal>;
+    /** Server edits by name, run by `mutateLiveCopy`. */
+    edits?: Record<string, (doc: Y.Doc, field: string, input: unknown) => MaybePromise<void | LiveCopyTaskRefusal>>;
+}
+export type LiveCopyTaskFailureCode = "malformed_state" | "unsupported_content" | "state_too_large" | "not_seeded" | "derive_refused" | "derive_failed" | "build_refused" | "build_failed";
+/**
+ * What brings a client up to date without decoding on the request thread:
+ * the state's vector, compared by bytes, and the deletions a client at that
+ * vector may still lack, since deleting never moves a state vector.
+ */
+export interface LiveCopyCatchUp {
+    stateVector: Uint8Array;
+    deletions: Uint8Array;
+}
+export type LiveCopyTaskResult = {
+    kind: "failed";
+    code: LiveCopyTaskFailureCode;
+    reason: string;
+    message: string;
+} | ({
+    kind: "unseeded";
+} & LiveCopyCatchUp) | ({
+    kind: "live";
+    text?: string;
+} & LiveCopyCatchUp) | {
+    kind: "unchanged";
+    text?: string;
+} | ({
+    kind: "changed";
+    state: Uint8Array;
+    text: string;
+    update?: Uint8Array;
+} & LiveCopyCatchUp);
+interface TaskInput {
+    field: string;
+    maxStateBytes: number;
+}
+export interface LiveCopyReadInput extends TaskInput {
+    state: Uint8Array;
+    derive: boolean;
+}
+export interface LiveCopyApplyInput extends TaskInput {
+    state: Uint8Array | null;
+    update: Uint8Array;
+}
+export interface LiveCopySeedInput extends TaskInput {
+    state: Uint8Array | null;
+    source: string;
+}
+export interface LiveCopyEditInput extends TaskInput {
+    state: Uint8Array;
+    edit: string;
+    input: unknown;
+}
+/**
+ * The tasks a live copy's runner must host. Export the result as `tasks`
+ * from the module the runner bundles, alongside any tasks of your own.
+ */
+export declare function defineLiveCopyTasks(handlers: LiveCopyTaskHandlers): Record<string, (input: never) => Promise<LiveCopyTaskResult>>;
+export {};