@plasm_lang/vercel-agent 0.3.78 → 0.3.81

package/templates/mcp-radar/agent/hooks/proof-audit.ts

@@ -0,0 +1,10 @@
+import { defineHook } from "@plasm_lang/vercel-agent";
+
+export default defineHook({
+  name: "proof-audit",
+  on: ["run:complete", "plan:commit"],
+  handler: (_ctx, detail) => {
+    const keys = detail && typeof detail === "object" ? Object.keys(detail) : [];
+    console.log(`[mcp-radar:hook:proof-audit] event detail keys=${keys.join(",")}`);
+  },
+});

package/templates/mcp-radar/agent/instructions.md

@@ -0,0 +1,24 @@
+# MCP Radar
+
+You track **Model Context Protocol (MCP)** innovation signals on Hacker News and corroborate them with Tavily web search.
+
+## Tool order
+
+1. **`discover_capabilities`** — only when unsure which catalog entities to use.
+2. **`plasm_context`** — open or extend a session with seeds:
+   - `hackernews:Item`
+   - `tavily:SearchResult`
+   - Use stable intent: `track MCP innovations from Hacker News and corroborate with Tavily web search`
+3. **`plasm`** — dry-run programs using teaching TSV symbols.
+4. **`plasm_run`** — live execute reviewed plans (`pcN` only).
+
+## Per-run workflow
+
+1. Search HN (`item_search` or `item_search_by_date`) for MCP-related stories from the candidate list in the user goal.
+2. For each **new** story, optionally `item_get` for score and metadata.
+3. If Tavily is available, run `web_search` with a query derived from the story title to corroborate.
+4. Emit **proof entries** using the `mcp-proof-format` skill template (one `###` block per story).
+
+If Tavily is unavailable, synthesize from HN only and set **Confidence: low**.
+
+Do not invent `e#` / `p#` symbols — copy from the teaching TSV.

package/templates/mcp-radar/agent/research/mcp-innovations-proof.md

@@ -0,0 +1,4 @@
+# MCP Innovations Proof Log
+
+Append-only research artifact maintained by the MCP Radar agent.
+Each automated or manual run adds a dated section below.

package/templates/mcp-radar/agent/schedules/mcp-radar-scan.ts

@@ -0,0 +1,14 @@
+import { defineSchedule } from "@plasm_lang/vercel-agent";
+
+import { runRadar } from "../../lib/run-radar.js";
+
+export default defineSchedule({
+  name: "mcp-radar-scan",
+  cron: "0 */6 * * *",
+  handler: async (ctx) => {
+    const result = await runRadar(ctx);
+    console.log(
+      `[mcp-radar:schedule] ok=${result.ok} skipped=${result.skipped} new=${result.newCandidates.length} reason=${result.reason ?? ""}`,
+    );
+  },
+});

package/templates/mcp-radar/agent/skills/mcp-proof-format.md

@@ -0,0 +1,19 @@
+# MCP proof entry format
+
+When the user asks for proof entries, output markdown blocks exactly in this shape (one per story):
+
+```markdown
+### [Story title](hn-url)
+- **HN**: id {id}, score {score}, posted {iso-or-relative}
+- **Tavily**: {source title} ({url}); {optional second source}
+- **Synthesis**: 2–3 sentences on what MCP innovation angle this represents.
+- **Confidence**: high | medium | low
+```
+
+## Correlation rubric
+
+- **high**: Tavily finds independent coverage of the same product/announcement within 7 days.
+- **medium**: Tavily finds related MCP ecosystem context but not the exact story.
+- **low**: HN only, or Tavily unavailable, or weak keyword match.
+
+Skip stories that are not meaningfully about MCP (Model Context Protocol), unless the run goal explicitly lists them.

package/templates/mcp-radar/api/[[...path]].ts

@@ -0,0 +1,23 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import agentDefinition from "../agent/agent.js";
+import { createPlasmApp, vercelPlasmHandler } from "@plasm_lang/vercel-agent";
+
+const packageRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const agentRoot = path.join(packageRoot, "agent");
+
+let app: Awaited<ReturnType<typeof createPlasmApp>> | undefined;
+
+export default async function handler(
+  req: import("node:http").IncomingMessage,
+  res: import("node:http").ServerResponse,
+): Promise<void> {
+  app ??= await createPlasmApp({
+    agentRoot,
+    definition: agentDefinition,
+    mode: "prod",
+    sessions: false,
+  });
+  await vercelPlasmHandler(app)(req, res);
+}

package/templates/mcp-radar/evals/mcp-radar-discover.eval.ts

@@ -0,0 +1,14 @@
+import { defineEval } from "@plasm_lang/vercel-agent";
+
+export default defineEval({
+  name: "mcp-radar-discover",
+  goal: [
+    "Search Hacker News for recent discussion about MCP (Model Context Protocol).",
+    "Open a federated plasm session for hackernews and tavily if available.",
+    "Summarize one interesting story and what MCP innovation it represents.",
+  ].join(" "),
+  assert: {
+    toolsUsedAny: ["plasm_context", "plasm_run"],
+    minSteps: 1,
+  },
+});

package/templates/mcp-radar/lib/proof-store.ts

@@ -0,0 +1,265 @@
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+export interface SeenState {
+  itemIds: string[];
+  lastRunAt?: string;
+  lastRunStatus?: "ok" | "skipped" | "error";
+  lastNewCount?: number;
+}
+
+export interface LastRunMeta {
+  at: string;
+  status: "ok" | "skipped" | "error";
+  newItems: number;
+  message?: string;
+}
+
+export type ProofStoreBackend = "fs" | "vercel";
+
+export interface ProofStore {
+  backend(): ProofStoreBackend;
+  readProofMarkdown(): Promise<string>;
+  appendProofRun(section: { runAt: string; body: string }): Promise<void>;
+  loadSeenState(): Promise<SeenState>;
+  saveSeenState(state: SeenState): Promise<void>;
+  addSeenIds(ids: string[]): Promise<SeenState>;
+  loadLastRun(): Promise<LastRunMeta | null>;
+  saveLastRun(meta: LastRunMeta): Promise<void>;
+}
+
+const SEEN_KV_KEY = "plasm:mcp-radar:seen";
+const LAST_RUN_KV_KEY = "plasm:mcp-radar:last-run";
+const PROOF_BLOB_KEY = "research/mcp-innovations-proof.md";
+const PROOF_HEADER = "# MCP Innovations Proof Log\n\n";
+
+function researchDir(agentRoot: string): string {
+  return path.join(agentRoot, ".plasm", "research");
+}
+
+function proofPath(agentRoot: string): string {
+  return path.join(agentRoot, "research", "mcp-innovations-proof.md");
+}
+
+function seenPath(agentRoot: string): string {
+  return path.join(researchDir(agentRoot), "seen-hn-items.json");
+}
+
+function lastRunPath(agentRoot: string): string {
+  return path.join(researchDir(agentRoot), "last-run.json");
+}
+
+export function resolveProofStoreBackend(): ProofStoreBackend {
+  const explicit = process.env.PLASM_PROOF_STORE_BACKEND?.trim().toLowerCase();
+  if (explicit === "fs" || explicit === "vercel") return explicit;
+  const hasKv =
+    Boolean(process.env.KV_REST_API_URL?.trim()) ||
+    Boolean(process.env.PLASM_KV_REST_API_URL?.trim());
+  const hasBlob = Boolean(process.env.BLOB_READ_WRITE_TOKEN?.trim());
+  if (hasKv && hasBlob) return "vercel";
+  return "fs";
+}
+
+type KvClient = {
+  get<T>(key: string): Promise<T | null>;
+  set(key: string, value: unknown): Promise<unknown>;
+};
+
+async function loadKv(): Promise<KvClient> {
+  const mod = await import("@vercel/kv");
+  return mod.kv as KvClient;
+}
+
+async function blobGetText(key: string): Promise<string | null> {
+  const { head } = await import("@vercel/blob");
+  const meta = await head(key).catch(() => null);
+  if (!meta?.url) return null;
+  const response = await fetch(meta.url);
+  if (!response.ok) return null;
+  return response.text();
+}
+
+async function blobPutText(key: string, body: string): Promise<void> {
+  const { put } = await import("@vercel/blob");
+  await put(key, body, { access: "public", addRandomSuffix: false });
+}
+
+class FsProofStore implements ProofStore {
+  constructor(private readonly agentRoot: string) {}
+
+  backend(): ProofStoreBackend {
+    return "fs";
+  }
+
+  async readProofMarkdown(): Promise<string> {
+    try {
+      return await readFile(proofPath(this.agentRoot), "utf8");
+    } catch {
+      return PROOF_HEADER;
+    }
+  }
+
+  async appendProofRun(section: { runAt: string; body: string }): Promise<void> {
+    const date = section.runAt.slice(0, 10);
+    const header = `\n\n## ${date} run (${section.runAt})\n\n`;
+    const block = section.body.trim();
+    if (!block) return;
+    await appendFile(proofPath(this.agentRoot), `${header}${block}\n`, "utf8");
+  }
+
+  async loadSeenState(): Promise<SeenState> {
+    try {
+      const raw = await readFile(seenPath(this.agentRoot), "utf8");
+      const parsed = JSON.parse(raw) as SeenState;
+      return {
+        itemIds: Array.isArray(parsed.itemIds) ? parsed.itemIds.map(String) : [],
+        lastRunAt: parsed.lastRunAt,
+        lastRunStatus: parsed.lastRunStatus,
+        lastNewCount: parsed.lastNewCount,
+      };
+    } catch {
+      return { itemIds: [] };
+    }
+  }
+
+  async saveSeenState(state: SeenState): Promise<void> {
+    await mkdir(researchDir(this.agentRoot), { recursive: true });
+    await writeFile(seenPath(this.agentRoot), `${JSON.stringify(state, null, 2)}\n`, "utf8");
+  }
+
+  async addSeenIds(ids: string[]): Promise<SeenState> {
+    const state = await this.loadSeenState();
+    const set = new Set(state.itemIds);
+    for (const id of ids) set.add(String(id));
+    const next: SeenState = { ...state, itemIds: [...set].sort() };
+    await this.saveSeenState(next);
+    return next;
+  }
+
+  async loadLastRun(): Promise<LastRunMeta | null> {
+    try {
+      const raw = await readFile(lastRunPath(this.agentRoot), "utf8");
+      return JSON.parse(raw) as LastRunMeta;
+    } catch {
+      return null;
+    }
+  }
+
+  async saveLastRun(meta: LastRunMeta): Promise<void> {
+    await mkdir(researchDir(this.agentRoot), { recursive: true });
+    await writeFile(lastRunPath(this.agentRoot), `${JSON.stringify(meta, null, 2)}\n`, "utf8");
+  }
+}
+
+class VercelProofStore implements ProofStore {
+  backend(): ProofStoreBackend {
+    return "vercel";
+  }
+
+  async readProofMarkdown(): Promise<string> {
+    const text = await blobGetText(PROOF_BLOB_KEY);
+    return text ?? PROOF_HEADER;
+  }
+
+  async appendProofRun(section: { runAt: string; body: string }): Promise<void> {
+    const date = section.runAt.slice(0, 10);
+    const header = `\n\n## ${date} run (${section.runAt})\n\n`;
+    const block = section.body.trim();
+    if (!block) return;
+    const existing = await this.readProofMarkdown();
+    await blobPutText(PROOF_BLOB_KEY, `${existing}${header}${block}\n`);
+  }
+
+  async loadSeenState(): Promise<SeenState> {
+    const kv = await loadKv();
+    const parsed = await kv.get<SeenState>(SEEN_KV_KEY);
+    if (!parsed) return { itemIds: [] };
+    return {
+      itemIds: Array.isArray(parsed.itemIds) ? parsed.itemIds.map(String) : [],
+      lastRunAt: parsed.lastRunAt,
+      lastRunStatus: parsed.lastRunStatus,
+      lastNewCount: parsed.lastNewCount,
+    };
+  }
+
+  async saveSeenState(state: SeenState): Promise<void> {
+    const kv = await loadKv();
+    await kv.set(SEEN_KV_KEY, state);
+  }
+
+  async addSeenIds(ids: string[]): Promise<SeenState> {
+    const state = await this.loadSeenState();
+    const set = new Set(state.itemIds);
+    for (const id of ids) set.add(String(id));
+    const next: SeenState = { ...state, itemIds: [...set].sort() };
+    await this.saveSeenState(next);
+    return next;
+  }
+
+  async loadLastRun(): Promise<LastRunMeta | null> {
+    const kv = await loadKv();
+    return kv.get<LastRunMeta>(LAST_RUN_KV_KEY);
+  }
+
+  async saveLastRun(meta: LastRunMeta): Promise<void> {
+    const kv = await loadKv();
+    await kv.set(LAST_RUN_KV_KEY, meta);
+  }
+}
+
+const storeCache = new Map<string, ProofStore>();
+
+export function resolveProofStore(agentRoot: string): ProofStore {
+  const key = `${resolveProofStoreBackend()}:${agentRoot}`;
+  const cached = storeCache.get(key);
+  if (cached) return cached;
+  const store =
+    resolveProofStoreBackend() === "vercel"
+      ? new VercelProofStore()
+      : new FsProofStore(agentRoot);
+  storeCache.set(key, store);
+  return store;
+}
+
+export async function readProofMarkdown(agentRoot: string): Promise<string> {
+  return resolveProofStore(agentRoot).readProofMarkdown();
+}
+
+export async function appendProofRun(
+  agentRoot: string,
+  section: { runAt: string; body: string },
+): Promise<void> {
+  return resolveProofStore(agentRoot).appendProofRun(section);
+}
+
+export async function loadSeenState(agentRoot: string): Promise<SeenState> {
+  return resolveProofStore(agentRoot).loadSeenState();
+}
+
+export async function saveSeenState(agentRoot: string, state: SeenState): Promise<void> {
+  return resolveProofStore(agentRoot).saveSeenState(state);
+}
+
+export async function addSeenIds(agentRoot: string, ids: string[]): Promise<SeenState> {
+  return resolveProofStore(agentRoot).addSeenIds(ids);
+}
+
+export async function saveLastRun(agentRoot: string, meta: LastRunMeta): Promise<void> {
+  return resolveProofStore(agentRoot).saveLastRun(meta);
+}
+
+export async function loadLastRun(agentRoot: string): Promise<LastRunMeta | null> {
+  return resolveProofStore(agentRoot).loadLastRun();
+}
+
+export function tavilyConfigured(): boolean {
+  return Boolean(process.env.TAVILY_API_TOKEN?.trim());
+}
+
+export function gatewayConfigured(): boolean {
+  return Boolean(
+    process.env.AI_GATEWAY_API_KEY?.trim() ||
+      process.env.AI_API_GATEWAY_KEY?.trim() ||
+      process.env.AI_GATEWAY_KEY?.trim(),
+  );
+}

package/templates/mcp-radar/lib/run-radar.ts

@@ -0,0 +1,214 @@
+import {
+  type AuthoringContext,
+} from "@plasm_lang/vercel-agent";
+
+import {
+  addSeenIds,
+  appendProofRun,
+  gatewayConfigured,
+  loadLastRun,
+  loadSeenState,
+  saveLastRun,
+  saveSeenState,
+  tavilyConfigured,
+} from "./proof-store.js";
+
+export const MCP_RADAR_INTENT =
+  "track MCP innovations from Hacker News and corroborate with Tavily web search";
+
+export const MCP_SEARCH_QUERY = "MCP OR Model Context Protocol";
+
+export interface HnStoryCandidate {
+  id: string;
+  title?: string;
+  url?: string;
+}
+
+export interface RadarRunOptions {
+  force?: boolean;
+}
+
+export interface RadarRunResult {
+  ok: boolean;
+  skipped: boolean;
+  reason?: string;
+  candidates: HnStoryCandidate[];
+  newCandidates: HnStoryCandidate[];
+  agentText?: string;
+  error?: string;
+}
+
+type HnStubModule = {
+  item_search?: (
+    input: { query: string; tags?: string; per_page?: number },
+    options?: { transport?: unknown },
+  ) => Promise<Array<{ id?: string | number; title?: string; url?: string }>>;
+};
+
+export async function preflightHnMcpStories(ctx: AuthoringContext): Promise<HnStoryCandidate[]> {
+  try {
+    const mod = (await ctx.importStub("hackernews")) as HnStubModule;
+    if (typeof mod.item_search !== "function") return [];
+    const rows = await mod.item_search(
+      { query: MCP_SEARCH_QUERY, tags: "story", per_page: 10 },
+    );
+    return rows
+      .map((row) => ({
+        id: String(row.id ?? ""),
+        title: row.title,
+        url: row.url,
+      }))
+      .filter((row) => row.id.length > 0);
+  } catch (err) {
+    console.warn("[mcp-radar] preflight HN search failed:", err);
+    return [];
+  }
+}
+
+function filterNewCandidates(
+  candidates: HnStoryCandidate[],
+  seenIds: Set<string>,
+  force: boolean,
+): HnStoryCandidate[] {
+  if (force) return candidates;
+  return candidates.filter((c) => !seenIds.has(c.id));
+}
+
+function buildAgentGoal(newCandidates: HnStoryCandidate[], tavily: boolean): string {
+  const lines = newCandidates.map(
+    (c) => `- id=${c.id} title=${JSON.stringify(c.title ?? "")} url=${JSON.stringify(c.url ?? "")}`,
+  );
+  const tavilyNote = tavily
+    ? "Tavily is configured — corroborate each story with web_search."
+    : "Tavily is NOT configured — HN-only synthesis; use Confidence: low.";
+  return [
+    "Produce MCP proof entries for these NEW Hacker News story candidates:",
+    ...lines,
+    "",
+    tavilyNote,
+    "",
+    "Use plasm_context with stable intent for hackernews + tavily, then plan and run programs.",
+    "Output markdown proof blocks per the mcp-proof-format skill (### headers).",
+    "Do not skip candidates unless they are clearly unrelated to MCP.",
+  ].join("\n");
+}
+
+export async function runRadar(
+  ctx: AuthoringContext,
+  options: RadarRunOptions = {},
+): Promise<RadarRunResult> {
+  const force = options.force === true;
+  const seen = await loadSeenState(ctx.agentRoot);
+  const seenSet = new Set(seen.itemIds);
+
+  const candidates = await preflightHnMcpStories(ctx);
+  const newCandidates = filterNewCandidates(candidates, seenSet, force);
+
+  if (!newCandidates.length && !force) {
+    const result: RadarRunResult = {
+      ok: true,
+      skipped: true,
+      reason: candidates.length ? "no_new_stories" : "no_hn_hits",
+      candidates,
+      newCandidates: [],
+    };
+    await saveSeenState(ctx.agentRoot, {
+      ...seen,
+      lastRunAt: new Date().toISOString(),
+      lastRunStatus: "skipped",
+      lastNewCount: 0,
+    });
+    await saveLastRun(ctx.agentRoot, {
+      at: new Date().toISOString(),
+      status: "skipped",
+      newItems: 0,
+      message: result.reason,
+    });
+    return result;
+  }
+
+  if (!gatewayConfigured()) {
+    const result: RadarRunResult = {
+      ok: false,
+      skipped: true,
+      reason: "ai_gateway_missing",
+      candidates,
+      newCandidates,
+      error: "AI_GATEWAY_API_KEY is required for agent synthesis",
+    };
+    await saveLastRun(ctx.agentRoot, {
+      at: new Date().toISOString(),
+      status: "error",
+      newItems: 0,
+      message: result.error,
+    });
+    return result;
+  }
+
+  const toProcess = newCandidates.length ? newCandidates : candidates;
+  const goal = buildAgentGoal(toProcess, tavilyConfigured());
+
+  try {
+    const agent = await ctx.getAgent();
+    const turn = await agent.generate(goal, { resetConversation: false });
+    const runAt = new Date().toISOString();
+
+    if (turn.text.trim()) {
+      await appendProofRun(ctx.agentRoot, { runAt, body: turn.text });
+    }
+
+    const ids = toProcess.map((c) => c.id);
+    await addSeenIds(ctx.agentRoot, ids);
+    await saveSeenState(ctx.agentRoot, {
+      ...(await loadSeenState(ctx.agentRoot)),
+      lastRunAt: runAt,
+      lastRunStatus: "ok",
+      lastNewCount: toProcess.length,
+    });
+    await saveLastRun(ctx.agentRoot, {
+      at: runAt,
+      status: "ok",
+      newItems: toProcess.length,
+    });
+
+    return {
+      ok: true,
+      skipped: false,
+      candidates,
+      newCandidates: toProcess,
+      agentText: turn.text,
+    };
+  } catch (err) {
+    const message = String(err);
+    await saveSeenState(ctx.agentRoot, {
+      ...(await loadSeenState(ctx.agentRoot)),
+      lastRunAt: new Date().toISOString(),
+      lastRunStatus: "error",
+    });
+    await saveLastRun(ctx.agentRoot, {
+      at: new Date().toISOString(),
+      status: "error",
+      newItems: 0,
+      message,
+    });
+    return {
+      ok: false,
+      skipped: false,
+      candidates,
+      newCandidates: toProcess,
+      error: message,
+    };
+  }
+}
+
+export async function radarStatus(agentRoot: string): Promise<Record<string, unknown>> {
+  const seen = await loadSeenState(agentRoot);
+  const last = await loadLastRun(agentRoot);
+  return {
+    gateway: gatewayConfigured(),
+    tavily: tavilyConfigured(),
+    seenCount: seen.itemIds.length,
+    lastRun: last,
+    intent: MCP_RADAR_INTENT,
+  };
+}

package/templates/mcp-radar/nitro.config.ts

@@ -0,0 +1,17 @@
+import { defineNitroConfig } from "nitropack/config";
+
+export default defineNitroConfig({
+  compatibilityDate: "2026-06-26",
+  srcDir: ".",
+  ignore: ["api/**"],
+  devServer: {
+    port: Number(process.env.PORT ?? 3000),
+    host: process.env.HOST ?? "127.0.0.1",
+  },
+  typescript: {
+    strict: false,
+  },
+  externals: {
+    inline: ["@plasm_lang/engine"],
+  },
+});

package/templates/mcp-radar/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "mcp-radar-agent",
+  "private": true,
+  "type": "module",
+  "description": "Event-driven MCP innovation radar — Hacker News + Tavily proof log",
+  "scripts": {
+    "smoke:channel": "tsx scripts/smoke-channel.ts",
+    "eval": "tsx scripts/run-evals.ts"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "tsx": "^4.19.4"
+  }
+}

package/templates/mcp-radar/public/index.html

@@ -0,0 +1,10 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>MCP Radar Agent</title>
+  </head>
+  <body>
+    <p>MCP Radar Agent — use <code>/channel/mcp-radar/status</code> or <code>/plasm/v1/info</code>.</p>
+  </body>
+</html>

package/templates/mcp-radar/routes/[...path].ts

@@ -0,0 +1,29 @@
+import path from "node:path";
+
+import { fromNodeMiddleware } from "h3";
+
+import agentDefinition from "../agent/agent.js";
+import { createPlasmApp, vercelPlasmHandler } from "@plasm_lang/vercel-agent";
+
+const agentRoot = path.join(process.cwd(), "agent");
+
+let appPromise: ReturnType<typeof createPlasmApp> | undefined;
+
+async function plasmApp() {
+  appPromise ??= createPlasmApp({
+    agentRoot,
+    definition: agentDefinition,
+    mode: "prod",
+    sessions: false,
+  });
+  return appPromise;
+}
+
+export default fromNodeMiddleware(async (req, res) => {
+  const app = await plasmApp();
+  await new Promise<void>((resolve, reject) => {
+    res.once("finish", () => resolve());
+    res.once("error", reject);
+    void vercelPlasmHandler(app)(req, res).catch(reject);
+  });
+});