@plasm_lang/vercel-agent 0.3.77 → 0.3.80

package/src/tools/plasm-tools.ts

@@ -1,4 +1,4 @@
-import { tool } from "ai";
+import { tool, type ToolSet } from "ai";
 import { z } from "zod";
 
 import type { AgentRuntime } from "../runtime/agent-runtime.js";
@@ -8,89 +8,98 @@ import {
   PLASM_RUN_TOOL_DESCRIPTION,
   PLASM_TOOL_DESCRIPTION,
 } from "./descriptions.js";
+import { toolInput } from "./tool-input.js";
 
 const seedSchema = z.object({
   api: z.string().describe("Registry entry_id / catalog api"),
   entity: z.string().describe("CGS entity name from discovery or prior knowledge"),
 });
 
-export function createPlasmTools(runtime: AgentRuntime) {
+const discoverInputSchema = z.object({
+  intent: z
+    .string()
+    .min(1)
+    .describe(
+      "One plain-language task description for the whole user goal. Returns catalog api/entity picks — not program symbols.",
+    ),
+});
+
+const plasmContextInputSchema = z.object({
+  intent: z
+    .string()
+    .min(1)
+    .describe(
+      "Stable string for one user goal (same value every turn for that goal — do not rotate per message).",
+    ),
+  seeds: z
+    .array(seedSchema)
+    .min(1)
+    .describe("Non-empty array of {api, entity} capability picks"),
+  ranked_capabilities: z
+    .array(z.string())
+    .nullable()
+    .optional()
+    .describe(
+      "Optional capability wire names from discover_capabilities. Omit on expand; null or [] clears.",
+    ),
+});
+
+const plasmInputSchema = z.object({
+  logical_session_ref: z
+    .string()
+    .describe("Same logical_session_ref returned by plasm_context"),
+  program: z
+    .string()
+    .min(1)
+    .describe("Plasm source program using e#/m#/p#/r# from the session teaching TSV"),
+  reasoning: z
+    .string()
+    .optional()
+    .describe("Optional short note explaining the intent of this call"),
+});
+
+const plasmRunInputSchema = z.object({
+  logical_session_ref: z
+    .string()
+    .describe("Same logical_session_ref returned by plasm_context"),
+  plan_commit_ref: z
+    .string()
+    .describe("Executable plan token (pcN) from a prior plasm dry-run"),
+  reasoning: z
+    .string()
+    .optional()
+    .describe("Optional short note explaining the intent of this call"),
+});
+
+export function createPlasmTools(runtime: AgentRuntime): ToolSet {
   return {
     discover_capabilities: tool({
       description: DISCOVER_TOOL_DESCRIPTION,
-      inputSchema: z.object({
-        intent: z
-          .string()
-          .min(1)
-          .describe(
-            "One plain-language task description for the whole user goal. Returns catalog api/entity picks — not program symbols.",
-          ),
-      }),
+      inputSchema: toolInput(discoverInputSchema),
       execute: async ({ intent }) => runtime.discoverCapabilities({ intent }),
     }),
 
     plasm_context: tool({
       description: PLASM_CONTEXT_TOOL_DESCRIPTION,
-      inputSchema: z.object({
-        intent: z
-          .string()
-          .min(1)
-          .describe(
-            "Stable string for one user goal (same value every turn for that goal — do not rotate per message).",
-          ),
-        seeds: z
-          .array(seedSchema)
-          .min(1)
-          .describe("Non-empty array of {api, entity} capability picks"),
-        ranked_capabilities: z
-          .array(z.string())
-          .nullable()
-          .optional()
-          .describe(
-            "Optional capability wire names from discover_capabilities. Omit on expand; null or [] clears.",
-          ),
-      }),
+      inputSchema: toolInput(plasmContextInputSchema),
       execute: async ({ intent, seeds, ranked_capabilities }) =>
         runtime.plasmContext({
           intent,
-          seeds,
+          seeds: seeds as Array<{ api: string; entity: string }>,
           rankedCapabilities: ranked_capabilities,
         }),
     }),
 
     plasm: tool({
       description: PLASM_TOOL_DESCRIPTION,
-      inputSchema: z.object({
-        logical_session_ref: z
-          .string()
-          .describe("Same logical_session_ref returned by plasm_context"),
-        program: z
-          .string()
-          .min(1)
-          .describe("Plasm source program using e#/m#/p#/r# from the session teaching TSV"),
-        reasoning: z
-          .string()
-          .optional()
-          .describe("Optional short note explaining the intent of this call"),
-      }),
+      inputSchema: toolInput(plasmInputSchema),
       execute: async ({ logical_session_ref, program, reasoning }) =>
         runtime.plasm({ logicalSessionRef: logical_session_ref, program, reasoning }),
     }),
 
     plasm_run: tool({
       description: PLASM_RUN_TOOL_DESCRIPTION,
-      inputSchema: z.object({
-        logical_session_ref: z
-          .string()
-          .describe("Same logical_session_ref returned by plasm_context"),
-        plan_commit_ref: z
-          .string()
-          .describe("Executable plan token (pcN) from a prior plasm dry-run"),
-        reasoning: z
-          .string()
-          .optional()
-          .describe("Optional short note explaining the intent of this call"),
-      }),
+      inputSchema: toolInput(plasmRunInputSchema),
       execute: async ({ logical_session_ref, plan_commit_ref, reasoning }) =>
         runtime.plasmRun({
           logicalSessionRef: logical_session_ref,

package/src/tools/tool-input.ts

@@ -0,0 +1,9 @@
+import { zodSchema, type FlexibleSchema } from "ai";
+import type { z } from "zod";
+
+/** Wrap Zod for AI SDK `tool()` — avoids TS2589 deep instantiation during Vercel typecheck. */
+export function toolInput<T extends z.ZodTypeAny>(
+  schema: T,
+): FlexibleSchema<z.infer<T>> {
+  return zodSchema(schema);
+}

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
+```

package/templates/mcp-radar/agent/catalogs/hackernews/domain.yaml

@@ -0,0 +1,329 @@
+version: 2
+auth:
+  scheme: none
+http_backend: https://hacker-news.firebaseio.com
+entities:
+  Item:
+    id_field: id
+    description: A Hacker News item (story, comment, job, poll, or poll option). Use item_search (Algolia) to discover ids.
+      from text, then item_get for full rows from Firebase. Feed endpoints return only numeric ids; use item_get to load title,
+      text, score, and comment trees. Direct replies are listed under kids as further item ids. Poll posts expose poll option
+      ids under parts; each option is another Item row.
+    fields:
+      id:
+        required: true
+        value_ref: nv_item_id
+      type:
+        required: false
+        value_ref: nv_item_type
+      by:
+        required: false
+        value_ref: nv_item_by
+      time:
+        required: false
+        value_ref: nv_item_time
+      title:
+        required: false
+        value_ref: nv_item_title
+      text:
+        required: false
+        value_ref: nv_item_text
+      url:
+        required: false
+        value_ref: nv_item_url
+      score:
+        required: false
+        value_ref: nv_item_score
+      descendants:
+        required: false
+        value_ref: nv_item_descendants
+      parent:
+        required: false
+        value_ref: nv_item_parent
+      poll:
+        required: false
+        value_ref: nv_item_poll
+      parts:
+        required: false
+        value_ref: nv_item_parts
+      deleted:
+        required: false
+        value_ref: nv_item_deleted
+      dead:
+        required: false
+        value_ref: nv_item_dead
+    relations:
+      kids:
+        description: Direct child item ids (typically comments under a story).
+        target: Item
+        cardinality: many
+        materialize:
+          kind: from_parent_get
+          path:
+          - key: kids
+          - wildcard: true
+      poll_options:
+        description: Poll option rows referenced by parts (each id is an Item).
+        target: Item
+        cardinality: many
+        materialize:
+          kind: from_parent_get
+          path:
+          - key: parts
+          - wildcard: true
+  User:
+    id_field: id
+    description: A Hacker News user profile keyed by username. The submitted list holds item ids only; fetch each via item_get.
+      when you need titles or comment bodies.
+    fields:
+      id:
+        required: true
+        value_ref: nv_user_id
+      created:
+        required: false
+        value_ref: nv_user_created
+      karma:
+        required: false
+        value_ref: nv_user_karma
+      about:
+        required: false
+        value_ref: nv_user_about
+      delay:
+        required: false
+        value_ref: nv_user_delay
+    relations:
+      submitted:
+        description: Item ids this user has submitted.
+        target: Item
+        cardinality: many
+        materialize:
+          kind: from_parent_get
+          path:
+          - key: submitted
+          - wildcard: true
+  MaxItemId:
+    id_field: id
+    description: Current largest item id reported by maxitem.json (a bare JSON integer on the wire). Hydrate the referenced.
+      row with item_get when you need the full record.
+    fields:
+      id:
+        required: true
+        value_ref: nv_max_item_id_id
+  RecentUpdatedItem:
+    id_field: id
+    description: Item ids listed under updates.json items (live slice of ids with recent activity). Each entry is an id only.
+      use item_get for payloads.
+    fields:
+      id:
+        required: true
+        value_ref: nv_recent_updated_item_id
+  RecentUpdatedUser:
+    id_field: id
+    description: Usernames listed under updates.json profiles (accounts whose profile data changed). Each entry is the username.
+      string only; use user_get for karma and about text.
+    fields:
+      id:
+        required: true
+        value_ref: nv_recent_updated_user_id
+capabilities:
+  item_search:
+    description: Full-text search over HN via the public Algolia index (https://hn.algolia.com/api). Returns story Item rows.
+      with id from objectID and title/url from the hit; use item_get to hydrate the full Firebase record, kids, and score.
+    kind: search
+    entity: Item
+    provides:
+    - id
+    - title
+    - url
+    parameters:
+    - name: query
+      value_ref: nv_wire_str_short
+      required: true
+      role: search
+    - name: tags
+      value_ref: nv_wire_str_short
+      required: false
+      role: filter
+    - name: page
+      value_ref: nv_wire_int
+      required: false
+      role: response_control
+    - name: per_page
+      value_ref: nv_wire_int
+      required: false
+      role: response_control
+  item_search_by_date:
+    description: Same as item_search but sorted by time (search_by_date). Use for recency; combine with item_get for full.
+      items.
+    kind: search
+    entity: Item
+    provides:
+    - id
+    - title
+    - url
+    parameters:
+    - name: query
+      value_ref: nv_wire_str_short
+      required: true
+      role: search
+    - name: tags
+      value_ref: nv_wire_str_short
+      required: false
+      role: filter
+    - name: page
+      value_ref: nv_wire_int
+      required: false
+      role: response_control
+    - name: per_page
+      value_ref: nv_wire_int
+      required: false
+      role: response_control
+  item_feed_query:
+    description: Ordered list of item ids for a public feed (top, new, best, ask, show, or job). Each entry is an Item id only.
+      hydrate with item_get for full records and kids.
+    kind: query
+    entity: Item
+    provides:
+    - id
+    parameters:
+    - name: feed
+      value_ref: nv_item_feed_query_feed
+      required: true
+      role: filter
+  max_item_id_query:
+    description: Current largest item id (maxitem.json).
+    kind: query
+    entity: MaxItemId
+    provides:
+    - id
+  recent_updated_item_query:
+    description: Item ids from the live updates snapshot (updates.json items array).
+    kind: query
+    entity: RecentUpdatedItem
+    provides:
+    - id
+  recent_updated_user_query:
+    description: Usernames from the live updates snapshot (updates.json profiles array).
+    kind: query
+    entity: RecentUpdatedUser
+    provides:
+    - id
+  item_get:
+    kind: get
+    entity: Item
+    provides:
+    - id
+    - type
+    - by
+    - time
+    - title
+    - text
+    - url
+    - score
+    - descendants
+    - parent
+    - poll
+    - parts
+    - deleted
+    - dead
+  user_get:
+    description: Load a user profile by username.
+    kind: get
+    entity: User
+    provides:
+    - id
+    - created
+    - karma
+    - about
+    - delay
+values:
+  nv_item_by:
+    type: string
+    string_semantics: short
+    description: Username of the author when present.
+  nv_item_dead:
+    type: boolean
+    description: Whether the item is dead.
+  nv_item_deleted:
+    type: boolean
+    description: Whether the item was deleted.
+  nv_item_descendants:
+    type: integer
+    description: Comment count for stories when known.
+  nv_item_feed_query_feed:
+    type: select
+    allowed_values:
+    - top
+    - new
+    - best
+    - ask
+    - show
+    - job
+  nv_item_id:
+    type: integer
+    description: Numeric item id used in Firebase paths.
+  nv_item_parent:
+    type: integer
+    description: Parent item id for comments and poll options.
+  nv_item_poll:
+    type: integer
+    description: Poll id when this item is a story that hosts a poll.
+  nv_item_score:
+    type: integer
+    description: Net votes for stories and jobs when present.
+  nv_item_text:
+    type: string
+    string_semantics: markdown
+    description: Comment or story text payload when present.
+  nv_item_time:
+    type: integer
+    description: Unix time the item was created.
+  nv_item_title:
+    type: string
+    string_semantics: short
+    description: Story or job title when applicable.
+  nv_item_type:
+    type: string
+    string_semantics: short
+    description: Wire kind such as story, comment, job, poll, or pollopt.
+  nv_item_url:
+    type: string
+    string_semantics: short
+    description: Outbound link for link posts when present.
+  nv_max_item_id_id:
+    type: integer
+    description: Largest item id currently allocated on HN.
+  nv_recent_updated_item_id:
+    type: integer
+    description: Item id from the live updates snapshot.
+  nv_recent_updated_user_id:
+    type: string
+    string_semantics: short
+    description: Username from the live updates snapshot.
+  nv_user_about:
+    type: string
+    string_semantics: markdown
+    description: Self-description text when set.
+  nv_user_created:
+    type: integer
+    description: Unix time the account was created.
+  nv_user_delay:
+    type: integer
+    description: Account delay setting when present.
+  nv_user_id:
+    type: string
+    string_semantics: short
+    description: Unique username.
+  nv_user_karma:
+    type: integer
+    description: User karma score.
+  nv_wire_int:
+    type: integer
+  nv_wire_str_short:
+    type: string
+    string_semantics: short
+  nv_item_parts:
+    type: array
+    items:
+      value_ref: nv_wire_int
+    description: Poll option item ids when type is poll (empty or absent otherwise).