@plasm_lang/vercel-agent 0.3.78 → 0.3.80

package/src/cli/init.ts

@@ -1,112 +1,17 @@
-import { access, cp, mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 
-import { FRAMEWORK_VERSION } from "../project-info.js";
+import {
+  blankPackageJsonScaffold,
+  exists,
+  patchProjectPackageJson,
+  plasmAgentPackageRoot,
+  runTemplateInit,
+  writeDeployScaffold,
+} from "./init-scaffold.js";
 import type { ResolvedAgentProject } from "./project-root.js";
 
-export interface InitOptions {
-  template?: string;
-}
-
-const SKIP_TEMPLATE_DIRS = new Set(["node_modules", ".plasm", ".nitro", ".output", "server"]);
-const SKIP_TEMPLATE_FILES = new Set(["package-lock.json"]);
-
-function plasmAgentPackageRoot(): string {
-  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
-}
-
-function resolveTemplateDir(template: string): string {
-  const templates: Record<string, string> = {
-    "mcp-radar": path.join(plasmAgentPackageRoot(), "../../../examples/mcp-radar-agent"),
-  };
-  const dir = templates[template];
-  if (!dir) {
-    throw new Error(
-      `Unknown template "${template}". Available: ${Object.keys(templates).join(", ")}`,
-    );
-  }
-  return dir;
-}
-
-function shouldCopyTemplateEntry(src: string, templateRoot: string): boolean {
-  const rel = path.relative(templateRoot, src);
-  if (!rel || rel === "") return true;
-  const parts = rel.split(path.sep);
-  if (parts.some((part) => SKIP_TEMPLATE_DIRS.has(part))) return false;
-  if (SKIP_TEMPLATE_FILES.has(path.basename(src))) return false;
-  return true;
-}
-
-async function copyTemplate(templateRoot: string, projectRoot: string): Promise<void> {
-  await cp(templateRoot, projectRoot, {
-    recursive: true,
-    filter: (src) => src === templateRoot || shouldCopyTemplateEntry(src, templateRoot),
-  });
-}
-
-async function patchBootstrapPackageJson(
-  projectRoot: string,
-  packageRoot: string,
-): Promise<void> {
-  const pkgPath = path.join(projectRoot, "package.json");
-  const raw = await readFile(pkgPath, "utf8");
-  const pkg = JSON.parse(raw) as {
-    name?: string;
-    scripts?: Record<string, string>;
-    dependencies?: Record<string, string>;
-    devDependencies?: Record<string, string>;
-  };
-  pkg.name = path.basename(projectRoot);
-  const engineRoot = path.resolve(packageRoot, "../plasm-engine");
-  pkg.dependencies = {
-    ...pkg.dependencies,
-    "@plasm_lang/vercel-agent": `file:${path.resolve(packageRoot)}`,
-    "@plasm_lang/engine": `file:${engineRoot}`,
-    "@vercel/blob": "^0.27.3",
-    "@vercel/functions": "^3.4.3",
-    "@vercel/kv": "^3.0.0",
-  };
-  const nodeRunner =
-    "node --experimental-strip-types --experimental-transform-types ./node_modules/@plasm_lang/vercel-agent/scripts/plasm-node.mjs";
-  pkg.scripts = {
-    build: "plasm-agent build",
-    "vercel-build": "plasm-agent build",
-    dev: "plasm-agent dev",
-    "dev:interactive": "plasm-agent dev --interactive",
-    info: "plasm-agent info",
-    deploy: "vercel deploy",
-    ...pkg.scripts,
-    eval: `${nodeRunner} scripts/run-evals.ts`,
-    "smoke:channel": `${nodeRunner} scripts/smoke-channel.ts`,
-  };
-  pkg.devDependencies = {
-    ...pkg.devDependencies,
-    nitropack: "^2.13.4",
-  };
-  await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, "utf8");
-}
-
-async function runTemplateInit(
-  targetDir: string,
-  template: string,
-): Promise<ResolvedAgentProject> {
-  const projectRoot = path.resolve(targetDir);
-  const agentRoot = path.join(projectRoot, "agent");
-  if (await exists(path.join(agentRoot, "agent.ts"))) {
-    throw new Error(`agent/agent.ts already exists in ${projectRoot}`);
-  }
-  const templateRoot = resolveTemplateDir(template);
-  if (!(await exists(templateRoot))) {
-    throw new Error(`Template source missing: ${templateRoot}`);
-  }
-  await mkdir(projectRoot, { recursive: true });
-  await copyTemplate(templateRoot, projectRoot);
-  await patchBootstrapPackageJson(projectRoot, plasmAgentPackageRoot());
-  await writeVercelScaffold(projectRoot, template);
-  await writeNitroScaffold(projectRoot);
-  return { projectRoot, agentRoot };
-}
+export type { InitOptions } from "./init-scaffold.js";
 
 const AGENT_TS = `import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -203,177 +108,12 @@ PLASM_TENANT_SCOPE=local
 PORT=3000
 `;
 
-const VERCEL_JSON_DEFAULT = `{
-  "buildCommand": "plasm-agent build",
-  "rewrites": [{ "source": "/(.*)", "destination": "/api/$1" }]
-}
-`;
-
-const VERCEL_JSON_MCP_RADAR = `{
-  "buildCommand": "plasm-agent build",
-  "rewrites": [{ "source": "/(.*)", "destination": "/api/$1" }],
-  "crons": [
-    {
-      "path": "/internal/cron/mcp-radar-scan",
-      "schedule": "0 */6 * * *"
-    }
-  ],
-  "functions": {
-    "api/**": {
-      "maxDuration": 300
-    }
-  }
-}
-`;
-
-const VERCELIGNORE = `node_modules
-.env*
-agent/.plasm/research
-`;
-
-const API_HANDLER_TS = `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);
-}
-`;
-
-const NITRO_CONFIG_TS = `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"],
-  },
-});
-`;
-
-const NITRO_CATCHALL_ROUTE_TS = `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);
-  });
-});
-`;
-
-const PACKAGE_JSON_TEMPLATE = {
-  name: "my-plasm-agent",
-  private: true,
-  type: "module",
-  scripts: {
-    dev: "plasm-agent dev",
-    "dev:interactive": "plasm-agent dev --interactive",
-    build: "plasm-agent build",
-    "vercel-build": "plasm-agent build",
-    info: "plasm-agent info",
-    deploy: "vercel deploy",
-  },
-  dependencies: {} as Record<string, string>,
-  devDependencies: {
-    nitropack: "^2.13.4",
-  },
-};
-
-async function writeVercelScaffold(
-  projectRoot: string,
-  template?: string,
-): Promise<void> {
-  const vercelJson =
-    template === "mcp-radar" ? VERCEL_JSON_MCP_RADAR : VERCEL_JSON_DEFAULT;
-  await mkdir(path.join(projectRoot, "api"), { recursive: true });
-  await writeFile(path.join(projectRoot, "vercel.json"), vercelJson, "utf8");
-  await writeFile(path.join(projectRoot, ".vercelignore"), VERCELIGNORE, "utf8");
-  await writeFile(
-    path.join(projectRoot, "api", "[[...path]].ts"),
-    API_HANDLER_TS,
-    "utf8",
-  );
-}
-
-async function writeNitroScaffold(projectRoot: string): Promise<void> {
-  await mkdir(path.join(projectRoot, "routes"), { recursive: true });
-  await writeFile(path.join(projectRoot, "nitro.config.ts"), NITRO_CONFIG_TS, "utf8");
-  await writeFile(
-    path.join(projectRoot, "routes", "[...path].ts"),
-    NITRO_CATCHALL_ROUTE_TS,
-    "utf8",
-  );
-}
-
-function packageJsonScaffold(): Record<string, unknown> {
-  return {
-    ...PACKAGE_JSON_TEMPLATE,
-    dependencies: {
-      "@plasm_lang/vercel-agent": `^${FRAMEWORK_VERSION}`,
-    },
-  };
-}
-
-async function exists(p: string): Promise<boolean> {
-  try {
-    await access(p);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 export async function runPlasmInit(
   targetDir: string,
-  options?: InitOptions,
+  options?: import("./init-scaffold.js").InitOptions,
 ): Promise<ResolvedAgentProject> {
   if (options?.template) {
-    return runTemplateInit(targetDir, options.template);
+    return runTemplateInit(targetDir, options.template, options);
   }
 
   const projectRoot = path.resolve(targetDir);
@@ -399,21 +139,19 @@ export async function runPlasmInit(
   if (!(await exists(path.join(projectRoot, "package.json")))) {
     await writeFile(
       path.join(projectRoot, "package.json"),
-      `${JSON.stringify(packageJsonScaffold(), null, 2)}\n`,
+      `${JSON.stringify(blankPackageJsonScaffold(), null, 2)}\n`,
       "utf8",
     );
-    await patchBootstrapPackageJson(projectRoot, plasmAgentPackageRoot());
+    await patchProjectPackageJson(projectRoot, plasmAgentPackageRoot(), { npm: options?.npm });
   }
 
-  await writeVercelScaffold(projectRoot);
-  await writeNitroScaffold(projectRoot);
-
+  await writeDeployScaffold(projectRoot);
   return { projectRoot, agentRoot };
 }
 
 export function formatInitSuccess(
   project: ResolvedAgentProject,
-  options?: InitOptions,
+  options?: import("./init-scaffold.js").InitOptions,
 ): string {
   if (options?.template === "mcp-radar") {
     return [

package/src/cli/nitro-dev.ts

@@ -3,6 +3,7 @@ import { access } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { nitroDevNodeOptions } from "./node-dev-imports.js";
 import type { ResolvedAgentProject } from "./project-root.js";
 
 function plasmAgentPackageRoot(): string {
@@ -32,12 +33,7 @@ function nitroBin(projectRoot: string): string {
 export async function startNitroDevForProject(project: ResolvedAgentProject): Promise<void> {
   await assertNitroScaffold(project.projectRoot);
 
-  const loader = path.join(plasmAgentPackageRoot(), "scripts", "register-plasm-loader.mjs");
-  const nodeOptions = [
-    "--experimental-strip-types",
-    "--experimental-transform-types",
-    `--import=${loader}`,
-  ].join(" ");
+  const nodeOptions = nitroDevNodeOptions(plasmAgentPackageRoot());
 
   const bin = nitroBin(project.projectRoot);
   try {

package/src/cli/node-dev-imports.ts

@@ -0,0 +1,14 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const require = createRequire(import.meta.url);
+
+/** NODE_OPTIONS imports for Nitro dev (tsx + Plasm .ts resolution). */
+export function nitroDevNodeOptions(packageRoot: string): string {
+  const tsxImport = require.resolve("tsx/esm");
+  const plasmLoader = pathToFileURL(
+    path.join(packageRoot, "scripts", "register-plasm-loader.mjs"),
+  ).href;
+  return [`--import=${tsxImport}`, `--import=${plasmLoader}`].join(" ");
+}

package/src/package-version.ts

@@ -0,0 +1,14 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+let cachedVersion: string | undefined;
+
+/** Published semver from @plasm_lang/vercel-agent package.json. */
+export function frameworkPackageVersion(): string {
+  if (cachedVersion) return cachedVersion;
+  const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+  const raw = readFileSync(path.join(packageRoot, "package.json"), "utf8");
+  cachedVersion = (JSON.parse(raw) as { version: string }).version;
+  return cachedVersion;
+}

package/src/project-info.ts

@@ -10,6 +10,7 @@ import { isNativeEngineAvailable } from "./engine/napi-binding.js";
 import { exportScheduleCronManifest } from "./authoring/schedule-manager.js";
 import { isGatewayConfigured } from "./gateway-model.js";
 import type { LoadedProjectSlots } from "./authoring/slot-loader.js";
+import { frameworkPackageVersion } from "./package-version.js";
 import { resolveCatalogLiveHash } from "./stubs/catalog-hash.js";
 import { stubFreshness } from "./stubs/generator.js";
 
@@ -21,7 +22,7 @@ export const PLASM_LANGUAGE_TOOLS = [
 ] as const;
 
 export const FRAMEWORK_NAME = "@plasm_lang/vercel-agent";
-export const FRAMEWORK_VERSION = "0.0.1";
+export const FRAMEWORK_VERSION = frameworkPackageVersion();
 
 export interface CatalogInfoEntry {
   name: string;

package/templates/mcp-radar/.vercelignore

@@ -0,0 +1,3 @@
+node_modules
+.env*
+agent/.plasm/research

package/templates/mcp-radar/README.md

@@ -0,0 +1,139 @@
+# MCP Radar Agent
+
+Event-driven research example for [`@plasm_lang/vercel-agent`](../../plasm-oss/packages/plasm-agent/): watch Hacker News for **MCP** innovation signals, corroborate with **Tavily**, and append structured entries to a maintained proof log.
+
+## Purpose
+
+Demonstrates Plasm’s **dual surface**:
+
+- **Code surface** — channel/schedule handlers preflight HN via typed stubs and own proof persistence
+- **Model surface** — federated `plasm_context` (hackernews + tavily) → `plasm` → `plasm_run` for synthesis
+
+## Bootstrap from CLI
+
+Scaffold a fresh copy (verified by `npm run smoke:bootstrap` in the framework package):
+
+```bash
+mkdir /tmp/my-radar && cd /tmp/my-radar
+plasm-agent init --template mcp-radar .
+npm install
+plasm-agent build
+npm run smoke:channel
+plasm-agent dev
+```
+
+The canonical template source is this directory (`examples/mcp-radar-agent/`).
+
+## Deploy to Vercel
+
+Low-friction production path (eve-aligned): `vercel.json` + catch-all `api/[[...path]].ts` mounts the same routes as local dev (channels, cron, `/plasm/v1/info`).
+
+```bash
+cd examples/mcp-radar-agent   # or your bootstrapped project
+plasm-agent link
+plasm-agent build
+vercel env pull .env.local    # AI_GATEWAY_API_KEY, CRON_SECRET, KV, Blob
+vercel deploy
+curl -s "$DEPLOY_URL/channel/mcp-radar/status" | jq .
+```
+
+| Variable | Deploy |
+|----------|--------|
+| `AI_GATEWAY_API_KEY` | Required for agent synthesis |
+| `CRON_SECRET` | Required — Vercel Cron hits `/internal/cron/mcp-radar-scan` |
+| `KV_REST_API_URL` + `KV_REST_API_TOKEN` | Durable seen-items + last-run state |
+| `BLOB_READ_WRITE_TOKEN` | Durable proof markdown log |
+| `TAVILY_API_TOKEN` | Optional corroboration |
+
+On Vercel, `POST /channel/mcp-radar/run` returns `202` and continues in the background via `waitUntil`. Locally it runs synchronously for smoke tests.
+
+Monorepo deploy: set Vercel **Root Directory** to `examples/mcp-radar-agent`.
+
+## Setup (monorepo checkout)
+
+```bash
+cd examples/mcp-radar-agent
+npm install
+cp .env.example .env.local
+```
+
+| Variable | Required | Role |
+|----------|----------|------|
+| `AI_GATEWAY_API_KEY` | Yes (live runs) | Agent model turns |
+| `TAVILY_API_TOKEN` | Optional | Tavily corroboration; HN-only when unset |
+
+Build CGS stubs (symlinked catalogs):
+
+```bash
+npm run build
+```
+
+## Dev
+
+```bash
+npm run build
+npm run dev              # Nitro dev server — Vercel routing parity (channels, cron, /plasm/v1/*)
+npm run dev:interactive  # optional: in-process server + TUI + sessions + hot reload
+```
+
+`plasm-agent dev` starts Nitro by default so channel routes like `/channel/mcp-radar/status` match production.
+
+Slash commands in the interactive TUI: `/info`, `/catalogs`, `/new`, `/quit`.
+
+## Channel API
+
+Start headless dev server (`npm run dev:headless`), then:
+
+```bash
+BASE=http://127.0.0.1:3000
+
+# Status
+curl -s "$BASE/channel/mcp-radar/status" | jq .
+
+# Read proof log (markdown)
+curl -s "$BASE/channel/mcp-radar/proof"
+
+# Trigger one scan (dedupes seen HN ids)
+curl -s -X POST "$BASE/channel/mcp-radar/run" -H 'content-type: application/json' -d '{}'
+
+# Force scan even when no new ids
+curl -s -X POST "$BASE/channel/mcp-radar/run" -H 'content-type: application/json' -d '{"force":true}'
+```
+
+Proof artifact (local fs): [`agent/research/mcp-innovations-proof.md`](./agent/research/mcp-innovations-proof.md)
+
+Dedupe state (local fs): `agent/.plasm/research/seen-hn-items.json` (gitignored). On Vercel deploy, proof + dedupe use Blob + KV when env vars are set.
+
+## Schedule
+
+`agent/schedules/mcp-radar-scan.ts` runs every **6 hours** (`0 */6 * * *`). Vercel Cron calls `/internal/cron/mcp-radar-scan` with `Authorization: Bearer $CRON_SECRET`.
+
+## Evals
+
+```bash
+npm run eval    # requires AI_GATEWAY_API_KEY
+```
+
+Live eval: `evals/mcp-radar-discover.eval.ts`
+
+## Smoke
+
+```bash
+npm run build
+npm run smoke:channel
+```
+
+## Catalogs
+
+Symlinked from monorepo `apis/`:
+
+- `agent/catalogs/hackernews` → `plasm-oss/apis/hackernews`
+- `agent/catalogs/tavily` → `plasm-oss/apis/tavily`
+
+## Stable session intent
+
+```
+track MCP innovations from Hacker News and corroborate with Tavily web search
+```
+
+Federated seeds: `hackernews:Item`, `tavily:SearchResult`

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

@@ -0,0 +1,38 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  createAgentFromProject,
+  createProductionHostTransport,
+  defineAgent,
+  loadAgentEnv,
+} from "@plasm_lang/vercel-agent";
+
+loadAgentEnv();
+
+const agentRoot = path.dirname(fileURLToPath(import.meta.url));
+
+const agentDefinition = defineAgent({
+  model: process.env.PLASM_AGENT_MODEL ?? "anthropic/claude-sonnet-4.6",
+  compaction: { thresholdPercent: 0.75 },
+  modelOptions: { temperature: 0.2 },
+  experimental: {
+    workflow: { world: { type: "vercel" } },
+    skills: true,
+  },
+  build: {
+    externalDependencies: ["@plasm_lang/engine"],
+  },
+});
+
+export default agentDefinition;
+
+export async function createPlasmAgent() {
+  return createAgentFromProject(agentDefinition, {
+    agentRoot,
+    tenantScope: process.env.PLASM_TENANT_SCOPE ?? "mcp-radar",
+    maxSteps: 24,
+    telemetry: process.env.PLASM_AGENT_TELEMETRY !== "0",
+    hostTransport: createProductionHostTransport(),
+  });
+}

package/templates/mcp-radar/agent/catalogs/hackernews/README.md

@@ -0,0 +1,23 @@
+# Hacker News (Firebase API)
+
+Read-only mirror of the public [Hacker News API](https://github.com/HackerNews/API) plus the [Algolia HN search API](https://hn.algolia.com/api) (full-URL CML; same `http_backend` is Firebase for `item_get`). No authentication.
+
+## Scope
+
+- **item_search** / **item_search_by_date** — Algolia `search` and `search_by_date` (default `tags=story`). Rows use `objectID` as `id`; use **item_get** to load the Firebase item.
+- **item_feed_query** — ordered item ids for `top`, `new`, `best`, `ask`, `show`, or `job` (ids only; use **item_get** to hydrate).
+- **max_item_id_query** — current largest item id (`maxitem.json` returns a bare integer; mapped via `wrap_root_scalar`).
+- **recent_updated_item_query** / **recent_updated_user_query** — live slices from `updates.json` (`items` and `profiles` arrays; profiles are usernames only).
+- **item_get** / **user_get** — full JSON for an item or user. Poll stories expose **`parts`** (option ids) and the **`poll_options`** relation for chaining.
+
+## Try it
+
+```bash
+cargo run --bin plasm-repl -- --schema apis/hackernews
+```
+
+Eval coverage (no LLM):
+
+```bash
+cargo run -p plasm-eval -- coverage --schema apis/hackernews --cases apis/hackernews/eval/cases.yaml
+```