feat(agents): refactor handlers to spec/proactive-runtime API

Each agent now matches the contract from
cloud/docs/proactive-runtime/spec.md — one `agent({ workspace,
schedule, watch, inbox, onEvent })` call per file, single handler
covering all triggers, progressive-disclosure events.

  agents/shared/sdk.ts        local mirror of @agent-relay/agent —
                              types + no-op shim. One-line swap when
                              the real package ships.
  agents/weekly-digest/agent.ts  fleshed out end-to-end with realistic
                              source choices (Tavily, Reddit JSON, GH
                              upsert) marked TODO where the runtime
                              still needs to land. Does the
                              dedupe-and-cluster work itself; only one
                              rolling issue per week.
  agents/{notion-to-blog,sunday-ping,pr-reviewer,manual-chatbot}/agent.ts
                              same shape, scaffolded against the spec
                              with restraint paths logged when they
                              fire (skip-with-reason vs act).

Build fix: sitemap.ts and robots.ts need `export const dynamic =
"force-static"` to play with `output: "export"`.

Plus the SEO scaffolding (lib/seo.ts, app/sitemap.ts, app/robots.ts,
metadata on each page, llms.txt) for the OG/structured-data layer.

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

Author: khaliqgant

agents/README.md

@@ -1,56 +1,76 @@
 # /agents
 
-The proactive agents that run this site. Each subdirectory is one agent. Each
-agent has a single entry point — `handler.ts` — that takes a typed event and
-returns nothing (side effects only).
+The proactive agents that run this site. Each agent is a single
+`agent({ ... })` call against the proactive-runtime SDK contract.
 
-## Why these live in this repo
+## The contract
 
-This site argues that a proactive agent is small code wrapped around the right
-runtime. Co-locating the agents with the site they operate keeps the demo
-honest and the deploy simple.
+Source: [`AgentWorkforce/cloud · spec/proactive-runtime · docs/proactive-runtime/spec.md`](https://github.com/AgentWorkforce/cloud/blob/spec/proactive-runtime/docs/proactive-runtime/spec.md).
 
-## The roster
-
-| Directory          | Trigger | What it does                                                                 |
-|--------------------|---------|------------------------------------------------------------------------------|
-| `notion-to-blog`   | change  | Watches a Notion database. When a page flips to `ready`, converts to MDX and opens a PR. |
-| `weekly-digest`    | time    | Weekly. Searches the web + Reddit for "proactive agents" mentions. Files one rolling GitHub issue, deduped, grouped by topic. |
-| `sunday-ping`      | time    | Sundays at 09:00 local. Reads the latest weekly digest and pings me on Slack with a draft outline for the next post. |
-| `pr-reviewer`      | change  | Comments on PRs to this repo with deploy preview, dead-link check, copy-edit notes. |
-| `manual-chatbot`   | message | Answers Slack DMs / emails grounded in the published essays.                  |
+The shape is:
 
-## Shape
+```ts
+import { agent } from "@agent-relay/agent";
 
+agent({
+  workspace: "support",
+  schedule: "*/5 * * * *",
+  watch: ["/zendesk/tickets/**"],
+  inbox: ["@self"],
+  onEvent: async (ctx, event) => {
+    // event.type is "cron.tick" | "relayfile.changed" | "relaycast.message"
+  },
+});
 ```
-agents/
-  shared/
-    log.ts          # writeLogEntry({ agent, action, summary, ... }) → appends to content/agent-log.json
-    types.ts        # AgentEntry, Trigger, Outcome (re-exports from lib/agent-log.ts)
-  notion-to-blog/
-    handler.ts      # export async function handler(event: NotionPageEvent)
-  weekly-digest/
-    handler.ts      # export async function handler() — invoked by relaycron
-  sunday-ping/
-    handler.ts      # export async function handler()
-  pr-reviewer/
-    handler.ts      # export async function handler(event: PullRequestEvent)
-  manual-chatbot/
-    handler.ts      # export async function handler(event: InboxMessage)
+
+One handler. Three triggers. One workspace. The whole API for the 90% case.
+
+## Status: spec-ahead
+
+`@agent-relay/agent` is not yet published. Until it is, the agents import
+from `agents/shared/sdk.ts` — a local mirror of the spec types plus a no-op
+`agent()` shim. When the package ships, the shim file gets one diff:
+
+```diff
+- export { agent, type AgentDefinition } from "./local-shim";
++ export { agent, type AgentDefinition } from "@agent-relay/agent";
 ```
 
-## Wiring
+Every agent file then runs unchanged.
+
+## The roster
+
+| File                              | Trigger | What it does                                                  |
+|-----------------------------------|---------|---------------------------------------------------------------|
+| `notion-to-blog/agent.ts`         | change  | Watch Notion drafts DB; on `status=ready`, MDX → PR.          |
+| `weekly-digest/agent.ts`          | time    | Saturday 09:00 UTC. Web + Reddit → one rolling GitHub issue. |
+| `sunday-ping/agent.ts`            | time    | Sunday 09:00 ET. Reads digest, drafts outline, Slack DM.      |
+| `pr-reviewer/agent.ts`            | change  | Watch repo PRs; deploy preview, dead-link, copy-edit notes.   |
+| `manual-chatbot/agent.ts`         | message | DMs + `#manual`. RAG over published essays. Refuses by default. |
+
+## Side effects
+
+Every agent calls `writeLogEntry(...)` from `shared/log.ts` so the public
+[/agent page](../app/agent/page.tsx) stays current. That page is the receipts.
+
+## Local dev
+
+```bash
+# Type-check the agents alongside the rest of the site
+npx tsc --noEmit
+```
 
-Each handler is invoked by the proactive runtime (`relaycron` for time,
-`relayfile` for change, `relaycast` for message). The wiring lives in the
-runtime config, not in the handler — so you can read each handler in isolation
-and see the full behaviour.
+To exercise an agent's behaviour without the runtime, call its `onEvent`
+directly from a test with a mock `Context` and `AgentEvent`. The shim's
+`agent()` registers the definition and returns; it does not dispatch events.
 
-Every handler ends by calling `writeLogEntry(...)` so the public `/agent` page
-on the site stays current. That page is the receipts.
+## Wiring (when the runtime ships)
 
-## Status
+1. `relay login`
+2. `relay workspaces create proactive-agents`
+3. `relay providers connect github notion slack reddit tavily`
+4. `relay deploy agents/weekly-digest/agent.ts` (and similar for the others)
 
-Skeletons. Each handler currently logs to the activity feed and returns;
-external integrations (Notion, GitHub, Slack, Reddit, web search) are stubbed.
-Wire them in PRs — the PR reviewer agent will check your work.
+The runtime reads the `agent({...})` definition, registers schedules with
+relaycron, watch globs with relayfile, channel subscriptions with relaycast,
+and starts dispatching events to `onEvent`.

agents/manual-chatbot/agent.ts

@@ -0,0 +1,100 @@
+/**
+ * @manual chatbot — MESSAGE trigger.
+ *
+ * Listens to DMs and the #manual channel. Answers questions about proactive
+ * agents grounded in the published essays (RAG over content/posts/*.mdx).
+ *
+ * Restraint matters here more than anywhere else. False answers cost trust
+ * faster than honest "don't knows". The agent refuses (politely, logged) when:
+ *   - the question isn't on-topic
+ *   - the corpus has no chunk above the relevance threshold
+ */
+import { agent, type Context, type AgentEvent } from "../shared/sdk";
+import { writeLogEntry } from "../shared/log";
+
+const RELEVANCE_THRESHOLD = 0.7;
+
+type MessageExpansion = {
+  data: {
+    text: string;
+    threadId?: string;
+    channel: string;
+    user: { id: string; displayName?: string };
+  };
+};
+
+export default agent({
+  workspace: "proactive-agents",
+  name: "manual-chatbot",
+  inbox: ["@self", "#manual"],
+
+  async onEvent(ctx: Context, event: AgentEvent) {
+    if (event.type !== "relaycast.message") return;
+
+    const msg = (await event.expand("full")) as MessageExpansion;
+    const question = msg.data.text;
+
+    // 1. Cheap intent classification: is this about proactive agents?
+    //    Use a small Claude Haiku call with a tight rubric.
+    //    TODO: implement isOnTopic(question)
+    const onTopic = true;
+
+    if (!onTopic) {
+      await polite("Sorry — I only answer questions about proactive agents. Try reframing?");
+      await writeLogEntry({
+        agent: "manual-chatbot",
+        trigger: "message",
+        action: "Refused — off topic",
+        summary: `${msg.data.user.displayName ?? msg.data.user.id} asked "${preview(question)}". Off topic; refused.`,
+        outcome: "skipped",
+        skippedReason: "off-topic",
+      });
+      return;
+    }
+
+    // 2. Retrieve top-K chunks from the published corpus.
+    //    The corpus is content/posts/*.mdx, indexed at deploy time into a
+    //    small embeddings file at /_internal/manual-chatbot/index.json.
+    //    TODO: implement retrieveCorpus(question, topK)
+    const chunks: { slug: string; title: string; text: string; score: number }[] = [];
+
+    if (chunks.length === 0 || chunks[0].score < RELEVANCE_THRESHOLD) {
+      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({
+        agent: "manual-chatbot",
+        trigger: "message",
+        action: "Refused — low confidence",
+        summary: `${msg.data.user.displayName ?? msg.data.user.id} asked "${preview(question)}". Top chunk score ${chunks[0]?.score ?? 0} < threshold ${RELEVANCE_THRESHOLD}. Refused.`,
+        outcome: "skipped",
+        skippedReason: "low confidence",
+      });
+      return;
+    }
+
+    // 3. Draft an answer with inline citations.
+    //    TODO: implement draftAnswer(question, chunks) — Claude Sonnet,
+    //    instructed to cite as [link text](/posts/<slug>) inline.
+    const answer = "TODO";
+
+    await ctx.messages.reply(msg.data.threadId ?? msg.data.channel, answer);
+
+    await writeLogEntry({
+      agent: "manual-chatbot",
+      trigger: "message",
+      action: `Answered ${msg.data.channel}`,
+      summary: `${msg.data.user.displayName ?? msg.data.user.id} asked "${preview(question)}". Answered with ${chunks.length} citation(s).`,
+      outcome: "success",
+      links: chunks.slice(0, 3).map((c) => ({ label: c.title, url: `/posts/${c.slug}` })),
+    });
+
+    async function polite(text: string) {
+      await ctx.messages.reply(msg.data.threadId ?? msg.data.channel, text);
+    }
+  },
+});
+
+function preview(s: string): string {
+  return s.length > 80 ? s.slice(0, 80) + "…" : s;
+}

agents/manual-chatbot/handler.ts

@@ -0,0 +1,92 @@
+/**
+ * Notion → blog agent — CHANGE trigger.
+ *
+ * Watches the Notion "Drafts" database (path mapped through relayfile-notion).
+ * When a page flips to status `ready`, converts blocks to MDX and opens a PR.
+ *
+ * Restraint: most page changes are NOT "ready" — they're typo fixes mid-draft.
+ * The agent skips with a logged reason rather than firing on every keystroke.
+ */
+import { agent, type Context, type AgentEvent } from "../shared/sdk";
+import { writeLogEntry } from "../shared/log";
+
+// One Notion DB id per workspace. Set via `relay providers connect notion`
+// during workspace setup; the relayfile-notion adapter mounts the DB at
+// /notion/databases/<dbId>/pages/* and emits a relayfile.changed event for
+// each page write.
+const DRAFTS_DB_PATH = "/notion/databases/drafts/pages/**";
+
+type NotionExpansion = {
+  data: {
+    id: string;
+    url: string;
+    properties: {
+      Title: { title: { plain_text: string }[] };
+      Slug: { rich_text: { plain_text: string }[] };
+      Status: { select: { name: "draft" | "editing" | "ready" | "published" } };
+    };
+    blocks: unknown[]; // Notion block list
+  };
+};
+
+export default agent({
+  workspace: "proactive-agents",
+  name: "notion-to-blog",
+  watch: DRAFTS_DB_PATH,
+
+  async onEvent(ctx: Context, event: AgentEvent) {
+    if (event.type !== "relayfile.changed") return;
+
+    // Cheap routing decision off the summary — no expand needed yet.
+    const status = event.summary.status;
+    const title = event.summary.title ?? "(untitled)";
+
+    if (status !== "ready") {
+      await writeLogEntry({
+        agent: "notion-to-blog",
+        trigger: "change",
+        action: `Skipped — page still ${status ?? "unset"}`,
+        summary: `Page "${title}" changed but status is "${status ?? "unset"}", not "ready". Nothing published.`,
+        outcome: "skipped",
+        skippedReason: `status != ready`,
+        links: [{ label: "Notion page", url: event.resource.path }],
+      });
+      return;
+    }
+
+    // Now we commit to the work — pull the full page including blocks.
+    const full = (await event.expand("full")) as NotionExpansion;
+    const slug = full.data.properties.Slug.rich_text[0]?.plain_text ?? slugify(title);
+
+    // TODO: blocks → MDX. Handle our Scene / Sidenote / Callout components by
+    // recognising specific Notion callout/toggle conventions.
+    //   const mdx = blocksToMdx(full.data.blocks, frontmatterFrom(full));
+
+    // TODO: open PR via Octokit. Idempotent on (workspace, page.id, page.last_edited):
+    // if a PR for this page+revision already exists, no-op.
+    //   const prUrl = await ctx.once(
+    //     `notion-pr:${full.data.id}:${event.digest}`,
+    //     () => openPr({ path: `content/posts/${slug}.mdx`, body: mdx, title: `Publish: ${title}` }),
+    //   );
+
+    await writeLogEntry({
+      agent: "notion-to-blog",
+      trigger: "change",
+      action: "Published essay",
+      summary: `New page "${title}" tagged ready. Converted to MDX, opened PR.`,
+      outcome: "success",
+      links: [
+        { label: "Notion source", url: full.data.url },
+        { label: "Will live at", url: `/posts/${slug}` },
+      ],
+    });
+  },
+});
+
+function slugify(s: string): string {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80);
+}