feat(runtime): wire weekly-digest end-to-end via relaycron + Pages Function

The agent now actually does work when invoked. Architecture:

  relaycron (cloud)              schedule lives here
       │  cron fires Sat 09:00 UTC
       ▼  POST /api/cron/weekly-digest  (X-Cron-Secret header)
  Pages Function in this repo    verifies secret; builds Context
       │
       ▼
  agents/weekly-digest/agent.ts  Brave search → cluster → upsert issue
       │
       ▼
  GitHub Contents API            log entry committed to
                                 content/agent-log.json
       │
       ▼
  site rebuilds                  /agent page reflects the new entry

Pieces:
- agents/shared/openrouter.ts     OpenRouter client; default model is
                                  google/gemini-2.5-flash (cheap, JSON-good)
- agents/shared/github-app.ts     App auth → Octokit + REST plugins; helpers
                                  for read/write JSON files in the repo
- agents/shared/runtime/cloudflare-context.ts
                                  spec Context impl that maps VFS paths to
                                  repo paths, persists log + dedup state via
                                  the Contents API
- agents/shared/log.ts            now takes ctx; uses ctx.files so the same
                                  call site works in any runtime
- agents/weekly-digest/agent.ts   clusterByTopic → real OpenRouter call;
                                  upsertDigestIssue → real Octokit; setEnv()
                                  hook so the Pages Function can pass env in
- agents/shared/sdk.ts            shim handle now exposes .definition so the
                                  function can dispatch onEvent directly
                                  until @agent-relay/agent ships
- functions/api/cron/[agent].ts   Pages Function — secret check, dispatch,
                                  onError fallback
- scripts/register-schedules.ts   one-shot: reads each agent's schedule,
                                  upserts into relaycron with the webhook
                                  URL + shared-secret header

Other 4 agents updated to writeLogEntry(ctx, …) signature; they remain
scaffolds (not yet wired to the function).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: khaliqgant

agents/manual-chatbot/agent.ts

@@ -41,7 +41,7 @@ export default agent({
 
     if (!onTopic) {
       await polite("Sorry — I only answer questions about proactive agents. Try reframing?");
-      await writeLogEntry({
+      await writeLogEntry(ctx, {
         agent: "manual-chatbot",
         trigger: "message",
         action: "Refused — off topic",
@@ -62,7 +62,7 @@ export default agent({
       await polite(
         `I couldn't find a confident answer in the published essays. Either the topic isn't covered yet, or the question phrasing doesn't match what's there. Try the [essays index](https://proactiveagents.dev/posts) directly?`,
       );
-      await writeLogEntry({
+      await writeLogEntry(ctx, {
         agent: "manual-chatbot",
         trigger: "message",
         action: "Refused — low confidence",
@@ -80,7 +80,7 @@ export default agent({
 
     await ctx.messages.reply(msg.data.threadId ?? msg.data.channel, answer);
 
-    await writeLogEntry({
+    await writeLogEntry(ctx, {
       agent: "manual-chatbot",
       trigger: "message",
       action: `Answered ${msg.data.channel}`,

agents/notion-to-blog/agent.ts

@@ -42,7 +42,7 @@ export default agent({
     const title = event.summary.title ?? "(untitled)";
 
     if (status !== "ready") {
-      await writeLogEntry({
+      await writeLogEntry(ctx, {
         agent: "notion-to-blog",
         trigger: "change",
         action: `Skipped — page still ${status ?? "unset"}`,
@@ -69,7 +69,7 @@ export default agent({
     //     () => openPr({ path: `content/posts/${slug}.mdx`, body: mdx, title: `Publish: ${title}` }),
     //   );
 
-    await writeLogEntry({
+    await writeLogEntry(ctx, {
       agent: "notion-to-blog",
       trigger: "change",
       action: "Published essay",

agents/pr-reviewer/agent.ts

@@ -39,7 +39,7 @@ export default agent({
     );
 
     if (mdxChanged.length === 0 && codeChanged.length === 0) {
-      await writeLogEntry({
+      await writeLogEntry(ctx, {
         agent: "pr-reviewer",
         trigger: "change",
         action: `Skipped PR #${pr.data.number}`,
@@ -70,7 +70,7 @@ export default agent({
     //   await ctx.once(`pr-comment:${pr.data.number}:${pr.data.head.sha}`,
     //     () => upsertPrComment(pr.data.number, body));
 
-    await writeLogEntry({
+    await writeLogEntry(ctx, {
       agent: "pr-reviewer",
       trigger: "change",
       action: `Reviewed PR #${pr.data.number}`,

agents/shared/github-app.ts

@@ -0,0 +1,98 @@
+/**
+ * GitHub App auth → Octokit. Works in Cloudflare Workers via @octokit/app
+ * (uses Web Crypto under the hood, no Node deps).
+ *
+ * Reads the three GITHUB_APP_* env vars. The PRIVATE_KEY may have escaped
+ * newlines if it was set via dashboard text input — we normalise.
+ */
+import { App } from "@octokit/app";
+import { Octokit } from "octokit";
+
+/** Octokit with REST + paginate plugins, configured via App auth. */
+export type AppOctokit = Octokit;
+
+export type GithubEnv = {
+  GITHUB_APP_ID: string;
+  GITHUB_APP_PRIVATE_KEY: string;
+  GITHUB_APP_INSTALLATION_ID: string;
+};
+
+let cached: { installationId: number; octokit: AppOctokit } | null = null;
+
+export async function getOctokit(env: GithubEnv): Promise<AppOctokit> {
+  const installationId = Number(env.GITHUB_APP_INSTALLATION_ID);
+  if (cached?.installationId === installationId) return cached.octokit;
+
+  const privateKey = env.GITHUB_APP_PRIVATE_KEY.replace(/\\n/g, "\n");
+
+  // Pass the umbrella `Octokit` class so installation instances inherit
+  // .rest (the REST methods we use) and .paginate.
+  const app = new App({
+    appId: env.GITHUB_APP_ID,
+    privateKey,
+    Octokit,
+  });
+  const octokit = (await app.getInstallationOctokit(installationId)) as unknown as AppOctokit;
+  cached = { installationId, octokit };
+  return octokit;
+}
+
+/**
+ * Read a JSON file from the repo, return null if missing.
+ * Returns the file's content + sha (sha is required to update it).
+ */
+export async function readRepoJson<T = unknown>(
+  octokit: AppOctokit,
+  args: { owner: string; repo: string; path: string; ref?: string },
+): Promise<{ data: T; sha: string } | null> {
+  try {
+    const res = await octokit.rest.repos.getContent({
+      owner: args.owner,
+      repo: args.repo,
+      path: args.path,
+      ref: args.ref,
+    });
+    if (Array.isArray(res.data) || res.data.type !== "file") return null;
+    const text = atob(res.data.content.replace(/\n/g, ""));
+    return { data: JSON.parse(text) as T, sha: res.data.sha };
+  } catch (err) {
+    const status = (err as { status?: number }).status;
+    if (status === 404) return null;
+    throw err;
+  }
+}
+
+/**
+ * Idempotent JSON write. If the file exists, updates with the prior sha;
+ * if not, creates. Commit message includes the agent name + summary so the
+ * git log doubles as a coarser activity feed.
+ */
+export async function writeRepoJson(
+  octokit: AppOctokit,
+  args: {
+    owner: string;
+    repo: string;
+    path: string;
+    branch?: string;
+    data: unknown;
+    message: string;
+  },
+): Promise<void> {
+  const existing = await readRepoJson(octokit, {
+    owner: args.owner,
+    repo: args.repo,
+    path: args.path,
+    ref: args.branch,
+  });
+  const content = btoa(unescape(encodeURIComponent(JSON.stringify(args.data, null, 2) + "\n")));
+
+  await octokit.rest.repos.createOrUpdateFileContents({
+    owner: args.owner,
+    repo: args.repo,
+    path: args.path,
+    branch: args.branch,
+    message: args.message,
+    content,
+    sha: existing?.sha,
+  });
+}

agents/shared/log.ts

@@ -1,47 +1,45 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import type { AgentEntry } from "@/lib/agent-log";
-
-const LOG_PATH = path.join(process.cwd(), "content", "agent-log.json");
-
 /**
- * Appends an entry to the public agent log. Idempotent on `id` — if an entry
- * with the same id is already present, it's replaced rather than duplicated.
+ * Append an entry to the public agent log via the spec Context.
  *
- * Designed to run from a Node-side handler (Cloudflare Worker, scheduled job,
- * webhook receiver). At deploy time, the static export bakes the log into the
- * /agent page; for live updates we'd swap this for an edge KV write.
+ * The log file is a JSON array at /_meta/agent-log.json in workspace VFS.
+ * Each runtime impl decides what that path means:
+ *   - Cloudflare runtime → committed to content/agent-log.json on GitHub
+ *   - Node/local dev     → written to ./content/agent-log.json on disk
+ *
+ * Agent code calls this via `await writeLogEntry(ctx, {...})` and stays
+ * runtime-agnostic.
  */
-export async function writeLogEntry(
-  entry: Omit<AgentEntry, "id" | "timestamp"> & {
-    id?: string;
-    timestamp?: string;
-  }
-): Promise<AgentEntry> {
-  const full: AgentEntry = {
-    id: entry.id ?? `${Date.now()}-${entry.agent}-${Math.random().toString(36).slice(2, 8)}`,
-    timestamp: entry.timestamp ?? new Date().toISOString(),
-    agent: entry.agent,
-    trigger: entry.trigger,
-    action: entry.action,
-    summary: entry.summary,
-    outcome: entry.outcome,
-    links: entry.links,
-    skippedReason: entry.skippedReason,
+import type { Context } from "./sdk";
+import type { AgentEntry } from "@/lib/agent-log";
+
+const LOG_VFS_PATH = "/_meta/agent-log.json";
+
+export type LogInput = Omit<AgentEntry, "id" | "timestamp"> & {
+  id?: string;
+  timestamp?: string;
+};
+
+export async function writeLogEntry(ctx: Context, input: LogInput): Promise<AgentEntry> {
+  const entry: AgentEntry = {
+    id: input.id ?? `${Date.now()}-${input.agent}-${Math.random().toString(36).slice(2, 8)}`,
+    timestamp: input.timestamp ?? new Date().toISOString(),
+    agent: input.agent,
+    trigger: input.trigger,
+    action: input.action,
+    summary: input.summary,
+    outcome: input.outcome,
+    links: input.links,
+    skippedReason: input.skippedReason,
   };
 
-  const existing = await readLog();
-  const without = existing.filter((e) => e.id !== full.id);
-  const next = [full, ...without];
-  await fs.writeFile(LOG_PATH, JSON.stringify(next, null, 2) + "\n", "utf8");
-  return full;
-}
+  const file = await ctx.files.read(LOG_VFS_PATH);
+  const existing = (file?.body as AgentEntry[] | undefined) ?? [];
+  const without = existing.filter((e) => e.id !== entry.id);
+  const next = [entry, ...without];
+
+  await ctx.files.write(LOG_VFS_PATH, next, {
+    message: `[${entry.agent}] ${entry.action}`,
+  });
 
-async function readLog(): Promise<AgentEntry[]> {
-  try {
-    const raw = await fs.readFile(LOG_PATH, "utf8");
-    return JSON.parse(raw) as AgentEntry[];
-  } catch {
-    return [];
-  }
+  return entry;
 }

agents/shared/openrouter.ts

@@ -0,0 +1,69 @@
+/**
+ * Thin OpenRouter wrapper. OpenRouter speaks the OpenAI chat-completions
+ * API, so this is a single fetch with no SDK dependency — keeps the bundle
+ * tiny on Cloudflare Workers.
+ *
+ * Model choice is centralised here. Cheap-and-good default for clustering
+ * and structured-output tasks; swap one constant if it ever needs upgrading.
+ */
+
+export const DEFAULT_MODEL = "google/gemini-2.5-flash";
+
+export type ChatMessage =
+  | { role: "system"; content: string }
+  | { role: "user"; content: string }
+  | { role: "assistant"; content: string };
+
+export type CompletionOptions = {
+  apiKey: string;
+  model?: string;
+  messages: ChatMessage[];
+  /** Force JSON output. Most modern models honour this. */
+  jsonMode?: boolean;
+  /** 0–2. Default 0.2 for analytical tasks. */
+  temperature?: number;
+  signal?: AbortSignal;
+};
+
+export async function complete(opts: CompletionOptions): Promise<string> {
+  const res = await fetch("https://openrouter.ai/api/v1/chat/completions", {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${opts.apiKey}`,
+      "Content-Type": "application/json",
+      // Optional but nice — OpenRouter shows it in their dashboard
+      "HTTP-Referer": "https://proactiveagents.dev",
+      "X-Title": "Proactive Agents",
+    },
+    body: JSON.stringify({
+      model: opts.model ?? DEFAULT_MODEL,
+      messages: opts.messages,
+      temperature: opts.temperature ?? 0.2,
+      ...(opts.jsonMode ? { response_format: { type: "json_object" } } : {}),
+    }),
+    signal: opts.signal,
+  });
+  if (!res.ok) {
+    throw new Error(`openrouter ${res.status}: ${await res.text().catch(() => "")}`);
+  }
+  const data = (await res.json()) as {
+    choices?: { message?: { content?: string } }[];
+    error?: { message: string };
+  };
+  if (data.error) throw new Error(`openrouter: ${data.error.message}`);
+  const text = data.choices?.[0]?.message?.content;
+  if (!text) throw new Error("openrouter: empty response");
+  return text;
+}
+
+/** Convenience: prompt the model for a JSON object, parse, validate shape. */
+export async function completeJson<T = unknown>(
+  opts: Omit<CompletionOptions, "jsonMode">,
+): Promise<T> {
+  const text = await complete({ ...opts, jsonMode: true });
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    throw new Error(`openrouter returned non-JSON despite jsonMode: ${text.slice(0, 200)}`);
+  }
+}