@tangle-network/agent-runtime 0.338.0 → 0.340.0

package/dist/{server-DQHJszfk.js → server-DkVBSN_S.js}

@@ -1,13 +1,12 @@
-import { Cn as buildLoopSpanNodes } from "./supervisor-CPG1I9UN.js";
-import { m as ValidationError, t as AgentEvalError } from "./errors-DodWX-cb.js";
-import { Q as fnv1a32Hex, Z as errorMessage } from "./sandbox-profile-compat-xSoVtdWw.js";
-import { r as createStdioToolServer } from "./tool-server-Dqer2M4_.js";
-import { n as delegate } from "./delegate-Se1YZKMb.js";
-import { _ as InMemoryFeedbackStore, c as DELEGATION_HISTORY_TOOL_NAME, f as DELEGATE_FEEDBACK_DESCRIPTION, h as createDelegateFeedbackHandler, i as createDelegationStatusHandler, l as createDelegationHistoryHandler, m as DELEGATE_FEEDBACK_TOOL_NAME, n as DELEGATION_STATUS_INPUT_SCHEMA, o as DELEGATION_HISTORY_DESCRIPTION, p as DELEGATE_FEEDBACK_INPUT_SCHEMA, r as DELEGATION_STATUS_TOOL_NAME, s as DELEGATION_HISTORY_INPUT_SCHEMA, t as DELEGATION_STATUS_DESCRIPTION } from "./delegation-status-CF4D0NZ_.js";
-import { n as UI_LENSES } from "./substrate-B0TYNrXn.js";
+import { an as buildLoopSpanNodes } from "./supervisor-VXuN2OHT.js";
+import { m as ValidationError, o as NotFoundError, t as AgentEvalError } from "./errors-DodWX-cb.js";
+import { X as errorMessage, Z as fnv1a32Hex } from "./sandbox-profile-compat-DRr3JwDx.js";
+import { n as createStdioToolServer } from "./tool-server-XV4aJwoQ.js";
+import { n as delegate } from "./delegate-CtJIS-tp.js";
+import { t as UI_LENSES } from "./substrate-CGDFTSRh.js";
 import path, { dirname } from "node:path";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
-import { Readable, Writable } from "node:stream";
+import "node:stream";
 //#region src/mcp/delegation-trace.ts
 /**
 *
@@ -60,8 +59,8 @@ function buildDelegationTraceSpans(events) {
 * @experimental
 */
 function capDelegationTrace(spans, caps) {
-	const maxSpans = caps?.maxSpans ?? 512;
-	const maxBytes = caps?.maxBytes ?? 262144;
+	const maxSpans = caps?.maxSpans ?? DELEGATION_TRACE_MAX_SPANS;
+	const maxBytes = caps?.maxBytes ?? DELEGATION_TRACE_MAX_BYTES;
 	let start = Math.max(0, spans.length - maxSpans);
 	const sizes = spans.map((span) => JSON.stringify(span).length + 1);
 	let total = 0;
@@ -306,6 +305,38 @@ function cloneRecord(record) {
 	return structuredClone(record);
 }
 //#endregion
+//#region src/mcp/feedback-store.ts
+/** In-memory `FeedbackStore` — suitable for single-process use and tests. @stable */
+var InMemoryFeedbackStore = class {
+	events = [];
+	async put(event) {
+		this.events.push({ ...event });
+	}
+	async list(filter = {}) {
+		let out = this.events;
+		if (filter.namespace !== void 0) out = out.filter((event) => event.namespace === filter.namespace);
+		if (filter.refersToRef !== void 0) out = out.filter((event) => event.refersTo.ref === filter.refersToRef);
+		return out.map((event) => ({ ...event }));
+	}
+};
+/**
+* Project a `FeedbackEvent` down to the snapshot shape carried on
+* `delegation_history` entries.
+*
+* @stable
+*/
+function eventToSnapshot(event) {
+	const snap = {
+		id: event.id,
+		score: event.rating.score,
+		by: event.by,
+		notes: event.rating.notes,
+		capturedAt: event.capturedAt
+	};
+	if (event.rating.label) snap.label = event.rating.label;
+	return snap;
+}
+//#endregion
 //#region src/mcp/task-queue.ts
 /**
 *
@@ -917,6 +948,169 @@ function createDelegateHandler(options) {
 	};
 }
 //#endregion
+//#region src/mcp/tools/delegate-feedback.ts
+/** MCP tool name for the `delegate_feedback` feedback-recording tool. @stable */
+const DELEGATE_FEEDBACK_TOOL_NAME = "delegate_feedback";
+/** Human-readable description of the `delegate_feedback` MCP tool, injected into the tool manifest. @stable */
+const DELEGATE_FEEDBACK_DESCRIPTION = [
+	"Record feedback on a delegation, artifact, or outcome. Synchronous — the",
+	"event is durably stored when this call returns.",
+	"",
+	"Use when: you (the agent), the user, or a downstream judge has formed an",
+	"opinion about a piece of work and want it persisted for calibration,",
+	"pricing, or future routing. Every call is a new event — multiple ratings",
+	"on the same target are expected and never deduped.",
+	"",
+	"`refersTo.kind`:",
+	"  - \"delegation\": ref is a taskId returned by delegate_ui_audit",
+	"  - \"artifact\":   ref is a URI/path/git-sha — anything you can dereference",
+	"  - \"outcome\":    ref is a free-form description of a downstream result",
+	"",
+	"`by`:",
+	"  - \"agent\":            the agent itself rated the work",
+	"  - \"user\":             the human user rated it",
+	"  - \"downstream-judge\": an automated evaluator emitted the rating",
+	"",
+	"When ref names a known taskId, the rating is also attached to the",
+	"delegation record so delegation_history surfaces it inline."
+].join("\n");
+/** JSON Schema for `delegate_feedback` tool arguments (`refersTo`, `rating`, `by`, optional fields). @stable */
+const DELEGATE_FEEDBACK_INPUT_SCHEMA = {
+	type: "object",
+	properties: {
+		refersTo: {
+			type: "object",
+			properties: {
+				kind: {
+					type: "string",
+					enum: [
+						"delegation",
+						"artifact",
+						"outcome"
+					]
+				},
+				ref: { type: "string" }
+			},
+			required: ["kind", "ref"],
+			additionalProperties: false
+		},
+		rating: {
+			type: "object",
+			properties: {
+				score: {
+					type: "number",
+					minimum: 0,
+					maximum: 1
+				},
+				label: {
+					type: "string",
+					enum: [
+						"good",
+						"bad",
+						"neutral",
+						"mixed"
+					]
+				},
+				notes: { type: "string" }
+			},
+			required: ["score", "notes"],
+			additionalProperties: false
+		},
+		by: {
+			type: "string",
+			enum: [
+				"agent",
+				"user",
+				"downstream-judge"
+			]
+		},
+		capturedAt: { type: "string" },
+		namespace: { type: "string" }
+	},
+	required: [
+		"refersTo",
+		"rating",
+		"by"
+	],
+	additionalProperties: false
+};
+/** Parse and validate raw MCP tool input into typed `DelegateFeedbackArgs`; throws `TypeError` on bad input. @stable */
+function validateDelegateFeedbackArgs(raw) {
+	if (raw === null || typeof raw !== "object") throw new TypeError("delegate_feedback: arguments must be an object");
+	const value = raw;
+	const refersTo = validateRefersTo(value.refersTo);
+	const rating = validateRating(value.rating);
+	const by = value.by;
+	if (by !== "agent" && by !== "user" && by !== "downstream-judge") throw new TypeError("delegate_feedback: `by` must be one of \"agent\" | \"user\" | \"downstream-judge\"");
+	const args = {
+		refersTo,
+		rating,
+		by
+	};
+	if (value.capturedAt !== void 0) {
+		if (typeof value.capturedAt !== "string" || Number.isNaN(Date.parse(value.capturedAt))) throw new TypeError("delegate_feedback: `capturedAt` must be an ISO datetime");
+		args.capturedAt = value.capturedAt;
+	}
+	if (typeof value.namespace === "string") args.namespace = value.namespace;
+	return args;
+}
+function validateRefersTo(raw) {
+	if (raw === null || typeof raw !== "object") throw new TypeError("delegate_feedback: `refersTo` must be an object");
+	const value = raw;
+	const kind = value.kind;
+	if (kind !== "delegation" && kind !== "artifact" && kind !== "outcome") throw new TypeError("delegate_feedback: `refersTo.kind` must be one of \"delegation\" | \"artifact\" | \"outcome\"");
+	const ref = value.ref;
+	if (typeof ref !== "string" || ref.trim().length === 0) throw new TypeError("delegate_feedback: `refersTo.ref` must be a non-empty string");
+	return {
+		kind,
+		ref: ref.trim()
+	};
+}
+function validateRating(raw) {
+	if (raw === null || typeof raw !== "object") throw new TypeError("delegate_feedback: `rating` must be an object");
+	const value = raw;
+	const score = Number(value.score);
+	if (!Number.isFinite(score) || score < 0 || score > 1) throw new RangeError("delegate_feedback: `rating.score` must be a number in [0, 1]");
+	const notes = value.notes;
+	if (typeof notes !== "string") throw new TypeError("delegate_feedback: `rating.notes` must be a string");
+	const rating = {
+		score,
+		notes
+	};
+	const label = value.label;
+	if (label !== void 0) {
+		if (label !== "good" && label !== "bad" && label !== "neutral" && label !== "mixed") throw new TypeError("delegate_feedback: `rating.label` must be one of \"good\" | \"bad\" | \"neutral\" | \"mixed\"");
+		rating.label = label;
+	}
+	return rating;
+}
+/** Build the MCP tool handler that persists feedback events and attaches them to delegation records. @stable */
+function createDelegateFeedbackHandler(options) {
+	const generateId = options.generateId ?? randomFeedbackId;
+	const now = options.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+	return async (raw) => {
+		const args = validateDelegateFeedbackArgs(raw);
+		const id = generateId();
+		const event = {
+			id,
+			refersTo: args.refersTo,
+			rating: args.rating,
+			by: args.by,
+			capturedAt: args.capturedAt ?? now(),
+			namespace: args.namespace
+		};
+		await options.store.put(event);
+		if (args.refersTo.kind === "delegation") options.queue.attachFeedback(args.refersTo.ref, eventToSnapshot(event));
+		return {
+			recorded: true,
+			id
+		};
+	};
+}
+function randomFeedbackId() {
+	return `fbk-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+//#endregion
 //#region src/mcp/tools/delegate-ui-audit.ts
 /**
 *
@@ -1172,28 +1366,166 @@ function defaultEstimate(args) {
 	return PER_LENS_PER_ROUTE_ESTIMATE_MS * lenses * routes;
 }
 //#endregion
-//#region src/mcp/server.ts
+//#region src/mcp/types.ts
+/**
+* Every delegation profile a queued record can carry. One owner: the tool schemas and validators
+* that filter on a profile read this list, so a profile added here cannot be one a tool refuses.
+* @experimental
+*/
+const delegationProfiles = [
+	"coder",
+	"researcher",
+	"ui-auditor"
+];
+//#endregion
+//#region src/mcp/tools/delegation-history.ts
+/** MCP tool name for the `delegation_history` read-past-delegations tool. @stable */
+const DELEGATION_HISTORY_TOOL_NAME = "delegation_history";
+/** Human-readable description of the `delegation_history` MCP tool, injected into the tool manifest. @stable */
+const DELEGATION_HISTORY_DESCRIPTION = [
+	"Read past delegations newest-first. Each entry carries the original",
+	"arguments, current status, cost, and any feedback attached via",
+	"delegate_feedback.",
+	"",
+	"Use when: you want to introspect prior decisions — \"have I asked this",
+	"question before?",
+	"did the last patch land?",
+	"what's the historical",
+	"success rate of coder delegations on this repo?\". Feed the results back",
+	"into your own routing and calibration.",
+	"",
+	"Each entry carries `hasTrace` — when true, the full loop-trace span tree",
+	"is retrievable via delegation_status { taskId, includeTrace: true }.",
+	"",
+	`Filters: \`namespace\` (multi-tenant scope), \`profile\` (${delegationProfiles.map((profile) => `"${profile}"`).join(" | ")}),`,
+	"`since` (ISO date — only delegations started at-or-after). `limit` defaults",
+	"to 50, capped at 500."
+].join("\n");
+/** JSON Schema for `delegation_history` tool arguments (optional `namespace`, `profile`, `since`, `limit`). @stable */
+const DELEGATION_HISTORY_INPUT_SCHEMA = {
+	type: "object",
+	properties: {
+		namespace: { type: "string" },
+		profile: {
+			type: "string",
+			enum: delegationProfiles
+		},
+		since: {
+			type: "string",
+			description: "ISO datetime — earliest startedAt to include."
+		},
+		limit: {
+			type: "integer",
+			minimum: 1,
+			maximum: 500
+		}
+	},
+	additionalProperties: false
+};
+/** Parse and validate raw MCP tool input into typed `DelegationHistoryArgs`; throws `TypeError` on bad input. @stable */
+function validateDelegationHistoryArgs(raw) {
+	if (raw === void 0 || raw === null) return {};
+	if (typeof raw !== "object") throw new TypeError("delegation_history: arguments must be an object");
+	const value = raw;
+	const out = {};
+	if (value.namespace !== void 0) {
+		if (typeof value.namespace !== "string") throw new TypeError("delegation_history: `namespace` must be a string");
+		out.namespace = value.namespace;
+	}
+	if (value.profile !== void 0) {
+		if (!delegationProfiles.includes(value.profile)) throw new TypeError(`delegation_history: \`profile\` must be one of ${delegationProfiles.join(", ")}`);
+		out.profile = value.profile;
+	}
+	if (value.since !== void 0) {
+		if (typeof value.since !== "string" || Number.isNaN(Date.parse(value.since))) throw new TypeError("delegation_history: `since` must be an ISO datetime");
+		out.since = value.since;
+	}
+	if (value.limit !== void 0) {
+		const n = Number(value.limit);
+		if (!Number.isFinite(n) || n < 1 || n > 500) throw new RangeError("delegation_history: `limit` must be an integer in [1, 500]");
+		out.limit = Math.trunc(n);
+	}
+	return out;
+}
+/** Build the MCP tool handler that reads filtered past delegations from a `DelegationTaskQueue`. @stable */
+function createDelegationHistoryHandler(options) {
+	return async (raw) => {
+		const args = validateDelegationHistoryArgs(raw);
+		return { delegations: options.queue.history(args) };
+	};
+}
+//#endregion
+//#region src/mcp/tools/delegation-status.ts
 /**
 *
-* Stdio JSON-RPC MCP server exposing the delegation tools to sandbox
-* coding-harness agents (claude-code, codex, opencode, ...): the generic
-* `delegate` verb plus the queue-bound `delegate_feedback`,
-* `delegation_status`, and `delegation_history`. `delegate_ui_audit` is served
-* when a `uiAuditorDelegate` is wired.
-*
-* The server is transport-bound but topology-free: tool execution is
-* delegated to handler functions composed from a queue, a feedback
-* store, and the wired run delegates. Consumers wire those at
-* construction time. The `agent-runtime-mcp` bin serves the generic
-* `delegate` verb over a real sandbox client when `MCP_ENABLE_DELEGATE=1`.
-*
-* Wire protocol: line-delimited JSON-RPC 2.0 over stdio. Each line is
-* one request; each response is one line. `tools/list` and `tools/call`
-* mirror the MCP 2024-11-05 spec. The production server does not depend on
-* `@modelcontextprotocol/sdk`; integration tests validate this wire with the official client.
+* `delegation_status` MCP tool — synchronous poll. Returns the current
+* state machine + optional progress + final result (when terminal).
 *
-* @experimental
+* @stable
 */
+/** MCP tool name for the `delegation_status` synchronous-poll tool. @stable */
+const DELEGATION_STATUS_TOOL_NAME = "delegation_status";
+/** Human-readable description of the `delegation_status` MCP tool, injected into the tool manifest. @stable */
+const DELEGATION_STATUS_DESCRIPTION = [
+	"Poll the status of an async delegation. Returns the current state",
+	"(pending | running | completed | failed | cancelled), optional progress,",
+	"and the final result when status === \"completed\".",
+	"",
+	"Use when: you previously kicked off an async delegation (delegate_ui_audit)",
+	"and need to know whether the work is done. The agent's right rhythm is to",
+	"call this every minute or two while waiting; do not busy-poll.",
+	"",
+	"For a completed delegate_ui_audit run, `result.output` is the array of UI",
+	"findings — one self-contained Markdown finding per issue, each with an",
+	"embedded screenshot and a suggested fix.",
+	"",
+	"Pass includeTrace: true to also receive the journaled loop-trace span",
+	"tree (loop → round → iteration, with placement/cost/verdict metadata).",
+	"Default false — keep routine polls light.",
+	"",
+	"Throws NotFoundError when taskId is unknown — never silently returns",
+	"`pending` for a typo."
+].join("\n");
+/** JSON Schema for `delegation_status` tool arguments (`taskId` + optional `includeTrace`). @stable */
+const DELEGATION_STATUS_INPUT_SCHEMA = {
+	type: "object",
+	properties: {
+		taskId: {
+			type: "string",
+			description: "Returned by delegate_ui_audit."
+		},
+		includeTrace: {
+			type: "boolean",
+			description: "Also return the journaled loop-trace span tree for this delegation. Default false."
+		}
+	},
+	required: ["taskId"],
+	additionalProperties: false
+};
+/** Parse and validate raw MCP tool input into typed `DelegationStatusArgs`; throws `TypeError` on bad input. @stable */
+function validateDelegationStatusArgs(raw) {
+	if (raw === null || typeof raw !== "object") throw new TypeError("delegation_status: arguments must be an object");
+	const value = raw;
+	const taskId = value.taskId;
+	if (typeof taskId !== "string" || taskId.trim().length === 0) throw new TypeError("delegation_status: `taskId` must be a non-empty string");
+	const out = { taskId: taskId.trim() };
+	if (value.includeTrace !== void 0) {
+		if (typeof value.includeTrace !== "boolean") throw new TypeError("delegation_status: `includeTrace` must be a boolean");
+		out.includeTrace = value.includeTrace;
+	}
+	return out;
+}
+/** Build the MCP tool handler that polls a `DelegationTaskQueue` for task status. @stable */
+function createDelegationStatusHandler(options) {
+	return async (raw) => {
+		const args = validateDelegationStatusArgs(raw);
+		const status = options.queue.status(args.taskId, args.includeTrace !== void 0 ? { includeTrace: args.includeTrace } : void 0);
+		if (!status) throw new NotFoundError(`delegation_status: unknown taskId "${args.taskId}"`);
+		return status;
+	};
+}
+//#endregion
+//#region src/mcp/server.ts
 const DEFAULT_SERVER_NAME = "agent-runtime-mcp";
 const DEFAULT_SERVER_VERSION = "0.22.0";
 /**
@@ -1261,44 +1593,7 @@ function createMcpServer(options = {}) {
 		stop: stdio.stop
 	};
 }
-/**
-* In-process pair of `Readable` + `Writable` streams suitable for driving
-* `server.serve(...)` from a test. Returns the agent-side stream (the
-* client writes to it) and the server-side stream (the test reads from it).
-*
-* @experimental
-*/
-function createInProcessTransport() {
-	const responses = [];
-	const input = new Readable({ read() {} });
-	return {
-		transport: {
-			input,
-			output: new Writable({ write(chunk, _enc, cb) {
-				const text = chunk.toString("utf8");
-				for (const line of text.split("\n")) {
-					const trimmed = line.trim();
-					if (!trimmed) continue;
-					try {
-						responses.push(JSON.parse(trimmed));
-					} catch {}
-				}
-				cb();
-			} })
-		},
-		clientWrite(line) {
-			input.push(`${line}\n`);
-		},
-		clientClose() {
-			input.push(null);
-		},
-		async readServer() {
-			for (let i = 0; i < 5; i += 1) await new Promise((r) => setImmediate(r));
-			return [...responses];
-		}
-	};
-}
 //#endregion
-export { composeLoopTraceEmitters as C, capDelegationTrace as S, FileDelegationStore as _, DELEGATE_UI_AUDIT_TOOL_NAME as a, DELEGATION_TRACE_MAX_SPANS as b, DELEGATE_DESCRIPTION as c, createDelegateHandler as d, validateDelegateArgs as f, DelegationStateCorruptError as g, DelegationPersistenceError as h, DELEGATE_UI_AUDIT_INPUT_SCHEMA as i, DELEGATE_INPUT_SCHEMA as l, hashIdempotencyInput as m, createMcpServer as n, createDelegateUiAuditHandler as o, DelegationTaskQueue as p, DELEGATE_UI_AUDIT_DESCRIPTION as r, validateDelegateUiAuditArgs as s, createInProcessTransport as t, DELEGATE_TOOL_NAME as u, InMemoryDelegationStore as v, createDelegationTraceCollector as w, buildDelegationTraceSpans as x, DELEGATION_TRACE_MAX_BYTES as y };
+export { composeLoopTraceEmitters as a, FileDelegationStore as i, createDelegateHandler as n, DelegationTaskQueue as r, createMcpServer as t };
 
-//# sourceMappingURL=server-DQHJszfk.js.map
+//# sourceMappingURL=server-DkVBSN_S.js.map