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

package/dist/capabilities/flow.js

@@ -0,0 +1,285 @@
+/**
+ * The `flow` capability module — running a registry node from guest code.
+ *
+ * The public "native flow" surface is a typed sandbox pack the guest imports;
+ * this is the host half it lands on. Four capabilities, and nothing else,
+ * cross the boundary:
+ *
+ *   invoke_node       — run a node, return its outputs
+ *   open_node_stream  — start a node, read its output item by item
+ *   take_node_stream  — one item, or {done: true}
+ *   close_node_stream — end it early and run the node's cleanup
+ *
+ * Streaming is cursor-shaped because an async iterable cannot cross the
+ * boundary: only plain data can, so the host holds the iterator and the guest
+ * pulls one item per call.
+ *
+ * Execution is the DSL's own native-flow backend (`@nodetool-ai/dsl/flow`) —
+ * registry resolve, `process()`/`genProcess()`/`run()`, the same fold the
+ * runner applies to terminal outputs. It runs on the **invoking** run's
+ * `ProcessingContext`, so cost, secrets and storage belong to the run that
+ * asked, not to a fresh flow of its own.
+ *
+ * That package is loaded through `importHidden`. A static import would close a
+ * workspace cycle — `@nodetool-ai/dsl` → `base-nodes` → `code-nodes` →
+ * `@nodetool-ai/agents` — which the topological build cannot order. The hidden
+ * import keeps the edge out of the package graph and out of every bundler's
+ * static analysis; a host that cannot resolve the specifier reports that
+ * instead of failing on an unresolved module.
+ *
+ * A Code node body can invoke a flow containing another Code node, so the
+ * depth gate is not optional: `enterFlowInvoke` mirrors `enterJsScript`.
+ */
+import { importHidden } from "@nodetool-ai/config";
+import { invokeNodeSpec, openNodeStreamSpec, takeNodeStreamSpec, closeNodeStreamSpec, MAX_FLOW_INVOKE_DEPTH, MAX_OPEN_NODE_STREAMS } from "./flow.specs.js";
+import { isNonBlankString, isRecord } from "../utils/type-guards.js";
+export { MAX_FLOW_INVOKE_DEPTH, MAX_OPEN_NODE_STREAMS } from "./flow.specs.js";
+/** Context variable carrying how many node invocations deep this run is. */
+export const FLOW_INVOKE_DEPTH_KEY = "__flow_invoke_depth";
+/** Context variable carrying the node types already on the call chain. */
+export const FLOW_INVOKE_CHAIN_KEY = "__flow_invoke_chain";
+const FLOW_MODULE = "@nodetool-ai/dsl/flow";
+let backendPromise = null;
+function loadFlowBackend() {
+    backendPromise ??= importHidden(FLOW_MODULE).catch(() => null);
+    return backendPromise;
+}
+/** Test seam: pin the backend (or `null` to restore the real load). */
+export function setFlowBackend(backend) {
+    backendPromise = backend === null ? null : Promise.resolve(backend);
+}
+async function requireBackend() {
+    const backend = await loadFlowBackend();
+    if (!backend) {
+        throw new Error(`Nodes cannot be invoked in this process: "${FLOW_MODULE}" does not ` +
+            "resolve here.");
+    }
+    return backend;
+}
+/**
+ * Enter one node invocation: refuse past the depth cap, else return a context
+ * copy carrying the deeper chain. The same gate `enterJsScript` applies, over
+ * this feature's own two keys — a node can be a Code node, whose body can
+ * invoke another node, so without it the recursion has no floor.
+ *
+ * Unlike a script chain, a repeated node type is not a cycle: invoking
+ * `nodetool.text.Concat` twice at different depths is ordinary work. Depth is
+ * what bounds this, and the chain rides along so a refusal can say where it
+ * came from.
+ */
+export function enterFlowInvoke(context, nodeType, maxDepth = MAX_FLOW_INVOKE_DEPTH) {
+    const depth = context.get(FLOW_INVOKE_DEPTH_KEY) ?? 0;
+    const chain = context.get(FLOW_INVOKE_CHAIN_KEY) ?? [];
+    if (depth >= maxDepth) {
+        return {
+            ok: false,
+            refusal: {
+                error: "max_flow_invoke_depth_reached",
+                depth,
+                max_depth: maxDepth,
+                chain: [...chain],
+                message: `Cannot invoke ${nodeType} — the node invocation depth limit of ` +
+                    `${maxDepth} is reached (${[...chain, nodeType].join(" → ")}). ` +
+                    "Finish the work at this level instead."
+            }
+        };
+    }
+    const childContext = context.copy();
+    childContext.set(FLOW_INVOKE_DEPTH_KEY, depth + 1);
+    childContext.set(FLOW_INVOKE_CHAIN_KEY, [...chain, nodeType]);
+    return { ok: true, childContext };
+}
+/**
+ * Narrow what the invoked node may read. A list can only take names away from
+ * the invoking run's own reach: the filter delegates to the parent context, so
+ * a name the caller could not read stays unreadable.
+ */
+function narrowSecrets(parent, child, names) {
+    if (!Array.isArray(names))
+        return;
+    const allowed = new Set(names.filter(isNonBlankString));
+    child.setSecretResolver(async (key) => allowed.has(key) ? parent.getSecret(key) : null);
+}
+/**
+ * The stream table lives on the run, not on this module: two runs may hold
+ * ids of the same shape, and neither may reach the other's iterator. It is
+ * weak so a run that is simply dropped takes its table with it, and every
+ * stream is closed when the run's own signal aborts.
+ */
+const STREAMS = new WeakMap();
+function streamTable(run) {
+    const existing = STREAMS.get(run);
+    if (existing)
+        return existing;
+    const table = new Map();
+    STREAMS.set(run, table);
+    run.context.signal?.addEventListener("abort", () => {
+        void closeAllStreams(run);
+    }, { once: true });
+    return table;
+}
+/** Close every stream this run holds. Called when the run is cancelled. */
+export async function closeAllStreams(run) {
+    const table = STREAMS.get(run);
+    if (!table)
+        return;
+    const open = [...table.keys()];
+    table.clear();
+    await Promise.all(open.map((id) => releaseStream({ id, table })));
+}
+/** Every held stream, so the release path is written once. */
+const released = new WeakSet();
+async function release(stream) {
+    if (released.has(stream))
+        return;
+    released.add(stream);
+    // `return()` is what runs the node's own `finally`, which is the whole
+    // reason an early close exists rather than dropping the iterator.
+    await stream.iterator.return?.(undefined).catch(() => { });
+    await stream.flow.close().catch(() => { });
+}
+async function releaseStream(entry) {
+    const stream = entry.stream ?? entry.table.get(entry.id);
+    entry.table.delete(entry.id);
+    if (stream)
+        await release(stream);
+}
+let streamCounter = 0;
+// ---------------------------------------------------------------------------
+// Capabilities
+// ---------------------------------------------------------------------------
+function nodeType(params) {
+    const type = params["type"];
+    if (!isNonBlankString(type)) {
+        throw new Error("type is required — the node type to run, e.g. nodetool.text.Concat.");
+    }
+    return type.trim();
+}
+function nodeInputs(params) {
+    const inputs = params["inputs"];
+    return isRecord(inputs) ? { ...inputs } : {};
+}
+/** The context one invocation runs on, or the gate's refusal. */
+function childContext(run, type, secrets) {
+    const gate = enterFlowInvoke(run.context, type);
+    if (!gate.ok || !gate.childContext) {
+        return { refusal: gate.refusal ?? { error: "flow_invoke_refused" } };
+    }
+    narrowSecrets(run.context, gate.childContext, secrets);
+    return { context: gate.childContext };
+}
+const invokeNode = {
+    spec: invokeNodeSpec,
+    impl: async (run, params) => {
+        const type = nodeType(params);
+        const gated = childContext(run, type, params["secrets"]);
+        if ("refusal" in gated)
+            return gated.refusal;
+        const backend = await requireBackend();
+        const flow = await backend.createFlowForContext(gated.context);
+        try {
+            // The outputs record itself, keyed by handle — the shape the typed
+            // guest pack returns to its caller unchanged.
+            return await backend.invoke(type, nodeInputs(params), { flow });
+        }
+        finally {
+            await flow.close();
+        }
+    }
+};
+const openNodeStream = {
+    spec: openNodeStreamSpec,
+    impl: async (run, params) => {
+        const type = nodeType(params);
+        const table = streamTable(run);
+        if (table.size >= MAX_OPEN_NODE_STREAMS) {
+            return {
+                error: "too_many_open_node_streams",
+                open: table.size,
+                max_open: MAX_OPEN_NODE_STREAMS,
+                message: `Cannot open another node stream — ${MAX_OPEN_NODE_STREAMS} are ` +
+                    "already open. Close one with close_node_stream first."
+            };
+        }
+        // No `secrets` here: the wire shape is {type, inputs}, and a stream reads
+        // the invoking run's own reach unchanged.
+        const gated = childContext(run, type, undefined);
+        if ("refusal" in gated)
+            return gated.refusal;
+        const backend = await requireBackend();
+        const flow = await backend.createFlowForContext(gated.context);
+        const iterator = backend
+            .invokeStream(type, nodeInputs(params), { flow })[Symbol.asyncIterator]();
+        streamCounter += 1;
+        const streamId = `node-stream-${streamCounter}`;
+        table.set(streamId, { iterator, flow, taking: false });
+        return { stream_id: streamId };
+    }
+};
+const takeNodeStream = {
+    spec: takeNodeStreamSpec,
+    impl: async (run, params) => {
+        const table = streamTable(run);
+        const streamId = params["stream_id"];
+        const stream = isNonBlankString(streamId)
+            ? table.get(streamId)
+            : undefined;
+        if (!stream || !isNonBlankString(streamId)) {
+            return {
+                error: "unknown_node_stream",
+                message: `No node stream ${JSON.stringify(streamId)} is open. Open one ` +
+                    "with open_node_stream; a stream that reported done is closed."
+            };
+        }
+        if (stream.taking) {
+            return {
+                error: "node_stream_busy",
+                message: `A take on ${streamId} is already in flight. Await it before ` +
+                    "taking again — one stream serves one reader."
+            };
+        }
+        stream.taking = true;
+        try {
+            const next = await stream.iterator.next();
+            if (next.done === true) {
+                await releaseStream({ id: streamId, table, stream });
+                return { done: true };
+            }
+            return { done: false, value: next.value };
+        }
+        catch (err) {
+            // The node failed. The stream is over either way, so it does not stay
+            // in the table waiting for a close nobody will send.
+            await releaseStream({ id: streamId, table, stream });
+            throw err;
+        }
+        finally {
+            stream.taking = false;
+        }
+    }
+};
+const closeNodeStream = {
+    spec: closeNodeStreamSpec,
+    impl: async (run, params) => {
+        const table = streamTable(run);
+        const streamId = params["stream_id"];
+        if (!isNonBlankString(streamId)) {
+            return { error: "unknown_node_stream", message: "stream_id is required." };
+        }
+        const stream = table.get(streamId);
+        await releaseStream({ id: streamId, table, stream });
+        return { closed: true, was_open: stream !== undefined };
+    }
+};
+export const FLOW_CAPABILITIES = [
+    invokeNode,
+    openNodeStream,
+    takeNodeStream,
+    closeNodeStream
+];
+export const module = {
+    module: "flow",
+    exports: FLOW_CAPABILITIES
+};
+export { invokeNode, openNodeStream, takeNodeStream, closeNodeStream };
+//# sourceMappingURL=flow.js.map

package/dist/capabilities/flow.js.map

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

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

@@ -0,0 +1,25 @@
+/**
+ * The `flow` module's specs — data only, no implementation.
+ *
+ * Split out for the same reason every other module splits: the registry's
+ * eager spec table imports this file and never `flow.ts`, so nothing the
+ * implementation pulls in (the DSL's node registry, six node packs) reaches
+ * the entry graph.
+ */
+import type { CapabilitySpec } from "./types.js";
+import type { JsonSchema } from "@nodetool-ai/runtime";
+/** How deep a chain of guest-invoked nodes may go before it is refused. */
+export declare const MAX_FLOW_INVOKE_DEPTH = 4;
+/** Streams one run may hold open at once. */
+export declare const MAX_OPEN_NODE_STREAMS = 16;
+export declare const INVOKE_NODE_SCHEMA: JsonSchema;
+export declare const OPEN_NODE_STREAM_SCHEMA: JsonSchema;
+export declare const TAKE_NODE_STREAM_SCHEMA: JsonSchema;
+export declare const CLOSE_NODE_STREAM_SCHEMA: JsonSchema;
+export declare const invokeNodeSpec: CapabilitySpec;
+export declare const openNodeStreamSpec: CapabilitySpec;
+export declare const takeNodeStreamSpec: CapabilitySpec;
+export declare const closeNodeStreamSpec: CapabilitySpec;
+/** Every spec this module declares, in declaration order. */
+export declare const flowSpecs: readonly CapabilitySpec[];
+//# sourceMappingURL=flow.specs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flow.specs.d.ts","sourceRoot":"","sources":["../../src/capabilities/flow.specs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,2EAA2E;AAC3E,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,6CAA6C;AAC7C,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAkBxC,eAAO,MAAM,kBAAkB,EAAE,UAchC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,UAIrC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,UASrC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,UAStC,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,cAY5B,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,cAYhC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,cAWhC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,cAQjC,CAAC;AAEF,6DAA6D;AAC7D,eAAO,MAAM,SAAS,EAAE,SAAS,cAAc,EAK9C,CAAC"}

package/dist/capabilities/flow.specs.js

@@ -0,0 +1,114 @@
+/**
+ * The `flow` module's specs — data only, no implementation.
+ *
+ * Split out for the same reason every other module splits: the registry's
+ * eager spec table imports this file and never `flow.ts`, so nothing the
+ * implementation pulls in (the DSL's node registry, six node packs) reaches
+ * the entry graph.
+ */
+/** How deep a chain of guest-invoked nodes may go before it is refused. */
+export const MAX_FLOW_INVOKE_DEPTH = 4;
+/** Streams one run may hold open at once. */
+export const MAX_OPEN_NODE_STREAMS = 16;
+const TYPE_FIELD = {
+    type: "string",
+    description: 'The node type, e.g. "nodetool.text.Concat". Use search_nodes / ' +
+        "get_node_info to find one and read its input and output handles."
+};
+const INPUTS_FIELD = {
+    type: "object",
+    description: "Values for the node's input handles, keyed by handle name. A handle " +
+        "the node reads as a stream also accepts an array, which is fed to it " +
+        "one item at a time; a live guest-produced stream is not supported.",
+    additionalProperties: true
+};
+export const INVOKE_NODE_SCHEMA = {
+    type: "object",
+    properties: {
+        type: TYPE_FIELD,
+        inputs: INPUTS_FIELD,
+        secrets: {
+            type: "array",
+            description: "Secret names this node may read. Omit to leave the invoking run's " +
+                "own reach unchanged; a list can only narrow it, never widen it.",
+            items: { type: "string" }
+        }
+    },
+    required: ["type"]
+};
+export const OPEN_NODE_STREAM_SCHEMA = {
+    type: "object",
+    properties: { type: TYPE_FIELD, inputs: INPUTS_FIELD },
+    required: ["type"]
+};
+export const TAKE_NODE_STREAM_SCHEMA = {
+    type: "object",
+    properties: {
+        stream_id: {
+            type: "string",
+            description: "The id open_node_stream returned."
+        }
+    },
+    required: ["stream_id"]
+};
+export const CLOSE_NODE_STREAM_SCHEMA = {
+    type: "object",
+    properties: {
+        stream_id: {
+            type: "string",
+            description: "The id open_node_stream returned."
+        }
+    },
+    required: ["stream_id"]
+};
+export const invokeNodeSpec = {
+    name: "invoke_node",
+    description: "Run one registry node and return its outputs, keyed by output handle. " +
+        "The node runs on the invoking run's own context, so its cost, secrets " +
+        "and storage are the caller's. A node that yields several records is " +
+        "drained and folded to the last value per handle — use " +
+        "open_node_stream to read the items themselves. An unknown node type " +
+        "is an error, not an empty result.",
+    inputSchema: INVOKE_NODE_SCHEMA,
+    category: "execute",
+    userMessage: (params) => `Running node ${String(params["type"] ?? "")}`
+};
+export const openNodeStreamSpec = {
+    name: "open_node_stream",
+    description: "Start a node and read its output item by item instead of waiting for " +
+        "the whole thing. Returns {stream_id}; read with take_node_stream and " +
+        "always finish with close_node_stream, which runs the node's own " +
+        "cleanup. At most " +
+        String(MAX_OPEN_NODE_STREAMS) +
+        " streams may be open at once.",
+    inputSchema: OPEN_NODE_STREAM_SCHEMA,
+    category: "execute",
+    userMessage: (params) => `Streaming node ${String(params["type"] ?? "")}`
+};
+export const takeNodeStreamSpec = {
+    name: "take_node_stream",
+    description: "Take the next item from an open node stream: {done: true} at the end, " +
+        "else {done: false, value}. `value` is one record of output handles for " +
+        "a generator node, or one {slot, value} emission for a node written " +
+        "against the streaming-input contract. Two takes cannot be in flight on " +
+        "one stream at once.",
+    inputSchema: TAKE_NODE_STREAM_SCHEMA,
+    category: "read",
+    userMessage: () => "Reading a node stream"
+};
+export const closeNodeStreamSpec = {
+    name: "close_node_stream",
+    description: "Close an open node stream and run the node's cleanup. Closing a stream " +
+        "that already ended is not an error.",
+    inputSchema: CLOSE_NODE_STREAM_SCHEMA,
+    category: "read",
+    userMessage: () => "Closing a node stream"
+};
+/** Every spec this module declares, in declaration order. */
+export const flowSpecs = [
+    invokeNodeSpec,
+    openNodeStreamSpec,
+    takeNodeStreamSpec,
+    closeNodeStreamSpec
+];
+//# sourceMappingURL=flow.specs.js.map

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

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

package/dist/capabilities/game-asset-source.d.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { type Workspace } from "@nodetool-ai/runtime";
+import type { CapabilityRun } from "./types.js";
+export declare const GAME_ASSET_NODE_RUNNER_CONTEXT_KEY = "game_asset.run_node";
+export type GameAssetNodeRunner = (args: {
+    readonly node_type: string;
+    readonly inputs: Record<string, unknown>;
+}) => Promise<unknown>;
+export declare const gameGenerationResult: z.ZodObject<{
+    error: z.ZodOptional<z.ZodString>;
+    asset_uri: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodString>;
+    generation_id: z.ZodOptional<z.ZodString>;
+    mime_type: z.ZodOptional<z.ZodString>;
+    background: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const gameModelResult: z.ZodObject<{
+    ref: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodOptional<z.ZodString>;
+        id: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare function readGameAssetInput(run: CapabilityRun, gameWorkspace: Workspace, input: string): Promise<Uint8Array | null>;
+export declare function generateGameSoundEffect(run: CapabilityRun, args: Record<string, unknown>): Promise<{
+    bytes: Uint8Array;
+    mime_type: string;
+} | {
+    error: string;
+    readonly [key: string]: unknown;
+}>;
+//# sourceMappingURL=game-asset-source.d.ts.map

package/dist/capabilities/game-asset-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-asset-source.d.ts","sourceRoot":"","sources":["../../src/capabilities/game-asset-source.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAA2C,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAE/F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,eAAO,MAAM,kCAAkC,wBAAwB,CAAC;AACxE,MAAM,MAAM,mBAAmB,GAAG,CAAC,IAAI,EAAE;IAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEvI,eAAO,MAAM,oBAAoB;;;;;;;iBAO/B,CAAC;AACH,eAAO,MAAM,eAAe;;;;;iBAAyG,CAAC;AAEtI,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,aAAa,EAAE,aAAa,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAWhI;AASD,wBAAsB,uBAAuB,CAAC,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CACvG;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAC9F,CAuCA"}

package/dist/capabilities/game-asset-source.js

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import { loadMediaRefBytes, sniffAudioMimeOrNull } from "@nodetool-ai/runtime";
+import { Asset } from "@nodetool-ai/models";
+export const GAME_ASSET_NODE_RUNNER_CONTEXT_KEY = "game_asset.run_node";
+export const gameGenerationResult = z.object({
+    error: z.string().optional(),
+    asset_uri: z.string().optional(),
+    path: z.string().optional(),
+    generation_id: z.string().optional(),
+    mime_type: z.string().optional(),
+    background: z.boolean().optional()
+});
+export const gameModelResult = z.object({ ref: z.object({ provider: z.string().optional(), id: z.string().optional() }).optional() });
+export async function readGameAssetInput(run, gameWorkspace, input) {
+    if (input.startsWith("asset://")) {
+        const id = input.slice("asset://".length).replace(/\.(png|jpe?g|webp|wav|ogg|mp3|ttf|otf)$/i, "");
+        const owner = run.context.userId;
+        const asset = owner ? await Asset.find(owner, id) : null;
+        return asset ? (await run.context.resolveAssetBytes(`asset://${asset.id}`)).bytes : null;
+    }
+    if (input.includes(":") || input.startsWith("/") || input.split(/[\\/]/).includes("..")) {
+        throw new Error("input_file must be an owned asset URI or workspace-relative path");
+    }
+    return (await run.context.workspace?.read(input)) ?? gameWorkspace.read(input);
+}
+const soundRef = z.object({
+    type: z.literal("audio").optional(),
+    uri: z.string().optional(),
+    asset_id: z.string().optional(),
+    data: z.union([z.instanceof(Uint8Array), z.string()]).optional()
+});
+export async function generateGameSoundEffect(run, args) {
+    const nodeType = args["node_type"];
+    if (typeof nodeType !== "string" || !nodeType.trim()) {
+        return { error: "sfx generation needs node_type and params. Discover an audio generator with search_nodes and get_node_info, or import input_file." };
+    }
+    if (args["background"] === true || args["generation_id"] !== undefined) {
+        return { error: "sfx node generation runs synchronously. Import input_file for a previously generated sound effect." };
+    }
+    const inputs = z.record(z.string(), z.unknown()).safeParse(args["params"] ?? {});
+    if (!inputs.success) {
+        return { error: "params must be an object containing the sound-effect node's inputs" };
+    }
+    const hostRunner = run.context.get?.(GAME_ASSET_NODE_RUNNER_CONTEXT_KEY);
+    const nodeArgs = { node_type: nodeType, inputs: inputs.data };
+    let result;
+    try {
+        result = typeof hostRunner === "function" ? await hostRunner(nodeArgs) : await run.invoke("run_node", nodeArgs);
+    }
+    catch (error) {
+        if (!(error instanceof Error) || error.message !== 'no capability is registered for "run_node"') {
+            throw error;
+        }
+        return { error: "This host has no sound-effect node runner. Generate the sound with run_node in the app and import its asset URI through input_file." };
+    }
+    const envelope = z.record(z.string(), z.unknown()).safeParse(result);
+    if (envelope.success && typeof envelope.data["error"] === "string") {
+        return { ...envelope.data, error: envelope.data["error"] };
+    }
+    const candidates = envelope.success ? [envelope.data["audio"], envelope.data["output"], envelope.data["result"], result] : [result];
+    for (const candidate of candidates) {
+        const parsed = soundRef.safeParse(candidate);
+        if (!parsed.success || !(parsed.data.uri || parsed.data.asset_id || parsed.data.data)) {
+            continue;
+        }
+        const persisted = parsed.data.asset_id
+            ? (await run.context.resolveAssetBytes(`asset://${parsed.data.asset_id}`)).bytes
+            : null;
+        const bytes = persisted ?? await loadMediaRefBytes({ ...parsed.data, type: "audio" }, run.context);
+        if (!bytes) {
+            continue;
+        }
+        const mime = sniffAudioMimeOrNull(bytes);
+        if (!mime || !["audio/wav", "audio/ogg", "audio/mpeg"].includes(mime)) {
+            return { error: "Sound-effect node output must be encoded WAV, Ogg or MP3 audio" };
+        }
+        return { bytes, mime_type: mime };
+    }
+    return { error: "Sound-effect node returned no readable audio ref in audio or output" };
+}
+//# sourceMappingURL=game-asset-source.js.map

package/dist/capabilities/game-asset-source.js.map

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

package/dist/capabilities/game.d.ts

@@ -0,0 +1,12 @@
+import { Game } from "@nodetool-ai/models";
+import { type GameDocument } from "@nodetool-ai/protocol";
+import type { CapabilityModule } from "./types.js";
+/** Shared by explicit game creation and the guided asset workflow builder. */
+export declare function createNativeGame(user: string, projectId: string, name: string, source?: GameDocument): Promise<{
+    game: Game;
+    document: GameDocument;
+} | {
+    error: string;
+}>;
+export declare const module: CapabilityModule;
+//# sourceMappingURL=game.d.ts.map

package/dist/capabilities/game.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game.d.ts","sourceRoot":"","sources":["../../src/capabilities/game.ts"],"names":[],"mappings":"AAIA,OAAO,EAA+B,IAAI,EAAkC,MAAM,qBAAqB,CAAC;AACxG,OAAO,EAAmE,KAAK,YAAY,EAA6C,MAAM,uBAAuB,CAAC;AAKtK,OAAO,KAAK,EAAoB,gBAAgB,EAAiB,MAAM,YAAY,CAAC;AAuVpF,8EAA8E;AAC9E,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,YAAY,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CA4BhL;AAirBD,eAAO,MAAM,MAAM,EAAE,gBAGpB,CAAC"}