open-tag 0.0.5 → 0.1.1

package/dist/cli/pi-extensions/web-tools.mjs

@@ -0,0 +1,1082 @@
+import { join, sep } from "node:path";
+import { constants } from "node:fs";
+import { createHash } from "node:crypto";
+import { lstat, mkdir, open, readdir, realpath, rename, rm, writeFile } from "node:fs/promises";
+import http from "node:http";
+//#region src/pi-extensions/web-tools.ts
+/**
+* OpenTag web tools Pi extension (trusted built artifact).
+*
+* Loaded explicitly with `pi -e <this file>` for actual execution only; `--no-extensions` stays
+* set so implicit discovery never loads it. The extension registers `web_search`/`web_fetch`,
+* forwards validated calls over the per-execution endpoint named by the nonsecret
+* OPENTAG_WEB_TOOLS_SOCKET descriptor, and saves bounded extracted content under the Session
+* workspace `.opentag/web/<stable-tool-id>/`.
+*
+* This module is intentionally self-contained (Node builtins only, no package imports): it runs
+* inside the Pi process and must never resolve workspace dependencies. The wire authority is
+* `@opentag/shared` web-tools; the gateway and Server re-validate everything authoritatively.
+*
+* Wire/artifact identity: the wire toolCallId is derived deterministically (UUID shape) from the
+* per-execution endpoint descriptor plus the actual Pi runtime tool call ID. Same-execution
+* retries reuse it (stable idempotency); a distinct execution can never collide with or
+* overwrite another execution's artifacts. Failures throw bounded redacted errors so Pi records
+* toolResult.isError=true; a normal return is never used for failed operations.
+*/
+/** Named export so Client tests can pin these against the shared wire authority. */
+const WEB_EXTENSION_LIMITS = {
+	requestMaxBytes: 16384,
+	searchResponseMaxBytes: 1048576,
+	fetchResponseMaxBytes: 3145728,
+	previewPageMaxBytes: 12288,
+	toolResultMaxBytes: 49152,
+	pageBodyMaxBytes: 1048576,
+	queryMaxCodepoints: 400,
+	searchLimitMax: 10,
+	domainsMax: 10,
+	fetchUrlsMax: 3,
+	urlMaxBytes: 4096,
+	/** End-to-end operation budgets, equal to the shared hard caps; the chain only decreases them. */
+	searchTimeoutMs: 15e3,
+	fetchTimeoutMs: 45e3,
+	protocolVersion: 1,
+	/** Remaining-budget hop header (hop metadata, never part of the semantic digest). */
+	remainingHeader: "x-web-remaining-ms"
+};
+const TRUNCATION_MARKER = "…[truncated]";
+const ENDPOINT_ENV = "OPENTAG_WEB_TOOLS_SOCKET";
+/** UUID-shaped stable id derivation namespace; version/variant bits are set below. */
+const TOOL_ID_NAMESPACE = "opentag.web.tool.v1";
+/** Exact UUID-v5 shape produced by `deriveWebToolIdentity`; the only id ever used as a directory. */
+const TOOL_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-5[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/** The deadline controller aborts with this exact reason so callers keep distinct timeout wording. */
+const WEB_CALL_TIMED_OUT = "The web call timed out";
+/** Plain JSON Schema (no TypeBox dependency); the gateway re-validates with the shared Zod authority. */
+const WEB_SEARCH_PARAMETERS = {
+	type: "object",
+	properties: {
+		query: {
+			type: "string",
+			minLength: 1,
+			maxLength: WEB_EXTENSION_LIMITS.queryMaxCodepoints,
+			description: "Search query (1–400 characters), kept verbatim including case."
+		},
+		limit: {
+			type: "integer",
+			minimum: 1,
+			maximum: WEB_EXTENSION_LIMITS.searchLimitMax,
+			default: 5,
+			description: "Maximum number of sources to return (default 5)."
+		},
+		domains: {
+			type: "array",
+			items: { type: "string" },
+			maxItems: WEB_EXTENSION_LIMITS.domainsMax,
+			description: "Optional public domain names to scope the search (max 10)."
+		},
+		timeRange: {
+			type: "string",
+			enum: [
+				"day",
+				"week",
+				"month",
+				"year"
+			],
+			description: "Optional recency window for results."
+		},
+		language: {
+			type: "string",
+			description: "Optional language preference (e.g. en, zh-CN, portuguese); not a strict filter."
+		},
+		depth: {
+			type: "string",
+			enum: ["basic", "advanced"],
+			default: "basic",
+			description: "Search depth; advanced costs more and must be chosen explicitly."
+		}
+	},
+	required: ["query"],
+	additionalProperties: false
+};
+const WEB_FETCH_PARAMETERS = {
+	type: "object",
+	properties: {
+		urls: {
+			type: "array",
+			items: { type: "string" },
+			minItems: 1,
+			maxItems: WEB_EXTENSION_LIMITS.fetchUrlsMax,
+			description: "1–3 public http(s) URLs to extract page content from."
+		},
+		depth: {
+			type: "string",
+			enum: ["basic", "advanced"],
+			default: "basic",
+			description: "Extraction depth; advanced handles complex pages and must be chosen explicitly."
+		}
+	},
+	required: ["urls"],
+	additionalProperties: false
+};
+/**
+* Deterministic UUID-shaped tool identity: SHA-256 over the derivation namespace, the
+* per-execution endpoint descriptor, and the actual Pi runtime tool call ID, formatted with
+* version-5/variant bits. Same endpoint + same call ID ⇒ same id (stable retry); a different
+* execution endpoint ⇒ a different id (no cross-execution artifact collision).
+*/
+function deriveWebToolIdentity(endpointDescriptor, runtimeToolCallId) {
+	if (typeof runtimeToolCallId !== "string" || runtimeToolCallId.length === 0) throw new Error("The runtime tool call id is missing");
+	const hash = createHash("sha256").update(TOOL_ID_NAMESPACE, "utf8").update("", "utf8").update(endpointDescriptor, "utf8").update("", "utf8").update(runtimeToolCallId, "utf8").digest();
+	hash[6] = (hash[6] ?? 0) & 15 | 80;
+	hash[8] = (hash[8] ?? 0) & 63 | 128;
+	const hex = hash.subarray(0, 16).toString("hex");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+/** Truncate to a UTF-8 byte budget on codepoint boundaries, appending a marker when it fits. */
+function truncateToByteBudget(text, budgetBytes) {
+	if (Buffer.byteLength(text, "utf8") <= budgetBytes) return {
+		text,
+		truncated: false
+	};
+	if (budgetBytes <= 0) return {
+		text: "",
+		truncated: true
+	};
+	const markerBytes = Buffer.byteLength(TRUNCATION_MARKER, "utf8");
+	const buffer = Buffer.from(text, "utf8");
+	if (budgetBytes < markerBytes) {
+		let cut = budgetBytes;
+		while (cut > 0 && ((buffer[cut] ?? 0) & 192) === 128) cut -= 1;
+		return {
+			text: buffer.subarray(0, cut).toString("utf8"),
+			truncated: true
+		};
+	}
+	let cut = budgetBytes - markerBytes;
+	while (cut > 0 && ((buffer[cut] ?? 0) & 192) === 128) cut -= 1;
+	return {
+		text: `${buffer.subarray(0, cut).toString("utf8")}${TRUNCATION_MARKER}`,
+		truncated: true
+	};
+}
+/**
+* Distinguish the operation deadline from a caller abort while keeping the established wording:
+* `The web call was aborted` (never leaks a caller-provided reason), `The web call timed out` when
+* the end-to-end deadline fired. Everything downstream fails closed on either.
+*/
+function webCallAbortError(signal) {
+	const reason = signal?.reason;
+	if (reason instanceof Error && reason.message === WEB_CALL_TIMED_OUT) return /* @__PURE__ */ new Error(WEB_CALL_TIMED_OUT);
+	return /* @__PURE__ */ new Error("The web call was aborted");
+}
+/**
+* End-to-end operation deadline (original 15s/45s budget): mirrors the caller abort signal and
+* additionally aborts when the remaining budget expires. The returned signal stays live through
+* the HTTP hop AND every artifact write/publication, so filesystem work can never outlive the
+* budget; callers must keep checking it after each await and dispose it in a `finally`.
+*/
+function startOperationDeadline(timeoutMs, externalSignal) {
+	const deadlineAtMs = Date.now() + timeoutMs;
+	const controller = new AbortController();
+	const onExternalAbort = () => controller.abort(externalSignal?.reason);
+	if (externalSignal?.aborted) controller.abort(externalSignal.reason);
+	else externalSignal?.addEventListener("abort", onExternalAbort, { once: true });
+	const timer = setTimeout(() => controller.abort(/* @__PURE__ */ new Error(WEB_CALL_TIMED_OUT)), timeoutMs);
+	timer.unref?.();
+	return {
+		signal: controller.signal,
+		deadlineAtMs,
+		dispose() {
+			clearTimeout(timer);
+			externalSignal?.removeEventListener("abort", onExternalAbort);
+		}
+	};
+}
+function postToGateway(socketPath, path, payload, options) {
+	return new Promise((resolvePromise, rejectPromise) => {
+		const fail = (message) => {
+			finish(new Error(message));
+		};
+		const remainingAtDispatch = options.deadlineAtMs - Date.now();
+		if (options.signal?.aborted) {
+			rejectPromise(webCallAbortError(options.signal));
+			return;
+		}
+		if (remainingAtDispatch <= 0) {
+			rejectPromise(/* @__PURE__ */ new Error("The web call budget was exhausted before dispatch"));
+			return;
+		}
+		const body = Buffer.from(JSON.stringify(payload), "utf8");
+		if (body.byteLength > WEB_EXTENSION_LIMITS.requestMaxBytes) {
+			rejectPromise(/* @__PURE__ */ new Error("The web request exceeds the 16 KiB request bound"));
+			return;
+		}
+		let settled = false;
+		let timer;
+		let request;
+		const onAbort = () => {
+			finish(webCallAbortError(options.signal));
+			request.destroy();
+		};
+		const finish = (error, reply) => {
+			if (settled) return;
+			settled = true;
+			if (timer) clearTimeout(timer);
+			options.signal?.removeEventListener("abort", onAbort);
+			if (error) rejectPromise(error);
+			else if (reply) resolvePromise(reply);
+		};
+		request = http.request({
+			socketPath,
+			path,
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				"content-length": String(body.byteLength),
+				accept: "application/json",
+				[WEB_EXTENSION_LIMITS.remainingHeader]: String(remainingAtDispatch)
+			}
+		}, (response) => {
+			const chunks = [];
+			let total = 0;
+			response.on("data", (chunk) => {
+				total += chunk.byteLength;
+				if (total > options.maxResponseBytes) {
+					fail("The web gateway response exceeds the bound");
+					request.destroy();
+					return;
+				}
+				chunks.push(chunk);
+			});
+			response.on("end", () => finish(void 0, {
+				status: response.statusCode ?? 500,
+				body: Buffer.concat(chunks)
+			}));
+			response.on("error", () => fail("The web gateway response failed"));
+		});
+		timer = setTimeout(() => {
+			fail("The web call timed out");
+			request.destroy();
+		}, remainingAtDispatch);
+		timer.unref?.();
+		request.on("error", (error) => {
+			const code = error.code;
+			if (options.signal?.aborted) fail(webCallAbortError(options.signal).message);
+			else if (settled) return;
+			else fail(`The web gateway is unavailable: ${code ?? "unreachable"}`);
+		});
+		options.signal?.addEventListener("abort", onAbort, { once: true });
+		request.end(body);
+	});
+}
+/** Create-if-missing without following symlinks, then prove the result is a real directory. */
+async function ensureOwnedDirectory(path) {
+	try {
+		await mkdir(path, { mode: 448 });
+	} catch (error) {
+		if (error.code !== "EEXIST") throw error;
+	}
+	await assertRealDirectory(path);
+}
+async function assertRealDirectory(path) {
+	const stat = await lstat(path);
+	if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error("The web artifact path is not a real directory");
+}
+/**
+* Open (or reuse) the artifact directory for one stable tool call id. Every parent component is
+* validated BEFORE anything is created through it, so a hostile symlink can never cause writes
+* outside the Session store; a second page under the same id reuses the verified directory.
+*/
+async function openArtifactDirectory(cwd, toolCallId, signal) {
+	if (!TOOL_ID_PATTERN.test(toolCallId)) throw new Error("Unsafe web artifact tool id");
+	signal?.throwIfAborted();
+	const root = await realpath(cwd);
+	await ensureOwnedDirectory(join(root, ".opentag"));
+	await ensureOwnedDirectory(join(root, ".opentag", "web"));
+	const baseReal = await realpath(join(root, ".opentag", "web"));
+	if (!baseReal.startsWith(`${root}${sep}`)) throw new Error("The web artifact store escapes the workspace");
+	const directory = join(baseReal, toolCallId);
+	await ensureOwnedDirectory(directory);
+	const resolvedDirectory = await realpath(directory);
+	if (!resolvedDirectory.startsWith(`${baseReal}${sep}`)) throw new Error("The web artifact directory escapes the Session store");
+	signal?.throwIfAborted();
+	return resolvedDirectory;
+}
+/**
+* Save one page: bounded content, temp file + atomic rename, post-write regular-file proof.
+* The operation deadline stays authoritative after every await (including after publication), so
+* an aborted/timed-out attempt never reports a fabricated success. The observer is notified of the
+* temp name before the first write and of the published name right after the rename, which is the
+* only ownership evidence later cleanup is allowed to trust.
+* Throws on any failure — callers must mark the artifact unsaved and never fabricate a path.
+*/
+async function saveWebArtifact(input) {
+	if (!/^[a-z0-9][a-z0-9.-]{0,63}$/.test(input.fileName)) throw new Error("Unsafe web artifact file name");
+	input.signal?.throwIfAborted();
+	const directory = await openArtifactDirectory(input.cwd, input.toolCallId, input.signal);
+	const truncated = truncateToByteBudget(input.content, WEB_EXTENSION_LIMITS.pageBodyMaxBytes);
+	const bytes = Buffer.byteLength(truncated.text, "utf8");
+	const sha256 = createHash("sha256").update(truncated.text, "utf8").digest("hex");
+	const finalPath = join(directory, input.fileName);
+	const existing = await readBoundedRegularFile(finalPath, WEB_EXTENSION_LIMITS.pageBodyMaxBytes, input.signal);
+	if (existing.kind === "oversize" || existing.kind === "unsafe") throw new Error("The existing web artifact is not a bounded regular file");
+	if (existing.kind === "regular" && existing.bytes.length === bytes && sha256Hex(existing.bytes) === sha256) return {
+		relativePath: [
+			".opentag",
+			"web",
+			input.toolCallId,
+			input.fileName
+		].join("/"),
+		bytes,
+		sha256,
+		artifactTruncated: truncated.truncated
+	};
+	const tempName = `.${input.fileName}.${randomSuffix()}.tmp`;
+	const tempPath = join(directory, tempName);
+	input.observer?.onTempFile?.(tempName);
+	try {
+		await writeFile(tempPath, truncated.text, {
+			encoding: "utf8",
+			mode: 384,
+			flag: "wx",
+			signal: input.signal
+		});
+		input.signal?.throwIfAborted();
+		await rename(tempPath, finalPath);
+		input.observer?.onPublished?.(input.fileName);
+		input.signal?.throwIfAborted();
+		const stat = await lstat(finalPath);
+		if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("The web artifact failed verification");
+		input.signal?.throwIfAborted();
+	} catch (error) {
+		await rm(tempPath, { force: true }).catch(() => void 0);
+		throw error instanceof Error ? error : /* @__PURE__ */ new Error("The web artifact write failed");
+	}
+	return {
+		relativePath: [
+			".opentag",
+			"web",
+			input.toolCallId,
+			input.fileName
+		].join("/"),
+		bytes,
+		sha256,
+		artifactTruncated: truncated.truncated
+	};
+}
+function randomSuffix() {
+	return createHash("sha256").update(`${Date.now()}:${Math.random()}`).digest("hex").slice(0, 16);
+}
+function sha256Hex(data) {
+	return createHash("sha256").update(data).digest("hex");
+}
+/**
+* Read cap for the attempt index: ample for three URLs plus failure records (URLs are bounded at
+* 4 KiB each), far below any allocation risk. Page content gets its own 1 MiB cap.
+*/
+const METADATA_READ_MAX_BYTES = 65536;
+/** Fixed read chunk: the loop stops as soon as the cap is crossed, never trusting fstat size. */
+const READ_CHUNK_BYTES = 65536;
+/** Read-only, non-following, non-blocking open flags (POSIX bits fall back to 0 where absent). */
+function boundedReadFlags() {
+	const noFollow = constants.O_NOFOLLOW ?? 0;
+	const nonBlocking = constants.O_NONBLOCK ?? 0;
+	return constants.O_RDONLY | noFollow | nonBlocking;
+}
+/**
+* Bounded, symlink-safe read of a workspace-controlled entry. The handle is opened with
+* O_NOFOLLOW and O_NONBLOCK so a symlinked entry can never be followed and a FIFO can never block
+* the open waiting for a writer; fstat must prove a regular file, and the read proceeds in fixed
+* chunks until the cap is crossed — a file growing between fstat and read therefore returns
+* `oversize` instead of allocating past the cap. Callers decide whether a non-regular result is a
+* fall-through (cleanup) or a bounded unsaved failure (writes).
+*/
+async function readBoundedRegularFile(path, maxBytes, signal) {
+	signal?.throwIfAborted();
+	let handle;
+	try {
+		handle = await open(path, boundedReadFlags());
+	} catch (error) {
+		const code = error.code;
+		if (code === "ENOENT") return { kind: "absent" };
+		if (code === "ELOOP" || code === "EMLINK") return { kind: "unsafe" };
+		throw error;
+	}
+	try {
+		const stat = await handle.stat();
+		if (!stat.isFile()) return { kind: "unsafe" };
+		if (stat.size > maxBytes) return { kind: "oversize" };
+		const chunks = [];
+		let total = 0;
+		while (total <= maxBytes) {
+			signal?.throwIfAborted();
+			const chunk = Buffer.allocUnsafe(Math.min(READ_CHUNK_BYTES, maxBytes + 1 - total));
+			const { bytesRead } = await handle.read(chunk, 0, chunk.length, total);
+			if (bytesRead === 0) break;
+			total += bytesRead;
+			if (total > maxBytes) return { kind: "oversize" };
+			chunks.push(chunk.subarray(0, bytesRead));
+		}
+		signal?.throwIfAborted();
+		return {
+			kind: "regular",
+			bytes: Buffer.concat(chunks, total)
+		};
+	} finally {
+		await handle.close().catch(() => void 0);
+	}
+}
+/** Files a finalized index references; malformed/absent metadata references nothing. */
+function finalizedPagesFromBytes(bytes) {
+	try {
+		const parsed = JSON.parse(bytes.toString("utf8"));
+		if (!parsed || !Array.isArray(parsed.pages)) return /* @__PURE__ */ new Set();
+		return new Set(parsed.pages.map((page) => page.file).filter((file) => typeof file === "string"));
+	} catch {
+		return /* @__PURE__ */ new Set();
+	}
+}
+async function finalizedFileSet(directory) {
+	const existing = await readBoundedRegularFile(join(directory, "metadata.json"), METADATA_READ_MAX_BYTES);
+	if (existing.kind !== "regular") return /* @__PURE__ */ new Set();
+	return finalizedPagesFromBytes(existing.bytes);
+}
+/**
+* Restore a prior finalized index atomically, and only over a regular file inside the validated
+* attempt directory. Best-effort: a restore failure never masks the original operation error.
+*/
+async function restoreMetadataBytes(directory, content) {
+	const target = join(directory, "metadata.json");
+	const stat = await lstat(target).catch(() => void 0);
+	if (!stat || stat.isSymbolicLink() || !stat.isFile()) return;
+	const tempPath = join(directory, `.metadata.restore.${randomSuffix()}.tmp`);
+	try {
+		await writeFile(tempPath, content, {
+			mode: 384,
+			flag: "wx"
+		});
+		await rename(tempPath, target);
+	} catch {
+		await rm(tempPath, { force: true }).catch(() => void 0);
+	}
+}
+/**
+* Which page names a surviving index protects. When this attempt published its own index and no
+* prior index is restored, its pages are its own to remove; otherwise pages referenced by the
+* surviving (prior or foreign) index must never be deleted.
+*/
+async function protectionSet(directory, input) {
+	if (input.publishedMetadata === true && input.priorMetadata !== void 0) return finalizedPagesFromBytes(input.priorMetadata);
+	if (input.publishedMetadata === true) return /* @__PURE__ */ new Set();
+	return finalizedFileSet(directory);
+}
+/**
+* Decide the fate of the index this attempt published: put the prior finalized bytes back when
+* they are provably the ones we replaced, withdraw a fresh index of our own, and never clobber
+* an index that another attempt published after ours.
+*/
+async function settlePublishedMetadata(directory, input) {
+	const digest = input.publishedMetadataDigest;
+	if (digest === void 0) {
+		await removeOwnedEntry(directory, "metadata.json");
+		return;
+	}
+	const current = await readBoundedRegularFile(join(directory, "metadata.json"), METADATA_READ_MAX_BYTES);
+	if (current.kind !== "regular" || sha256Hex(current.bytes) !== digest) return;
+	if (input.priorMetadata !== void 0) {
+		await restoreMetadataBytes(directory, input.priorMetadata);
+		return;
+	}
+	await removeOwnedEntry(directory, "metadata.json");
+}
+/** A relative entry name that can only address one file directly inside the attempt directory. */
+function isSafeEntryName(name) {
+	return name.length > 0 && name !== "." && name !== ".." && !name.includes("/") && !name.includes("\\");
+}
+/**
+* Resolve the attempt directory for cleanup without ever traversing a symlink: every component
+* (`.opentag`, `web`, the stable id) must be a real directory. A symlinked parent means this is
+* not the Session store this execution opened, so cleanup does nothing at all.
+*/
+async function resolveCleanupDirectory(cwd, toolCallId) {
+	if (!TOOL_ID_PATTERN.test(toolCallId)) return void 0;
+	let root;
+	try {
+		root = await realpath(cwd);
+	} catch {
+		return;
+	}
+	const directory = join(root, ".opentag", "web", toolCallId);
+	for (const component of [
+		join(root, ".opentag"),
+		join(root, ".opentag", "web"),
+		directory
+	]) try {
+		const stat = await lstat(component);
+		if (stat.isSymbolicLink() || !stat.isDirectory()) return void 0;
+	} catch {
+		return;
+	}
+	try {
+		const resolved = await realpath(directory);
+		if (!resolved.startsWith(`${root}${sep}`)) return void 0;
+		return resolved;
+	} catch {
+		return;
+	}
+}
+/** Remove one explicitly owned entry, and only when it is still a regular file (never a link). */
+async function removeOwnedEntry(directory, name) {
+	const target = join(directory, name);
+	try {
+		const stat = await lstat(target);
+		if (stat.isSymbolicLink() || !stat.isFile()) return;
+	} catch {
+		return;
+	}
+	await rm(target, { force: true }).catch(() => void 0);
+}
+/**
+* Aborted/failed attempt cleanup: remove ONLY the entries this attempt explicitly registered —
+* the temp file names it reported before writing and the page files it published — and never a
+* wildcard `*.tmp` sweep. Anything else in the directory (another attempt's temp/publication
+* files, earlier successful artifacts, and pages protected by a surviving index) is preserved.
+* When this attempt published an index over a prior finalized one, the prior bytes are restored
+* unless another attempt has since published its own (proven by digest); a fresh index with no
+* prior is withdrawn. The whole path is validated first, so a symlinked intermediate component
+* cannot redirect the deletion outside the Session store.
+*/
+async function cleanupWebArtifacts(input) {
+	const directory = await resolveCleanupDirectory(input.cwd, input.toolCallId);
+	if (!directory) return;
+	const finalized = await protectionSet(directory, input);
+	const owned = /* @__PURE__ */ new Set();
+	for (const name of input.tempFiles ?? []) if (isSafeEntryName(name)) owned.add(name);
+	for (const name of input.writtenThisAttempt) {
+		if (!isSafeEntryName(name)) continue;
+		if (input.preExisting.has(name)) continue;
+		if (finalized.has(name)) continue;
+		owned.add(name);
+	}
+	if (input.publishedMetadata) await settlePublishedMetadata(directory, input);
+	await Promise.all([...owned].map((name) => removeOwnedEntry(directory, name)));
+}
+/**
+* Publish the attempt index. Like page writes, every await is followed by a deadline check:
+* cancellation while the temp file is being written must never rename metadata into place, and an
+* abort right after the rename is still surfaced to the caller. The caller then withdraws its own
+* index and restores the prior finalized bytes it captured before this rename.
+*/
+async function writeFetchMetadata(directory, serialized, signal, observer) {
+	const finalPath = join(directory, "metadata.json");
+	const tempName = `.metadata.json.${randomSuffix()}.tmp`;
+	const tempPath = join(directory, tempName);
+	signal?.throwIfAborted();
+	observer?.onTempFile?.(tempName);
+	try {
+		await writeFile(tempPath, serialized, {
+			encoding: "utf8",
+			mode: 384,
+			flag: "wx",
+			signal
+		});
+		signal?.throwIfAborted();
+		await rename(tempPath, finalPath);
+		observer?.onPublished?.("metadata.json");
+		signal?.throwIfAborted();
+		const stat = await lstat(finalPath);
+		if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("The web metadata failed verification");
+		signal?.throwIfAborted();
+	} catch (error) {
+		await rm(tempPath, { force: true }).catch(() => void 0);
+		throw error instanceof Error ? error : /* @__PURE__ */ new Error("The web metadata write failed");
+	}
+}
+function searchOutput(result) {
+	const results = result.results;
+	const lines = [`web_search ok — ${results.length} source(s); requestId ${String(result.requestId)}; retrievedAt ${String(result.retrievedAt)}; depth ${String(result.effectiveDepth)}.`, "Snippets are provider search snippets for source selection, not page content."];
+	results.forEach((item, index) => {
+		const published = typeof item.publishedAt === "string" ? `; published ${item.publishedAt}` : "";
+		lines.push(`\n[${index + 1}] ${typeof item.title === "string" && item.title ? item.title : "(untitled)"}`, `URL: ${String(item.url)}${published}`, String(item.snippet ?? ""));
+	});
+	return truncateToByteBudget(lines.join("\n"), WEB_EXTENSION_LIMITS.toolResultMaxBytes);
+}
+/** Details artifact records returned to Pi: same combined truncation flag as the metadata. */
+function artifactDetails(artifacts) {
+	return artifacts.map((artifact) => ({
+		path: artifact.relativePath,
+		bytes: artifact.bytes,
+		sha256: artifact.sha256,
+		artifactTruncated: artifact.artifactTruncated
+	}));
+}
+/** Every requested URL failed: the batch is an operation failure, not a partial success. */
+function allFailedError(items) {
+	const codes = items.map((item) => `${item.url}: ${String(item.code)}${item.retryable ? " (retryable)" : ""}`);
+	return /* @__PURE__ */ new Error(`web_fetch failed for every requested URL — ${truncateToByteBudget(codes.join("; "), 512).text}`);
+}
+/** One page's report section: metadata lines, flags, and the bounded preview. */
+function pageSection(index, item, content, saved) {
+	const preview = truncateToByteBudget(content, WEB_EXTENSION_LIMITS.previewPageMaxBytes);
+	const flags = ["completeness unknown (extracted content, not raw HTML)"];
+	if (preview.truncated || item.previewTruncated === true) flags.push("preview truncated");
+	if (saved?.artifactTruncated || item.artifactTruncated === true) flags.push("stored content truncated");
+	if (item.upstreamTruncated === true) flags.push("upstream truncated");
+	if (item.upstreamTruncated === null || item.upstreamTruncated === void 0) flags.push("upstream truncation unknown");
+	return [
+		`\n[${index + 1}] ${item.url} — ${item.status}`,
+		`finalUrl: ${item.finalUrl ?? "unknown"}; sourceFetchedAt: ${item.sourceFetchedAt ?? "unknown"}`,
+		saved ? `saved: ${saved.relativePath} (${saved.bytes} bytes, sha256:${saved.sha256})` : "saved: none (artifact write failed; content exists only in this preview)",
+		`flags: ${flags.join("; ")}`,
+		"preview:",
+		preview.text
+	];
+}
+/** The attempt index, including the combined upstream + local truncation flag per page. */
+function buildFetchMetadata(result, toolCallId, pages, results) {
+	return {
+		version: 1,
+		toolCallId,
+		requestId: String(result.requestId),
+		retrievedAt: String(result.retrievedAt),
+		effectiveDepth: String(result.effectiveDepth),
+		pages: pages.map((page) => ({
+			index: page.index,
+			url: page.item.url,
+			file: page.artifact.relativePath.split("/").pop() ?? "",
+			bytes: page.artifact.bytes,
+			sha256: page.artifact.sha256,
+			artifactTruncated: page.artifact.artifactTruncated,
+			upstreamTruncated: page.item.upstreamTruncated ?? null,
+			finalUrl: page.item.finalUrl ?? null,
+			sourceFetchedAt: page.item.sourceFetchedAt ?? null,
+			completeness: "unknown"
+		})),
+		failures: results.filter((item) => item.status === "failed").map((item) => ({
+			url: item.url,
+			code: String(item.code),
+			retryable: item.retryable === true
+		}))
+	};
+}
+/** Save one non-failed page with the combined truncation flag; abort always propagates. */
+async function saveOnePage(input) {
+	try {
+		const saved = await saveWebArtifact({
+			cwd: input.cwd,
+			toolCallId: input.toolCallId,
+			fileName: `page-${input.index}.md`,
+			content: input.content,
+			signal: input.signal,
+			observer: input.observer
+		});
+		return {
+			saved: {
+				...saved,
+				artifactTruncated: saved.artifactTruncated || input.item.artifactTruncated === true
+			},
+			writeFailed: false
+		};
+	} catch (error) {
+		if (input.signal.aborted) throw error;
+		return { writeFailed: true };
+	}
+}
+function createAttemptLedger() {
+	const tempFiles = /* @__PURE__ */ new Set();
+	const writtenThisAttempt = /* @__PURE__ */ new Set();
+	return {
+		tempFiles,
+		writtenThisAttempt,
+		metadataPublished: false,
+		publishedMetadataDigest: void 0,
+		priorMetadata: void 0,
+		observer: {
+			onTempFile: (name) => {
+				tempFiles.add(name);
+			},
+			onPublished: (name) => {
+				writtenThisAttempt.add(name);
+			}
+		}
+	};
+}
+function fetchHeader(result, results) {
+	return `web_fetch ${String(result.status)} — ${results.length} URL result(s); requestId ${String(result.requestId)}; retrievedAt ${String(result.retrievedAt)}; depth ${String(result.effectiveDepth)}.`;
+}
+/** Open the attempt store up front so pre-existing files are known before any write. */
+async function openAttemptStore(cwd, toolCallId, signal) {
+	const directory = await openArtifactDirectory(cwd, toolCallId, signal);
+	return {
+		directory,
+		preExisting: new Set(await readdir(directory).catch(() => []))
+	};
+}
+function failedPageSection(index, item) {
+	return `\n[${index + 1}] ${item.url} — FAILED: ${String(item.code)}${item.retryable ? " (retryable with a new call)" : ""}`;
+}
+/**
+* Save every non-failed page for this attempt and build its report sections. A genuine write
+* failure is counted and reported; an abort always propagates so the caller never sees success.
+*/
+async function saveResultPages(results, toolCallId, cwd, signal, ledger) {
+	const artifacts = [];
+	const pages = [];
+	const sections = [];
+	let artifactWriteFailures = 0;
+	for (const [index, item] of results.entries()) {
+		signal.throwIfAborted();
+		if (item.status === "failed") {
+			sections.push(failedPageSection(index, item));
+			continue;
+		}
+		const content = typeof item.content === "string" ? item.content : "";
+		const { saved, writeFailed } = await saveOnePage({
+			cwd,
+			toolCallId,
+			index,
+			item,
+			content,
+			signal,
+			observer: ledger.observer
+		});
+		if (writeFailed) artifactWriteFailures += 1;
+		if (saved) {
+			artifacts.push(saved);
+			pages.push({
+				index,
+				item,
+				artifact: saved
+			});
+		}
+		sections.push(...pageSection(index, item, content, saved));
+	}
+	return {
+		artifacts,
+		pages,
+		sections,
+		artifactWriteFailures
+	};
+}
+/**
+* Publish the attempt index. A cancellation during the temp write is rethrown (never a degraded
+* success); only a genuine non-abort write failure returns `failed: true`.
+*/
+async function publishAttemptMetadata(directory, result, toolCallId, pages, results, signal, ledger) {
+	const metadata = buildFetchMetadata(result, toolCallId, pages, results);
+	const serialized = `${JSON.stringify(metadata, void 0, 2)}\n`;
+	const digest = sha256Hex(Buffer.from(serialized, "utf8"));
+	const prior = await readBoundedRegularFile(join(directory, "metadata.json"), METADATA_READ_MAX_BYTES, signal);
+	if (prior.kind === "oversize" || prior.kind === "unsafe") throw new Error("The existing web metadata is not a bounded regular file");
+	ledger.priorMetadata = prior.kind === "regular" ? prior.bytes : void 0;
+	try {
+		await writeFetchMetadata(directory, serialized, signal, {
+			onTempFile: (name) => {
+				ledger.tempFiles.add(name);
+			},
+			onPublished: () => {
+				ledger.metadataPublished = true;
+				ledger.publishedMetadataDigest = digest;
+			}
+		});
+		return {
+			written: true,
+			failed: false
+		};
+	} catch (error) {
+		if (signal.aborted) throw error;
+		return {
+			written: false,
+			failed: true
+		};
+	}
+}
+async function cleanupAttempt(cwd, toolCallId, preExisting, ledger) {
+	await cleanupWebArtifacts({
+		cwd,
+		toolCallId,
+		preExisting,
+		writtenThisAttempt: ledger.writtenThisAttempt,
+		tempFiles: ledger.tempFiles,
+		publishedMetadata: ledger.metadataPublished,
+		priorMetadata: ledger.priorMetadata,
+		publishedMetadataDigest: ledger.publishedMetadataDigest
+	});
+}
+/** One final truncation covers framing AND suffix: the total never exceeds the tool bound. */
+function assembleFetchText(sections, artifactWriteFailures) {
+	const suffix = artifactWriteFailures > 0 ? `\n${artifactWriteFailures} artifact write(s) failed; no fabricated paths are reported.` : "";
+	return truncateToByteBudget(`${sections.join("\n")}${suffix}`, WEB_EXTENSION_LIMITS.toolResultMaxBytes).text;
+}
+async function fetchOutput(result, toolCallId, cwd, signal) {
+	const results = result.results;
+	const ledger = createAttemptLedger();
+	const sections = [fetchHeader(result, results)];
+	let directory;
+	let preExisting = /* @__PURE__ */ new Set();
+	try {
+		signal.throwIfAborted();
+		if (results.some((item) => item.status !== "failed")) {
+			const store = await openAttemptStore(cwd, toolCallId, signal);
+			directory = store.directory;
+			preExisting = store.preExisting;
+		}
+		const pageOutcome = await saveResultPages(results, toolCallId, cwd, signal, ledger);
+		sections.push(...pageOutcome.sections);
+		signal.throwIfAborted();
+		let artifactWriteFailures = pageOutcome.artifactWriteFailures;
+		let metadataWritten = false;
+		if (directory && pageOutcome.pages.length > 0) {
+			const published = await publishAttemptMetadata(directory, result, toolCallId, pageOutcome.pages, results, signal, ledger);
+			metadataWritten = published.written;
+			if (published.written) sections.push(`\nmetadata: .opentag/web/${toolCallId}/metadata.json`);
+			else if (published.failed) {
+				artifactWriteFailures += 1;
+				sections.push("\nmetadata: write failed (page files above remain saved)");
+			}
+		}
+		signal.throwIfAborted();
+		return {
+			text: assembleFetchText(sections, artifactWriteFailures),
+			artifacts: pageOutcome.artifacts,
+			artifactWriteFailures,
+			metadataWritten
+		};
+	} catch (error) {
+		await cleanupAttempt(cwd, toolCallId, preExisting, ledger);
+		throw error;
+	}
+}
+function errorEnvelope(body) {
+	try {
+		const parsed = JSON.parse(body.toString("utf8"));
+		if (typeof parsed?.error?.code !== "string") return void 0;
+		return {
+			code: parsed.error.code,
+			retryable: parsed.error.retryable === true
+		};
+	} catch {
+		return;
+	}
+}
+function boundedString(value, maxBytes) {
+	return typeof value === "string" && Buffer.byteLength(value, "utf8") <= maxBytes;
+}
+const INVALID_WIRE_PAYLOAD = "The web gateway returned an invalid payload";
+function invalidWirePayload() {
+	return /* @__PURE__ */ new Error(INVALID_WIRE_PAYLOAD);
+}
+function isPlainRecord(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function requireBoundedString(value, maxBytes) {
+	if (!boundedString(value, maxBytes)) throw invalidWirePayload();
+	return value;
+}
+function requireNonEmptyBoundedString(value, maxBytes) {
+	const text = requireBoundedString(value, maxBytes);
+	if (text.length === 0) throw invalidWirePayload();
+	return text;
+}
+/** Shared envelope: request id, retrieval time, depth, and the results array shape. */
+function assertWireEnvelope(record) {
+	requireNonEmptyBoundedString(record.requestId, 128);
+	requireBoundedString(record.retrievedAt, 64);
+	if (record.effectiveDepth !== "basic" && record.effectiveDepth !== "advanced") throw invalidWirePayload();
+	if (!Array.isArray(record.results)) throw invalidWirePayload();
+}
+function assertSearchWireItem(value) {
+	if (!isPlainRecord(value)) throw invalidWirePayload();
+	requireNonEmptyBoundedString(value.sourceId, 128);
+	requireBoundedString(value.title, 2048);
+	requireNonEmptyBoundedString(value.url, WEB_EXTENSION_LIMITS.urlMaxBytes);
+	requireBoundedString(value.snippet, 8192);
+	if (value.publishedAt !== void 0 && !boundedString(value.publishedAt, 128)) throw invalidWirePayload();
+}
+function assertFailedFetchWireItem(item) {
+	requireNonEmptyBoundedString(item.code, 64);
+	if (typeof item.retryable !== "boolean") throw invalidWirePayload();
+}
+function assertContentFetchWireItem(item) {
+	if (item.status !== "ok" && item.status !== "partial") throw invalidWirePayload();
+	if (item.contentKind !== "extracted" || item.completeness !== "unknown") throw invalidWirePayload();
+	requireBoundedString(item.content, WEB_EXTENSION_LIMITS.pageBodyMaxBytes);
+	if (item.finalUrl !== null && !boundedString(item.finalUrl, WEB_EXTENSION_LIMITS.urlMaxBytes)) throw invalidWirePayload();
+	if (item.sourceFetchedAt !== null && !boundedString(item.sourceFetchedAt, 64)) throw invalidWirePayload();
+	if (item.upstreamTruncated !== null && typeof item.upstreamTruncated !== "boolean") throw invalidWirePayload();
+	if (typeof item.previewTruncated !== "boolean" || typeof item.artifactTruncated !== "boolean") throw invalidWirePayload();
+}
+function assertFetchWireItem(value) {
+	if (!isPlainRecord(value)) throw invalidWirePayload();
+	requireNonEmptyBoundedString(value.url, WEB_EXTENSION_LIMITS.urlMaxBytes);
+	if (value.status === "failed") {
+		assertFailedFetchWireItem(value);
+		return;
+	}
+	assertContentFetchWireItem(value);
+}
+function assertSearchWireResult(record, results) {
+	if (record.status !== "ok") throw invalidWirePayload();
+	if (results.length > 25) throw invalidWirePayload();
+	for (const item of results) assertSearchWireItem(item);
+}
+function assertFetchWireResult(record, results) {
+	if (![
+		"ok",
+		"partial",
+		"failed"
+	].includes(String(record.status))) throw invalidWirePayload();
+	if (results.length > WEB_EXTENSION_LIMITS.fetchUrlsMax) throw invalidWirePayload();
+	for (const item of results) assertFetchWireItem(item);
+}
+/**
+* Defensive wire validation (the trusted gateway/client hold the authoritative shared schemas).
+* Enough shape and bounds are checked here to prevent mislabeled or synthetic successes.
+*/
+function assertWireResult(value, kind) {
+	if (!isPlainRecord(value)) throw invalidWirePayload();
+	assertWireEnvelope(value);
+	const results = value.results;
+	if (kind === "search") assertSearchWireResult(value, results);
+	else assertFetchWireResult(value, results);
+	return value;
+}
+function normalizeUrl(raw) {
+	try {
+		const url = new URL(raw);
+		url.hash = "";
+		if (url.protocol === "http:" && url.port === "80" || url.protocol === "https:" && url.port === "443") url.port = "";
+		return url.toString();
+	} catch {
+		return;
+	}
+}
+/**
+* Results must correspond exactly to the requested URLs after documented normalization/dedup
+* (fragment removed, host case/default ports normalized): every item matches one unclaimed
+* request, none are missing, and duplicates never borrow another URL's content.
+*/
+function requestedUrlsMatch(urls, results) {
+	const expected = /* @__PURE__ */ new Map();
+	for (const url of urls) {
+		const normalized = normalizeUrl(url);
+		if (normalized) expected.set(normalized, (expected.get(normalized) ?? 0) + 1);
+	}
+	const seen = /* @__PURE__ */ new Set();
+	for (const item of results) {
+		const normalized = normalizeUrl(item.url);
+		if (!normalized || !expected.has(normalized) || seen.has(normalized)) throw new Error("The web gateway returned a result for an unrequested or duplicated URL");
+		seen.add(normalized);
+	}
+	if (seen.size !== expected.size) throw new Error("The web gateway omitted a requested URL from the results");
+}
+/** Validate the HTTP status and parse a successful JSON reply; failures stay bounded/redacted. */
+function requireWebSuccessReply(operation, reply) {
+	if (reply.status !== 200) {
+		const failure = errorEnvelope(reply.body);
+		throw new Error(`${operation} failed: ${failure?.code ?? `http_${reply.status}`}${failure?.retryable ? " (retryable)" : ""}`);
+	}
+	return JSON.parse(reply.body.toString("utf8"));
+}
+/** Optional search fields are included only when the caller supplied them. */
+function searchRequestBody(toolCallId, params) {
+	return {
+		protocolVersion: WEB_EXTENSION_LIMITS.protocolVersion,
+		toolCallId,
+		query: params.query,
+		...params.limit !== void 0 ? { limit: params.limit } : {},
+		...params.domains ? { domains: params.domains } : {},
+		...params.timeRange ? { timeRange: params.timeRange } : {},
+		...params.language ? { language: params.language } : {},
+		depth: params.depth === "advanced" ? "advanced" : "basic"
+	};
+}
+function openTagWebTools(pi) {
+	const socketPath = process.env[ENDPOINT_ENV];
+	if (!socketPath) return;
+	pi.registerTool({
+		name: "web_search",
+		label: "Web Search",
+		description: "Search the public web through OpenTag's managed provider. Returns bounded source snippets for selection; use web_fetch on chosen URLs for page content. depth=advanced costs more and must be chosen explicitly. No automatic retries; a failed call may be retried as a new explicit call when marked retryable.",
+		parameters: WEB_SEARCH_PARAMETERS,
+		async execute(runtimeToolCallId, rawParams, signal, _onUpdate, _ctx) {
+			const params = rawParams;
+			const toolCallId = deriveWebToolIdentity(socketPath, runtimeToolCallId);
+			const deadline = startOperationDeadline(WEB_EXTENSION_LIMITS.searchTimeoutMs, signal);
+			try {
+				const reply = await postToGateway(socketPath, "/web/search", searchRequestBody(toolCallId, params), {
+					deadlineAtMs: deadline.deadlineAtMs,
+					signal: deadline.signal,
+					maxResponseBytes: WEB_EXTENSION_LIMITS.searchResponseMaxBytes
+				});
+				deadline.signal.throwIfAborted();
+				const result = assertWireResult(requireWebSuccessReply("web_search", reply), "search");
+				const output = searchOutput(result);
+				deadline.signal.throwIfAborted();
+				return {
+					content: [{
+						type: "text",
+						text: output.text
+					}],
+					details: {
+						requestId: String(result.requestId),
+						status: "ok",
+						sourceCount: result.results.length,
+						truncated: output.truncated
+					}
+				};
+			} finally {
+				deadline.dispose();
+			}
+		}
+	});
+	pi.registerTool({
+		name: "web_fetch",
+		label: "Web Fetch",
+		description: "Extract page content for 1–3 public http(s) URLs through OpenTag's managed provider. Content is the provider's extraction (not raw HTML; completeness unknown). Full pages are saved under the Session workspace .opentag/web/ with sha256 metadata; previews are bounded. HTTP 200 can still contain per-URL failures — read every item. depth=advanced costs more and must be chosen explicitly.",
+		parameters: WEB_FETCH_PARAMETERS,
+		async execute(runtimeToolCallId, rawParams, signal, _onUpdate, ctx) {
+			const params = rawParams;
+			const toolCallId = deriveWebToolIdentity(socketPath, runtimeToolCallId);
+			const deadline = startOperationDeadline(WEB_EXTENSION_LIMITS.fetchTimeoutMs, signal);
+			try {
+				const reply = await postToGateway(socketPath, "/web/fetch", {
+					protocolVersion: WEB_EXTENSION_LIMITS.protocolVersion,
+					toolCallId,
+					urls: params.urls,
+					depth: params.depth === "advanced" ? "advanced" : "basic"
+				}, {
+					deadlineAtMs: deadline.deadlineAtMs,
+					signal: deadline.signal,
+					maxResponseBytes: WEB_EXTENSION_LIMITS.fetchResponseMaxBytes
+				});
+				deadline.signal.throwIfAborted();
+				const result = assertWireResult(requireWebSuccessReply("web_fetch", reply), "fetch");
+				const items = result.results;
+				requestedUrlsMatch(params.urls, items);
+				if (items.length === 0 || items.every((item) => item.status === "failed")) throw allFailedError(items);
+				const output = await fetchOutput(result, toolCallId, ctx.cwd, deadline.signal);
+				deadline.signal.throwIfAborted();
+				return {
+					content: [{
+						type: "text",
+						text: output.text
+					}],
+					details: {
+						requestId: String(result.requestId),
+						status: String(result.status),
+						artifacts: artifactDetails(output.artifacts),
+						artifactWriteFailures: output.artifactWriteFailures,
+						metadataWritten: output.metadataWritten
+					}
+				};
+			} finally {
+				deadline.dispose();
+			}
+		}
+	});
+}
+//#endregion
+export { WEB_EXTENSION_LIMITS, WEB_FETCH_PARAMETERS, WEB_SEARCH_PARAMETERS, cleanupWebArtifacts, openTagWebTools as default, deriveWebToolIdentity, saveWebArtifact, truncateToByteBudget };
+
+//# sourceMappingURL=web-tools.mjs.map