@hollware/agents 0.0.0-stage → 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Sergio Azócar and Hollware contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# @hollware/agents
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Agents for [Hollware](https://hollware.com), an open-source headless CMS for the agent era,
+native to Cloudflare Workers. They run on a Worker of their own, next to your Hollware:
+
+- **a reviewer**, which comments once on each pending review: clarity, the voice of the style
+  guide, claims without an example; what the contracts cannot see;
+- **a translator**, which drafts the missing translation of a published entry, fixes what the
+  contracts refuse, and asks a person to review it;
+- **a weekly auditor**, which reports the entries readers read most that have not changed in
+  months, and the published entries the contracts refuse now, as a draft and, if you want, to a
+  Slack webhook.
+
+None of them publishes: their MCP client refuses every tool that publishes or decides, whatever
+the token holds.
+
+```ts
+import { createHollwareAgents } from '@hollware/agents'
+
+export default createHollwareAgents({
+  auditor: { collection: 'reports', locale: 'en' },
+})
+```
+
+The guide is at <https://hollware.com/docs/agents/>.
+
+## Links
+
+- Repository: <https://github.com/hollware/hollware>
+- Issues: <https://github.com/hollware/hollware/issues>
+- License: MIT

package/dist/index.d.mts

@@ -0,0 +1,259 @@
+//#region src/hollware.d.ts
+/**
+ * How the agents reach Hollware: as any agent does, over MCP, with a personal token. They call
+ * only the tools of `ALLOWED_TOOLS`, which read, write drafts, comment and ask for reviews; the
+ * tools that publish or decide (`publish`, `approve_review`, `request_changes`, `unpublish`) are
+ * refused here, before any request, whatever the token holds.
+ */
+/** The tools an agent may call. */
+export declare const ALLOWED_TOOLS: readonly ['comment_review', 'content_stats', 'create_draft', 'describe_site', 'get_entry', 'get_translations', 'list_entries', 'list_reviews', 'request_review', 'search', 'update_draft', 'validate'];
+type AllowedTool = (typeof ALLOWED_TOOLS)[number];
+/** A tool's structured output, as JSON. */
+type ToolOutput = Readonly<Record<string, unknown>>;
+/** Calls a tool of Hollware. */
+interface Hollware {
+  call(tool: AllowedTool, input: Readonly<Record<string, unknown>>): Promise<ToolOutput>;
+}
+/** Refuses every tool outside the allowlist, so a mistake of a role can never publish. */
+export declare function allowOnly(call: (tool: string, input: Readonly<Record<string, unknown>>) => Promise<ToolOutput>): Hollware;
+/** What the MCP client needs: where Hollware is, how to reach it, and the token. */
+interface McpOptions {
+  /** The public URL of Hollware: its guard answers only requests for its own host. */
+  readonly url: string;
+  readonly token: string;
+  /** `fetch` of a service binding to the Hollware Worker, or the global one. */
+  readonly fetch: (request: Request) => Promise<Response>;
+}
+/**
+ * Hollware over MCP, one JSON-RPC request per call (Hollware keeps no session). The answer may come
+ * as JSON or as a server-sent event; the tool's output is its `structuredContent`.
+ */
+export declare function mcpHollware(options: McpOptions): Hollware;
+//#endregion
+//#region src/memory.d.ts
+/** What the agents remember between runs: a few small values by key, some for a while only. */
+interface Memory {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string, ttlSeconds?: number): Promise<void>;
+}
+interface KvBinding {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string, options?: {
+    expirationTtl?: number;
+  }): Promise<void>;
+}
+/** Memory in a KV namespace. KV keeps a value at least 60 seconds. */
+export declare function kvMemory(kv: KvBinding): Memory;
+/** Memory in a Map, for tests and for a single run. */
+export declare function mapMemory(): Memory & {
+  readonly values: Map<string, string>;
+};
+//#endregion
+//#region src/auditor.d.ts
+/** Where the weekly report goes: a draft in a collection of the site, and a webhook if set. */
+interface ReportOptions {
+  readonly collection: string;
+  readonly locale: string;
+  /** The frontmatter of the report of a day (YYYY-MM-DD), as the collection's schema asks. */
+  readonly frontmatter?: (day: string) => Readonly<Record<string, string>>;
+}
+interface AuditorDeps {
+  readonly hollware: Hollware;
+  /** Posts the report as `{ "text": "<markdown>" }`, as Slack's incoming webhooks take it. */
+  readonly webhook?: ((report: string) => Promise<void>) | undefined;
+}
+interface AuditOptions {
+  readonly report: ReportOptions;
+  /** The day of the report, YYYY-MM-DD. */
+  readonly day: string;
+  /** An entry read this much but not updated in these many days is out of date. */
+  readonly staleDays?: number;
+}
+interface Finding {
+  readonly kind: 'stale' | 'contract';
+  readonly where: string;
+  readonly what: string;
+}
+/** The report as Markdown, with its frontmatter. */
+export declare function reportOf(day: string, findings: readonly Finding[], report: ReportOptions): string;
+/** The memory's key of what the auditor has checked: where it is, and what it found by entry. */
+export declare const AUDIT_STATE = "audit:state";
+interface StepDeps {
+  readonly hollware: Hollware;
+  readonly memory: Memory;
+}
+/**
+ * One step of the audit: the next `perRun` published entries of the site (outside the report's
+ * collection), each checked against the contracts as they are now, and what was found kept in the
+ * memory. A step reads a dozen entries, two calls each, so that a run stays within the fifty calls
+ * a free Worker has; the steps go round the entries, and the report is written from them.
+ */
+export declare function auditStep(deps: StepDeps, options: {
+  readonly report: ReportOptions;
+  readonly now: string;
+  readonly perRun?: number;
+}): Promise<{
+  readonly checked: number;
+}>;
+/**
+ * The report of the audit: the most read pages whose entry has not changed in `staleDays`, and
+ * what the steps of the last eight days found. It is saved as a draft (never published) in the
+ * report's collection, its slug the day, and posted to the webhook when there is one.
+ */
+export declare function writeReport(deps: AuditorDeps & StepDeps, options: AuditOptions): Promise<{
+  readonly findings: number;
+}>;
+/** A whole audit at once, every published entry and then the report: for a site with few entries. */
+export declare function audit(deps: AuditorDeps & Partial<StepDeps>, options: AuditOptions): Promise<{
+  readonly findings: number;
+}>;
+//#endregion
+//#region src/model.d.ts
+/** A message of a conversation with a model. */
+interface Message {
+  readonly role: 'system' | 'user';
+  readonly content: string;
+}
+/** A model that answers a conversation with text. */
+type Model = (messages: readonly Message[]) => Promise<string>;
+/** The model of Workers AI the agents use when the options name none. */
+export declare const DEFAULT_MODEL = "@cf/meta/llama-3.3-70b-instruct-fp8-fast";
+interface AiBinding {
+  run(model: string, input: object, options?: object): Promise<unknown>;
+}
+/** A model of Workers AI, through an AI Gateway when its id is given. */
+export declare function workersAiModel(ai: AiBinding, model: string, options?: {
+  readonly gateway?: string;
+  readonly maxTokens?: number;
+}): Model;
+/** The day's cap of model calls was reached; the agents stop until the next day. */
+export declare class DailyLimitReached extends Error {
+  constructor(limit: number);
+}
+/** A model that counts its calls of the day in the memory and refuses one over `limit`. */
+export declare function capped(model: Model, memory: Memory, limit: number, today: () => string): Model;
+//#endregion
+//#region src/reviewer.d.ts
+/** The name the agents' client gives: a comment of theirs carries it. */
+export declare const AGENTS_CLIENT = "hollware-agents";
+interface ReviewerDeps {
+  readonly hollware: Hollware;
+  readonly model: Model;
+  readonly memory: Memory;
+}
+/**
+ * Comments once on each pending review: what the contracts cannot see. A review that has a
+ * comment of the agents, or that the memory has, is left alone, so a run that fails halfway is
+ * picked up by the next one without commenting twice.
+ */
+export declare function reviewPending(deps: ReviewerDeps): Promise<{
+  readonly commented: number;
+}>;
+//#endregion
+//#region src/translator.d.ts
+/** A slug from a title: lowercase ASCII words joined by hyphens. */
+export declare function slugOf(title: string): string;
+interface TranslatorDeps {
+  readonly hollware: Hollware;
+  readonly model: Model;
+  readonly memory: Memory;
+}
+/**
+ * For each published entry of a collection with translations whose group lacks a locale of the
+ * site, writes the translation as a draft, fixes what the contracts refuse up to `FIX_ROUNDS`
+ * times, and asks a person to review it, at most `limit` a run. It reads each locale's entries in
+ * one listing, so a run stays within the fifty calls a free Worker has; an entry of any status
+ * in a locale counts as the translation, and the memory keeps what was tried, once it was saved or
+ * refused: a run that stops before tries it again.
+ */
+export declare function translateMissing(deps: TranslatorDeps, options?: {
+  readonly limit?: number;
+}): Promise<{
+  readonly drafted: number;
+  readonly sentToReview: number;
+}>;
+//#endregion
+//#region src/worker.d.ts
+/** The bindings and variables of the Worker of the agents. */
+interface AgentsEnv {
+  /** A service binding to the Hollware Worker; without it, the agents reach it over the network. */
+  readonly HOLLWARE?: {
+    fetch(request: Request): Promise<Response>;
+  };
+  /** The public URL of Hollware, such as https://cms.example.com. */
+  readonly HOLLWARE_PUBLIC_URL: string;
+  /** A personal token of the site, with content:read and content:write (a secret). */
+  readonly HOLLWARE_AGENT_TOKEN: string;
+  /** Workers AI, for the default model. */
+  readonly AI?: {
+    run(model: string, input: object, options?: object): Promise<unknown>;
+  };
+  /** What the agents remember: the reviews they read, the translations they tried, the day's calls. */
+  readonly AGENTS_KV: {
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, options?: {
+      expirationTtl?: number;
+    }): Promise<void>;
+  };
+  /** Where the weekly report is posted as well, such as a Slack incoming webhook (a secret). */
+  readonly AGENTS_WEBHOOK_URL?: string;
+}
+/** The options of `createHollwareAgents`. */
+interface AgentsOptions {
+  /** A model of Workers AI by its id, or a model of your own; `DEFAULT_MODEL` when not given. */
+  readonly model?: string | Model;
+  /** The id of an AI Gateway for the calls to Workers AI. */
+  readonly gateway?: string;
+  /** The model calls of a day, at most; 100 by default. */
+  readonly dailyLimit?: number;
+  /** The reviewer comments on pending reviews; on by default. */
+  readonly reviewer?: boolean;
+  /** The translator drafts missing translations, at most `limit` a run (3); on by default. */
+  readonly translator?: boolean | {
+    readonly limit?: number;
+  };
+  /**
+   * The auditor writes a report every `everyDays` days (7), on the first trigger after; off unless
+   * a collection for it is given.
+   */
+  readonly auditor?: false | (ReportOptions & {
+    readonly everyDays?: number;
+    readonly staleDays?: number;
+  });
+  /** The time; the system clock when absent. */
+  readonly clock?: () => Date;
+}
+/** The roles, by turn: each run is one, so that it stays within the fifty calls of a free run. */
+export declare const ROLES: readonly ['reviewer', 'translator', 'auditor'];
+/** The role whose turn it is at `time`: the ten minutes of the time, in turn. */
+export declare function roleAt(time: number): (typeof ROLES)[number];
+/** The memory's key of the day of the last audit. */
+export declare const LAST_AUDIT = "audit:last";
+/** Whether an audit is due: none yet, or the last one `everyDays` or more days before `day`. */
+export declare function auditDue(last: string | null, day: string, everyDays: number): boolean;
+interface AgentsWorker {
+  /**
+   * One run of the agents, awaited: what a named entrypoint calls when Hollware's own cron wakes
+   * the agents over a service binding, so that they need no cron trigger of their own.
+   */
+  readonly run: (env: AgentsEnv) => Promise<void>;
+  readonly scheduled: (controller: {
+    readonly cron: string;
+  }, env: AgentsEnv, ctx: {
+    waitUntil(promise: Promise<unknown>): void;
+  }) => Promise<void>;
+  readonly fetch: (request: Request, env: AgentsEnv) => Promise<Response>;
+}
+/**
+ * The Worker of the agents. Hollware's cron wakes them every ten minutes over a service binding
+ * (`run`), or a cron trigger of their own does (`scheduled`). Each run is one role, in turn: the
+ * reviewer, the translator, then the auditor, which checks a dozen entries and writes its report
+ * when it is due. A free Worker makes fifty calls a run at most, which one role fits in. A role
+ * that fails is logged; reaching the day's limit of model calls ends it quietly.
+ */
+export declare function createHollwareAgents(options?: AgentsOptions): AgentsWorker;
+//#endregion
+//#region src/index.d.ts
+export declare const name = "@hollware/agents";
+//#endregion
+export type { AgentsEnv, AgentsOptions, AgentsWorker, AllowedTool, AuditOptions, Finding, Hollware, Memory, Message, Model, ReportOptions };

package/dist/index.mjs

@@ -0,0 +1,694 @@
+//#region src/read.ts
+function record(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? Object.fromEntries(Object.entries(value)) : {};
+}
+function list(value) {
+	return Array.isArray(value) ? value.map(record) : [];
+}
+function text(value) {
+	return typeof value === "string" ? value : null;
+}
+function number(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+/** The entries of a collection, in a locale and status when given, a page of 100 at a time. */
+async function entriesOf(hollware, query) {
+	const entries = [];
+	let cursor = null;
+	for (let page = 0; page < 3; page++) {
+		const answer = await hollware.call("list_entries", {
+			...query,
+			limit: 100,
+			...cursor === null ? {} : { cursor }
+		});
+		entries.push(...list(answer["entries"]));
+		cursor = text(answer["nextCursor"]);
+		if (cursor === null) break;
+	}
+	return entries;
+}
+//#endregion
+//#region src/memory.ts
+/** Memory in a KV namespace. KV keeps a value at least 60 seconds. */
+function kvMemory(kv) {
+	return {
+		get: (key) => kv.get(key),
+		put: (key, value, ttlSeconds) => kv.put(key, value, ttlSeconds === void 0 ? void 0 : { expirationTtl: Math.max(60, ttlSeconds) })
+	};
+}
+/** Memory in a Map, for tests and for a single run. */
+function mapMemory() {
+	const values = /* @__PURE__ */ new Map();
+	return {
+		values,
+		async get(key) {
+			return values.get(key) ?? null;
+		},
+		async put(key, value) {
+			values.set(key, value);
+		}
+	};
+}
+//#endregion
+//#region src/auditor.ts
+function yamlValue(value) {
+	return JSON.stringify(value);
+}
+/** The report as Markdown, with its frontmatter. */
+function reportOf(day, findings, report) {
+	const frontmatter = report.frontmatter?.(day) ?? {
+		title: `Content audit of ${day}`,
+		description: `What the weekly audit of ${day} found: read but old, and failing contracts.`
+	};
+	const lines = [
+		"---",
+		...Object.entries(frontmatter).map(([key, value]) => `${key}: ${yamlValue(value)}`),
+		"---",
+		""
+	];
+	lines.push(`# Content audit of ${day}`, "");
+	const stale = findings.filter((finding) => finding.kind === "stale");
+	const failing = findings.filter((finding) => finding.kind === "contract");
+	lines.push("## Read a lot, updated long ago", "");
+	lines.push(...stale.length === 0 ? ["Nothing."] : stale.map((finding) => `- ${finding.where}: ${finding.what}`), "");
+	lines.push("## Published, and failing the contracts now", "");
+	lines.push(...failing.length === 0 ? ["Nothing."] : failing.map((finding) => `- ${finding.where}: ${finding.what}`), "");
+	return lines.join("\n");
+}
+function problemsOf$1(verdict) {
+	return [...list(verdict["errors"]), ...list(verdict["warnings"])].map((problem) => `${String(problem["severity"])} ${String(problem["contract"])}: ${String(problem["message"])}`);
+}
+/** The memory's key of what the auditor has checked: where it is, and what it found by entry. */
+const AUDIT_STATE = "audit:state";
+function stateOf(text_) {
+	if (text_ === null) return {
+		offset: 0,
+		found: {}
+	};
+	try {
+		const parsed = record(JSON.parse(text_));
+		return {
+			offset: number(parsed["offset"]) ?? 0,
+			found: Object.fromEntries(Object.entries(record(parsed["found"])).map(([key, value]) => {
+				const one = record(value);
+				return [key, {
+					problems: Array.isArray(one["problems"]) ? one["problems"].map(String) : [],
+					at: text(one["at"]) ?? ""
+				}];
+			}))
+		};
+	} catch {
+		return {
+			offset: 0,
+			found: {}
+		};
+	}
+}
+/**
+* One step of the audit: the next `perRun` published entries of the site (outside the report's
+* collection), each checked against the contracts as they are now, and what was found kept in the
+* memory. A step reads a dozen entries, two calls each, so that a run stays within the fifty calls
+* a free Worker has; the steps go round the entries, and the report is written from them.
+*/
+async function auditStep(deps, options) {
+	const perRun = options.perRun ?? 12;
+	const site = record((await deps.hollware.call("describe_site", {}))["site"]);
+	const refs = [];
+	for (const collection of list(site["collections"])) {
+		const name = text(collection["name"]);
+		if (name === null || name === options.report.collection) continue;
+		for (const entry of await entriesOf(deps.hollware, {
+			collection: name,
+			status: "published"
+		})) {
+			const locale = text(entry["locale"]);
+			const slug = text(entry["slug"]);
+			if (locale !== null && slug !== null) refs.push({
+				collection: name,
+				locale,
+				slug
+			});
+		}
+	}
+	const state = stateOf(await deps.memory.get(AUDIT_STATE));
+	const found = { ...state.found };
+	const count = Math.min(perRun, refs.length);
+	for (let step = 0; step < count; step++) {
+		const ref = refs[(state.offset + step) % refs.length];
+		if (ref === void 0) continue;
+		const markdown = text(record((await deps.hollware.call("get_entry", {
+			...ref,
+			published: true
+		}))["entry"])["markdown"]);
+		if (markdown === null) continue;
+		const verdict = record((await deps.hollware.call("validate", {
+			...ref,
+			markdown
+		}))["verdict"]);
+		found[`${ref.collection}/${ref.locale}/${ref.slug}`] = {
+			problems: problemsOf$1(verdict),
+			at: options.now
+		};
+	}
+	const offset = refs.length === 0 ? 0 : (state.offset + count) % refs.length;
+	await deps.memory.put(AUDIT_STATE, JSON.stringify({
+		offset,
+		found
+	}), 2592e3);
+	return { checked: count };
+}
+/**
+* The report of the audit: the most read pages whose entry has not changed in `staleDays`, and
+* what the steps of the last eight days found. It is saved as a draft (never published) in the
+* report's collection, its slug the day, and posted to the webhook when there is one.
+*/
+async function writeReport(deps, options) {
+	const staleDays = options.staleDays ?? 180;
+	const findings = [];
+	const stats = await deps.hollware.call("content_stats", {
+		days: 30,
+		limit: 20
+	});
+	const cutoff = Date.parse(options.day) - staleDays * 864e5;
+	for (const page of list(stats["pages"])) {
+		const entry = record(page["entry"]);
+		const updated = text(entry["updatedAt"]);
+		if (updated === null || Date.parse(updated) > cutoff) continue;
+		findings.push({
+			kind: "stale",
+			where: `${String(page["path"])} (${String(entry["collection"])}/${String(entry["locale"])}/${String(entry["slug"])})`,
+			what: `${number(page["views"]) ?? 0} views in 30 days, last updated ${updated.slice(0, 10)}`
+		});
+	}
+	const since = Date.parse(options.day) - 6912e5;
+	const state = stateOf(await deps.memory.get(AUDIT_STATE));
+	for (const [where, { problems, at }] of Object.entries(state.found).sort(([a], [b]) => a.localeCompare(b))) {
+		if (Date.parse(at) < since) continue;
+		for (const problem of problems) findings.push({
+			kind: "contract",
+			where,
+			what: problem
+		});
+	}
+	const report = reportOf(options.day, findings, options.report);
+	const slug = `audit-${options.day}`;
+	const where = {
+		collection: options.report.collection,
+		locale: options.report.locale,
+		slug
+	};
+	const existing = record((await deps.hollware.call("get_entry", where))["entry"]);
+	if (text(existing["id"]) === null) await deps.hollware.call("create_draft", {
+		...where,
+		markdown: report
+	});
+	else await deps.hollware.call("update_draft", {
+		id: existing["id"],
+		version: existing["version"],
+		markdown: report
+	});
+	await deps.webhook?.(report);
+	return { findings: findings.length };
+}
+/** A whole audit at once, every published entry and then the report: for a site with few entries. */
+async function audit(deps, options) {
+	const memory = deps.memory ?? mapMemory();
+	await auditStep({
+		hollware: deps.hollware,
+		memory
+	}, {
+		report: options.report,
+		now: `${options.day}T00:00:00.000Z`,
+		perRun: Number.POSITIVE_INFINITY
+	});
+	return writeReport({
+		...deps,
+		memory
+	}, options);
+}
+//#endregion
+//#region src/hollware.ts
+/**
+* How the agents reach Hollware: as any agent does, over MCP, with a personal token. They call
+* only the tools of `ALLOWED_TOOLS`, which read, write drafts, comment and ask for reviews; the
+* tools that publish or decide (`publish`, `approve_review`, `request_changes`, `unpublish`) are
+* refused here, before any request, whatever the token holds.
+*/
+/** The tools an agent may call. */
+const ALLOWED_TOOLS = [
+	"comment_review",
+	"content_stats",
+	"create_draft",
+	"describe_site",
+	"get_entry",
+	"get_translations",
+	"list_entries",
+	"list_reviews",
+	"request_review",
+	"search",
+	"update_draft",
+	"validate"
+];
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Refuses every tool outside the allowlist, so a mistake of a role can never publish. */
+function allowOnly(call) {
+	const allowed = new Set(ALLOWED_TOOLS);
+	return { call(tool, input) {
+		if (!allowed.has(tool)) return Promise.reject(/* @__PURE__ */ new Error(`The agents never call ${tool}`));
+		return call(tool, input);
+	} };
+}
+/**
+* Hollware over MCP, one JSON-RPC request per call (Hollware keeps no session). The answer may come
+* as JSON or as a server-sent event; the tool's output is its `structuredContent`.
+*/
+function mcpHollware(options) {
+	const endpoint = `${options.url.replace(/\/+$/, "")}/mcp`;
+	return allowOnly(async (tool, input) => {
+		const response = await options.fetch(new Request(endpoint, {
+			method: "POST",
+			headers: {
+				host: new URL(endpoint).host,
+				authorization: `Bearer ${options.token}`,
+				"content-type": "application/json",
+				accept: "application/json, text/event-stream",
+				"mcp-protocol-version": "2026-07-28",
+				"mcp-method": "tools/call",
+				"mcp-name": tool
+			},
+			body: JSON.stringify({
+				jsonrpc: "2.0",
+				id: 1,
+				method: "tools/call",
+				params: {
+					name: tool,
+					arguments: input,
+					_meta: {
+						"io.modelcontextprotocol/protocolVersion": "2026-07-28",
+						"io.modelcontextprotocol/clientInfo": {
+							name: "hollware-agents",
+							version: "0.6.0"
+						},
+						"io.modelcontextprotocol/clientCapabilities": {}
+					}
+				}
+			})
+		}));
+		const text = await response.text();
+		const json = text.trimStart().startsWith("{") ? text : /^data: (.*)$/m.exec(text)?.[1] ?? "";
+		let message = null;
+		try {
+			message = JSON.parse(json);
+		} catch {
+			message = null;
+		}
+		const result = isRecord$1(message) ? message["result"] : void 0;
+		const output = isRecord$1(result) ? result["structuredContent"] : void 0;
+		if (!isRecord$1(output)) throw new Error(`Hollware answered ${tool} with ${response.status}: ${text.slice(0, 200)}`);
+		return output;
+	});
+}
+//#endregion
+//#region src/model.ts
+/** The model of Workers AI the agents use when the options name none. */
+const DEFAULT_MODEL = "@cf/meta/llama-3.3-70b-instruct-fp8-fast";
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The text of an answer of Workers AI, in the shapes its text models answer with. */
+function textOf(answer) {
+	if (typeof answer === "string") return answer;
+	if (!isRecord(answer)) return null;
+	if (typeof answer["response"] === "string") return answer["response"];
+	const choices = answer["choices"];
+	if (Array.isArray(choices) && isRecord(choices[0]) && isRecord(choices[0]["message"])) {
+		const content = choices[0]["message"]["content"];
+		if (typeof content === "string") return content;
+	}
+	return null;
+}
+/** A model of Workers AI, through an AI Gateway when its id is given. */
+function workersAiModel(ai, model, options = {}) {
+	return async (messages) => {
+		const text = textOf(await ai.run(model, {
+			messages: messages.map(({ role, content }) => ({
+				role,
+				content
+			})),
+			max_tokens: options.maxTokens ?? 4096
+		}, options.gateway === void 0 ? void 0 : { gateway: { id: options.gateway } }));
+		if (text === null) throw new Error(`${model} answered no text`);
+		return text;
+	};
+}
+/** The day's cap of model calls was reached; the agents stop until the next day. */
+var DailyLimitReached = class extends Error {
+	constructor(limit) {
+		super(`The agents reached their ${limit} model calls of the day`);
+		this.name = "DailyLimitReached";
+	}
+};
+/** A model that counts its calls of the day in the memory and refuses one over `limit`. */
+function capped(model, memory, limit, today) {
+	return async (messages) => {
+		const key = `usage:${today()}`;
+		const used = Number(await memory.get(key) ?? "0");
+		if (used >= limit) throw new DailyLimitReached(limit);
+		await memory.put(key, String(used + 1), 172800);
+		return model(messages);
+	};
+}
+//#endregion
+//#region src/reviewer.ts
+/** The name the agents' client gives: a comment of theirs carries it. */
+const AGENTS_CLIENT = "hollware-agents";
+/** The longest comment the reviewer writes, under the 4,000 characters of `comment_review`. */
+const MAX_COMMENT = 3500;
+const REVIEWER_PROMPT = [
+	"You review an entry of a website before a person decides whether to publish it.",
+	"The contracts of the site already checked its schema, links, images and translations: never repeat those.",
+	"Read it as an editor: is it clear, does it follow the style guide, does each claim have an example, is anything missing, wrong or out of date?",
+	"Answer in the language of the entry, in Markdown, in at most eight short bullet points, the most important first.",
+	"Name the section of each point. Say what reads well in one bullet at most. Do not rewrite the entry."
+].join(" ");
+/**
+* Comments once on each pending review: what the contracts cannot see. A review that has a
+* comment of the agents, or that the memory has, is left alone, so a run that fails halfway is
+* picked up by the next one without commenting twice.
+*/
+async function reviewPending(deps) {
+	const site = record((await deps.hollware.call("describe_site", {}))["site"]);
+	const reviews = list((await deps.hollware.call("list_reviews", { status: "pending" }))["reviews"]);
+	let commented = 0;
+	for (const review of reviews) {
+		if (commented >= 8) break;
+		const id = text(review["id"]);
+		if (id === null) continue;
+		if (list(review["comments"]).some((comment) => comment["client"] === "hollware-agents") || await deps.memory.get(`reviewed:${id}`) !== null) continue;
+		const summary = record(review["entry"]);
+		const markdown = text(record((await deps.hollware.call("get_entry", {
+			collection: summary["collection"],
+			locale: summary["locale"],
+			slug: summary["slug"]
+		}))["entry"])["markdown"]);
+		if (markdown === null) continue;
+		const collection = list(site["collections"]).find((one) => one["name"] === summary["collection"]);
+		const guides = [text(site["styleGuide"]), text(collection?.["styleGuide"])].filter((guide) => guide !== null);
+		const answer = (await deps.model([{
+			role: "system",
+			content: REVIEWER_PROMPT
+		}, {
+			role: "user",
+			content: [`Style guide:\n${guides.length === 0 ? "(none)" : guides.join("\n\n")}`, `Entry (${String(summary["locale"])}):\n\n${markdown}`].join("\n\n")
+		}])).trim();
+		if (answer === "") continue;
+		const body = answer.length > 3500 ? `${answer.slice(0, MAX_COMMENT)}…` : answer;
+		const result = await deps.hollware.call("comment_review", {
+			id,
+			body
+		});
+		await deps.memory.put(`reviewed:${id}`, String(result["outcome"]), 2592e3);
+		if (result["outcome"] === "commented") commented += 1;
+	}
+	return { commented };
+}
+const TRANSLATOR_PROMPT = [
+	"You translate a Markdown file of a website into another language.",
+	"Answer with the whole translated file and nothing else: no code fence around it, no comment.",
+	"Keep the frontmatter between its --- lines, with the same keys. Translate the values a reader sees, such as title and description;",
+	"keep dates, tags, identifiers and the value of the translation group exactly as they are.",
+	"Put a frontmatter value in double quotes when it holds a colon or starts with a symbol.",
+	"Keep Markdown structure, links, code blocks and components (lines that start with ::) as they are; translate only their text.",
+	"Write naturally, as a native speaker would, in the voice of the style guide."
+].join(" ");
+/** A slug from a title: lowercase ASCII words joined by hyphens. */
+function slugOf(title) {
+	return title.normalize("NFD").replace(/[̀-ͯ]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80).replace(/-+$/, "") || "translation";
+}
+/** The model's file without a code fence around it, if it put one. */
+function unfenced(answer) {
+	const trimmed = answer.trim();
+	return `${(/^```[a-z]*\n([\s\S]*?)\n```$/.exec(trimmed)?.[1] ?? trimmed).trimEnd()}\n`;
+}
+function titleOf(markdown) {
+	return /^title:\s*["']?(.+?)["']?\s*$/m.exec(markdown)?.[1] ?? null;
+}
+function problemsOf(verdict) {
+	return list(verdict["errors"]).map((error) => `- ${String(error["path"])}: ${String(error["message"])} Fix: ${String(error["fix"])}`).join("\n");
+}
+/**
+* For each published entry of a collection with translations whose group lacks a locale of the
+* site, writes the translation as a draft, fixes what the contracts refuse up to `FIX_ROUNDS`
+* times, and asks a person to review it, at most `limit` a run. It reads each locale's entries in
+* one listing, so a run stays within the fifty calls a free Worker has; an entry of any status
+* in a locale counts as the translation, and the memory keeps what was tried, once it was saved or
+* refused: a run that stops before tries it again.
+*/
+async function translateMissing(deps, options = {}) {
+	const limit = options.limit ?? 2;
+	const site = record((await deps.hollware.call("describe_site", {}))["site"]);
+	const given = site["locales"];
+	const locales = Array.isArray(given) ? given.filter((one) => typeof one === "string") : [];
+	let drafted = 0;
+	let sentToReview = 0;
+	for (const collection of list(site["collections"])) {
+		const name = text(collection["name"]);
+		if (name === null || text(collection["translationGroupField"]) === null) continue;
+		const style = text(collection["styleGuide"]) ?? text(site["styleGuide"]) ?? "(none)";
+		const byLocale = /* @__PURE__ */ new Map();
+		for (const locale of locales) byLocale.set(locale, await entriesOf(deps.hollware, {
+			collection: name,
+			locale
+		}));
+		const groupsIn = new Map(locales.map((locale) => [locale, new Set((byLocale.get(locale) ?? []).map((entry) => text(entry["translationGroup"])))]));
+		for (const [source, entries] of byLocale) for (const entry of entries) {
+			const group = text(entry["translationGroup"]);
+			const id = text(entry["id"]);
+			if (entry["status"] !== "published" || group === null || id === null) continue;
+			for (const locale of locales) {
+				const present = groupsIn.get(locale);
+				if (locale === source || present === void 0 || present.has(group)) continue;
+				if (drafted >= limit) return {
+					drafted,
+					sentToReview
+				};
+				present.add(group);
+				const key = `translated:${id}:${locale}`;
+				if (await deps.memory.get(key) !== null) continue;
+				const source_ = text(record((await deps.hollware.call("get_entry", {
+					collection: name,
+					locale: source,
+					slug: entry["slug"]
+				}))["entry"])["markdown"]);
+				if (source_ === null) continue;
+				const translated = unfenced(await deps.model([{
+					role: "system",
+					content: TRANSLATOR_PROMPT
+				}, {
+					role: "user",
+					content: `Translate from ${source} into ${locale}.\n\nStyle guide:\n${style}\n\nFile:\n\n${source_}`
+				}]));
+				const slug = slugOf(titleOf(translated) ?? String(entry["slug"]));
+				let saved = await deps.hollware.call("create_draft", {
+					collection: name,
+					locale,
+					slug,
+					markdown: translated
+				});
+				if (saved["outcome"] === "refused") saved = await deps.hollware.call("create_draft", {
+					collection: name,
+					locale,
+					slug: `${slug}-${locale}`,
+					markdown: translated
+				});
+				await deps.memory.put(key, String(saved["outcome"]), 7776e3);
+				if (saved["outcome"] !== "saved") continue;
+				drafted += 1;
+				if (await fixAndAsk(deps, saved, name, locale)) sentToReview += 1;
+			}
+		}
+	}
+	return {
+		drafted,
+		sentToReview
+	};
+}
+/** Fixes a saved draft up to `FIX_ROUNDS` times, then asks for its review if the contracts allow it. */
+async function fixAndAsk(deps, saved, collection, locale) {
+	let entry = record(saved["entry"]);
+	let verdict = record(saved["verdict"]);
+	for (let round = 0; round < 2 && verdict["ok"] === false; round++) {
+		const current = text(record((await deps.hollware.call("get_entry", {
+			collection,
+			locale,
+			slug: entry["slug"]
+		}))["entry"])["markdown"]);
+		if (current === null) return false;
+		const fixed = unfenced(await deps.model([{
+			role: "system",
+			content: TRANSLATOR_PROMPT
+		}, {
+			role: "user",
+			content: `The contracts of the site refuse this file. Fix these problems, change nothing else, and answer with the whole file.\n\n${problemsOf(verdict)}\n\nFile:\n\n${current}`
+		}]));
+		const updated = await deps.hollware.call("update_draft", {
+			id: entry["id"],
+			version: entry["version"],
+			markdown: fixed
+		});
+		if (updated["outcome"] !== "saved") return false;
+		entry = record(updated["entry"]);
+		verdict = record(updated["verdict"]);
+	}
+	if (verdict["ok"] === false) return false;
+	const version = number(entry["version"]);
+	let asked = await deps.hollware.call("request_review", {
+		id: entry["id"],
+		version
+	});
+	if (asked["outcome"] === "needs_acknowledgement") {
+		const warnings = list(record(asked["verdict"])["warnings"]).map((warning) => ({
+			contract: warning["contract"],
+			path: warning["path"]
+		}));
+		asked = await deps.hollware.call("request_review", {
+			id: entry["id"],
+			version,
+			acknowledgeWarnings: warnings
+		});
+	}
+	return asked["outcome"] === "pending_review";
+}
+//#endregion
+//#region src/worker.ts
+/** The roles, by turn: each run is one, so that it stays within the fifty calls of a free run. */
+const ROLES = [
+	"reviewer",
+	"translator",
+	"auditor"
+];
+/** The role whose turn it is at `time`: the ten minutes of the time, in turn. */
+function roleAt(time) {
+	return ROLES[Math.floor(time / 6e5) % ROLES.length] ?? "reviewer";
+}
+/** The memory's key of the day of the last audit. */
+const LAST_AUDIT = "audit:last";
+/** Whether an audit is due: none yet, or the last one `everyDays` or more days before `day`. */
+function auditDue(last, day, everyDays) {
+	return last === null || Date.parse(day) - Date.parse(last) >= everyDays * 864e5;
+}
+function log(entry) {
+	console.log(JSON.stringify({
+		source: "hollware-agents",
+		...entry
+	}));
+}
+/**
+* The Worker of the agents. Hollware's cron wakes them every ten minutes over a service binding
+* (`run`), or a cron trigger of their own does (`scheduled`). Each run is one role, in turn: the
+* reviewer, the translator, then the auditor, which checks a dozen entries and writes its report
+* when it is due. A free Worker makes fifty calls a run at most, which one role fits in. A role
+* that fails is logged; reaching the day's limit of model calls ends it quietly.
+*/
+function createHollwareAgents(options = {}) {
+	const clock = options.clock ?? (() => /* @__PURE__ */ new Date());
+	const auditor = options.auditor === void 0 ? false : options.auditor;
+	const depsOf = (env) => {
+		const hollware = mcpHollware({
+			url: env.HOLLWARE_PUBLIC_URL,
+			token: env.HOLLWARE_AGENT_TOKEN,
+			fetch: (request) => env.HOLLWARE === void 0 ? fetch(request) : env.HOLLWARE.fetch(request)
+		});
+		const memory = kvMemory(env.AGENTS_KV);
+		const chosen = options.model ?? "@cf/meta/llama-3.3-70b-instruct-fp8-fast";
+		const base = typeof chosen === "function" ? chosen : (messages) => {
+			if (env.AI === void 0) throw new Error("The agents need the AI binding for a Workers AI model");
+			return workersAiModel(env.AI, chosen, options.gateway === void 0 ? {} : { gateway: options.gateway })(messages);
+		};
+		const today = () => clock().toISOString().slice(0, 10);
+		return {
+			hollware,
+			memory,
+			model: capped(base, memory, options.dailyLimit ?? 100, today)
+		};
+	};
+	const run = async (role, work) => {
+		try {
+			log({
+				role,
+				...await work()
+			});
+			return true;
+		} catch (error) {
+			if (error instanceof DailyLimitReached) {
+				log({
+					role,
+					stopped: error.message
+				});
+				return false;
+			}
+			log({
+				role,
+				failed: error instanceof Error ? error.message : String(error)
+			});
+			return true;
+		}
+	};
+	/** One role a run, by the ten minutes of the time: the reviewer, the translator, the auditor. */
+	const runOnce = async (env) => {
+		const deps = depsOf(env);
+		const now = clock();
+		const role = roleAt(now.getTime());
+		if (role === "reviewer") {
+			if (options.reviewer !== false) await run("reviewer", () => reviewPending(deps));
+			return;
+		}
+		if (role === "translator") {
+			if (options.translator === false) return;
+			const limit = typeof options.translator === "object" ? options.translator.limit : void 0;
+			await run("translator", () => translateMissing(deps, limit === void 0 ? {} : { limit }));
+			return;
+		}
+		if (auditor === false) return;
+		await run("auditor", () => auditStep(deps, {
+			report: auditor,
+			now: now.toISOString()
+		}));
+		const day = now.toISOString().slice(0, 10);
+		if (!auditDue(await deps.memory.get("audit:last"), day, auditor.everyDays ?? 7)) return;
+		const url = env.AGENTS_WEBHOOK_URL;
+		if (await run("report", () => writeReport({
+			hollware: deps.hollware,
+			memory: deps.memory,
+			webhook: url === void 0 || url === "" ? void 0 : async (report) => {
+				const response = await fetch(url, {
+					method: "POST",
+					headers: { "content-type": "application/json" },
+					body: JSON.stringify({ text: report })
+				});
+				if (!response.ok) throw new Error(`The webhook answered ${response.status}`);
+			}
+		}, {
+			report: auditor,
+			day,
+			...auditor.staleDays === void 0 ? {} : { staleDays: auditor.staleDays }
+		}))) await deps.memory.put(LAST_AUDIT, day);
+	};
+	return {
+		run: runOnce,
+		async scheduled(_controller, env, ctx) {
+			ctx.waitUntil(runOnce(env));
+		},
+		async fetch(request) {
+			const { pathname } = new URL(request.url);
+			return pathname === "/health" ? Response.json({ ok: true }, { headers: { "cache-control": "no-store" } }) : new Response("Not found", { status: 404 });
+		}
+	};
+}
+//#endregion
+//#region src/index.ts
+const name = "@hollware/agents";
+//#endregion
+export { AGENTS_CLIENT, ALLOWED_TOOLS, AUDIT_STATE, DEFAULT_MODEL, DailyLimitReached, LAST_AUDIT, ROLES, allowOnly, audit, auditDue, auditStep, capped, createHollwareAgents, kvMemory, mapMemory, mcpHollware, name, reportOf, reviewPending, roleAt, slugOf, translateMissing, workersAiModel, writeReport };

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@hollware/agents",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.6.0",
+  "description": "Agents for Hollware on Cloudflare: an editorial reviewer, a translator and a weekly auditor, none of which publishes.",
+  "homepage": "https://hollware.com",
+  "bugs": {
+    "url": "https://github.com/hollware/hollware/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hollware/hollware.git",
+    "directory": "packages/agents"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@hollware/core": "0.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.19.2",
+    "publint": "0.3.25",
+    "typescript": "7.0.2",
+    "vite-plus": "1.1.0",
+    "zod": "4.6.5"
+  },
+  "peerDependencies": {
+    "zod": "^4.2.0"
+  },
+  "engines": {
+    "node": ">=24.11.0"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "test": "vp test",
+    "publint": "publint --strict"
+  }
 }