@crawlcheck/sdk 1.5.2 → 1.6.0

package/README.md

@@ -20,6 +20,25 @@ Every verification returns `integrity_valid`, `issuer_trusted` and `accepted`. A
 
 `preflight(domain, action, { agent, template, policy })` returns the signed receipt without deciding for you; `verifyDocument(doc)` verifies any signed resolve answer or decision receipt offline. `resolve(domain)` returns the full signed ResolveV1 answer.
 
+## Give your agent the check as a tool
+
+Two tools your agent can call itself: `crawlcheck_check_site` (the signed, verified decision for an action on a site) and `crawlcheck_fetch` (fetches a page only after its domain, and every redirect hop, is allowed). Both fail closed.
+
+```js
+import { CrawlCheck, agentTools, toolsFor } from "@crawlcheck/sdk";
+const tools = agentTools(new CrawlCheck(), { agent: "MyAgentBot" });
+
+// OpenAI function calling
+const oa = toolsFor("openai", tools);          // oa.tools → tools: [...]; on a tool call: await oa.call(name, argumentsJson)
+// Anthropic tool use
+const an = toolsFor("anthropic", tools);       // an.tools → tools: [...]; on tool_use: await an.call(block.name, block.input)
+// Vercel AI SDK
+import { tool, jsonSchema } from "ai";
+const vt = Object.fromEntries(tools.map((t) => [t.name, tool({ description: t.description, parameters: jsonSchema(t.parameters), execute: t.execute })]));
+// An MCP server you run
+const mc = toolsFor("mcp", tools);             // list mc.tools; answer tools/call with mc.call(name, args)
+```
+
 ## Read a record
 
 ```js

package/dist/index.d.ts

@@ -686,4 +686,26 @@ export declare class CrawlCheck {
     }>;
     private req;
 }
+/**
+ * Agent tools (1.6.0): CrawlCheck as two tools any agent framework can register, so the check happens inside the agent's
+ * own tool loop. crawlcheck_check_site returns the signed, verified decision for an action on a site; crawlcheck_fetch
+ * fetches a page only after its domain (and every redirect hop) proceeds. Both fail closed, exactly like guard().
+ * toolsFor() shapes them for OpenAI function calling, Anthropic tool use, the Vercel AI SDK or an MCP server.
+ */
+export interface AgentTool {
+    name: string;
+    description: string;
+    parameters: JsonObject;
+    execute: (args: any) => Promise<JsonObject>;
+}
+export interface AgentToolOptions extends GuardOptions {
+    maxChars?: number;
+}
+export declare function agentTools(cc: CrawlCheck, opts?: AgentToolOptions): AgentTool[];
+export type ToolFormat = "openai" | "anthropic" | "vercel" | "mcp";
+/** Shape agentTools() for a framework. call(name, args) runs a tool by name for formats that hand you the call (OpenAI, Anthropic, MCP). For the Vercel AI SDK wrap each parameters object: tool({ description, parameters: jsonSchema(t.parameters), execute: t.execute }). */
+export declare function toolsFor(format: ToolFormat, tools: AgentTool[]): {
+    tools: unknown;
+    call: (name: string, args: unknown) => Promise<JsonObject>;
+};
 export default CrawlCheck;

package/dist/index.js

@@ -563,4 +563,63 @@ export class CrawlCheck {
         return j;
     }
 }
+const AT_ACTIONS = ["read", "cite", "connect", "transact", "administer"];
+function atDomain(v) { const s = String(v ?? "").trim(); try {
+    return normalizeDomain(/^[a-z][a-z0-9+.-]*:\/\//i.test(s) ? new URL(s).hostname : s);
+}
+catch {
+    return "";
+} }
+function atAction(v) { return AT_ACTIONS.includes(String(v)) ? String(v) : "read"; }
+export function agentTools(cc, opts = {}) {
+    const max = opts.maxChars ?? 20000;
+    return [
+        { name: "crawlcheck_check_site",
+            description: "Before acting on a website, get CrawlCheck's signed decision for that action: allow, warn, require_confirmation, block or unsupported, with the reasons. Use it before reading, citing, connecting to, buying from or administering a site you have not checked. proceed is false whenever the site should not be used for that action.",
+            parameters: { type: "object", additionalProperties: false, required: ["site"], properties: {
+                    site: { type: "string", description: "The site's domain or any URL on it, e.g. example.com or https://example.com/page" },
+                    action: { type: "string", enum: AT_ACTIONS, description: "What you are about to do: read (default), cite, connect (an API or MCP server), transact (pay, book, submit personal data) or administer" }
+                } },
+            execute: async (a) => {
+                const domain = atDomain(a?.site), action = atAction(a?.action);
+                if (!domain)
+                    return { proceed: false, why: ["not a public domain name: " + String(a?.site ?? "")] };
+                const g = await cc.guard(domain, action, opts);
+                return { domain, action, proceed: g.proceed, decision: g.receipt ? String(g.receipt.decision) : null, why: g.why, reasons: Array.isArray(g.receipt?.steps) ? g.receipt.steps.map((x) => String(x?.why ?? "")).filter(Boolean) : [], reason_codes: g.receipt?.reason_codes ?? [],
+                    receipt_sha256: g.receipt?.sha256 ?? null, verified: g.verification ? g.verification.accepted : false, alternatives: g.receipt?.alternatives ?? null };
+            } },
+        { name: "crawlcheck_fetch",
+            description: "Fetch a web page only if CrawlCheck allows reading that site; every redirect to a new domain is checked again before it is followed. Returns the page text (truncated) or, when refused, why. Prefer this over a plain fetch for sites you have not checked.",
+            parameters: { type: "object", additionalProperties: false, required: ["url"], properties: {
+                    url: { type: "string", description: "The http(s) URL to fetch" },
+                    action: { type: "string", enum: ["read", "cite"], description: "read (default) or cite, if the text will be quoted back to someone" }
+                } },
+            execute: async (a) => {
+                const r = await cc.guardedFetch(String(a?.url ?? ""), Object.assign({}, opts, { action: (a?.action === "cite" ? "cite" : "read") }));
+                const hops = r.hops.map((h) => ({ url: h.url, domain: h.domain, decision: h.decision, proceed: h.proceed, status: h.status ?? null }));
+                if (!r.proceed || !r.response)
+                    return { proceed: false, url: r.url, why: r.why, hops };
+                const text = await r.response.text();
+                return { proceed: true, url: r.url, status: r.response.status, content_type: r.response.headers.get("content-type"), text: text.slice(0, max), truncated: text.length > max, chars: text.length, hops };
+            } }
+    ];
+}
+/** Shape agentTools() for a framework. call(name, args) runs a tool by name for formats that hand you the call (OpenAI, Anthropic, MCP). For the Vercel AI SDK wrap each parameters object: tool({ description, parameters: jsonSchema(t.parameters), execute: t.execute }). */
+export function toolsFor(format, tools) {
+    const by = new Map(tools.map((t) => [t.name, t]));
+    const call = async (name, args) => { const t = by.get(name); if (!t)
+        return { proceed: false, why: ["no CrawlCheck tool named " + name] }; return t.execute(typeof args === "string" ? (() => { try {
+        return JSON.parse(args);
+    }
+    catch {
+        return {};
+    } })() : (args ?? {})); };
+    if (format === "openai")
+        return { tools: tools.map((t) => ({ type: "function", function: { name: t.name, description: t.description, parameters: t.parameters } })), call };
+    if (format === "anthropic")
+        return { tools: tools.map((t) => ({ name: t.name, description: t.description, input_schema: t.parameters })), call };
+    if (format === "mcp")
+        return { tools: tools.map((t) => ({ name: t.name, description: t.description, inputSchema: t.parameters, annotations: { readOnlyHint: true, openWorldHint: true } })), call };
+    return { tools: Object.fromEntries(tools.map((t) => [t.name, { description: t.description, parameters: t.parameters, execute: t.execute }])), call };
+}
 export default CrawlCheck;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crawlcheck/sdk",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "description": "Typed client for the CrawlCheck API (generated from its OpenAPI document) and the zero-dependency offline verifier for evidence bundles and remediation receipts.",
   "type": "module",
   "main": "./dist/index.js",

package/test/tools.test.js

@@ -0,0 +1,37 @@
+// Agent tools (1.6.0): shapes offline, decisions against the live API. npm test
+import test from "node:test"; import assert from "node:assert/strict";
+import { CrawlCheck, agentTools, toolsFor } from "../dist/index.js";
+const cc = new CrawlCheck();
+const tools = agentTools(cc);
+
+test("agent tools: two tools, each with a JSON-schema object and an execute()", () => {
+  assert.deepEqual(tools.map((t) => t.name), ["crawlcheck_check_site", "crawlcheck_fetch"]);
+  for (const t of tools) { assert.equal(t.parameters.type, "object"); assert.equal(typeof t.execute, "function"); assert.ok(t.description.length > 40); }
+});
+
+test("toolsFor: OpenAI, Anthropic, MCP and Vercel shapes carry the same schema", () => {
+  const o = toolsFor("openai", tools).tools, a = toolsFor("anthropic", tools).tools, m = toolsFor("mcp", tools).tools, v = toolsFor("vercel", tools).tools;
+  assert.equal(o[0].type, "function"); assert.equal(o[0].function.parameters, tools[0].parameters);
+  assert.equal(a[1].input_schema, tools[1].parameters); assert.equal(m[0].inputSchema, tools[0].parameters);
+  assert.equal(typeof v.crawlcheck_fetch.execute, "function");
+});
+
+test("check_site fails closed on a non-domain without calling the API", async () => {
+  const r = await toolsFor("openai", tools).call("crawlcheck_check_site", JSON.stringify({ site: "not a domain" }));
+  assert.equal(r.proceed, false);
+  assert.equal((await toolsFor("openai", tools).call("no_such_tool", {})).proceed, false);
+});
+
+test("live: check_site returns a verified, signed decision for crawlcheck.io", async () => {
+  const r = await tools[0].execute({ site: "https://crawlcheck.io/pricing", action: "read" });
+  assert.equal(r.domain, "crawlcheck.io");
+  assert.ok(["allow", "warn", "require_confirmation", "block", "unsupported"].includes(r.decision), JSON.stringify(r));
+  assert.match(String(r.receipt_sha256), /^[0-9a-f]{64}$/);
+  assert.equal(r.verified, true);
+});
+
+test("live: fetch returns page text only after the check proceeds", async () => {
+  const r = await tools[1].execute({ url: "https://crawlcheck.io/llms.txt" });
+  if (r.proceed) { assert.equal(r.status, 200); assert.ok(r.text.length > 100); assert.ok(r.hops.length >= 1 && r.hops[0].proceed); }
+  else assert.ok(r.why.length, "a refusal names why");
+});