@nodetool-ai/runtime 0.7.0-rc.23 → 0.8.2

package/dist/permission-gate.js

@@ -0,0 +1,87 @@
+/**
+ * The permission gate contract: the mode, the category, the decision matrix,
+ * the approval callback, and the context key a host publishes its gate under.
+ *
+ * It lives here rather than in `@nodetool-ai/agents` because the hosts that
+ * run a workflow (`@nodetool-ai/execution`, the headless job runner) sit
+ * below `agents` in the package graph and still have to set a gate on the
+ * context they build. The ladder that reads the gate, the classification of
+ * tool names, and the loops that gate through it stay in `agents`; this is
+ * only what a host needs to say "this run is headless".
+ *
+ * Design: docs/AGENTS.md § "The permission gate",
+ * packages/agents/AGENTS.md § "Where the permission gate is set".
+ */
+/**
+ * ProcessingContext variable key under which a host publishes the
+ * `PermissionGateOptions` every loop under it must gate through.
+ *
+ * The gate has to reach loops the host never constructs: an `AgentNode` a chat
+ * turn started through `run_node`, a JS script, a sub-agent several levels
+ * down. The context bag is the one channel all of them already carry, and
+ * `ProcessingContext.copy()` shallow-copies it, so a child context shares the
+ * host's gate object rather than a clone — which is what makes
+ * `set_permission_mode` mid-turn reach a node that started before it
+ * (invariant I-1).
+ *
+ * Read it with `gateFromContext` in `@nodetool-ai/agents`, never directly: a
+ * context with no gate on it is a host that forgot to set one, and the answer
+ * there is a gate that denies every call past read, not "ungated".
+ */
+export const PERMISSION_GATE_CONTEXT_KEY = "nodetool_permission_gate";
+/**
+ * The matrix: `read` always runs; in `auto` everything runs; in `plan`
+ * anything actionable is blocked; in `default` actionable calls ask.
+ */
+export function decidePermission(mode, category) {
+    if (category === "read") {
+        return "allow";
+    }
+    if (mode === "auto") {
+        return "allow";
+    }
+    if (mode === "plan") {
+        return "block";
+    }
+    return "ask";
+}
+/**
+ * Why a headless host refuses an escalation, in one sentence naming it.
+ *
+ * Exported because two callers need the same words: the gate reports it when
+ * it denies, and a host that runs headless on purpose (the CLI behind a pipe)
+ * prints it once up front so the user is not left guessing why a later call
+ * was refused.
+ */
+export function headlessDenialReason(hostName) {
+    return (`${hostName} runs without a user to ask, so calls the permission ladder ` +
+        `escalates are denied.`);
+}
+/**
+ * The gate for a host with nobody to ask: `auto`, denying every escalation.
+ *
+ * `decidePermission` allows read, write, execute and external outright in
+ * `auto`, so this approver is reached only by a request the ladder itself
+ * raises — a security-monitor consult, or a category that starts asking in
+ * `auto` later. Denying is the only answer a host with no user can give
+ * honestly: resolving `"allow"` would grant exactly what the escalation was
+ * raised to withhold, and never resolving would hang the run (invariant I-4).
+ *
+ * `hostName` names the caller so the refusal says which host had no one to
+ * ask, rather than only that something was refused.
+ */
+export function headlessGate(hostName) {
+    const reason = headlessDenialReason(hostName);
+    const headlessDeny = async (request) => {
+        // Loud on the refusal (I-4): a denial nobody can see reads as a tool that
+        // silently did nothing.
+        console.warn(`Denied \`${request.toolName}\` without asking: ${reason}`);
+        return "deny";
+    };
+    return {
+        mode: "auto",
+        sessionAllow: new Set(),
+        requestApproval: headlessDeny
+    };
+}
+//# sourceMappingURL=permission-gate.js.map

package/dist/permission-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-gate.js","sourceRoot":"","sources":["../src/permission-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,0BAA0B,CAAC;AActE;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAoB,EACpB,QAA4B;IAE5B,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;QACxB,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAgGD;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAgB;IACnD,OAAO,CACL,GAAG,QAAQ,8DAA8D;QACzE,uBAAuB,CACxB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC3C,MAAM,MAAM,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IAC9C,MAAM,YAAY,GAAoB,KAAK,EAAE,OAAO,EAAE,EAAE;QACtD,0EAA0E;QAC1E,wBAAwB;QACxB,OAAO,CAAC,IAAI,CAAC,YAAY,OAAO,CAAC,QAAQ,sBAAsB,MAAM,EAAE,CAAC,CAAC;QACzE,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;IACF,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,YAAY,EAAE,IAAI,GAAG,EAAU;QAC/B,eAAe,EAAE,YAAY;KAC9B,CAAC;AACJ,CAAC"}

package/dist/prefixed-storage-adapter.d.ts

@@ -0,0 +1,33 @@
+import { type StorageAdapter, type StorageListResult, type StorageStat } from "./context.js";
+/**
+ * A `StorageAdapter` that carves a key prefix out of another one.
+ *
+ * Cloud deployments keep one bucket. Giving each user a workspace inside it
+ * means their keys have to be namespaced, and the namespacing has to be
+ * invisible to whatever holds the adapter — a caller that stores `notes.md`
+ * must read it back as `notes.md`, not as `workspaces/u1/notes.md`. Every key
+ * going in gains the prefix and every key coming out loses it again.
+ *
+ * The prefix is applied to *keys*, never to URIs: a URI is opaque and already
+ * carries the full key, so it passes through untouched.
+ */
+export declare class PrefixedStorageAdapter implements StorageAdapter {
+    private readonly inner;
+    /** Normalized prefix with no trailing slash. */
+    readonly prefix: string;
+    constructor(inner: StorageAdapter, prefix: string);
+    private scope;
+    /** Strip the prefix from a key the inner adapter reported. */
+    private unscope;
+    store(key: string, data: Uint8Array, contentType?: string): Promise<string>;
+    retrieve(uri: string): Promise<Uint8Array | null>;
+    exists(uri: string): Promise<boolean>;
+    uriForKey(key: string): string;
+    list(prefix: string, opts?: {
+        delimiter?: string;
+    }): Promise<StorageListResult>;
+    delete(uri: string): Promise<boolean>;
+    stat(uri: string): Promise<StorageStat | null>;
+    localPath(uri: string): Promise<string | null>;
+}
+//# sourceMappingURL=prefixed-storage-adapter.d.ts.map

package/dist/prefixed-storage-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefixed-storage-adapter.d.ts","sourceRoot":"","sources":["../src/prefixed-storage-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EACjB,MAAM,cAAc,CAAC;AAEtB;;;;;;;;;;;GAWG;AACH,qBAAa,sBAAuB,YAAW,cAAc;IAKzD,OAAO,CAAC,QAAQ,CAAC,KAAK;IAJxB,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,YACmB,KAAK,EAAE,cAAc,EACtC,MAAM,EAAE,MAAM,EAGf;IAED,OAAO,CAAC,KAAK;IAIb,8DAA8D;IAC9D,OAAO,CAAC,OAAO;IAKf,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE1E;IAED,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAEhD;IAED,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAEpC;IAED,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7B;IAEK,IAAI,CACR,MAAM,EAAE,MAAM,EACd,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAChC,OAAO,CAAC,iBAAiB,CAAC,CAe5B;IAED,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAEpC;IAEK,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAKnD;IAED,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAE7C;CACF"}

package/dist/prefixed-storage-adapter.js

@@ -0,0 +1,70 @@
+import { normalizeStorageKey } from "./context.js";
+/**
+ * A `StorageAdapter` that carves a key prefix out of another one.
+ *
+ * Cloud deployments keep one bucket. Giving each user a workspace inside it
+ * means their keys have to be namespaced, and the namespacing has to be
+ * invisible to whatever holds the adapter — a caller that stores `notes.md`
+ * must read it back as `notes.md`, not as `workspaces/u1/notes.md`. Every key
+ * going in gains the prefix and every key coming out loses it again.
+ *
+ * The prefix is applied to *keys*, never to URIs: a URI is opaque and already
+ * carries the full key, so it passes through untouched.
+ */
+export class PrefixedStorageAdapter {
+    inner;
+    /** Normalized prefix with no trailing slash. */
+    prefix;
+    constructor(inner, prefix) {
+        this.inner = inner;
+        this.prefix = normalizeStorageKey(prefix);
+    }
+    scope(key) {
+        return `${this.prefix}/${normalizeStorageKey(key)}`;
+    }
+    /** Strip the prefix from a key the inner adapter reported. */
+    unscope(key) {
+        const head = `${this.prefix}/`;
+        return key.startsWith(head) ? key.slice(head.length) : null;
+    }
+    store(key, data, contentType) {
+        return this.inner.store(this.scope(key), data, contentType);
+    }
+    retrieve(uri) {
+        return this.inner.retrieve(uri);
+    }
+    exists(uri) {
+        return this.inner.exists(uri);
+    }
+    uriForKey(key) {
+        return this.inner.uriForKey(this.scope(key));
+    }
+    async list(prefix, opts = {}) {
+        // An empty prefix means "everything in the workspace", which is the
+        // adapter's own prefix rather than the bucket root.
+        const scoped = prefix ? this.scope(prefix) : this.prefix;
+        const result = await this.inner.list(scoped, opts);
+        const head = `${this.prefix}/`;
+        return {
+            entries: result.entries.flatMap((entry) => {
+                const key = this.unscope(entry.key);
+                return key ? [{ ...entry, key }] : [];
+            }),
+            commonPrefixes: result.commonPrefixes.flatMap((p) => p.startsWith(head) ? [p.slice(head.length)] : [])
+        };
+    }
+    delete(uri) {
+        return this.inner.delete(uri);
+    }
+    async stat(uri) {
+        const st = await this.inner.stat(uri);
+        if (!st)
+            return null;
+        const key = this.unscope(st.key);
+        return key ? { ...st, key } : st;
+    }
+    localPath(uri) {
+        return this.inner.localPath(uri);
+    }
+}
+//# sourceMappingURL=prefixed-storage-adapter.js.map

package/dist/prefixed-storage-adapter.js.map

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

package/dist/prompt-asset-refs.d.ts

@@ -0,0 +1,222 @@
+/**
+ * Inline asset references in prompt text.
+ *
+ * Prompt-style surfaces (the Prompt composer, chat) let users mention an asset
+ * with `@`, which encodes as an `asset://<id>.<ext>` token inside the plain
+ * prompt string. Text-generation tasks expand these tokens into multimodal
+ * image / audio message blocks before the provider call. This module is the
+ * shared, provider-agnostic parser so other task types (e.g. image-to-image)
+ * can pull the same referenced media out of a prompt and route it to a typed
+ * input instead of leaving a dangling `asset://` URI in the text.
+ *
+ * The low-level parsing is resolution-free — callers hand the verbatim
+ * `asset://` URI to {@link loadMediaRefBytes} / `resolveMessageMediaUris`,
+ * which dereference it to bytes / a data URI just before it is consumed. The
+ * higher-level {@link mapPromptAssetsToInputs} does resolve, so provider nodes
+ * (FAL / KIE / Replicate / image-to-image) can route a mentioned image / audio
+ * / video into a typed asset input with bytes already in hand.
+ *
+ * A mentioned plain-text document (`.md`, `.txt`, `.csv`, `.json`, …) has no
+ * typed input to route to — {@link inlineTextAssetRefs} substitutes its decoded
+ * contents into the prompt text in place of the token.
+ */
+import type { AssetInfoEntry, ProcessingContext } from "./context.js";
+import type { MessageContent } from "./providers/types.js";
+export type AssetMediaKind = "image" | "audio" | "video";
+/**
+ * Classify an `asset://<id>.<ext>` token by its extension. Image, audio and
+ * video are provider-consumable media (reference-to-video / lipsync models take
+ * a video clip); everything else (text, unknown) returns null so the reference
+ * is left for the text-inlining pass or kept as literal text in the prompt.
+ */
+export declare function classifyAssetToken(token: string): {
+    kind: AssetMediaKind;
+    mime: string;
+} | null;
+/**
+ * Classify an `asset://<id>.<ext>` token as a plain-text document. Returns null
+ * for non-text tokens (media, folders, unknown) so they are left untouched by
+ * the text-inlining pass.
+ */
+export declare function classifyTextToken(token: string): {
+    mime: string;
+} | null;
+/**
+ * Convert a media / document ref — the `{ type, uri, asset_id, mimeType }` shape
+ * image / audio / video / document outputs carry — into the inline
+ * `asset://<id>.<ext>` token the prompt-expansion machinery understands.
+ *
+ * This lets an asset wired into a Prompt node's `{{ variable }}` flow through
+ * the same path as an inline `@`-mention: once rendered, the token is picked up
+ * by {@link expandAssetReferences} (LLM message blocks), `mapPromptAssetsToInputs`
+ * (typed provider inputs), or {@link inlineTextAssetRefs} (text documents),
+ * instead of stringifying to `"[object Object]"`.
+ *
+ * Returns null for values that aren't asset refs (strings, numbers, plain
+ * objects with no `uri`/`asset_id`) so callers fall back to normal stringify.
+ * A ref pointing only at a non-asset uri (http / data / file) yields that uri
+ * verbatim — it won't route as media, but it still beats `"[object Object]"`.
+ */
+export declare function assetRefToPromptToken(value: unknown): string | null;
+export interface PromptAssetRef {
+    /** Full `asset://<id>.<ext>` token, trailing sentence punctuation trimmed. */
+    uri: string;
+    kind: AssetMediaKind;
+    mime: string;
+    /** Start offset of the token in the source prompt. */
+    index: number;
+    /** Length of the (trimmed) token in the source prompt. */
+    length: number;
+}
+/**
+ * Find every classifiable media reference in a prompt, in source order.
+ *
+ * Unclassifiable tokens (no/unknown extension, e.g. `asset://doc.txt`) are
+ * skipped and remain literal text — text documents are handled separately by
+ * {@link findTextAssetRefs} / {@link inlineTextAssetRefs}.
+ */
+export declare function findAssetRefs(prompt: string): PromptAssetRef[];
+/** A text-document reference found inline in a prompt. */
+export interface TextAssetRef {
+    uri: string;
+    mime: string;
+    index: number;
+    length: number;
+}
+/** Find every plain-text document reference in a prompt, in source order. */
+export declare function findTextAssetRefs(prompt: string): TextAssetRef[];
+/**
+ * Replace each plain-text document mention in `prompt` with the asset's decoded
+ * UTF-8 contents, inline. A mention that can't be resolved to bytes is left as
+ * its literal token (never silently dropped). Media mentions are untouched.
+ */
+export declare function inlineTextAssetRefs(prompt: string, context?: ProcessingContext): Promise<string>;
+/** Convenience: only the image references in a prompt. */
+export declare function findImageAssetRefs(prompt: string): PromptAssetRef[];
+/**
+ * Split a prompt containing inline `asset://<id>.<ext>` references into a
+ * multimodal content array: text segments interleaved with image / audio
+ * blocks that carry the `asset://` URI verbatim. The blocks are NOT resolved
+ * here — {@link ProcessingContext.resolveMessageMediaUris} dereferences the
+ * URIs to data URIs just before the provider call. Tokens that aren't a
+ * supported chat media type (video, unknown) stay as literal text so the
+ * model still sees the mention.
+ */
+export declare function expandAssetReferences(prompt: string): MessageContent[];
+/**
+ * Remove the given references from the prompt, collapsing the horizontal
+ * whitespace left behind so the remaining text reads as a clean instruction.
+ * Refs must come from {@link findAssetRefs} on the same string. Newlines are
+ * preserved.
+ */
+export declare function stripAssetRefs(prompt: string, refs: PromptAssetRef[]): string;
+/** A free-text field whose value should be scanned for asset mentions. */
+export interface PromptAssetTextField {
+    name: string;
+    value: string;
+}
+/** A typed media input the node exposes (image/audio), with its current state. */
+export interface PromptAssetInputField {
+    name: string;
+    /**
+     * Token used to reference this input back in the prompt text once a mention
+     * is routed into it (e.g. the API param name `image_url`). Defaults to
+     * `name`. List inputs are indexed: `${label}[0]`, `${label}[1]`, …
+     */
+    label?: string;
+    kind: AssetMediaKind;
+    /** True for `list[...]` fields that accept multiple refs. */
+    list?: boolean;
+    /** True when the field already holds a real source (wired/set upstream). */
+    hasSource: boolean;
+}
+/** A resolved media ref ready to drop into a node's asset input. */
+export interface InjectedAssetRef {
+    type: AssetMediaKind;
+    /** The original `asset://` URI, kept for provenance / fallback resolution. */
+    uri: string;
+    mimeType: string;
+    /** base64 of the resolved bytes; present when resolution succeeded. */
+    data?: string;
+}
+/**
+ * What entity-mention expansion needs from its caller: owned-asset lookup.
+ * `ProcessingContext` satisfies this structurally; standalone surfaces that
+ * have no context instance (the direct media-generation RPC) supply their own.
+ */
+export interface EntityRefResolver {
+    getAssetInfo(assetId: string): Promise<AssetInfoEntry | null>;
+}
+/**
+ * Expand `entity://<id>` mentions (entities are library assets tagged with a
+ * `nodetool_entity` marker; the `@`-mention pickers encode them as this token).
+ *
+ * Each token is replaced inline with the entity's **name** so the sentence
+ * still reads naturally, and every mentioned entity contributes once to a
+ * trailing `Consistency references:` block carrying its canonical descriptor —
+ * the same shape the Apply Entities node produces. With `includeImageRefs`,
+ * each entity's reference image is appended as an `asset://<id>.<ext>` token so
+ * the normal media-mention machinery routes it into a typed image input.
+ *
+ * Resolution happens here, at generation time, so later edits to an entity's
+ * descriptor or image propagate to every prompt that mentions it. A token that
+ * cannot be resolved (unknown id, no marker, no context) is dropped.
+ */
+export declare function expandEntityRefs(text: string, context: EntityRefResolver | undefined, includeImageRefs: boolean): Promise<string>;
+/** The result of {@link expandEntitiesForGeneration}. */
+export interface ExpandedEntityPrompt {
+    /** The prompt with entity mentions expanded; no `entity://` tokens remain. */
+    prompt: string;
+    /**
+     * Reference images contributed by mentioned entities, as `asset://` refs.
+     * Callers with image inputs resolve these to bytes and pass them alongside
+     * any source image; callers without inputs drop them (the descriptor text
+     * has already been folded into `prompt`).
+     */
+    referenceImages: PromptAssetRef[];
+}
+/**
+ * Expand the entity mentions in a generation prompt and separate what the
+ * provider call needs from it: the seasoned text (names inline + a
+ * Consistency references block) and the entities' reference images as typed
+ * refs — never left in the text as dangling tokens.
+ *
+ * This is the direct-generation counterpart of what node prompts get through
+ * {@link mapPromptAssetsToInputs}: same expansion rule, but returning the
+ * routed images instead of writing them onto node input fields. Image
+ * mentions that were already in the caller's text are left untouched — only
+ * tokens this expansion itself produced are extracted and stripped.
+ */
+export declare function expandEntitiesForGeneration(prompt: string, resolver: EntityRefResolver): Promise<ExpandedEntityPrompt>;
+/**
+ * Map media mentioned inline in a node's text inputs onto its typed media
+ * inputs. This is the generalized form of what text-generation tasks do when
+ * they expand `asset://` references into image / audio message blocks.
+ *
+ * A mention may be a single asset or a folder: folder mentions are expanded
+ * recursively to their member assets first (see {@link expandFolderRefs}), so a
+ * referenced folder fills as many inputs as it can.
+ *
+ * For every media kind the node actually accepts (derived from `assetFields`):
+ *   - mentions of that kind are pulled out of the text inputs, in order;
+ *   - each still-empty input of that kind is filled with the next mention,
+ *     resolved to bytes (`data`) so the provider's normal `data` path uploads
+ *     it — no provider needs to learn the `asset://` scheme;
+ *   - `list[...]` inputs absorb all remaining mentions of their kind;
+ *   - each placed mention is rewritten in the text to the input label it now
+ *     lives in (`image_url`, `reference_image_urls[0]`, …) so the model can
+ *     tell which slot holds which image; mentions that could not be placed
+ *     (an input was already wired, or capacity ran out) are dropped rather
+ *     than left as a dangling URI.
+ *
+ * Plain-text document mentions are inlined into the prompt as their decoded
+ * contents (see {@link inlineTextAssetRefs}). This applies even when the node
+ * has no media inputs at all (e.g. a text-to-image prompt referencing a brief).
+ *
+ * Inputs that already carry a source are left untouched. Returns a flat map of
+ * field name → replacement value (cleaned string for text fields, an
+ * {@link InjectedAssetRef} or array for asset fields); fields that did not
+ * change are absent, so callers do `overrides[name] ?? instance[name]`.
+ */
+export declare function mapPromptAssetsToInputs(textFields: PromptAssetTextField[], assetFields: PromptAssetInputField[], context?: ProcessingContext): Promise<Record<string, unknown>>;
+//# sourceMappingURL=prompt-asset-refs.d.ts.map

package/dist/prompt-asset-refs.d.ts.map

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