@iowarp/clio-coder 0.4.4 → 0.4.6

package/src/tools/web-fetch-network.ts

@@ -0,0 +1,179 @@
+import { lookup } from "node:dns/promises";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { BlockList, isIP } from "node:net";
+import { Readable } from "node:stream";
+import { createBrotliDecompress, createGunzip, createInflate } from "node:zlib";
+import { WEB_FETCH_ALLOW_PRIVATE_NETWORK_ENV } from "./network-policy.js";
+
+const blocked = new BlockList();
+for (const [address, prefix] of [
+	["0.0.0.0", 8],
+	["10.0.0.0", 8],
+	["100.64.0.0", 10],
+	["127.0.0.0", 8],
+	["169.254.0.0", 16],
+	["172.16.0.0", 12],
+	["192.168.0.0", 16],
+	["192.0.0.0", 24],
+	["192.0.2.0", 24],
+	["198.18.0.0", 15],
+	["198.51.100.0", 24],
+	["203.0.113.0", 24],
+	["224.0.0.0", 4],
+	["240.0.0.0", 4],
+] as const)
+	blocked.addSubnet(address, prefix, "ipv4");
+// Permit only global unicast IPv6. Block transition mechanisms that can embed
+// an IPv4 destination and local/documentation allocations within that range.
+for (const [address, prefix] of [
+	["2001::", 32],
+	["2001:db8::", 32],
+	["2002::", 16],
+] as const)
+	blocked.addSubnet(address, prefix, "ipv6");
+const globalV6 = new BlockList();
+globalV6.addSubnet("2000::", 3, "ipv6");
+export function isPublicWebAddress(address: string): boolean {
+	const family = isIP(address);
+	if (family === 4) return !blocked.check(address, "ipv4");
+	return family === 6 && globalV6.check(address, "ipv6") && !blocked.check(address, "ipv6");
+}
+
+export class WebFetchNetworkError extends Error {
+	constructor(message: string) {
+		super(`WEB_FETCH_PRIVATE_NETWORK: ${message}`);
+		this.name = "WebFetchNetworkError";
+	}
+}
+
+interface Address {
+	address: string;
+	family: number;
+}
+export interface WebFetchNetworkDependencies {
+	resolve?: (hostname: string) => Promise<Address[]>;
+	request?: (url: URL, init: RequestInit, address: Address) => Promise<Response>;
+	allowPrivateNetwork?: boolean;
+}
+
+/** Pin the checked address in the socket lookup while retaining the URL host
+ * for Host, TLS SNI and certificate verification. No second DNS resolution,
+ * proxy, pooled socket, or automatic redirect can bypass admission. */
+async function requestPinnedWebUrl(url: URL, init: RequestInit, address: Address): Promise<Response> {
+	return new Promise((resolve, reject) => {
+		const headers = new Headers(init.headers);
+		headers.delete("host");
+		const request = (url.protocol === "https:" ? httpsRequest : httpRequest)(
+			url,
+			{
+				method: init.method ?? "GET",
+				headers: Object.fromEntries(headers),
+				agent: false,
+				...(init.signal ? { signal: init.signal } : {}),
+				lookup: (_hostname, options, callback) => {
+					if (options.all) callback(null, [address]);
+					else callback(null, address.address, address.family);
+				},
+			},
+			(response) => {
+				const responseHeaders = new Headers();
+				for (const [key, value] of Object.entries(response.headers)) {
+					if (value !== undefined) responseHeaders.set(key, Array.isArray(value) ? value.join(", ") : value);
+				}
+				const status = response.statusCode ?? 500;
+				let stream: Readable = response;
+				const encoding = responseHeaders.get("content-encoding");
+				const decoder =
+					encoding === "gzip"
+						? createGunzip()
+						: encoding === "br"
+							? createBrotliDecompress()
+							: encoding === "deflate"
+								? createInflate()
+								: null;
+				if (decoder) {
+					response.on("error", (error) => decoder.destroy(error));
+					decoder.on("close", () => response.destroy());
+					stream = response.pipe(decoder);
+					responseHeaders.delete("content-encoding");
+					responseHeaders.delete("content-length");
+				}
+				const noBody = init.method === "HEAD" || [204, 205, 304].includes(status);
+				if (noBody) response.resume();
+				const result = new Response(noBody ? null : (Readable.toWeb(stream) as ReadableStream<Uint8Array>), {
+					status,
+					statusText: response.statusMessage ?? "",
+					headers: responseHeaders,
+				});
+				Object.defineProperty(result, "url", { value: url.toString() });
+				resolve(result);
+			},
+		);
+		request.on("error", reject);
+		request.end(typeof init.body === "string" ? init.body : undefined);
+	});
+}
+
+/** DNS lookup itself is not cancellable; stop awaiting it on turn cancellation. */
+async function abortableLookup(
+	pending: Promise<Address[]>,
+	signal: AbortSignal | null | undefined,
+): Promise<Address[]> {
+	if (!signal) return pending;
+	signal.throwIfAborted();
+	return new Promise((resolve, reject) => {
+		const onAbort = (): void => reject(signal.reason);
+		signal.addEventListener("abort", onAbort, { once: true });
+		pending.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+	});
+}
+
+/** Every hop, including helper URLs, resolves and validates before connecting. */
+export async function fetchWebUrl(
+	input: string | URL,
+	initial: RequestInit = {},
+	dependencies: WebFetchNetworkDependencies = {},
+): Promise<Response> {
+	let url = new URL(input);
+	const init = { ...initial, headers: new Headers(initial.headers) };
+	const allowPrivate = dependencies.allowPrivateNetwork ?? process.env[WEB_FETCH_ALLOW_PRIVATE_NETWORK_ENV] === "1";
+	for (let hop = 0; hop <= 10; hop++) {
+		init.signal?.throwIfAborted();
+		if (!["http:", "https:"].includes(url.protocol) || url.username || url.password)
+			throw new Error("web_fetch: unsupported URL scheme or embedded credentials");
+		const hostname = url.hostname.replace(/^\[|\]$/g, "");
+		const addresses = isIP(hostname)
+			? [{ address: hostname, family: isIP(hostname) }]
+			: await abortableLookup((dependencies.resolve ?? ((host) => lookup(host, { all: true })))(hostname), init.signal);
+		init.signal?.throwIfAborted();
+		const address = addresses[0];
+		if (address === undefined) throw new Error("web_fetch: DNS returned no addresses");
+		if (!allowPrivate && addresses.some((address) => !isPublicWebAddress(address.address)))
+			throw new WebFetchNetworkError(
+				`destination ${url.hostname} is not public; operator opt-in ${WEB_FETCH_ALLOW_PRIVATE_NETWORK_ENV}=1 is required`,
+			);
+		const response = await (dependencies.request ?? requestPinnedWebUrl)(url, init, address);
+		const location = response.headers.get("location");
+		if (![301, 302, 303, 307, 308].includes(response.status) || location === null) return response;
+		await response.body?.cancel();
+		if (hop === 10) throw new Error("web_fetch: too many redirects");
+		const next = new URL(location, url);
+		if (next.origin !== url.origin) {
+			// Custom headers can carry credentials too. A cross-origin redirect gets
+			// no caller headers; the target still receives the ordinary Host header.
+			init.headers = new Headers();
+		}
+		if (
+			(response.status === 303 && init.method !== "HEAD") ||
+			([301, 302].includes(response.status) && init.method === "POST")
+		) {
+			init.method = "GET";
+			delete init.body;
+			init.headers.delete("content-type");
+			init.headers.delete("content-length");
+		}
+		url = next;
+	}
+	throw new Error("web_fetch: too many redirects");
+}

package/src/tools/web-fetch-surface.ts

@@ -4,7 +4,8 @@ import type { ToolSurface } from "./lazy-tool.js";
 
 export const webFetchToolSurface = {
 	name: ToolNames.WebFetch,
-	description: "Fetch an http(s) URL; HTML is cleaned and converted to Markdown. Non-2xx responses are errors.",
+	description:
+		"Fetch an http(s) URL; HTML is cleaned and converted to Markdown. Non-2xx responses are errors. Non-GET/HEAD methods or any body require outward-action approval; private networks require operator opt-in.",
 	parameters: Type.Object({
 		url: Type.String({ description: "Fully-qualified http(s) URL." }),
 		method: Type.Optional(Type.String({ description: "HTTP method (default GET)." })),

package/src/tools/web-fetch.ts

@@ -1,5 +1,7 @@
+import { UNTRUSTED_CONTENT_BANNER } from "../core/untrusted-content.js";
 import type { ToolResult, ToolSpec } from "./registry.js";
 import { truncateUtf8 } from "./truncate-utf8.js";
+import { fetchWebUrl } from "./web-fetch-network.js";
 import { webFetchToolSurface } from "./web-fetch-surface.js";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
@@ -374,7 +376,7 @@ async function fetchArxivPaperSummary(
 	maxBytes: number,
 ): Promise<ToolResult | null> {
 	const metadataUrl = `https://export.arxiv.org/api/query?id_list=${encodeURIComponent(paperId)}`;
-	const response = await fetch(metadataUrl, init);
+	const response = await fetchWebUrl(metadataUrl, init);
 	if (response.status < 200 || response.status >= 300) return null;
 	const read = await readResponseText(response, Math.min(120_000, maxBytes));
 	const entry = /<entry\b[^>]*>([\s\S]*?)<\/entry>/i.exec(read.text)?.[1];
@@ -384,7 +386,7 @@ async function fetchArxivPaperSummary(
 	let alphaxivRead: ReadResult | null = null;
 	const alphaUrl = `https://alphaxiv.org/overview/${encodeURIComponent(paperId)}.md`;
 	try {
-		const alpha = await fetch(alphaUrl, init);
+		const alpha = await fetchWebUrl(alphaUrl, init);
 		if (alpha.status >= 200 && alpha.status < 300) {
 			alphaxivRead = await readResponseText(alpha, Math.min(80_000, Math.max(0, maxBytes - read.bytesRead)));
 			if (alphaxivRead.text.trim().length > 0) paper.alphaxivOverview = alphaxivRead.text.trim();
@@ -416,7 +418,7 @@ async function fetchArxivPaperSummary(
 	const bytesRead = read.bytesRead + (alphaxivRead?.bytesRead ?? 0);
 	return {
 		kind: "ok",
-		output: truncate(lines.join("\n"), maxBytes),
+		output: truncate(`${UNTRUSTED_CONTENT_BANNER}\n${lines.join("\n")}`, maxBytes),
 		details: {
 			url: `https://arxiv.org/abs/${paper.id}`,
 			status: 200,
@@ -437,7 +439,7 @@ async function fetchArxivApiSummary(
 	init: Parameters<typeof fetch>[1],
 	maxBytes: number,
 ): Promise<ToolResult | null> {
-	const response = await fetch(url, init);
+	const response = await fetchWebUrl(url, init);
 	if (response.status < 200 || response.status >= 300) return null;
 	const read = await readResponseText(response, Math.min(240_000, maxBytes));
 	const entries = Array.from(read.text.matchAll(/<entry\b[^>]*>([\s\S]*?)<\/entry>/gi))
@@ -469,7 +471,7 @@ async function fetchArxivApiSummary(
 	}
 	return {
 		kind: "ok",
-		output: truncate(lines.join("\n"), maxBytes),
+		output: truncate(`${UNTRUSTED_CONTENT_BANNER}\n${lines.join("\n")}`, maxBytes),
 		details: {
 			url: url.toString(),
 			status: 200,
@@ -553,7 +555,7 @@ async function fetchRepoTreeSummary(
 	init: Parameters<typeof fetch>[1],
 	maxBytes: number,
 ): Promise<ToolResult | null> {
-	const apiResponse = await fetch(target.apiUrl, init);
+	const apiResponse = await fetchWebUrl(target.apiUrl, init);
 	if (apiResponse.status < 200 || apiResponse.status >= 300) return null;
 	const apiRead = await readResponseText(apiResponse, Math.min(200_000, maxBytes));
 	let entries: unknown[];
@@ -581,7 +583,7 @@ async function fetchRepoTreeSummary(
 	for (const file of files) {
 		if (remaining <= 2000) break;
 		const rawUrl = `${target.rawBaseUrl}/${file}`;
-		const rawResponse = await fetch(rawUrl, init);
+		const rawResponse = await fetchWebUrl(rawUrl, init);
 		if (rawResponse.status < 200 || rawResponse.status >= 300) continue;
 		const rawRead = await readResponseText(rawResponse, Math.min(80_000, remaining));
 		sections.push("", `--- ${file} ---`, rawRead.text.trim());
@@ -589,7 +591,7 @@ async function fetchRepoTreeSummary(
 	}
 	return {
 		kind: "ok",
-		output: truncate(sections.join("\n"), maxBytes),
+		output: truncate(`${UNTRUSTED_CONTENT_BANNER}\n${sections.join("\n")}`, maxBytes),
 		details: {
 			url: target.apiUrl,
 			status: 200,
@@ -621,7 +623,7 @@ function formatOutput(args: {
 	if (args.extracted.description) lines.push(`Description: ${args.extracted.description}`);
 	if (args.extracted.canonical) lines.push(`Canonical: ${args.extracted.canonical}`);
 	lines.push("", "Content:", args.extracted.content || "[empty]");
-	return truncate(lines.join("\n"), args.maxBytes);
+	return truncate(`${UNTRUSTED_CONTENT_BANNER}\n${lines.join("\n")}`, args.maxBytes);
 }
 
 export const webFetchTool: ToolSpec = {
@@ -683,10 +685,10 @@ export const webFetchTool: ToolSpec = {
 				method,
 				headers,
 				signal: controller.signal,
-				redirect: "follow",
+				redirect: "manual",
 			};
 			if (body !== undefined) init.body = body;
-			if (method === "GET" && body === undefined && format !== "raw") {
+			if (method === "GET" && body === undefined && format !== "raw" && Object.keys(userHeaders).length === 0) {
 				if (arxivApiUrl(parsed)) {
 					const arxivApiSummary = await fetchArxivApiSummary(parsed, init, maxBytes);
 					if (arxivApiSummary) return arxivApiSummary;
@@ -702,7 +704,7 @@ export const webFetchTool: ToolSpec = {
 					if (repoSummary) return repoSummary;
 				}
 			}
-			const response = await fetch(parsed, init);
+			const response = await fetchWebUrl(parsed, init);
 			const contentType = headerValue(response, "content-type");
 			const readLimit =
 				response.status >= 200 && response.status < 300 ? maxBytes : Math.min(ERROR_PREVIEW_BYTES, maxBytes);
@@ -711,7 +713,7 @@ export const webFetchTool: ToolSpec = {
 				const preview = extractWebFetchContent(read.text, contentType, response.url || parsed.toString(), "auto").content;
 				return {
 					kind: "error",
-					message: `web_fetch: HTTP ${response.status}: ${response.statusText}${preview ? `\nPreview:\n${truncate(preview, ERROR_PREVIEW_BYTES)}` : ""}`,
+					message: `web_fetch: HTTP ${response.status}: ${response.statusText}${preview ? `\n${UNTRUSTED_CONTENT_BANNER}\nPreview:\n${truncate(preview, ERROR_PREVIEW_BYTES)}` : ""}`,
 				};
 			}
 			if (isProbablyBinary(contentType, read.text)) {

package/src/tools/worker-evidence.ts

@@ -1,4 +1,5 @@
 import { mentionsWorkerToolCallCap } from "../core/guardrails.js";
+import { RESULT_SUMMARY_MAX_BYTES_CEILING, resultContractAuthorship } from "../domains/agents/result-contract.js";
 import {
 	formatBudgetPolicy,
 	formatBudgetReasons,
@@ -158,6 +159,7 @@ export function receiptEvidenceLabels(
 	return [
 		...canonical,
 		`receipt_integrity=verified/v${receipt.integrity.version}/${receipt.integrity.algorithm}`,
+		...documenterDeliveryLabels(receipt),
 		`evidence_verification=${verification.state}/${verification.basis}`,
 		`host_verification=${receipt.hostVerification?.status ?? "not_requested"}`,
 		...(responseModelIdObservation ? [responseModelIdObservation] : []),
@@ -170,6 +172,31 @@ export function receiptEvidenceLabels(
 	];
 }
 
+/** Delivery guidance uses only an authenticated, terminal mutation report. */
+function documenterDeliveryLabels(receipt: RunReceipt): string[] {
+	if (
+		receipt.agentId !== "documenter" ||
+		!receipt.quality.resultContract?.sourceId.startsWith("agent-result-contract:mutation-report:")
+	)
+		return [];
+	const output = receipt.output;
+	// Read at the ceiling: the receipt already sealed conformance under the
+	// run's own allowance, which this reader does not know; any conforming
+	// summary is within the ceiling, and a reader that re-applied the default
+	// would report a delivered 20 KB summary as absent.
+	const summary =
+		output?.state === "final"
+			? resultContractAuthorship(
+					{ kind: "mutation-report", maxSummaryBytes: RESULT_SUMMARY_MAX_BYTES_CEILING },
+					output.text,
+				).summary
+			: null;
+	return [
+		`terminal Documenter result: ${summary === null ? "no inline summary is available" : "the inline deliverable or limitation is in output.text JSON field summary"}. Execution success and contract conformance alone do not prove the requested explanation was delivered.`,
+		"Read the summary or the task-authorized artifact once and check it against the requested deliverable. If it is absent, incomplete, or states a limitation, report the specific limitation and the run ID; do not repeatedly read this unchanged terminal receipt or poll it for new output. Keep any separately authorized recovery and its outcome distinct from the original run.",
+	];
+}
+
 /**
  * The compact projection first, then the canonical axis line, both from the
  * shared projection so the dispatch and monitor text can never spell a state

package/src/worker/spec-contract.ts

@@ -47,20 +47,22 @@ export interface WorkerProtectedArtifactState {
 	artifacts: ReadonlyArray<ProtectedArtifact>;
 }
 
-/** Concrete dispatch-time budget after recipe policy and operator clamping. */
+/** Concrete dispatch-time planning estimates, or a legacy enforced budget. */
 export interface WorkerBudgetPhase {
 	toolCalls: number;
 	readReserve: number;
 }
 
 export interface WorkerBudget {
-	/** Agent phase boundary before synthesis or bounded termination. */
+	/** New dispatches are advisory; omitted mode preserves legacy enforcement. */
+	mode?: "advisory" | "enforced";
+	/** Estimated tool calls; a phase boundary only in enforced mode. */
 	toolCalls: number;
-	/** Tail of toolCalls reserved for canonical read calls. */
+	/** Suggested read allowance; reserved calls only in enforced mode. */
 	readReserve: number;
-	/** True enters text-only synthesis; false ends at the phase boundary. */
+	/** Legacy enforced-mode phase behavior; advisory mode never forces synthesis. */
 	synthesis: boolean;
-	/** Independent operator-owned attempt ceiling; recipes cannot widen it. */
+	/** Legacy enforced-mode attempt ceiling; advisory-mode planning baseline. */
 	hardCap: number;
 	/** Optional ceiling that a bounded result-contract revision may activate. */
 	revision?: WorkerBudgetPhase;
@@ -429,7 +431,7 @@ function validateAllowedTools(value: unknown): void {
 
 function validateWorkerBudget(value: unknown): void {
 	const budget = readRecord(value, "WorkerSpec.budget");
-	const expected = ["hardCap", "readReserve", "revision", "synthesis", "toolCalls"];
+	const expected = ["mode", "hardCap", "readReserve", "revision", "synthesis", "toolCalls"];
 	const actual = Object.keys(budget).sort();
 	if (
 		actual.some((key) => !expected.includes(key)) ||
@@ -437,6 +439,8 @@ function validateWorkerBudget(value: unknown): void {
 	) {
 		throw new Error(`WorkerSpec.budget may contain only: ${expected.join(", ")}`);
 	}
+	if (budget.mode !== undefined && budget.mode !== "advisory" && budget.mode !== "enforced")
+		throw new Error("WorkerSpec.budget.mode must be advisory or enforced");
 	for (const required of ["hardCap", "readReserve", "synthesis", "toolCalls"] as const) {
 		if (!Object.hasOwn(budget, required)) throw new Error(`WorkerSpec.budget.${required} is required`);
 	}
@@ -448,7 +452,7 @@ function validateWorkerBudget(value: unknown): void {
 	}
 	if ((budget.toolCalls as number) <= 0) throw new Error("WorkerSpec.budget.toolCalls must be greater than zero");
 	if ((budget.hardCap as number) <= 0) throw new Error("WorkerSpec.budget.hardCap must be greater than zero");
-	if ((budget.toolCalls as number) > (budget.hardCap as number)) {
+	if (budget.mode !== "advisory" && (budget.toolCalls as number) > (budget.hardCap as number)) {
 		throw new Error("WorkerSpec.budget.toolCalls must not exceed WorkerSpec.budget.hardCap");
 	}
 	if ((budget.readReserve as number) < 0 || (budget.readReserve as number) >= (budget.toolCalls as number)) {
@@ -475,7 +479,7 @@ function validateWorkerBudget(value: unknown): void {
 		) {
 			throw new Error("WorkerSpec.budget.revision must increase toolCalls or readReserve");
 		}
-		if ((revision.toolCalls as number) > (budget.hardCap as number)) {
+		if (budget.mode !== "advisory" && (revision.toolCalls as number) > (budget.hardCap as number)) {
 			throw new Error("WorkerSpec.budget.revision.toolCalls must not exceed WorkerSpec.budget.hardCap");
 		}
 		if ((revision.readReserve as number) < 0 || (revision.readReserve as number) >= (revision.toolCalls as number)) {

package/dist/builtins-WGALA46I.js

@@ -1,22 +0,0 @@
-import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
-import {
-  BUILTIN_RUNTIMES,
-  registerBuiltinRuntimes
-} from "./chunk-6OSVSQL5.js";
-import "./chunk-UXCU4E3T.js";
-import "./chunk-LL4KHSZI.js";
-import "./chunk-S66XZJOF.js";
-import "./chunk-TOIVGRUX.js";
-import "./chunk-U6TMQNSI.js";
-import "./chunk-EBY63B7G.js";
-import "./chunk-6EJMN2Y3.js";
-import "./chunk-5OIVVPHF.js";
-import "./chunk-YPC6ZR5L.js";
-import "./chunk-YXLYO42X.js";
-import "./chunk-BYP5D4HI.js";
-import "./chunk-3R73A4XB.js";
-export {
-  BUILTIN_RUNTIMES,
-  registerBuiltinRuntimes
-};
-//# sourceMappingURL=builtins-WGALA46I.js.map