@tangle-network/agent-runtime 0.168.0 → 0.169.0

package/dist/graph.d.ts

@@ -2,28 +2,6 @@ import { $l as MakeWorkerAgent, Gt as AgentGraph, If as DeliverableSpec, Qt as R
 import { H as SpawnJournal, K as Spend, V as SpawnEvent, i as Budget, j as ResultBlobStore, t as Agent, z as Scope } from "./types-DjVO-p7R.js";
 import { o as ExecutorConfig } from "./runtime-B0HZbuEv.js";
 import { AgentProfile } from "@tangle-network/agent-interface";
-//#region src/runtime/graph/condition.d.ts
-/** The leaf comparison operators; `exists`/`truthy` are unary, the rest compare against `value`. */
-declare const CONDITION_OPS: readonly ["eq", "neq", "gt", "gte", "lt", "lte", "in", "contains", "exists", "truthy"];
-type ConditionOp = (typeof CONDITION_OPS)[number];
-interface ConditionLeaf {
-  /** Dotted path with `[N]` indexing into the guard context, e.g. `out.findings[0].severity`. */
-  readonly path: string;
-  readonly op: ConditionOp;
-  readonly value?: unknown;
-}
-type Condition = ConditionLeaf | {
-  readonly all: ReadonlyArray<Condition>;
-} | {
-  readonly any: ReadonlyArray<Condition>;
-} | {
-  readonly not: Condition;
-};
-/** Validate shape, bounds, and per-leaf path/operator rules; returns the input for chaining. */
-declare function validateCondition(raw: unknown, context: string): Condition;
-/** Walk a validated condition over a context to a boolean. Never throws on data shape. */
-declare function evaluateCondition(condition: Condition, context: unknown): boolean;
-//#endregion
 //#region src/runtime/graph/registry.d.ts
 /**
  * `Registry<T>` — the ONE name→thing shape for the graph engine.
@@ -197,6 +175,97 @@ declare function kindHandle(kind: Pick<NodeKind, 'id' | 'version'>): RegistryHan
  */
 declare function narrowEffects<Effects extends ReadonlyArray<EffectName>>(declared: Effects, provided: Readonly<Record<string, unknown>>, context: string): EffectContext<Effects>;
 //#endregion
+//#region src/runtime/graph/codemode.d.ts
+/** One operation the authored program may call, and the line the model is shown about it. */
+interface CodeOperation {
+  /** Identifier the program calls, e.g. `search`. Must be a valid JS identifier. */
+  readonly name: string;
+  /** The signature and meaning, as the model sees it: `search(query: string): Promise<Hit[]>`. */
+  readonly signature: string;
+  readonly description: string;
+  /** What the call actually does. A spend it reports is added to the node's settlement. */
+  readonly call: (...args: ReadonlyArray<unknown>) => Promise<CodeOperationResult> | CodeOperationResult;
+}
+/** An operation's answer. `spend` is optional; an operation that costs nothing omits it. */
+interface CodeOperationResult {
+  readonly value: unknown;
+  readonly spend?: Spend;
+}
+/** What a host's `codeRunner` effect must do: run authored source with `api` in scope, and answer
+ *  what it returned. The host decides WHERE that happens — in process, or jailed. */
+interface CodeRunner {
+  run(args: {
+    readonly code: string;
+    readonly api: Readonly<Record<string, (...args: ReadonlyArray<unknown>) => Promise<unknown>>>;
+    readonly signal: AbortSignal;
+  }): Promise<unknown>;
+}
+/** What a host's `model` effect must do: answer one prompt with text. */
+interface CodeAuthor {
+  complete(args: {
+    readonly prompt: string;
+    readonly profile: AgentProfile;
+    readonly signal: AbortSignal;
+  }): Promise<{
+    readonly text: string;
+    readonly spend?: Spend;
+  }>;
+}
+interface CodeModeConfig {
+  readonly operations: ReadonlyArray<CodeOperation>;
+  /** What the program must accomplish, in the author's words. Appended to the generated API doc. */
+  readonly task: string;
+  /** Import specifiers the authored code may name. Empty (the default) bans every import. */
+  readonly allowedImports?: ReadonlyArray<string>;
+}
+/**
+ * Refuse the obvious escapes in authored source. A LINT, not a sandbox: it reads text and cannot
+ * constrain what running code does. Generalized from `strategy-author.ts`'s contract check, which
+ * has guarded agent-authored optimization strategies since 0.60.
+ */
+declare function assertAuthoredCode(code: string, options?: {
+  readonly allowedImports?: ReadonlyArray<string>;
+  readonly context?: string;
+}): void;
+/** The API doc the model is shown — generated from the grant, so the two cannot disagree. */
+declare function renderCodeApi(config: CodeModeConfig): string;
+/** Pull the first fenced block out of a model reply; the whole reply if it carries no fence. */
+declare function extractCodeBlock(reply: string): string;
+/**
+ * A node that asks a model for a program and runs it. Declares the two effects it cannot supply
+ * itself — `model` (who writes the code) and `codeRunner` (where it runs) — so the host owns both.
+ */
+declare function codemodeKind(): NodeKind<CodeModeConfig, readonly ['model', 'codeRunner']>;
+/**
+ * An in-process `codeRunner`: builds the authored body as a function with the granted API in
+ * scope. **A development convenience, not a security boundary** — `assertAuthoredCode` is a lint,
+ * and code running in this process can reach whatever the process can. Supply a jailed runner for
+ * code you did not write.
+ */
+declare function inlineCodeRunner(): CodeRunner;
+//#endregion
+//#region src/runtime/graph/condition.d.ts
+/** The leaf comparison operators; `exists`/`truthy` are unary, the rest compare against `value`. */
+declare const CONDITION_OPS: readonly ["eq", "neq", "gt", "gte", "lt", "lte", "in", "contains", "exists", "truthy"];
+type ConditionOp = (typeof CONDITION_OPS)[number];
+interface ConditionLeaf {
+  /** Dotted path with `[N]` indexing into the guard context, e.g. `out.findings[0].severity`. */
+  readonly path: string;
+  readonly op: ConditionOp;
+  readonly value?: unknown;
+}
+type Condition = ConditionLeaf | {
+  readonly all: ReadonlyArray<Condition>;
+} | {
+  readonly any: ReadonlyArray<Condition>;
+} | {
+  readonly not: Condition;
+};
+/** Validate shape, bounds, and per-leaf path/operator rules; returns the input for chaining. */
+declare function validateCondition(raw: unknown, context: string): Condition;
+/** Walk a validated condition over a context to a boolean. Never throws on data shape. */
+declare function evaluateCondition(condition: Condition, context: unknown): boolean;
+//#endregion
 //#region src/runtime/graph/projection.d.ts
 type Projection = {
   readonly path: string;
@@ -729,5 +798,5 @@ declare function runEngineGraph(engine: GraphEngine, spec: EngineGraphSpec | Com
  */
 declare function createGraphRun(engine: GraphEngine, spec: EngineGraphSpec | CompiledGraph, task: string, options: GraphRunOptions): GraphRunHandle;
 //#endregion
-export { type AgentKindConfig, type AnyNodeKind, type BudgetMode, CONDITION_OPS, type CompiledEdge, type CompiledGraph, type CompiledNode, type Condition, type ConditionLeaf, type ConditionOp, DEFAULT_MAX_NODE_VISITS, ENGINE_WOKEN_SEQ_BASE, type EdgeLedger, type EffectContext, type EffectName, type EngineGraphEdge, type EngineGraphNode, type EngineGraphSpec, type FinalizerChoice, type FoldEdge, type FoldEdgeState, type FoldInstance, type FoldInstanceStatus, type FoldNode, type FoldSuspension, type GatingEdge, type GraphEdgeKind, type GraphEdgeTraversal, type GraphEngine, type GraphEngineOptions, type GraphFoldState, type GraphHost, type GraphNodeSettle, type GraphRunContext, type GraphRunHandle, type GraphRunOptions, type GraphRunReason, type GraphRunResult, JOIN_RULES, type JoinDecision, type JoinRule, type JsonSchema, MAX_MAX_NODE_VISITS, type NodeFlags, type NodeKind, type OnCrash, type PortSpec, type Projection, RUN_GRAPH_ROOT_KIND, type Registered, type Registry, type RegistryHandle, type ScriptBody, type ScriptKindConfig, type SubgraphKindConfig, type SupervisorKindConfig, type SuspensionRequest, admitPayload, agentKind, applyGraphFoldEvent, applyProjection, assembleGraphResult, compileGraph, createEdgeLedger, createGraphEngine, createGraphRun, createRegistry, decideJoin, emptyFoldState, evaluateCondition, foldGraphJournal, formatRegistryHandle, graphFromRunGraph, isEngineFired, isSuspensionRequest, kindHandle, materializeSettles, mintSuspensionToken, narrowEffects, openGraphRun, parseRegistryHandle, runEngineGraph, schemaAccepts, scriptKind, subgraphKind, supervisorKind, suspended, suspensionNodeId, tokenFromSuspensionNodeId, validateCondition, validateNodeKind, validateProjection };
+export { type AgentKindConfig, type AnyNodeKind, type BudgetMode, CONDITION_OPS, type CodeAuthor, type CodeModeConfig, type CodeOperation, type CodeOperationResult, type CodeRunner, type CompiledEdge, type CompiledGraph, type CompiledNode, type Condition, type ConditionLeaf, type ConditionOp, DEFAULT_MAX_NODE_VISITS, ENGINE_WOKEN_SEQ_BASE, type EdgeLedger, type EffectContext, type EffectName, type EngineGraphEdge, type EngineGraphNode, type EngineGraphSpec, type FinalizerChoice, type FoldEdge, type FoldEdgeState, type FoldInstance, type FoldInstanceStatus, type FoldNode, type FoldSuspension, type GatingEdge, type GraphEdgeKind, type GraphEdgeTraversal, type GraphEngine, type GraphEngineOptions, type GraphFoldState, type GraphHost, type GraphNodeSettle, type GraphRunContext, type GraphRunHandle, type GraphRunOptions, type GraphRunReason, type GraphRunResult, JOIN_RULES, type JoinDecision, type JoinRule, type JsonSchema, MAX_MAX_NODE_VISITS, type NodeFlags, type NodeKind, type OnCrash, type PortSpec, type Projection, RUN_GRAPH_ROOT_KIND, type Registered, type Registry, type RegistryHandle, type ScriptBody, type ScriptKindConfig, type SubgraphKindConfig, type SupervisorKindConfig, type SuspensionRequest, admitPayload, agentKind, applyGraphFoldEvent, applyProjection, assembleGraphResult, assertAuthoredCode, codemodeKind, compileGraph, createEdgeLedger, createGraphEngine, createGraphRun, createRegistry, decideJoin, emptyFoldState, evaluateCondition, extractCodeBlock, foldGraphJournal, formatRegistryHandle, graphFromRunGraph, inlineCodeRunner, isEngineFired, isSuspensionRequest, kindHandle, materializeSettles, mintSuspensionToken, narrowEffects, openGraphRun, parseRegistryHandle, renderCodeApi, runEngineGraph, schemaAccepts, scriptKind, subgraphKind, supervisorKind, suspended, suspensionNodeId, tokenFromSuspensionNodeId, validateCondition, validateNodeKind, validateProjection };
 //# sourceMappingURL=graph.d.ts.map

package/dist/graph.js

@@ -4,6 +4,188 @@ import { t as addSpend } from "./util-D6ZEuBMi.js";
 import { N as createBudgetPool, U as createExecutorRegistry, a as uncertainSpawnBudgets, i as sumMeasuredSpendFromEvents, l as runFinalizer, o as bestDelivered, p as createScope, r as maxSeqOf, s as collectDelivered } from "./supervisor-B-mmmiOU.js";
 import { i as workerFromBackend, s as supervisorAgent } from "./supervise-rEE46ruH.js";
 import { t as GraphEdgeCapError } from "./graph-ZDMygFIo.js";
+//#region src/runtime/graph/codemode.ts
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/u;
+/**
+* Refuse the obvious escapes in authored source. A LINT, not a sandbox: it reads text and cannot
+* constrain what running code does. Generalized from `strategy-author.ts`'s contract check, which
+* has guarded agent-authored optimization strategies since 0.60.
+*/
+function assertAuthoredCode(code, options = {}) {
+	const context = options.context ?? "authored code";
+	const allowed = options.allowedImports ?? [];
+	for (const line of code.split("\n")) {
+		if (!/^\s*import\s/.test(line)) continue;
+		if (!allowed.some((specifier) => line.includes(`'${specifier}'`) || line.includes(`"${specifier}"`))) throw new ValidationError(`${context} rejected: foreign import — ${line.trim().slice(0, 120)}${allowed.length === 0 ? " (no import is allowed here)" : ` (allowed: ${allowed.join(", ")})`}`);
+	}
+	for (const [pattern, what] of [
+		[/\brequire\s*\(/, "require()"],
+		[/\bimport\s*\(/, "dynamic import()"],
+		[/\beval\s*\(/, "eval()"],
+		[/new\s+Function\s*\(/, "new Function()"],
+		[/\bprocess\s*[.[]/, "process access"],
+		[/\bglobalThis\s*[.[]/, "globalThis access"],
+		[/\bfetch\s*\(/, "network access"],
+		[/child_process|node:fs|node:net|node:http|worker_threads/, "node builtin access"]
+	]) if (pattern.test(code)) throw new ValidationError(`${context} rejected: ${what}`);
+}
+/** The API doc the model is shown — generated from the grant, so the two cannot disagree. */
+function renderCodeApi(config) {
+	return [
+		"Write ONE async function body. It may call only these operations:",
+		"",
+		...config.operations.map((operation) => `  ${operation.signature}\n    // ${operation.description}`),
+		"",
+		"Return the result as the body's return value. No imports, no require, no process, no fetch.",
+		"Reply with a single fenced code block and nothing else.",
+		"",
+		`TASK: ${config.task}`
+	].join("\n");
+}
+/** Pull the first fenced block out of a model reply; the whole reply if it carries no fence. */
+function extractCodeBlock(reply) {
+	const code = (/```(?:[a-zA-Z]*)\n([\s\S]*?)```/u.exec(reply)?.[1] ?? reply).trim();
+	if (code.length === 0) throw new ValidationError("codemode: the model returned no code");
+	return code;
+}
+/**
+* A node that asks a model for a program and runs it. Declares the two effects it cannot supply
+* itself — `model` (who writes the code) and `codeRunner` (where it runs) — so the host owns both.
+*/
+function codemodeKind() {
+	return {
+		id: "codemode",
+		version: 1,
+		description: "Ask a model for a program over a granted API, then run it as one node.",
+		validateConfig: (raw, context) => {
+			if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new ValidationError(`${context}: codemode config must be an object`);
+			const config = raw;
+			if (typeof config.task !== "string" || config.task.trim().length === 0) throw new ValidationError(`${context}: codemode config.task must be a non-empty string`);
+			if (!Array.isArray(config.operations) || config.operations.length === 0) throw new ValidationError(`${context}: codemode config.operations must grant at least one operation`);
+			const seen = /* @__PURE__ */ new Set();
+			for (const operation of config.operations) {
+				if (!IDENTIFIER.test(operation?.name ?? "")) throw new ValidationError(`${context}: operation name ${JSON.stringify(operation?.name)} is not a JS identifier`);
+				if (seen.has(operation.name)) throw new ValidationError(`${context}: duplicate operation ${operation.name}`);
+				seen.add(operation.name);
+				if (typeof operation.call !== "function") throw new ValidationError(`${context}: operation ${operation.name} has no call`);
+			}
+			return {
+				operations: config.operations,
+				task: config.task,
+				...config.allowedImports === void 0 ? {} : { allowedImports: config.allowedImports }
+			};
+		},
+		configSchema: {
+			type: "object",
+			properties: {
+				task: { type: "string" },
+				operations: { type: "array" }
+			},
+			required: ["task", "operations"]
+		},
+		inputs: [{
+			name: "context",
+			schema: {}
+		}],
+		outputs: [],
+		effects: ["model", "codeRunner"],
+		onCrash: "restart",
+		budget: "metered",
+		run: ({ config, profile, inputs, effects }) => {
+			const author = effects.model;
+			const runner = effects.codeRunner;
+			let artifact;
+			return {
+				name: profile.name ?? "codemode",
+				act: () => Promise.reject(new ValidationError("codemode: act() is not the execution path")),
+				executorSpec: {
+					profile,
+					harness: null,
+					executor: {
+						runtime: "inline",
+						async execute(task, signal) {
+							const spends = [];
+							const prompt = [
+								renderCodeApi(config),
+								inputs.context === void 0 ? "" : `\nCONTEXT: ${JSON.stringify(inputs.context)}`,
+								typeof task === "string" && task.length > 0 ? `\n${task}` : ""
+							].filter((part) => part.length > 0).join("\n");
+							const authored = await author.complete({
+								prompt,
+								profile,
+								signal
+							});
+							if (authored.spend) spends.push(authored.spend);
+							const code = extractCodeBlock(authored.text);
+							assertAuthoredCode(code, {
+								...config.allowedImports === void 0 ? {} : { allowedImports: config.allowedImports },
+								context: `codemode ${JSON.stringify(profile.name ?? "node")}`
+							});
+							const api = {};
+							for (const operation of config.operations) api[operation.name] = async (...args) => {
+								const result = await operation.call(...args);
+								if (result?.spend) spends.push(result.spend);
+								return result?.value;
+							};
+							const out = await runner.run({
+								code,
+								api: Object.freeze(api),
+								signal
+							});
+							artifact = {
+								outRef: contentAddress({ codemode: out }),
+								out,
+								spent: totalSpend(spends)
+							};
+							return artifact;
+						},
+						teardown: () => Promise.resolve({ destroyed: true }),
+						resultArtifact: () => {
+							if (!artifact) throw new ValidationError("codemode: resultArtifact() read before execute()");
+							return artifact;
+						}
+					}
+				}
+			};
+		}
+	};
+}
+/** The node's spend is the model call plus every operation that reported one. An operation that
+*  reports nothing is not assumed free — it contributes an UNKNOWN mark, like the kernel's own. */
+function totalSpend(parts) {
+	return parts.reduce((total, part) => ({
+		iterations: total.iterations + (part.iterations ?? 0),
+		tokens: {
+			input: total.tokens.input + (part.tokens?.input ?? 0),
+			output: total.tokens.output + (part.tokens?.output ?? 0),
+			...part.tokens?.tokensKnown === false ? { tokensKnown: false } : {}
+		},
+		usd: total.usd + (part.usd ?? 0),
+		...part.usdKnown === false ? { usdKnown: false } : {},
+		ms: total.ms + (part.ms ?? 0)
+	}), {
+		iterations: 1,
+		tokens: {
+			input: 0,
+			output: 0
+		},
+		usd: 0,
+		ms: 0
+	});
+}
+/**
+* An in-process `codeRunner`: builds the authored body as a function with the granted API in
+* scope. **A development convenience, not a security boundary** — `assertAuthoredCode` is a lint,
+* and code running in this process can reach whatever the process can. Supply a jailed runner for
+* code you did not write.
+*/
+function inlineCodeRunner() {
+	return { async run({ code, api }) {
+		const names = Object.keys(api);
+		return new Function(...names, `"use strict"; return (async () => { ${code} })()`)(...names.map((name) => api[name]));
+	} };
+}
+//#endregion
 //#region src/runtime/graph/condition.ts
 /**
 * The ONE predicate tree: every guard in a graph — an edge `guard`, a filter projection's
@@ -2072,6 +2254,6 @@ async function runGraphLoop(engine, compiled, task, options, wakes, onWakeSignal
 	});
 }
 //#endregion
-export { CONDITION_OPS, DEFAULT_MAX_NODE_VISITS, ENGINE_WOKEN_SEQ_BASE, JOIN_RULES, MAX_MAX_NODE_VISITS, RUN_GRAPH_ROOT_KIND, admitPayload, agentKind, applyGraphFoldEvent, applyProjection, assembleGraphResult, compileGraph, createEdgeLedger, createGraphEngine, createGraphRun, createRegistry, decideJoin, emptyFoldState, evaluateCondition, foldGraphJournal, formatRegistryHandle, graphFromRunGraph, isEngineFired, isSuspensionRequest, kindHandle, materializeSettles, mintSuspensionToken, narrowEffects, openGraphRun, parseRegistryHandle, runEngineGraph, schemaAccepts, scriptKind, subgraphKind, supervisorKind, suspended, suspensionNodeId, tokenFromSuspensionNodeId, validateCondition, validateNodeKind, validateProjection };
+export { CONDITION_OPS, DEFAULT_MAX_NODE_VISITS, ENGINE_WOKEN_SEQ_BASE, JOIN_RULES, MAX_MAX_NODE_VISITS, RUN_GRAPH_ROOT_KIND, admitPayload, agentKind, applyGraphFoldEvent, applyProjection, assembleGraphResult, assertAuthoredCode, codemodeKind, compileGraph, createEdgeLedger, createGraphEngine, createGraphRun, createRegistry, decideJoin, emptyFoldState, evaluateCondition, extractCodeBlock, foldGraphJournal, formatRegistryHandle, graphFromRunGraph, inlineCodeRunner, isEngineFired, isSuspensionRequest, kindHandle, materializeSettles, mintSuspensionToken, narrowEffects, openGraphRun, parseRegistryHandle, renderCodeApi, runEngineGraph, schemaAccepts, scriptKind, subgraphKind, supervisorKind, suspended, suspensionNodeId, tokenFromSuspensionNodeId, validateCondition, validateNodeKind, validateProjection };
 
 //# sourceMappingURL=graph.js.map