@asterxsk/kiln 0.1.0 → 0.3.0

package/agent.bak.20260905-190020/extensions/pi-web-access/declared-web-links.ts

@@ -0,0 +1,173 @@
+const MAX_DECLARED_LINKS = 20;
+const MAX_DECLARED_URL_LENGTH = 4096;
+const DECLARATION_RELATIONS = new Set([
+	"api-catalog",
+	"describedby",
+	"service-desc",
+	"service-doc",
+	"service-meta",
+]);
+
+const RELATION_LABELS: Record<string, string> = {
+	"api-catalog": "API catalog",
+	"describedby": "Description",
+	"service-desc": "Service description",
+	"service-doc": "Service documentation",
+	"service-meta": "Service metadata",
+};
+
+export interface DeclaredWebLink {
+	url: string;
+	relations: string[];
+	type?: string;
+}
+
+export function discoverDeclaredWebLinks(
+	document: Document,
+	linkHeader: string | null,
+	responseUrl: string,
+): DeclaredWebLink[] {
+	const links = new Map<string, DeclaredWebLink>();
+	for (const value of splitLinkHeader(linkHeader ?? "")) {
+		const target = /^\s*<([^>]*)>/.exec(value);
+		if (!target) continue;
+		const parameters = parseLinkParameters(value.slice(target[0].length));
+		if (!parameters || parameters.has("anchor")) continue;
+		addDeclaredLink(links, {
+			url: resolveHttpUrl(target[1], responseUrl),
+			relations: declaredRelations(parameters.get("rel")),
+			type: parameters.get("type"),
+		});
+		if (links.size >= MAX_DECLARED_LINKS) break;
+	}
+
+	if (links.size < MAX_DECLARED_LINKS) {
+		const declaredBase = document.querySelector("base[href]")?.getAttribute("href");
+		const documentBase = resolveHttpUrl(declaredBase, responseUrl) ?? responseUrl;
+		for (const element of document.querySelectorAll("link[rel][href], a[rel][href]")) {
+			addDeclaredLink(links, {
+				url: resolveHttpUrl(element.getAttribute("href"), documentBase),
+				relations: declaredRelations(element.getAttribute("rel")),
+				type: element.getAttribute("type"),
+			});
+			if (links.size >= MAX_DECLARED_LINKS) break;
+		}
+	}
+
+	return [...links.values()];
+}
+
+export function appendDeclaredWebLinks(content: string, links: DeclaredWebLink[]): string {
+	if (links.length === 0) return content;
+	const section = [
+		"## Declared links",
+		"",
+		...links.map(formatDeclaredLink),
+	].join("\n");
+	return content.trim() ? `${content.trim()}\n\n${section}` : section;
+}
+
+function addDeclaredLink(
+	links: Map<string, DeclaredWebLink>,
+	candidate: { url: string | null; relations: string[]; type?: string | null },
+): void {
+	if (!candidate.url || candidate.relations.length === 0) return;
+	const existing = links.get(candidate.url);
+	if (existing) {
+		for (const relation of candidate.relations) {
+			if (!existing.relations.includes(relation)) existing.relations.push(relation);
+		}
+		if (!existing.type) existing.type = normalizeMetadata(candidate.type);
+		return;
+	}
+	if (links.size >= MAX_DECLARED_LINKS) return;
+	const type = normalizeMetadata(candidate.type);
+	links.set(candidate.url, {
+		url: candidate.url,
+		relations: candidate.relations,
+		...(type ? { type } : {}),
+	});
+}
+
+function declaredRelations(value: string | null | undefined): string[] {
+	if (!value) return [];
+	return [...new Set(
+		value.trim().toLowerCase().split(/\s+/).filter((relation) => DECLARATION_RELATIONS.has(relation)),
+	)];
+}
+
+function resolveHttpUrl(value: string | null | undefined, baseUrl: string): string | null {
+	if (!value || value.length > MAX_DECLARED_URL_LENGTH) return null;
+	try {
+		const url = new URL(value, baseUrl);
+		if (url.href.length > MAX_DECLARED_URL_LENGTH) return null;
+		return url.protocol === "http:" || url.protocol === "https:" ? url.href : null;
+	} catch {
+		return null;
+	}
+}
+
+function splitOutsideSyntax(input: string, separator: string, protectTargets: boolean): string[] | null {
+	const parts: string[] = [];
+	let start = 0;
+	let inTarget = false;
+	let inQuotes = false;
+	let escaped = false;
+	for (let index = 0; index < input.length; index++) {
+		const character = input[index];
+		if (inQuotes) {
+			if (escaped) escaped = false;
+			else if (character === "\\") escaped = true;
+			else if (character === '"') inQuotes = false;
+			continue;
+		}
+		if (character === '"' && !inTarget) inQuotes = true;
+		else if (protectTargets && character === "<") inTarget = true;
+		else if (protectTargets && character === ">") inTarget = false;
+		else if (character === separator && !inTarget) {
+			parts.push(input.slice(start, index));
+			start = index + 1;
+		}
+	}
+	if (inQuotes || inTarget) return null;
+	parts.push(input.slice(start));
+	return parts;
+}
+
+function splitLinkHeader(header: string): string[] {
+	return (splitOutsideSyntax(header, ",", true) ?? [])
+		.map((value) => value.trim())
+		.filter(Boolean);
+}
+
+function parseLinkParameters(input: string): Map<string, string> | null {
+	const parts = splitOutsideSyntax(input, ";", false);
+	if (!parts || parts.shift()?.trim()) return null;
+
+	const parameters = new Map<string, string>();
+	for (const part of parts) {
+		const match = /^\s*([!#$%&'*+\-.^_`|~A-Za-z0-9]+)(?:\s*=\s*(?:"((?:\\.|[^"])*)"|(\S+)))?\s*$/.exec(part);
+		if (!match) return null;
+		const name = match[1].toLowerCase();
+		const value = match[2] === undefined ? (match[3] ?? "") : match[2].replace(/\\(.)/g, "$1");
+		if (!parameters.has(name)) parameters.set(name, value);
+	}
+	return parameters;
+}
+
+function normalizeMetadata(value: string | null | undefined): string | undefined {
+	if (!value) return undefined;
+	const normalized = value.replace(/\s+/g, " ").trim().slice(0, 160);
+	return normalized || undefined;
+}
+
+function formatDeclaredLink(link: DeclaredWebLink): string {
+	const relation = link.relations.map(inlineCode).join(", ");
+	const type = link.type ? `; ${inlineCode(link.type)}` : "";
+	const label = RELATION_LABELS[link.relations[0]] ?? "Declared link";
+	return `- ${label} (${relation}${type}): <${link.url}>`;
+}
+
+function inlineCode(value: string): string {
+	return `\`${value.replace(/`/g, "'")}\``;
+}

package/agent.bak.20260905-190020/extensions/pi-web-access/evidence/CONTRACT-EVIDENCE.md

@@ -0,0 +1,496 @@
+# SERPdive API — contract evidence
+
+Every block below is a real call against `https://api.serpdive.com/v1/search`, captured on 2026-07-25. Reproduce any of them with your own key: the script that
+generated this file is `evidence/contract-probe.mjs`. Page content is truncated to keep the file
+readable — nothing else is edited, and the API key is redacted.
+
+---
+
+## 1. Default request and response shape
+
+### Query only
+
+The whole request surface is `query`, `model`, `answer`, `max_results`. Everything else is ignored.
+
+```http
+POST https://api.serpdive.com/v1/search
+authorization: Bearer sd_live_…            # a valid key, redacted
+content-type: application/json
+
+{"query":"best open source vector databases"}
+```
+
+`HTTP 200` in 2059 ms
+
+```json
+{
+  "query": "best open source vector databases",
+  "model": "mako",
+  "response_time_ms": 1906,
+  "results": [
+    {
+      "url": "https://www.instaclustr.com/education/vector-database/best-open-source-vector-database-solutions-top-5-in-2026/",
+      "title": "Best open source vector database solutions: Top 5 in 2026",
+      "content": "Notable open source vector database solutions · 1. Opensearch · 2. Apache Cassandra · 3. p… (431 chars)"
+    },
+    {
+      "url": "https://redis.io/blog/best-open-source-vector-databases-comparison/",
+      "title": "Comparing the best open source vector databases (2026)",
+      "content": "Chroma prioritizes simplicity and developer experience, particularly for Python workflows.… (90 chars)"
+    },
+    "… 5 more, same shape"
+  ]
+}
+```
+
+## 2. Models
+
+### krill — free tier
+
+No answer synthesis on this tier: requesting one is ignored rather than refused (see §3).
+
+```http
+POST https://api.serpdive.com/v1/search
+authorization: Bearer sd_live_…            # a valid key, redacted
+content-type: application/json
+
+{"query":"best open source vector databases","model":"krill"}
+```
+
+`HTTP 200` in 2145 ms
+
+```json
+{
+  "query": "best open source vector databases",
+  "model": "krill",
+  "response_time_ms": 2113,
+  "results": [
+    {
+      "url": "https://www.instaclustr.com/education/vector-database/best-open-source-vector-database-solutions-top-5-in-2026/",
+      "title": "Best open source vector database solutions: Top 5 in 2026",
+      "content": "Notable open source vector database solutions · 1. Opensearch · 2. Apache Cassandra · 3. p… (213 chars)"
+    },
+    {
+      "url": "https://redis.io/blog/best-open-source-vector-databases-comparison/",
+      "title": "Comparing the best open source vector databases (2026)",
+      "content": "This comparison breaks down the leading open source vector databases for production AI wor… (190 chars)"
+    },
+    "… 3 more, same shape"
+  ]
+}
+```
+
+### mako — 1 credit
+
+```http
+POST https://api.serpdive.com/v1/search
+authorization: Bearer sd_live_…            # a valid key, redacted
+content-type: application/json
+
+{"query":"best open source vector databases","model":"mako"}
+```
+
+`HTTP 200` in 1976 ms
+
+```json
+{
+  "query": "best open source vector databases",
+  "model": "mako",
+  "response_time_ms": 1941,
+  "results": [
+    {
+      "url": "https://www.instaclustr.com/education/vector-database/best-open-source-vector-database-solutions-top-5-in-2026/",
+      "title": "Best open source vector database solutions: Top 5 in 2026",
+      "content": "Notable open source vector database solutions · 1. Opensearch · 2. Apache Cassandra · 3. p… (713 chars)"
+    },
+    {
+      "url": "https://redis.io/blog/best-open-source-vector-databases-comparison/",
+      "title": "Comparing the best open source vector databases (2026)",
+      "content": "This comparison breaks down the leading open source vector databases for production AI wor… (457 chars)"
+    },
+    "… 3 more, same shape"
+  ]
+}
+```
+
+### moby — 1.5 credits
+
+Full readable page content; note the content lengths against mako above.
+
+```http
+POST https://api.serpdive.com/v1/search
+authorization: Bearer sd_live_…            # a valid key, redacted
+content-type: application/json
+
+{"query":"best open source vector databases","model":"moby"}
+```
+
+`HTTP 200` in 2647 ms
+
+```json
+{
+  "query": "best open source vector databases",
+  "model": "moby",
+  "response_time_ms": 2561,
+  "results": [
+    {
+      "url": "https://www.instaclustr.com/education/vector-database/best-open-source-vector-database-solutions-top-5-in-2026/",
+      "title": "Best open source vector database solutions: Top 5 in 2026",
+      "content": "Notable open source vector database solutions · 1. Opensearch · 2. Apache Cassandra · 3. p… (14041 chars)"
+    },
+    {
+      "url": "https://redis.io/blog/best-open-source-vector-databases-comparison/",
+      "title": "Comparing the best open source vector databases (2026)",
+      "content": "Serve your agents fresh data at Redis speed.\nComparing the best open source vector databas… (13856 chars)"
+    },
+    "… 4 more, same shape"
+  ]
+}
+```
+
+## 3. `answer`
+
+### answer: true with mako
+
+The `answer` key is present only when requested.
+
+```http
+POST https://api.serpdive.com/v1/search
+authorization: Bearer sd_live_…            # a valid key, redacted
+content-type: application/json
+
+{"query":"best open source vector databases","model":"mako","answer":true}
+```
+
+`HTTP 200` in 2490 ms
+
+```json
+{
+  "query": "best open source vector databases",
+  "model": "mako",
+  "response_time_ms": 2456,
+  "answer": "The best open source vector databases are: \n1. Opensearch \n2. Apache Cassandra \n3. pgvector \n4. Milvus \n5. Qdrant \n6. Weaviate \n7. Vald.… (136 chars)",
+  "results": [
+    {
+      "url": "https://www.instaclustr.com/education/vector-database/best-open-source-vector-database-solutions-top-5-in-2026/",
+      "title": "Best open source vector database solutions: Top 5 in 2026",
+      "content": "Notable open source vector database solutions · 1. Opensearch · 2. Apache Cassandra · 3. p… (529 chars)"
+    },
+    {
+      "url": "https://redis.io/blog/best-open-source-vector-databases-comparison/",
+      "title": "Comparing the best open source vector databases (2026)",
+      "content": "This comparison breaks down the leading open source vector databases for production AI wor… (591 chars)"
+    },
+    "… 3 more, same shape"
+  ]
+}
+```
+
+### answer: true with krill
+
+Silently ignored on the free tier — no `answer` key, no error, still a complete result.
+
+```http
+POST https://api.serpdive.com/v1/search
+authorization: Bearer sd_live_…            # a valid key, redacted
+content-type: application/json
+
+{"query":"best open source vector databases","model":"krill","answer":true}
+```
+
+`HTTP 200` in 1642 ms
+
+```json
+{
+  "query": "best open source vector databases",
+  "model": "krill",
+  "response_time_ms": 1612,
+  "results": [
+    {
+      "url": "https://www.instaclustr.com/education/vector-database/best-open-source-vector-database-solutions-top-5-in-2026/",
+      "title": "Best open source vector database solutions: Top 5 in 2026",
+      "content": "Notable open source vector database solutions · 1. Opensearch · 2. Apache Cassandra · 3. p… (322 chars)"
+    },
+    {
+      "url": "https://redis.io/blog/best-open-source-vector-databases-comparison/",
+      "title": "Comparing the best open source vector databases (2026)",
+      "content": "This comparison breaks down the leading open source vector databases for production AI wor… (293 chars)"
+    },
+    "… 2 more, same shape"
+  ]
+}
+```
+
+## 4. `max_results` is a cap, never a minimum
+
+A cap, applied at the edge after the search. The engine still reads a full corpus, so a small
+cap trims the response, not the work — and asking for more does not produce more.
+
+### max_results: 1
+
+```http
+POST https://api.serpdive.com/v1/search
+authorization: Bearer sd_live_…            # a valid key, redacted
+content-type: application/json
+
+{"query":"best open source vector databases","model":"krill","max_results":1}
+```
+
+`HTTP 200` in 1697 ms
+
+```json
+{
+  "query": "best open source vector databases",
+  "model": "krill",
+  "response_time_ms": 1665,
+  "results": [
+    {
+      "url": "https://www.instaclustr.com/education/vector-database/best-open-source-vector-database-solutions-top-5-in-2026/",
+      "title": "Best open source vector database solutions: Top 5 in 2026",
+      "content": "Notable open source vector database solutions · 1. Opensearch · 2. Apache Cassandra · 3. p… (213 chars)"
+    }
+  ]
+}
+```
+
+### max_results: 3
+
+```http
+POST https://api.serpdive.com/v1/search
+authorization: Bearer sd_live_…            # a valid key, redacted
+content-type: application/json
+
+{"query":"best open source vector databases","model":"krill","max_results":3}
+```
+
+`HTTP 200` in 1725 ms
+
+```json
+{
+  "query": "best open source vector databases",
+  "model": "krill",
+  "response_time_ms": 1681,
+  "results": [
+    {
+      "url": "https://www.instaclustr.com/education/vector-database/best-open-source-vector-database-solutions-top-5-in-2026/",
+      "title": "Best open source vector database solutions: Top 5 in 2026",
+      "content": "Notable open source vector database solutions · 1. Opensearch · 2. Apache Cassandra · 3. p… (634 chars)"
+    },
+    {
+      "url": "https://redis.io/blog/best-open-source-vector-databases-comparison/",
+      "title": "Comparing the best open source vector databases (2026)",
+      "content": "Some vector databases work best with Kubernetes orchestration, while others offer cloud-ho… (182 chars)"
+    },
+    "… 1 more, same shape"
+  ]
+}
+```
+
+### max_results: 10
+
+The ceiling of the range. Fewer come back when fewer are judged relevant — see §1, where no cap returned 5.
+
+```http
+POST https://api.serpdive.com/v1/search
+authorization: Bearer sd_live_…            # a valid key, redacted
+content-type: application/json
+
+{"query":"best open source vector databases","model":"krill","max_results":10}
+```
+
+`HTTP 200` in 1706 ms
+
+```json
+{
+  "query": "best open source vector databases",
+  "model": "krill",
+  "response_time_ms": 1676,
+  "results": [
+    {
+      "url": "https://www.instaclustr.com/education/vector-database/best-open-source-vector-database-solutions-top-5-in-2026/",
+      "title": "Best open source vector database solutions: Top 5 in 2026",
+      "content": "Notable open source vector database solutions · 1. Opensearch · 2. Apache Cassandra · 3. p… (502 chars)"
+    },
+    {
+      "url": "https://redis.io/blog/best-open-source-vector-databases-comparison/",
+      "title": "Comparing the best open source vector databases (2026)",
+      "content": "This comparison breaks down the leading open source vector databases for production AI wor… (97 chars)"
+    },
+    "… 5 more, same shape"
+  ]
+}
+```
+
+### max_results: 50
+
+Above the range: clamped down to 10, silently. Never a 400.
+
+```http
+POST https://api.serpdive.com/v1/search
+authorization: Bearer sd_live_…            # a valid key, redacted
+content-type: application/json
+
+{"query":"best open source vector databases","model":"krill","max_results":50}
+```
+
+`HTTP 200` in 1820 ms
+
+```json
+{
+  "query": "best open source vector databases",
+  "model": "krill",
+  "response_time_ms": 1788,
+  "results": [
+    {
+      "url": "https://www.instaclustr.com/education/vector-database/best-open-source-vector-database-solutions-top-5-in-2026/",
+      "title": "Best open source vector database solutions: Top 5 in 2026",
+      "content": "Notable open source vector database solutions · 1. Opensearch · 2. Apache Cassandra · 3. p… (213 chars)"
+    },
+    {
+      "url": "https://redis.io/blog/best-open-source-vector-databases-comparison/",
+      "title": "Comparing the best open source vector databases (2026)",
+      "content": "This comparison breaks down the leading open source vector databases for production AI wor… (247 chars)"
+    },
+    "… 3 more, same shape"
+  ]
+}
+```
+
+### max_results: 0
+
+Below the range: clamped UP to 1, silently — it is the minimum of the range, NOT a way to say "no cap". One result comes back.
+
+```http
+POST https://api.serpdive.com/v1/search
+authorization: Bearer sd_live_…            # a valid key, redacted
+content-type: application/json
+
+{"query":"best open source vector databases","model":"krill","max_results":0}
+```
+
+`HTTP 200` in 1845 ms
+
+```json
+{
+  "query": "best open source vector databases",
+  "model": "krill",
+  "response_time_ms": 1800,
+  "results": [
+    {
+      "url": "https://www.instaclustr.com/education/vector-database/best-open-source-vector-database-solutions-top-5-in-2026/",
+      "title": "Best open source vector database solutions: Top 5 in 2026",
+      "content": "Notable open source vector database solutions · 1. Opensearch · 2. Apache Cassandra · 3. p… (322 chars)"
+    }
+  ]
+}
+```
+
+### max_results: "abc"
+
+Unparseable, and this is the asymmetry worth knowing: an out-of-range NUMBER is clamped into the range, but a value that is not a number at all drops the cap entirely and the default applies. Same for null or an absent field.
+
+```http
+POST https://api.serpdive.com/v1/search
+authorization: Bearer sd_live_…            # a valid key, redacted
+content-type: application/json
+
+{"query":"best open source vector databases","model":"krill","max_results":"abc"}
+```
+
+`HTTP 200` in 2096 ms
+
+```json
+{
+  "query": "best open source vector databases",
+  "model": "krill",
+  "response_time_ms": 2014,
+  "results": [
+    {
+      "url": "https://www.instaclustr.com/education/vector-database/best-open-source-vector-database-solutions-top-5-in-2026/",
+      "title": "Best open source vector database solutions: Top 5 in 2026",
+      "content": "Notable open source vector database solutions · 1. Opensearch · 2. Apache Cassandra · 3. p… (520 chars)"
+    },
+    {
+      "url": "https://medium.com/@pratik-rupareliya/top-15-vector-databases-in-2026-a-production-decision-guide-from-100-enterprise-deployments-dd58a04f51a5",
+      "title": "Medium",
+      "content": "Top 15 vector databases in 2026: A production decision guide from 100+ enterprise deployme… (408 chars)"
+    },
+    "… 4 more, same shape"
+  ]
+}
+```
+
+## 5. Errors
+
+### Missing query
+
+```http
+POST https://api.serpdive.com/v1/search
+authorization: Bearer sd_live_…            # a valid key, redacted
+content-type: application/json
+
+{"model":"krill"}
+```
+
+`HTTP 400` in 39 ms
+
+```json
+{
+  "error": "missing_query",
+  "message": "The \"query\" field is required, e.g. {\"query\": \"your search\"}."
+}
+```
+
+### Invalid key
+
+```http
+POST https://api.serpdive.com/v1/search
+authorization: Bearer sd_live_not_a_real_key
+content-type: application/json
+
+{"query":"best open source vector databases"}
+```
+
+`HTTP 401` in 533 ms
+
+```json
+{
+  "error": "invalid_api_key",
+  "message": "This API key is invalid or was revoked. Manage your keys at https://serpdive.com/dashboard/keys"
+}
+```
+
+### No key at all
+
+```http
+POST https://api.serpdive.com/v1/search
+(no authorization header sent)
+content-type: application/json
+
+{"query":"best open source vector databases"}
+```
+
+`HTTP 401` in 27 ms
+
+```json
+{
+  "error": "missing_api_key",
+  "message": "No API key. Send it as \"Authorization: Bearer sd_live_…\" — create one at https://serpdive.com/dashboard/keys"
+}
+```
+
+## 6. Abort
+
+### Client aborts mid-flight
+
+The request is cancellable at any point; the provider maps this to the framework abort path.
+
+```http
+POST https://api.serpdive.com/v1/search
+authorization: Bearer sd_live_…            # a valid key, redacted
+content-type: application/json
+
+{"query":"best open source vector databases","model":"krill"}
+```
+
+Client aborted after 300 ms → `AbortError` raised locally; no response body.