@tangle-network/agent-runtime 0.161.0 → 0.162.0

package/dist/graph.d.ts

@@ -0,0 +1,241 @@
+import { $l as MakeWorkerAgent, If as DeliverableSpec, bo as SupervisorAgentDeps, mu as WorkerSpawnContext } from "./index-8b0o4dMF.js";
+import { K as Spend, t as Agent } from "./types-DXKDG6DQ.js";
+import { o as ExecutorConfig } from "./runtime-B0FIFwpH.js";
+import { AgentProfile } from "@tangle-network/agent-interface";
+//#region src/runtime/graph/registry.d.ts
+/**
+ * `Registry<T>` — the ONE name→thing shape for the graph engine.
+ *
+ * The kernel grew fourteen of these (agent-runtime#978) that differ in three properties:
+ * whether names can be listed, what a miss does, and whether the table is global. This one
+ * fixes all three — enumerable, a miss is refused BY NAME listing what is registered, and every
+ * registry is per-instance — and it is lifted from `AgentEnvironmentProviderRegistry`, the
+ * richest and best-tested of the fourteen, not invented.
+ *
+ * Entries are addressed by a versioned handle, `<id>/v<n>`, the same way the prompt registry
+ * addresses directives. A graph names a kind by handle; a host registers exact versions; a
+ * missing version is refused, never served by a newer one.
+ */
+/** A versioned name: what a graph writes and what a host registers. */
+interface RegistryHandle {
+  readonly id: string;
+  readonly version: number;
+}
+/** `<id>/v<n>` — the only spelling a handle has on the wire, in a journal, or in an error. */
+declare function formatRegistryHandle(handle: RegistryHandle): string;
+/** Parse the wire spelling back. Refuses anything that is not exactly `<id>/v<n>`. */
+declare function parseRegistryHandle(text: string, context: string): RegistryHandle;
+/** Anything a registry holds carries its own handle, so the table cannot drift from the entry. */
+interface Registered extends RegistryHandle {}
+interface Registry<T extends Registered> {
+  /** Add one entry. A second entry under the same handle is refused unless `replace` is set —
+   *  silently shadowing a registered kind is how a key no caller could produce once survived. */
+  register(entry: T, options?: {
+    readonly replace?: boolean;
+  }): void;
+  has(handle: RegistryHandle): boolean;
+  get(handle: RegistryHandle): T | undefined;
+  /** The entry, or a refusal that names the handle AND lists every registered handle — a miss
+   *  must be diagnosable from its message alone. */
+  require(handle: RegistryHandle, context?: string): T;
+  /** Every registered handle, sorted, as wire spellings. The thing the fourteen predecessors
+   *  mostly could not do and four callers needed. */
+  names(): string[];
+  /** Every entry, in `names()` order. */
+  entries(): T[];
+}
+/**
+ * Create a registry. Per-instance by construction: two engines in one process may hold
+ * different kind sets, a test is hermetic, and a run can print its own table. There is
+ * deliberately no module-level singleton — `builtinShapes` was the one mutable global in the
+ * kernel and it had zero tests.
+ */
+declare function createRegistry<T extends Registered>(label: string, seed?: Iterable<T>): Registry<T>;
+//#endregion
+//#region src/runtime/graph/kind.d.ts
+/** A JSON Schema document as the kernel already spells it: an opaque record, validated by the
+ *  consumer's own validator, published verbatim. */
+type JsonSchema = Readonly<Record<string, unknown>>;
+/**
+ * One declared port on a node. Ports are how a `data` edge binds one node's output to another's
+ * input with a type the compiler can check structurally before any spend. A node has two implicit
+ * output ports beside its declared ones: `out` (its result) and `trace` (its `WorkerTraceEvidence`
+ * by `traceRef`); only an `analyzes` edge may bind `trace`.
+ */
+interface PortSpec {
+  readonly name: string;
+  readonly schema: JsonSchema;
+  readonly description?: string;
+}
+/**
+ * What a kind declares it needs from the host. The engine never imports a host capability; it
+ * knows only that a kind SAID it needs something under this name and the host PROVIDED something
+ * under it. The context a kind receives is narrowed to exactly its declaration — an undeclared
+ * effect is `undefined`, never a service locator.
+ */
+type EffectName = string;
+type EffectContext<Effects extends ReadonlyArray<EffectName>> = Readonly<{ [K in Effects[number]]: unknown; }>;
+/**
+ * What happens to a node that was IN FLIGHT when the process died. A settled node is never a
+ * per-kind choice — it restores from its content-addressed `outRef` on replay. `'restart'` re-runs
+ * from the journaled `inputRef`; `'resume'` is legal only for a kind whose executor can re-attach
+ * to the live process (the bridge backend's session re-attachment is the existing instance).
+ */
+type OnCrash = 'restart' | 'resume';
+/**
+ * Whether a kind's spend enters the conserved pool. `'metered'`: the executor reports `Spend` and
+ * settling without one is an ENGINE ERROR — never "free". `'exempt'`: the whole reservation is
+ * refunded on settle, keeping the node out of Σk by construction (the kernel's `budgetExempt`).
+ */
+type BudgetMode = 'metered' | 'exempt';
+/** The validated declaration every kind provides. `Config` is the per-node config shape;
+ *  `Effects` is the tuple of host capabilities it declares, so the context `run` receives is typed
+ *  to exactly that tuple. */
+interface NodeKind<Config = unknown, Effects extends ReadonlyArray<EffectName> = ReadonlyArray<EffectName>> extends Registered {
+  /** Kind id, e.g. `agent`, `integration.invoke`. With `version`, forms the handle `<id>/v<n>`. */
+  readonly id: string;
+  readonly version: number;
+  readonly description: string;
+  /** Validate and narrow one node's config. Throw `ValidationError` to refuse; the compiler
+   *  surfaces the message with the node id prefixed. */
+  readonly validateConfig: (raw: unknown, context: string) => Config;
+  /** The portable form of `validateConfig`'s accepted shape, for manifests and hosts. */
+  readonly configSchema: JsonSchema;
+  /** Declared input ports; a `data` edge may bind only these. Empty for a source node. */
+  readonly inputs: ReadonlyArray<PortSpec>;
+  /** Declared output ports beside the implicit `out` and `trace`. */
+  readonly outputs: ReadonlyArray<PortSpec>;
+  /** Host capabilities this kind reaches for, by name. The context is narrowed to exactly these. */
+  readonly effects: Effects;
+  readonly onCrash: OnCrash;
+  readonly budget: BudgetMode;
+  /**
+   * Build the agent for one node instance. The kernel spawns it under `Scope.spawn`, so it is
+   * authorized, classified, journaled, pooled and gated like any child — the kind owns only what
+   * the agent DOES. `profile` is the node's pinned profile (an `agent`/`supervisor` kind runs it;
+   * a `script` kind may ignore it); `inputs` are the resolved, content-addressed port values;
+   * `effects` is the narrowed host context; `spawn` is the kernel's per-spawn context when the
+   * kind needs it (a supervisor kind threads it into `nodeContext`).
+   */
+  readonly run: (args: {
+    readonly config: Config;
+    readonly profile: AgentProfile;
+    readonly inputs: Readonly<Record<string, unknown>>;
+    readonly effects: EffectContext<Effects>;
+    readonly spawn?: WorkerSpawnContext;
+  }) => Agent<unknown, unknown>;
+}
+/** Per-node flags a graph author sets; they are node properties, not kinds (agent-runtime#970). */
+interface NodeFlags {
+  /** An oracle — a judge, grader, auditor, trace analyst — may be bound only by an `analyzes`
+   *  edge. The compiler refuses a `delegates` or `data` edge INTO an oracle: an edge to a grader
+   *  leaks the rubric. */
+  readonly oracle?: boolean;
+  /** `script` only: pure over `(config, inputs)` ⇒ budget exempt, output restorable on replay,
+   *  runs in-process. A pure script that settles with a different `outRef` for the same inputs
+   *  has lied, and the first replay mismatch is an engine error. */
+  readonly pure?: boolean;
+}
+/** Validate a kind declaration at registration — so a malformed kind is refused by name once,
+ *  not at the first node that uses it. */
+declare function validateNodeKind(kind: NodeKind, context?: string): NodeKind;
+/** The handle a graph writes to name this kind. */
+declare function kindHandle(kind: Pick<NodeKind, 'id' | 'version'>): RegistryHandle;
+/**
+ * Narrow a host's effect table to exactly what one kind declared. Anything the kind did not
+ * declare is absent — `undefined` on read — so a kind cannot reach past its declaration, and the
+ * engine can list a graph's required effects before spending a token.
+ */
+declare function narrowEffects<Effects extends ReadonlyArray<EffectName>>(declared: Effects, provided: Readonly<Record<string, unknown>>, context: string): EffectContext<Effects>;
+//#endregion
+//#region src/runtime/graph/engine.d.ts
+interface GraphEngineOptions {
+  /** Kinds to register beside the core set. A host adds its own here; nothing is global. */
+  readonly kinds?: ReadonlyArray<NodeKind>;
+  /** The host's effect table, by name. A kind receives only the effects it declared. */
+  readonly effects?: Readonly<Record<EffectName, unknown>>;
+  /** The core set. Injected so a test can substitute, and so the engine never imports a
+   *  backend-specific factory at module load. */
+  readonly coreKinds: ReadonlyArray<NodeKind>;
+}
+interface GraphEngine {
+  readonly kinds: Registry<NodeKind>;
+  readonly effects: Readonly<Record<EffectName, unknown>>;
+  /** Every effect name any registered kind declares — what a host must provide for this engine's
+   *  whole kind set to be runnable. Listed, never discovered mid-run. */
+  requiredEffects(): string[];
+  /** The declared effects no host value covers. Empty means every registered kind is runnable. */
+  missingEffects(): string[];
+}
+/**
+ * Build one engine: a kind registry seeded with the core kinds plus the host's, and the host's
+ * effect values. Every kind is validated by name at construction, so a malformed host kind fails
+ * here, never at its first node.
+ */
+declare function createGraphEngine(options: GraphEngineOptions): GraphEngine;
+//#endregion
+//#region src/runtime/graph/kinds.d.ts
+interface AgentKindConfig {
+  /** Where this node's profile runs. Omit to inherit the engine's default backend. */
+  readonly backend?: ExecutorConfig;
+  /** This node's completion check. Omit to inherit the graph's terminal check. */
+  readonly deliverable?: DeliverableSpec<unknown>;
+}
+/**
+ * One profile, one run: the kernel's leaf, exactly as `supervise()` derives it from `backend`.
+ * The model cannot decide this — it is what gets run.
+ */
+declare function agentKind(defaults: {
+  readonly backend?: ExecutorConfig;
+  readonly deliverable?: DeliverableSpec<unknown>;
+}): NodeKind<AgentKindConfig>;
+interface SupervisorKindConfig {
+  /** Per-child budget reserved from the pool on each spawn this supervisor makes. */
+  readonly perWorker: SupervisorAgentDeps['perWorker'];
+  readonly maxLiveWorkers?: number;
+}
+/**
+ * The thing that DECIDES: a nested `supervisorAgent` with the coordination verbs. Its children
+ * are its own tree — the graph sees one node in, one `Settled` out. A `subgraph` constrains what
+ * it may spawn; without one it is free-form under `profileSecurity` and `allowedModels`.
+ */
+declare function supervisorKind(deps: {
+  readonly blobs: SupervisorAgentDeps['blobs'];
+  readonly makeWorkerAgent: MakeWorkerAgent;
+  readonly router?: SupervisorAgentDeps['router'];
+  readonly driveHarness?: SupervisorAgentDeps['driveHarness'];
+}): NodeKind<SupervisorKindConfig>;
+/** The caller code a `script` node runs. Receives the resolved inputs; returns the output. */
+type ScriptBody = (inputs: Readonly<Record<string, unknown>>, signal: AbortSignal) => Promise<unknown> | unknown;
+interface ScriptKindConfig {
+  readonly body: ScriptBody;
+  /**
+   * `pure: true` is the promise that the output is a function of `(config, inputs)` alone: the
+   * node is then budget-exempt, its output restorable on replay by content address, and it runs
+   * in-process. A pure script that settles with a different `outRef` for the same inputs has
+   * lied, and the first replay mismatch is an engine error.
+   */
+  readonly pure?: boolean;
+  /** For a metered script: what it spent. Omit on a pure script. A metered script that reports
+   *  nothing is metered as NOTHING-KNOWN, never as free. */
+  readonly spent?: Spend;
+}
+/**
+ * Caller code as a node. The one kind with no kernel primitive behind it: the kernel has no
+ * "data→data with no execution" concept (agent-runtime#970 fact-finding), so this is new. It is
+ * still a leaf `Agent` carrying an `Executor`, so the journal, the gate and the pool treat it like
+ * any other node.
+ */
+declare function scriptKind(): NodeKind<ScriptKindConfig>;
+/**
+ * A node carrying its own graph: the constraint on what a supervisor may spawn at depth>1. Its
+ * executor is a nested engine run; that needs the scheduler (#980), so until then this kind is
+ * registered and REFUSES at run time by name rather than being absent — a graph that names it
+ * compiles, and the refusal says exactly what is missing.
+ */
+declare function subgraphKind(): NodeKind<{
+  readonly graph: unknown;
+}>;
+//#endregion
+export { type AgentKindConfig, type BudgetMode, type EffectContext, type EffectName, type GraphEngine, type GraphEngineOptions, type JsonSchema, type NodeFlags, type NodeKind, type OnCrash, type PortSpec, type Registered, type Registry, type RegistryHandle, type ScriptBody, type ScriptKindConfig, type SupervisorKindConfig, agentKind, createGraphEngine, createRegistry, formatRegistryHandle, kindHandle, narrowEffects, parseRegistryHandle, scriptKind, subgraphKind, supervisorKind, validateNodeKind };
+//# sourceMappingURL=graph.d.ts.map

package/dist/graph.js

@@ -0,0 +1,380 @@
+import { m as ValidationError } from "./errors-CDZ8XsVj.js";
+import { x as contentAddress } from "./spawn-journal-oewq1g2h.js";
+import { i as workerFromBackend, s as supervisorAgent } from "./supervise-Di6xvnOL.js";
+//#region src/runtime/graph/kind.ts
+/** Validate a kind declaration at registration — so a malformed kind is refused by name once,
+*  not at the first node that uses it. */
+function validateNodeKind(kind, context = "registerNodeKind") {
+	const who = `${context}: kind ${JSON.stringify(`${kind.id}/v${kind.version}`)}`;
+	if (typeof kind.id !== "string" || kind.id.length === 0) throw new ValidationError(`${context}: a kind must carry a non-empty id`);
+	if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(kind.id)) throw new ValidationError(`${who}: id may contain only letters, digits, ".", "_" and "-"`);
+	if (!Number.isSafeInteger(kind.version) || kind.version < 1) throw new ValidationError(`${who}: version must be a positive integer`);
+	if (typeof kind.description !== "string" || kind.description.trim().length === 0) throw new ValidationError(`${who}: description is required`);
+	if (typeof kind.validateConfig !== "function") throw new ValidationError(`${who}: validateConfig must be a function`);
+	if (!isRecord(kind.configSchema)) throw new ValidationError(`${who}: configSchema must be a JSON Schema object`);
+	for (const [field, ports] of [["inputs", kind.inputs], ["outputs", kind.outputs]]) {
+		if (!Array.isArray(ports)) throw new ValidationError(`${who}: ${field} must be an array`);
+		const seen = /* @__PURE__ */ new Set();
+		for (const port of ports) {
+			if (!port || typeof port.name !== "string" || port.name.length === 0) throw new ValidationError(`${who}: every ${field} port needs a non-empty name`);
+			if (field === "outputs" && (port.name === "out" || port.name === "trace")) throw new ValidationError(`${who}: output port ${JSON.stringify(port.name)} is implicit on every node and cannot be declared`);
+			if (seen.has(port.name)) throw new ValidationError(`${who}: duplicate ${field} port ${JSON.stringify(port.name)}`);
+			seen.add(port.name);
+			if (!isRecord(port.schema)) throw new ValidationError(`${who}: ${field} port ${JSON.stringify(port.name)} needs a JSON Schema`);
+		}
+	}
+	if (!Array.isArray(kind.effects) || kind.effects.some((e) => typeof e !== "string" || e.length === 0)) throw new ValidationError(`${who}: effects must be an array of non-empty names`);
+	if (new Set(kind.effects).size !== kind.effects.length) throw new ValidationError(`${who}: effects must not repeat a name`);
+	if (kind.onCrash !== "restart" && kind.onCrash !== "resume") throw new ValidationError(`${who}: onCrash must be "restart" or "resume"`);
+	if (kind.budget !== "metered" && kind.budget !== "exempt") throw new ValidationError(`${who}: budget must be "metered" or "exempt"`);
+	if (typeof kind.run !== "function") throw new ValidationError(`${who}: run must be a function`);
+	return kind;
+}
+/** The handle a graph writes to name this kind. */
+function kindHandle(kind) {
+	return {
+		id: kind.id,
+		version: kind.version
+	};
+}
+/**
+* Narrow a host's effect table to exactly what one kind declared. Anything the kind did not
+* declare is absent — `undefined` on read — so a kind cannot reach past its declaration, and the
+* engine can list a graph's required effects before spending a token.
+*/
+function narrowEffects(declared, provided, context) {
+	const out = {};
+	const missing = [];
+	for (const name of declared) {
+		if (!(name in provided)) {
+			missing.push(name);
+			continue;
+		}
+		out[name] = provided[name];
+	}
+	if (missing.length > 0) throw new ValidationError(`${context}: host provides no effect for ${missing.map((m) => JSON.stringify(m)).join(", ")}; provided: ${Object.keys(provided).sort().join(", ") || "none"}`);
+	return Object.freeze(out);
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+//#region src/runtime/graph/registry.ts
+/**
+* `Registry<T>` — the ONE name→thing shape for the graph engine.
+*
+* The kernel grew fourteen of these (agent-runtime#978) that differ in three properties:
+* whether names can be listed, what a miss does, and whether the table is global. This one
+* fixes all three — enumerable, a miss is refused BY NAME listing what is registered, and every
+* registry is per-instance — and it is lifted from `AgentEnvironmentProviderRegistry`, the
+* richest and best-tested of the fourteen, not invented.
+*
+* Entries are addressed by a versioned handle, `<id>/v<n>`, the same way the prompt registry
+* addresses directives. A graph names a kind by handle; a host registers exact versions; a
+* missing version is refused, never served by a newer one.
+*/
+/** `<id>/v<n>` — the only spelling a handle has on the wire, in a journal, or in an error. */
+function formatRegistryHandle(handle) {
+	return `${handle.id}/v${handle.version}`;
+}
+/** Parse the wire spelling back. Refuses anything that is not exactly `<id>/v<n>`. */
+function parseRegistryHandle(text, context) {
+	const match = /^([A-Za-z0-9][A-Za-z0-9._-]*)\/v(\d+)$/u.exec(text);
+	if (!match) throw new ValidationError(`${context}: ${JSON.stringify(text)} is not a registry handle; expected "<id>/v<n>"`);
+	const version = Number(match[2]);
+	if (!Number.isSafeInteger(version) || version < 1) throw new ValidationError(`${context}: handle version must be a positive integer`);
+	return {
+		id: match[1],
+		version
+	};
+}
+/**
+* Create a registry. Per-instance by construction: two engines in one process may hold
+* different kind sets, a test is hermetic, and a run can print its own table. There is
+* deliberately no module-level singleton — `builtinShapes` was the one mutable global in the
+* kernel and it had zero tests.
+*/
+function createRegistry(label, seed = []) {
+	const table = /* @__PURE__ */ new Map();
+	const registry = {
+		register(entry, options = {}) {
+			if (typeof entry.id !== "string" || entry.id.length === 0) throw new ValidationError(`${label}: an entry must carry a non-empty id`);
+			if (!Number.isSafeInteger(entry.version) || entry.version < 1) throw new ValidationError(`${label}: ${JSON.stringify(entry.id)} must carry a positive integer version`);
+			const key = formatRegistryHandle(entry);
+			if (!options.replace && table.has(key)) throw new ValidationError(`${label}: ${JSON.stringify(key)} is already registered`);
+			table.set(key, entry);
+		},
+		has(handle) {
+			return table.has(formatRegistryHandle(handle));
+		},
+		get(handle) {
+			return table.get(formatRegistryHandle(handle));
+		},
+		require(handle, context = label) {
+			const key = formatRegistryHandle(handle);
+			const entry = table.get(key);
+			if (entry === void 0) {
+				const known = registry.names();
+				const suffix = known.length > 0 ? `; registered: ${known.join(", ")}` : "; nothing is registered";
+				throw new ValidationError(`${context}: ${JSON.stringify(key)} is not registered${suffix}`);
+			}
+			return entry;
+		},
+		names() {
+			return Array.from(table.keys()).sort();
+		},
+		entries() {
+			return registry.names().map((key) => table.get(key));
+		}
+	};
+	for (const entry of seed) registry.register(entry);
+	return registry;
+}
+//#endregion
+//#region src/runtime/graph/engine.ts
+/**
+* `createGraphEngine` — one engine instance: its kind registry (core kinds pre-registered, host
+* kinds added by the caller), its effect table, and nothing global.
+*
+* The scheduler (#980), journal fold (#981) and the `runGraph` preset (#982) attach here; this
+* file is the part that must exist first so a host can register kinds and a compiler can ask
+* "which effects does this graph need" before a token is spent.
+*/
+/**
+* Build one engine: a kind registry seeded with the core kinds plus the host's, and the host's
+* effect values. Every kind is validated by name at construction, so a malformed host kind fails
+* here, never at its first node.
+*/
+function createGraphEngine(options) {
+	const kinds = createRegistry("graph kinds");
+	for (const kind of options.coreKinds) kinds.register(validateNodeKind(kind, "createGraphEngine"));
+	for (const kind of options.kinds ?? []) kinds.register(validateNodeKind(kind, "createGraphEngine"));
+	const effects = Object.freeze({ ...options.effects ?? {} });
+	if (Object.keys(effects).some((name) => name.length === 0)) throw new ValidationError("createGraphEngine: an effect name must be non-empty");
+	const engine = {
+		kinds,
+		effects,
+		requiredEffects() {
+			const names = /* @__PURE__ */ new Set();
+			for (const kind of kinds.entries()) for (const name of kind.effects) names.add(name);
+			return Array.from(names).sort();
+		},
+		missingEffects() {
+			return engine.requiredEffects().filter((name) => !(name in effects));
+		}
+	};
+	return engine;
+}
+//#endregion
+//#region src/runtime/graph/kinds.ts
+/**
+* One profile, one run: the kernel's leaf, exactly as `supervise()` derives it from `backend`.
+* The model cannot decide this — it is what gets run.
+*/
+function agentKind(defaults) {
+	return {
+		id: "agent",
+		version: 1,
+		description: "One AgentProfile run as a leaf on a backend; the kernel derives the executor.",
+		validateConfig: (raw, context) => {
+			const config = asRecord(raw, `${context}: agent config`);
+			return {
+				...config.backend !== void 0 ? { backend: config.backend } : {},
+				...config.deliverable !== void 0 ? { deliverable: config.deliverable } : {}
+			};
+		},
+		configSchema: {
+			type: "object",
+			properties: {
+				backend: { type: "object" },
+				deliverable: { type: "object" }
+			},
+			additionalProperties: false
+		},
+		inputs: [],
+		outputs: [],
+		effects: [],
+		onCrash: "restart",
+		budget: "metered",
+		run: ({ config, profile, spawn }) => {
+			const backend = config.backend ?? defaults.backend;
+			if (!backend) throw new ValidationError(`agent kind: node ${JSON.stringify(profile.name)} has no backend — set config.backend or the engine default`);
+			return workerFromBackend(backend, config.deliverable ?? defaults.deliverable)(profile, spawn);
+		}
+	};
+}
+/**
+* The thing that DECIDES: a nested `supervisorAgent` with the coordination verbs. Its children
+* are its own tree — the graph sees one node in, one `Settled` out. A `subgraph` constrains what
+* it may spawn; without one it is free-form under `profileSecurity` and `allowedModels`.
+*/
+function supervisorKind(deps) {
+	return {
+		id: "supervisor",
+		version: 1,
+		description: "A nested supervisor: spawns, observes, steers and awaits its own children with the coordination verbs.",
+		validateConfig: (raw, context) => {
+			const config = asRecord(raw, `${context}: supervisor config`);
+			return {
+				perWorker: asRecord(config.perWorker, `${context}: supervisor config.perWorker`),
+				...config.maxLiveWorkers !== void 0 ? { maxLiveWorkers: Number(config.maxLiveWorkers) } : {}
+			};
+		},
+		configSchema: {
+			type: "object",
+			properties: {
+				perWorker: { type: "object" },
+				maxLiveWorkers: { type: "integer" }
+			},
+			required: ["perWorker"],
+			additionalProperties: false
+		},
+		inputs: [],
+		outputs: [],
+		effects: [],
+		onCrash: "restart",
+		budget: "metered",
+		run: ({ config, profile }) => supervisorAgent(profile, {
+			blobs: deps.blobs,
+			makeWorkerAgent: deps.makeWorkerAgent,
+			perWorker: config.perWorker,
+			...config.maxLiveWorkers !== void 0 ? { maxLiveWorkers: config.maxLiveWorkers } : {},
+			...deps.router ? { router: deps.router } : {},
+			...deps.driveHarness ? { driveHarness: deps.driveHarness } : {}
+		})
+	};
+}
+/** The script kind's handle; it also names the kind in every script node's identity. */
+const SCRIPT = {
+	id: "script",
+	version: 1
+};
+/**
+* Caller code as a node. The one kind with no kernel primitive behind it: the kernel has no
+* "data→data with no execution" concept (agent-runtime#970 fact-finding), so this is new. It is
+* still a leaf `Agent` carrying an `Executor`, so the journal, the gate and the pool treat it like
+* any other node.
+*/
+function scriptKind() {
+	return {
+		...SCRIPT,
+		description: "Run caller code over the resolved inputs; pure scripts are exempt and restorable.",
+		validateConfig: (raw, context) => {
+			const config = asRecord(raw, `${context}: script config`);
+			if (typeof config.body !== "function") throw new ValidationError(`${context}: script config.body must be a function`);
+			if (config.pure !== void 0 && typeof config.pure !== "boolean") throw new ValidationError(`${context}: script config.pure must be a boolean`);
+			if (config.pure === true && config.spent !== void 0) throw new ValidationError(`${context}: a pure script is budget-exempt and cannot report spent`);
+			return {
+				body: config.body,
+				...config.pure !== void 0 ? { pure: config.pure } : {},
+				...config.spent !== void 0 ? { spent: config.spent } : {}
+			};
+		},
+		configSchema: {
+			type: "object",
+			properties: {
+				pure: { type: "boolean" },
+				spent: { type: "object" }
+			},
+			additionalProperties: true
+		},
+		inputs: [],
+		outputs: [],
+		effects: [],
+		onCrash: "restart",
+		budget: "metered",
+		run: ({ config, profile, inputs }) => scriptAgent(profile, config, inputs, SCRIPT)
+	};
+}
+function scriptAgent(profile, config, inputs, kind) {
+	let artifact;
+	const spec = {
+		profile,
+		harness: null,
+		executor: {
+			runtime: "inline",
+			...config.pure ? { budgetExempt: true } : {},
+			async execute(_task, signal) {
+				const startedAt = Date.now();
+				const out = await config.body(inputs, signal);
+				const ms = Date.now() - startedAt;
+				const spent = config.pure ? {
+					iterations: 0,
+					tokens: {
+						input: 0,
+						output: 0
+					},
+					usd: 0,
+					ms
+				} : config.spent ?? {
+					iterations: 1,
+					tokens: {
+						input: 0,
+						output: 0,
+						tokensKnown: false
+					},
+					tokensKnown: false,
+					usd: 0,
+					usdKnown: false,
+					ms
+				};
+				artifact = {
+					outRef: contentAddress(out),
+					out,
+					spent
+				};
+				return artifact;
+			},
+			teardown: () => Promise.resolve({ destroyed: true }),
+			resultArtifact() {
+				if (!artifact) throw new ValidationError("script: resultArtifact() read before execute()");
+				return artifact;
+			}
+		},
+		execution: { correlation: { nodeKind: formatRegistryHandle(kind) } }
+	};
+	return {
+		name: profile.name ?? "script",
+		act: () => Promise.reject(new ValidationError("script: act() is not the execution path")),
+		executorSpec: spec
+	};
+}
+/**
+* A node carrying its own graph: the constraint on what a supervisor may spawn at depth>1. Its
+* executor is a nested engine run; that needs the scheduler (#980), so until then this kind is
+* registered and REFUSES at run time by name rather than being absent — a graph that names it
+* compiles, and the refusal says exactly what is missing.
+*/
+function subgraphKind() {
+	return {
+		id: "subgraph",
+		version: 1,
+		description: "A node that runs its own graph; constrains a supervisor at depth>1.",
+		validateConfig: (raw, context) => {
+			const config = asRecord(raw, `${context}: subgraph config`);
+			if (config.graph === void 0) throw new ValidationError(`${context}: subgraph config.graph is required`);
+			return { graph: config.graph };
+		},
+		configSchema: {
+			type: "object",
+			properties: { graph: { type: "object" } },
+			required: ["graph"]
+		},
+		inputs: [],
+		outputs: [],
+		effects: [],
+		onCrash: "restart",
+		budget: "metered",
+		run: ({ profile }) => {
+			throw new ValidationError(`subgraph kind: node ${JSON.stringify(profile.name)} cannot run yet — the scheduler that executes a nested graph lands in agent-runtime#980`);
+		}
+	};
+}
+function asRecord(value, context) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new ValidationError(`${context} must be an object`);
+	return value;
+}
+//#endregion
+export { agentKind, createGraphEngine, createRegistry, formatRegistryHandle, kindHandle, narrowEffects, parseRegistryHandle, scriptKind, subgraphKind, supervisorKind, validateNodeKind };
+
+//# sourceMappingURL=graph.js.map