@nodetool-ai/agents 0.7.0-rc.22 → 0.8.1

package/dist/capabilities/browser.js

@@ -0,0 +1,250 @@
+/**
+ * The `browser` capability module — driving one real Chrome page.
+ *
+ * These are the `browser_*` actions that used to exist only as `AgentNode`
+ * tool classes, reachable from a workflow graph and nowhere else. As
+ * capabilities they reach every surface the registry serves: the chat agent,
+ * MCP, CodeAct, a Code node, a JS script.
+ *
+ * The page they drive is either a headless Chrome this process launched or —
+ * over the NodeTool Chrome extension's `/ws/extension` relay — the tab the
+ * user is already signed in to, cookies, 2FA and all. Nothing here knows
+ * which: the action loop in `@nodetool-ai/browser` is transport-agnostic, so
+ * the only two capabilities that mention transports at all are
+ * `browser_status`, which reports the one in force, and `browser_restart`,
+ * which changes it.
+ *
+ * Not offered under the cloud profile: the session is one page per server
+ * process, shared by every caller, which is a single-tenant shape. See
+ * `../browser-gate.ts`.
+ *
+ * What this file owns is the half the action package deliberately does not:
+ * the `ProcessingContext`. A screenshot comes back from `@nodetool-ai/browser`
+ * as base64 and leaves here as an asset reference; an upload arrives as an
+ * asset id and reaches the page as bytes. Keeping that split is what lets the
+ * `lib.browser.Screenshot` node share the same action loop without depending
+ * on the agent layer.
+ */
+import { Buffer } from "node:buffer";
+import { browserCaptureMedia, browserClick, browserConsoleExec, browserConsoleView, browserInput, browserMoveMouse, browserNavigate, browserPressKey, browserRestart, browserScroll, browserSelectOption, browserStatus, browserUploadAsset, browserView } from "@nodetool-ai/browser";
+import { BROWSER_DISABLED_ERROR, isBrowserEnabled } from "../browser-gate.js";
+import { persistOutput } from "../tools/asset-persist.js";
+import { browserActionKey, browserCaptureMediaSpec, browserClickSpec, browserConsoleExecSpec, browserConsoleViewSpec, browserInputTextSpec, browserMoveMouseSpec, browserNavigateSpec, browserPressKeySpec, browserRestartSpec, browserScrollSpec, browserSelectOptionSpec, browserStatusSpec, browserUploadAssetSpec, browserViewSpec } from "./browser.specs.js";
+/** Every action key, mapped to what performs it. */
+const ACTIONS = {
+    // SAFETY: each action validates its own input with the Zod schema the
+    // capability's JSON schema was written from, so this is the one place the
+    // untyped tool-call bag becomes a typed input.
+    view: (p) => browserView(p),
+    navigate: (p) => browserNavigate(p),
+    restart: (p) => browserRestart(p),
+    click: (p) => browserClick(p),
+    input_text: (p) => browserInput(p),
+    move_mouse: (p) => browserMoveMouse(p),
+    press_key: (p) => browserPressKey(p),
+    select_option: (p) => browserSelectOption(p),
+    scroll: (p) => browserScroll(p),
+    console_exec: (p) => browserConsoleExec(p),
+    console_view: (p) => browserConsoleView(p),
+    capture_media: (p) => browserCaptureMedia(p),
+    upload_asset: (p) => browserUploadAsset(p)
+};
+/**
+ * Replace a `view` result's raw `screenshot_png_b64` with a proper ImageRef.
+ * When the context exposes `createAsset` the bytes are persisted as an asset
+ * and the ref carries `asset_id` + `asset_uri`; otherwise a workspace file
+ * path is returned. The base64 field is dropped either way, so downstream
+ * consumers see one shape.
+ */
+async function persistViewScreenshot(context, result) {
+    const b64 = result.screenshot_png_b64;
+    const { screenshot_png_b64: _drop, ...rest } = result;
+    if (b64 == null || b64.length === 0) {
+        return { ...rest, screenshot: null };
+    }
+    const saved = await persistOutput(context, new Uint8Array(Buffer.from(b64, "base64")), { namePrefix: "browser-screenshot", mime: "image/png" });
+    return {
+        ...rest,
+        screenshot: {
+            type: "image",
+            asset_id: saved.asset_id,
+            asset_uri: saved.asset_uri,
+            uri: saved.asset_uri ?? saved.path,
+            path: saved.path,
+            mime_type: saved.mime_type,
+            bytes: saved.bytes
+        }
+    };
+}
+/**
+ * Persist a `capture_media` result's bytes and replace them with an AssetRef,
+ * through the same `persistOutput` path screenshots use.
+ */
+async function persistCaptureMedia(context, raw) {
+    if (typeof raw.media_b64 !== "string" || raw.media_b64.length === 0) {
+        // An error object (or already transformed) — pass through unchanged.
+        return raw;
+    }
+    const mime = raw.mime_type || "application/octet-stream";
+    const saved = await persistOutput(context, new Uint8Array(Buffer.from(raw.media_b64, "base64")), { namePrefix: "browser-capture", mime });
+    const kind = mime.startsWith("video/")
+        ? "video"
+        : mime.startsWith("audio/")
+            ? "audio"
+            : "image";
+    return {
+        type: kind,
+        asset_id: saved.asset_id,
+        asset_uri: saved.asset_uri,
+        uri: saved.asset_uri ?? saved.path ?? null,
+        path: saved.path,
+        mime_type: saved.mime_type,
+        bytes: saved.bytes,
+        source_url: raw.source_url ?? null
+    };
+}
+/** Minimal extension → MIME map for naming the injected upload File. */
+const UPLOAD_EXT_TO_MIME = {
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    webp: "image/webp",
+    gif: "image/gif",
+    svg: "image/svg+xml",
+    mp4: "video/mp4",
+    webm: "video/webm",
+    mov: "video/quicktime",
+    mp3: "audio/mpeg",
+    wav: "audio/wav",
+    ogg: "audio/ogg",
+    flac: "audio/flac",
+    pdf: "application/pdf",
+    json: "application/json",
+    txt: "text/plain",
+    csv: "text/csv"
+};
+function extOf(name) {
+    const dot = name.lastIndexOf(".");
+    return dot >= 0 ? name.slice(dot + 1).toLowerCase() : "";
+}
+/**
+ * Resolve an `upload_asset` call into the {@link BrowserUploadAssetRaw} the
+ * action consumes: read the asset's bytes from the context (the same asset-read
+ * path other tools use, covering asset ids, `asset://` uris, and storage/http
+ * URLs) and derive the file name + MIME the website should see.
+ */
+async function resolveUploadParams(context, params) {
+    const assetId = params["asset_id"];
+    const uri = params["uri"];
+    const handle = typeof assetId === "string" && assetId.length > 0
+        ? assetId
+        : typeof uri === "string" && uri.length > 0
+            ? uri
+            : null;
+    if (!handle) {
+        throw new Error("upload_asset requires asset_id or uri");
+    }
+    const { bytes, attempts } = await context.resolveAssetBytes(handle);
+    if (!bytes) {
+        const details = attempts.length > 0 ? ` Attempts: ${attempts.join("; ")}` : "";
+        throw new Error(`Unable to resolve asset '${handle}' to bytes.${details}`);
+    }
+    const explicitName = typeof params["file_name"] === "string" && params["file_name"].length > 0
+        ? params["file_name"]
+        : null;
+    // Derive a name from the handle's last path segment when none was supplied.
+    const fromHandle = handle.split(/[/?#]/).filter(Boolean).pop() ?? "";
+    const fileName = explicitName ?? (extOf(fromHandle) ? fromHandle : "upload.bin");
+    const mimeType = UPLOAD_EXT_TO_MIME[extOf(fileName)] ?? "application/octet-stream";
+    const raw = {
+        file_b64: Buffer.from(bytes).toString("base64"),
+        file_name: fileName,
+        mime_type: mimeType
+    };
+    if (typeof params["index"] === "number")
+        raw.index = params["index"];
+    if (typeof params["coordinate_x"] === "number")
+        raw.coordinate_x = params["coordinate_x"];
+    if (typeof params["coordinate_y"] === "number")
+        raw.coordinate_y = params["coordinate_y"];
+    return raw;
+}
+/**
+ * One capability per action: run it, then give the agent back media it can
+ * refer to rather than base64 it would have to carry.
+ *
+ * Errors come back as `{error}` rather than a throw because a browser action
+ * fails for reasons the model can act on — nobody attached a tab, the element
+ * index is stale, the page navigated away — and an agent that reads the
+ * sentence can retry differently.
+ */
+function action(spec) {
+    const key = browserActionKey(spec.name);
+    const perform = ACTIONS[key];
+    if (perform === undefined) {
+        throw new Error(`no browser action implements "${spec.name}"`);
+    }
+    return {
+        spec,
+        impl: async (run, args) => {
+            // The cloud profile leaves these off every belt, so a model never sees
+            // them. A guest that imports this module by name still lands here.
+            if (!isBrowserEnabled())
+                return { error: BROWSER_DISABLED_ERROR };
+            const { context } = run;
+            try {
+                const params = key === "upload_asset"
+                    ? await resolveUploadParams(context, args)
+                    : args;
+                // SAFETY: `resolveUploadParams` returns the raw shape the upload action
+                // takes; every other action takes the argument bag unchanged.
+                const out = await perform(params);
+                if (key === "view") {
+                    // SAFETY: the `view` entry is `browserView`.
+                    return await persistViewScreenshot(context, out);
+                }
+                if (key === "capture_media") {
+                    // SAFETY: the `capture_media` entry is `browserCaptureMedia`.
+                    return await persistCaptureMedia(context, out);
+                }
+                return out;
+            }
+            catch (err) {
+                return { error: err instanceof Error ? err.message : String(err) };
+            }
+        }
+    };
+}
+const browserStatusCapability = {
+    spec: browserStatusSpec,
+    impl: async () => {
+        if (!isBrowserEnabled())
+            return { error: BROWSER_DISABLED_ERROR };
+        try {
+            return await browserStatus();
+        }
+        catch (err) {
+            return { error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+};
+export const module = {
+    module: "browser",
+    exports: [
+        browserStatusCapability,
+        action(browserViewSpec),
+        action(browserNavigateSpec),
+        action(browserRestartSpec),
+        action(browserClickSpec),
+        action(browserInputTextSpec),
+        action(browserMoveMouseSpec),
+        action(browserPressKeySpec),
+        action(browserSelectOptionSpec),
+        action(browserScrollSpec),
+        action(browserConsoleExecSpec),
+        action(browserConsoleViewSpec),
+        action(browserCaptureMediaSpec),
+        action(browserUploadAssetSpec)
+    ]
+};
+//# sourceMappingURL=browser.js.map

package/dist/capabilities/browser.js.map

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

package/dist/capabilities/browser.specs.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The `browser` module's specs — data only, no implementation.
+ *
+ * These drive one real Chrome page: either a headless one this process
+ * launched, or — through the NodeTool Chrome extension's `/ws/extension`
+ * relay — the tab the user is already signed in to. The action loop is the
+ * same either way, which is why the transport is not a per-action argument:
+ * `browser_status` reports which one is live and `browser_restart` switches it.
+ *
+ * Split out from `browser.ts` for the reason every `.specs.ts` here is: the
+ * registry's eager spec table imports this file, so a belt can be assembled
+ * synchronously without pulling Chrome into the entry graph.
+ */
+import type { CapabilitySpec } from "./types.js";
+/**
+ * The action key behind one capability — `browser_view` runs `view`. The
+ * runner in `@nodetool-ai/automation-nodes` dispatches on it, so the mapping
+ * is a property of the spec rather than a second table to keep in step.
+ */
+export declare function browserActionKey(name: string): string;
+export declare const browserStatusSpec: CapabilitySpec;
+export declare const browserViewSpec: CapabilitySpec;
+export declare const browserNavigateSpec: CapabilitySpec;
+export declare const browserRestartSpec: CapabilitySpec;
+export declare const browserClickSpec: CapabilitySpec;
+export declare const browserInputTextSpec: CapabilitySpec;
+export declare const browserMoveMouseSpec: CapabilitySpec;
+export declare const browserPressKeySpec: CapabilitySpec;
+export declare const browserSelectOptionSpec: CapabilitySpec;
+export declare const browserScrollSpec: CapabilitySpec;
+export declare const browserConsoleExecSpec: CapabilitySpec;
+export declare const browserConsoleViewSpec: CapabilitySpec;
+export declare const browserCaptureMediaSpec: CapabilitySpec;
+export declare const browserUploadAssetSpec: CapabilitySpec;
+/** Every spec this module declares, in declaration order. */
+export declare const browserSpecs: readonly CapabilitySpec[];
+//# sourceMappingURL=browser.specs.d.ts.map

package/dist/capabilities/browser.specs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.specs.d.ts","sourceRoot":"","sources":["../../src/capabilities/browser.specs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAcjD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAyBD,eAAO,MAAM,iBAAiB,gBAY7B,CAAC;AAEF,eAAO,MAAM,eAAe,gBAe3B,CAAC;AAEF,eAAO,MAAM,mBAAmB,gBAiB/B,CAAC;AAEF,eAAO,MAAM,kBAAkB,gBAwB9B,CAAC;AAEF,eAAO,MAAM,gBAAgB,gBAQ5B,CAAC;AAEF,eAAO,MAAM,oBAAoB,gBAYhC,CAAC;AAEF,eAAO,MAAM,oBAAoB,gBAUhC,CAAC;AAEF,eAAO,MAAM,mBAAmB,gBAO/B,CAAC;AAEF,eAAO,MAAM,uBAAuB,gBAWnC,CAAC;AAEF,eAAO,MAAM,iBAAiB,gBAW7B,CAAC;AAEF,eAAO,MAAM,sBAAsB,gBAQlC,CAAC;AAEF,eAAO,MAAM,sBAAsB,gBAOlC,CAAC;AAEF,eAAO,MAAM,uBAAuB,gBA+BnC,CAAC;AAEF,eAAO,MAAM,sBAAsB,gBA4BlC,CAAC;AAEF,6DAA6D;AAC7D,eAAO,MAAM,YAAY,EAAE,SAAS,cAAc,EAejD,CAAC"}

package/dist/capabilities/browser.specs.js

@@ -0,0 +1,173 @@
+/**
+ * The `browser` module's specs — data only, no implementation.
+ *
+ * These drive one real Chrome page: either a headless one this process
+ * launched, or — through the NodeTool Chrome extension's `/ws/extension`
+ * relay — the tab the user is already signed in to. The action loop is the
+ * same either way, which is why the transport is not a per-action argument:
+ * `browser_status` reports which one is live and `browser_restart` switches it.
+ *
+ * Split out from `browser.ts` for the reason every `.specs.ts` here is: the
+ * registry's eager spec table imports this file, so a belt can be assembled
+ * synchronously without pulling Chrome into the entry graph.
+ */
+/** Addressing one element: by index from the last view, or by coordinates. */
+const ELEMENT_REF_PROPS = {
+    index: {
+        type: "integer",
+        description: "Element index from the most recent browser_view call. Required if coordinate_x/y are not provided."
+    },
+    coordinate_x: { type: "integer" },
+    coordinate_y: { type: "integer" }
+};
+/**
+ * The action key behind one capability — `browser_view` runs `view`. The
+ * runner in `@nodetool-ai/automation-nodes` dispatches on it, so the mapping
+ * is a property of the spec rather than a second table to keep in step.
+ */
+export function browserActionKey(name) {
+    return name.slice("browser_".length);
+}
+function spec(key, category, description, properties, required, userMessage) {
+    const inputSchema = required
+        ? { type: "object", properties, required: [...required] }
+        : { type: "object", properties };
+    const built = {
+        name: `browser_${key}`,
+        description,
+        inputSchema,
+        category
+    };
+    if (userMessage) {
+        built.userMessage = userMessage;
+    }
+    return built;
+}
+export const browserStatusSpec = spec("status", "read", "Report the live browser session without opening one: which transport is " +
+    "selected (a headless Chrome this server launched, or the user's own " +
+    "signed-in Chrome behind the NodeTool extension), whether an extension " +
+    "is attached, and where an open session is pointed. Call this before a " +
+    "task that needs the user's logged-in session — an unattached extension " +
+    "otherwise shows up as a 30-second timeout on the first action.", {}, undefined, () => "Checking the browser session");
+export const browserViewSpec = spec("view", "read", "Inspect the current browser page: URL, title, viewport size, indexed " +
+    "interactive elements, and a screenshot. Every click, type and select " +
+    "addresses an element by its index here, and the indexes are rebuilt on " +
+    "each view — so view before you act on an index.", {
+    include_screenshot: {
+        type: "boolean",
+        description: "Capture a PNG of the viewport (defaults to true)."
+    }
+}, undefined, () => "Looking at the browser page");
+export const browserNavigateSpec = spec("navigate", "external", "Navigate the browser to a URL.", {
+    url: { type: "string", description: "Absolute URL to load." },
+    wait_until: {
+        type: "string",
+        enum: ["load", "domcontentloaded", "networkidle"]
+    }
+}, ["url"], (params) => {
+    const url = String(params["url"] ?? "a page");
+    const msg = `Opening ${url}`;
+    return msg.length > 80 ? "Opening a page in the browser" : msg;
+});
+export const browserRestartSpec = spec("restart", "execute", "Restart the browser session and optionally navigate afterwards. Also the " +
+    "one place the transport changes: transport:'extension' drives the " +
+    "user's own signed-in Chrome through the NodeTool extension (they must " +
+    "have clicked 'Attach to this tab'), transport:'local' drives a headless " +
+    "Chrome with no login. Restarting the local transport clears cookies and " +
+    "history; restarting the extension transport only re-attaches the " +
+    "debugger and leaves the user's browser alone.", {
+    url: { type: "string" },
+    transport: {
+        type: "string",
+        enum: ["local", "extension"],
+        description: "Which browser to drive from now on. Omit to keep the current one."
+    }
+}, undefined, (params) => params["transport"] === "extension"
+    ? "Switching to your signed-in Chrome"
+    : "Restarting the browser");
+export const browserClickSpec = spec("click", "external", "Click an interactive element by its index from browser_view, or by " +
+    "viewport coordinates.", { ...ELEMENT_REF_PROPS }, undefined, () => "Clicking in the browser");
+export const browserInputTextSpec = spec("input_text", "external", "Type text into an element identified by index or coordinates. Optionally " +
+    "presses Enter after typing.", {
+    text: { type: "string" },
+    press_enter: { type: "boolean" },
+    ...ELEMENT_REF_PROPS
+}, ["text"], () => "Typing in the browser");
+export const browserMoveMouseSpec = spec("move_mouse", "external", "Move the mouse pointer to viewport coordinates.", {
+    coordinate_x: { type: "integer" },
+    coordinate_y: { type: "integer" }
+}, ["coordinate_x", "coordinate_y"], () => "Moving the mouse");
+export const browserPressKeySpec = spec("press_key", "external", "Press a keyboard key (Enter, Tab, Escape, ArrowDown, single character, etc.).", { key: { type: "string" } }, ["key"], (params) => `Pressing ${String(params["key"] ?? "a key")}`);
+export const browserSelectOptionSpec = spec("select_option", "external", "Select an option in a <select> element identified by its index from " +
+    "browser_view.", {
+    index: { type: "integer" },
+    option: { type: "string" }
+}, ["index", "option"], () => "Choosing an option");
+export const browserScrollSpec = spec("scroll", "external", "Scroll the page to top, bottom, or by a relative pixel amount.", {
+    to_top: { type: "boolean" },
+    to_bottom: { type: "boolean" },
+    pixels: { type: "integer" }
+}, undefined, () => "Scrolling the page");
+export const browserConsoleExecSpec = spec("console_exec", "execute", "Evaluate a JavaScript expression in the page and return the " +
+    "JSON-stringified result.", { javascript: { type: "string" } }, ["javascript"], () => "Running JavaScript in the page");
+export const browserConsoleViewSpec = spec("console_view", "read", "Read recent browser console messages.", { max_lines: { type: "integer" } }, undefined, () => "Reading the browser console");
+export const browserCaptureMediaSpec = spec("capture_media", "external", "Capture generated media (image, video, or audio) from the current page " +
+    "into a NodeTool asset. Address it by element index (a <video>/<audio>/" +
+    "<img> from browser_view), by an absolute or blob: URL, or by a " +
+    "resource_url the page already fetched. Returns an asset reference.", {
+    index: {
+        type: "integer",
+        description: "Element index from the most recent browser_view (a media element)."
+    },
+    url: {
+        type: "string",
+        description: "Absolute or blob: URL of the media to capture."
+    },
+    resource_url: {
+        type: "string",
+        description: "URL of a media resource the page already loaded; captured from the network response when available."
+    },
+    media_type: {
+        type: "string",
+        enum: ["image", "video", "audio"],
+        description: "Optional hint biasing element resolution and the inferred MIME type."
+    }
+}, undefined, () => "Capturing media from the page");
+export const browserUploadAssetSpec = spec("upload_asset", "external", 'Inject an existing NodeTool asset into a page <input type="file"> (file ' +
+    "picker). Address the file input by element index (from browser_view) or " +
+    "viewport coordinates, and name the asset by asset_id or uri. Optionally " +
+    "override the file_name the website sees. Tries a native filesystem " +
+    "injection first and falls back to an in-page DataTransfer injection " +
+    "when the browser runs on a different machine.", {
+    ...ELEMENT_REF_PROPS,
+    asset_id: {
+        type: "string",
+        description: "Id of the NodeTool asset to upload."
+    },
+    uri: {
+        type: "string",
+        description: "asset:// uri (or storage/http URL) of the asset to upload, as an alternative to asset_id."
+    },
+    file_name: {
+        type: "string",
+        description: "Optional file name the website sees; defaults to the asset's name."
+    }
+}, undefined, () => "Uploading a file to the page");
+/** Every spec this module declares, in declaration order. */
+export const browserSpecs = [
+    browserStatusSpec,
+    browserViewSpec,
+    browserNavigateSpec,
+    browserRestartSpec,
+    browserClickSpec,
+    browserInputTextSpec,
+    browserMoveMouseSpec,
+    browserPressKeySpec,
+    browserSelectOptionSpec,
+    browserScrollSpec,
+    browserConsoleExecSpec,
+    browserConsoleViewSpec,
+    browserCaptureMediaSpec,
+    browserUploadAssetSpec
+];
+//# sourceMappingURL=browser.specs.js.map

package/dist/capabilities/browser.specs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.specs.js","sourceRoot":"","sources":["../../src/capabilities/browser.specs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,8EAA8E;AAC9E,MAAM,iBAAiB,GAAG;IACxB,KAAK,EAAE;QACL,IAAI,EAAE,SAAS;QACf,WAAW,EACT,oGAAoG;KACvG;IACD,YAAY,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;IACjC,YAAY,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;CACzB,CAAC;AAEX;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;AACvC,CAAC;AAED,SAAS,IAAI,CACX,GAAW,EACX,QAAoC,EACpC,WAAmB,EACnB,UAAmC,EACnC,QAA4B,EAC5B,WAAyD;IAEzD,MAAM,WAAW,GAAe,QAAQ;QACtC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,GAAG,QAAQ,CAAC,EAAE;QACzD,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;IACnC,MAAM,KAAK,GAAmB;QAC5B,IAAI,EAAE,WAAW,GAAG,EAAE;QACtB,WAAW;QACX,WAAW;QACX,QAAQ;KACT,CAAC;IACF,IAAI,WAAW,EAAE,CAAC;QAChB,KAAK,CAAC,WAAW,GAAG,WAAW,CAAC;IAClC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CACnC,QAAQ,EACR,MAAM,EACN,0EAA0E;IACxE,sEAAsE;IACtE,wEAAwE;IACxE,wEAAwE;IACxE,yEAAyE;IACzE,gEAAgE,EAClE,EAAE,EACF,SAAS,EACT,GAAG,EAAE,CAAC,8BAA8B,CACrC,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CACjC,MAAM,EACN,MAAM,EACN,uEAAuE;IACrE,uEAAuE;IACvE,yEAAyE;IACzE,iDAAiD,EACnD;IACE,kBAAkB,EAAE;QAClB,IAAI,EAAE,SAAS;QACf,WAAW,EAAE,mDAAmD;KACjE;CACF,EACD,SAAS,EACT,GAAG,EAAE,CAAC,6BAA6B,CACpC,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CACrC,UAAU,EACV,UAAU,EACV,gCAAgC,EAChC;IACE,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,uBAAuB,EAAE;IAC7D,UAAU,EAAE;QACV,IAAI,EAAE,QAAQ;QACd,IAAI,EAAE,CAAC,MAAM,EAAE,kBAAkB,EAAE,aAAa,CAAC;KAClD;CACF,EACD,CAAC,KAAK,CAAC,EACP,CAAC,MAAM,EAAE,EAAE;IACT,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,QAAQ,CAAC,CAAC;IAC9C,MAAM,GAAG,GAAG,WAAW,GAAG,EAAE,CAAC;IAC7B,OAAO,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,+BAA+B,CAAC,CAAC,CAAC,GAAG,CAAC;AACjE,CAAC,CACF,CAAC;AAEF,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CACpC,SAAS,EACT,SAAS,EACT,2EAA2E;IACzE,oEAAoE;IACpE,wEAAwE;IACxE,0EAA0E;IAC1E,0EAA0E;IAC1E,mEAAmE;IACnE,+CAA+C,EACjD;IACE,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;IACvB,SAAS,EAAE;QACT,IAAI,EAAE,QAAQ;QACd,IAAI,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC;QAC5B,WAAW,EACT,mEAAmE;KACtE;CACF,EACD,SAAS,EACT,CAAC,MAAM,EAAE,EAAE,CACT,MAAM,CAAC,WAAW,CAAC,KAAK,WAAW;IACjC,CAAC,CAAC,oCAAoC;IACtC,CAAC,CAAC,wBAAwB,CAC/B,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAClC,OAAO,EACP,UAAU,EACV,qEAAqE;IACnE,uBAAuB,EACzB,EAAE,GAAG,iBAAiB,EAAE,EACxB,SAAS,EACT,GAAG,EAAE,CAAC,yBAAyB,CAChC,CAAC;AAEF,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CACtC,YAAY,EACZ,UAAU,EACV,2EAA2E;IACzE,6BAA6B,EAC/B;IACE,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;IACxB,WAAW,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;IAChC,GAAG,iBAAiB;CACrB,EACD,CAAC,MAAM,CAAC,EACR,GAAG,EAAE,CAAC,uBAAuB,CAC9B,CAAC;AAEF,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CACtC,YAAY,EACZ,UAAU,EACV,iDAAiD,EACjD;IACE,YAAY,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;IACjC,YAAY,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;CAClC,EACD,CAAC,cAAc,EAAE,cAAc,CAAC,EAChC,GAAG,EAAE,CAAC,kBAAkB,CACzB,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CACrC,WAAW,EACX,UAAU,EACV,+EAA+E,EAC/E,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAC3B,CAAC,KAAK,CAAC,EACP,CAAC,MAAM,EAAE,EAAE,CAAC,YAAY,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,EAAE,CAC3D,CAAC;AAEF,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,CACzC,eAAe,EACf,UAAU,EACV,sEAAsE;IACpE,eAAe,EACjB;IACE,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;IAC1B,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;CAC3B,EACD,CAAC,OAAO,EAAE,QAAQ,CAAC,EACnB,GAAG,EAAE,CAAC,oBAAoB,CAC3B,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CACnC,QAAQ,EACR,UAAU,EACV,gEAAgE,EAChE;IACE,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;IAC3B,SAAS,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;IAC9B,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;CAC5B,EACD,SAAS,EACT,GAAG,EAAE,CAAC,oBAAoB,CAC3B,CAAC;AAEF,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CACxC,cAAc,EACd,SAAS,EACT,8DAA8D;IAC5D,0BAA0B,EAC5B,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAClC,CAAC,YAAY,CAAC,EACd,GAAG,EAAE,CAAC,gCAAgC,CACvC,CAAC;AAEF,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CACxC,cAAc,EACd,MAAM,EACN,uCAAuC,EACvC,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAClC,SAAS,EACT,GAAG,EAAE,CAAC,6BAA6B,CACpC,CAAC;AAEF,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,CACzC,eAAe,EACf,UAAU,EACV,yEAAyE;IACvE,wEAAwE;IACxE,iEAAiE;IACjE,oEAAoE,EACtE;IACE,KAAK,EAAE;QACL,IAAI,EAAE,SAAS;QACf,WAAW,EACT,oEAAoE;KACvE;IACD,GAAG,EAAE;QACH,IAAI,EAAE,QAAQ;QACd,WAAW,EAAE,gDAAgD;KAC9D;IACD,YAAY,EAAE;QACZ,IAAI,EAAE,QAAQ;QACd,WAAW,EACT,qGAAqG;KACxG;IACD,UAAU,EAAE;QACV,IAAI,EAAE,QAAQ;QACd,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC;QACjC,WAAW,EACT,sEAAsE;KACzE;CACF,EACD,SAAS,EACT,GAAG,EAAE,CAAC,+BAA+B,CACtC,CAAC;AAEF,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CACxC,cAAc,EACd,UAAU,EACV,0EAA0E;IACxE,0EAA0E;IAC1E,0EAA0E;IAC1E,qEAAqE;IACrE,sEAAsE;IACtE,+CAA+C,EACjD;IACE,GAAG,iBAAiB;IACpB,QAAQ,EAAE;QACR,IAAI,EAAE,QAAQ;QACd,WAAW,EAAE,qCAAqC;KACnD;IACD,GAAG,EAAE;QACH,IAAI,EAAE,QAAQ;QACd,WAAW,EACT,2FAA2F;KAC9F;IACD,SAAS,EAAE;QACT,IAAI,EAAE,QAAQ;QACd,WAAW,EACT,oEAAoE;KACvE;CACF,EACD,SAAS,EACT,GAAG,EAAE,CAAC,8BAA8B,CACrC,CAAC;AAEF,6DAA6D;AAC7D,MAAM,CAAC,MAAM,YAAY,GAA8B;IACrD,iBAAiB;IACjB,eAAe;IACf,mBAAmB;IACnB,kBAAkB;IAClB,gBAAgB;IAChB,oBAAoB;IACpB,oBAAoB;IACpB,mBAAmB;IACnB,uBAAuB;IACvB,iBAAiB;IACjB,sBAAsB;IACtB,sBAAsB;IACtB,uBAAuB;IACvB,sBAAsB;CACvB,CAAC"}

package/dist/capabilities/code-grading.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The result shape of one sandboxed body run, and the grading `test_code`
+ * applies to a case list.
+ *
+ * A leaf module so both harnesses grade identically: `test_code` (a body plus
+ * an ad-hoc case list) and `test_js_script` (a saved document's own cases) call
+ * {@link gradeCodeCases} with the same runner. A second copy of the comparison
+ * rules is how the two would silently diverge.
+ */
+/** One `await emit(name, value)` call, in call order. */
+export interface EmittedEntry {
+    name: string;
+    value: unknown;
+}
+/**
+ * What a run streamed: `{name, value}` entries under the emit/output contract,
+ * legacy `yield` bags under the return contract.
+ */
+export type StreamedItems = EmittedEntry[] | Record<string, unknown>[];
+export interface HarnessRunResult {
+    ok: boolean;
+    outputs?: Record<string, unknown>;
+    streamed?: StreamedItems;
+    logs: string[];
+    error?: string;
+    duration_ms: number;
+}
+/** One case as the grader reads it, whatever wire shape it arrived in. */
+export interface GradedCase {
+    name: string;
+    inputs: Record<string, unknown>;
+    /** Expected final value per output handle; unnamed handles are ignored. */
+    expect?: Record<string, unknown>;
+    /** The full ordered list of values the body must emit. */
+    expectedStreamed?: readonly unknown[];
+    /** Pre-staged items per input handle for a body that reads `stream`. */
+    inputStreams?: Record<string, unknown[]>;
+}
+export interface TestCaseReport {
+    name: string;
+    ok: boolean;
+    outputs?: Record<string, unknown>;
+    streamed?: StreamedItems;
+    logs: string[];
+    error?: string;
+    mismatches: {
+        output: string;
+        expected: unknown;
+        actual: unknown;
+    }[];
+}
+export interface CodeTestReport {
+    ok: boolean;
+    passed: number;
+    failed: number;
+    results: TestCaseReport[];
+}
+/** Structural equality by JSON normalization — the values already crossed the sandbox boundary as plain data. */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+/**
+ * Grade a case's expected stream against what the run streamed: the same
+ * entries, in the same order. A length difference is one mismatch on
+ * `streamed`; a differing entry is one mismatch on `streamed[i]`.
+ */
+export declare function streamMismatches(expected: readonly unknown[], actual: StreamedItems): TestCaseReport["mismatches"];
+/** Run every case through `runCase` and grade what came back. */
+export declare function gradeCodeCases(cases: readonly GradedCase[], runCase: (testCase: GradedCase) => Promise<HarnessRunResult>): Promise<CodeTestReport>;
+//# sourceMappingURL=code-grading.d.ts.map

package/dist/capabilities/code-grading.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-grading.d.ts","sourceRoot":"","sources":["../../src/capabilities/code-grading.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,yDAAyD;AACzD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,YAAY,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;AAEvE,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,0EAA0E;AAC1E,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;CACtE;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,iHAAiH;AACjH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,MAAM,EAAE,aAAa,GACpB,cAAc,CAAC,YAAY,CAAC,CAe9B;AAED,iEAAiE;AACjE,wBAAsB,cAAc,CAClC,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,OAAO,EAAE,CAAC,QAAQ,EAAE,UAAU,KAAK,OAAO,CAAC,gBAAgB,CAAC,GAC3D,OAAO,CAAC,cAAc,CAAC,CAyCzB"}

package/dist/capabilities/code-grading.js

@@ -0,0 +1,75 @@
+/**
+ * The result shape of one sandboxed body run, and the grading `test_code`
+ * applies to a case list.
+ *
+ * A leaf module so both harnesses grade identically: `test_code` (a body plus
+ * an ad-hoc case list) and `test_js_script` (a saved document's own cases) call
+ * {@link gradeCodeCases} with the same runner. A second copy of the comparison
+ * rules is how the two would silently diverge.
+ */
+/** Structural equality by JSON normalization — the values already crossed the sandbox boundary as plain data. */
+export function deepEqual(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/**
+ * Grade a case's expected stream against what the run streamed: the same
+ * entries, in the same order. A length difference is one mismatch on
+ * `streamed`; a differing entry is one mismatch on `streamed[i]`.
+ */
+export function streamMismatches(expected, actual) {
+    if (expected.length !== actual.length) {
+        return [{ output: "streamed", expected, actual }];
+    }
+    const mismatches = [];
+    for (let i = 0; i < expected.length; i++) {
+        if (!deepEqual(expected[i], actual[i])) {
+            mismatches.push({
+                output: `streamed[${i}]`,
+                expected: expected[i],
+                actual: actual[i]
+            });
+        }
+    }
+    return mismatches;
+}
+/** Run every case through `runCase` and grade what came back. */
+export async function gradeCodeCases(cases, runCase) {
+    const results = [];
+    for (const testCase of cases) {
+        const outcome = await runCase(testCase);
+        const mismatches = [];
+        if (outcome.ok && testCase.expect) {
+            const actualBag = outcome.outputs ?? {};
+            for (const [key, expected] of Object.entries(testCase.expect)) {
+                const actual = actualBag[key];
+                if (!deepEqual(expected, actual)) {
+                    mismatches.push({ output: key, expected, actual });
+                }
+            }
+        }
+        if (outcome.ok && testCase.expectedStreamed) {
+            mismatches.push(...streamMismatches(testCase.expectedStreamed, outcome.streamed ?? []));
+        }
+        const entry = {
+            name: testCase.name,
+            ok: outcome.ok && mismatches.length === 0,
+            logs: outcome.logs,
+            mismatches
+        };
+        if (outcome.outputs !== undefined)
+            entry.outputs = outcome.outputs;
+        if (outcome.streamed !== undefined)
+            entry.streamed = outcome.streamed;
+        if (outcome.error !== undefined)
+            entry.error = outcome.error;
+        results.push(entry);
+    }
+    const passed = results.filter((entry) => entry.ok).length;
+    return {
+        ok: passed === results.length,
+        passed,
+        failed: results.length - passed,
+        results
+    };
+}
+//# sourceMappingURL=code-grading.js.map

package/dist/capabilities/code-grading.js.map

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