@plasm_lang/vercel-agent 0.3.77 → 0.3.80

package/README.md

@@ -152,9 +152,16 @@ npm run smoke:stubs:matrix
 npm run agent -- "your prompt"   # requires AI_GATEWAY_API_KEY (Vercel AI Gateway)
 ```
 
-### Dev server (`npm run dev` / `plasm-agent dev`)
+### Dev server (`plasm-agent dev`)
 
-When stdin is a TTY, `plasm-agent dev` starts the server **and** opens an interactive terminal client (eve-style). Use `--no-tui` or `PLASM_DEV_NO_TUI=1` for headless mode. Attach later with `plasm-agent chat --url http://127.0.0.1:3000`.
+**Default:** Nitro dev server with **Vercel routing parity** (channels, cron, `/plasm/v1/info`) — same `vercelPlasmHandler` as deploy. Init scaffolds `nitro.config.ts` + `routes/[...path].ts` and adds `nitropack` as a devDependency.
+
+```bash
+plasm-agent dev                    # Nitro (default)
+plasm-agent dev --interactive      # in-process server + TUI when TTY
+plasm-agent dev --interactive --no-tui
+plasm-agent chat --url http://127.0.0.1:3000
+```
 
 Slash commands in the TUI: `/help`, `/info`, `/model`, `/channels`, `/catalogs`, `/new`, `/quit`.
 

package/agent/instructions.md

@@ -13,8 +13,7 @@ You operate external APIs through **Plasm catalogs**, not ad-hoc REST tools.
 
 - **One user goal → one stable `intent` string → one `logical_session_ref`.**
 - Do not rotate `intent` per message (e.g. `"msg 3: sort moves"` breaks symbol reuse).
-- Copy symbols from the **left column** of teaching TSV into programs — never invent `e#` / `p#` values.
-- Federated catalogs: use opaque symbols from the table; never bare homonym wire names.
+- Copy symbols from the **left column** of teaching TSV into programs — never invent `e#` / `p#` values or catalog English names (`Issue`, `create`).
 
 ## Programs
 

package/bin/plasm-agent.mjs

@@ -4,14 +4,12 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 const packageRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
-const runner = path.join(packageRoot, "scripts", "plasm-node.mjs");
-const cli = path.join(packageRoot, "scripts", "plasm-cli.ts");
+const runner = path.join(packageRoot, "scripts", "run-plasm-cli.mjs");
 
-const child = spawn(
-  process.execPath,
-  ["--experimental-strip-types", "--experimental-transform-types", runner, cli, ...process.argv.slice(2)],
-  { stdio: "inherit", env: process.env },
-);
+const child = spawn(process.execPath, [runner, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  env: process.env,
+});
 
 child.on("exit", (code) => {
   process.exit(code ?? 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasm_lang/vercel-agent",
-  "version": "0.3.77",
+  "version": "0.3.80",
   "description": "Catalog-native TypeScript agent framework (Plasm CGS/CML, Vercel AI SDK, Nitro-oriented)",
   "license": "GPL-3.0-or-later",
   "repository": {
@@ -15,6 +15,8 @@
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
+    "./build": "./src/cli/build.ts",
+    "./server": "./src/server/plasm-handler.ts",
     "./instrumentation": "./src/instrumentation.ts",
     "./operator": "./src/operator/routes.ts",
     "./agent": "./agent/agent.ts"
@@ -25,36 +27,43 @@
   "files": [
     "src",
     "bin",
+    "templates",
     "scripts/plasm-node.mjs",
+    "scripts/plasm-cli.ts",
+    "scripts/run-plasm-cli.mjs",
+    "scripts/build-stubs.ts",
+    "scripts/register-plasm-loader.mjs",
     "scripts/resolve-ts-extension.mjs",
     "agent",
     "README.md"
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "plasm-agent": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/plasm-cli.ts",
+    "plasm-agent": "node scripts/run-plasm-cli.mjs",
     "build:engine": "npm run build --prefix ../plasm-engine",
-    "build:stubs": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/build-stubs.ts",
-    "smoke:tools": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/smoke-agent-tools.ts",
-    "smoke:async-transport": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/smoke-async-transport.ts",
-    "smoke:operator": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/smoke-operator.ts",
-    "smoke:stubs": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/smoke-stubs.ts",
-    "smoke:stubs:matrix": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/smoke-stubs-matrix.ts",
-    "eval": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/run-evals.ts",
-    "eval:catalog": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/run-catalog-eval.ts",
-    "smoke:hot-reload": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/smoke-hot-reload.ts",
-    "smoke:sessions": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/smoke-sessions.ts",
-    "smoke:tui-async": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/smoke-tui-async.ts",
-    "smoke:bootstrap": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/smoke-bootstrap-devx.ts",
-    "smoke:vercel-handler": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/smoke-vercel-handler.ts",
-    "agent": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/run-agent.ts",
-    "dev": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/dev-server.ts",
+    "build:stubs": "node scripts/run-plasm-cli.mjs scripts/build-stubs.ts",
+    "smoke:tools": "node scripts/run-plasm-cli.mjs scripts/smoke-agent-tools.ts",
+    "smoke:async-transport": "node scripts/run-plasm-cli.mjs scripts/smoke-async-transport.ts",
+    "smoke:operator": "node scripts/run-plasm-cli.mjs scripts/smoke-operator.ts",
+    "smoke:stubs": "node scripts/run-plasm-cli.mjs scripts/smoke-stubs.ts",
+    "smoke:stubs:matrix": "node scripts/run-plasm-cli.mjs scripts/smoke-stubs-matrix.ts",
+    "eval": "node scripts/run-plasm-cli.mjs scripts/run-evals.ts",
+    "eval:catalog": "node scripts/run-plasm-cli.mjs scripts/run-catalog-eval.ts",
+    "smoke:hot-reload": "node scripts/run-plasm-cli.mjs scripts/smoke-hot-reload.ts",
+    "smoke:sessions": "node scripts/run-plasm-cli.mjs scripts/smoke-sessions.ts",
+    "smoke:tui-async": "node scripts/run-plasm-cli.mjs scripts/smoke-tui-async.ts",
+    "smoke:bootstrap": "node scripts/run-plasm-cli.mjs scripts/smoke-bootstrap-devx.ts",
+    "smoke:bootstrap:npm": "node scripts/run-plasm-cli.mjs scripts/smoke-bootstrap-npm.ts",
+    "smoke:vercel-build": "node scripts/run-plasm-cli.mjs scripts/smoke-vercel-build.ts",
+    "smoke:vercel-handler": "node scripts/run-plasm-cli.mjs scripts/smoke-vercel-handler.ts",
+    "agent": "node scripts/run-plasm-cli.mjs scripts/run-agent.ts",
+    "dev": "node scripts/run-plasm-cli.mjs scripts/dev-server.ts",
     "plasm:dev": "npm run dev"
   },
   "dependencies": {
     "@ai-sdk/otel": "^1.0.0-beta.6",
     "@opentelemetry/api": "^1.9.0",
-    "@plasm_lang/engine": "^0.3.77",
+    "@plasm_lang/engine": "^0.3.80",
     "@vercel/blob": "^0.27.3",
     "@vercel/connect": "^0.2.6",
     "@vercel/kv": "^3.0.0",
@@ -63,7 +72,8 @@
     "js-yaml": "^4.1.0",
     "pg": "^8.22.0",
     "workflow": "^4.5.0",
-    "zod": "^3.24.0"
+    "zod": "^3.25.76",
+    "tsx": "^4.19.4"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",

package/scripts/build-stubs.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * Scan agent/catalogs/ and emit TypeScript stubs to agent/.plasm/stubs/<entry_id>.ts
+ */
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { generateAllStubs } from "../src/stubs/generator.js";
+
+const packageRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const agentRoot = path.join(packageRoot, "agent");
+
+async function main() {
+  const results = await generateAllStubs(agentRoot);
+  if (!results.length) {
+    console.error("no catalogs found under agent/catalogs/");
+    process.exit(1);
+  }
+  for (const result of results) {
+    console.log(`${result.entryId}\t${result.catalogCgsHash}\t${result.outPath}`);
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/scripts/plasm-cli.ts

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+/**
+ * TypeScript CLI for @plasm_lang/vercel-agent (not the Rust plasm-server TUI).
+ */
+import path from "node:path";
+
+import { runPlasmBuild } from "../src/cli/build.js";
+import {
+  installDevServerShutdown,
+  startDevServerForProject,
+} from "../src/cli/dev.js";
+import { startNitroDevForProject } from "../src/cli/nitro-dev.js";
+import { runDevTui } from "../src/dev/client/repl.js";
+import { collectProjectInfo, formatPlasmInfoHuman } from "../src/cli/info.js";
+import { runPlasmInit, formatInitSuccess } from "../src/cli/init.js";
+import { runPlasmLink } from "../src/cli/link.js";
+import {
+  requireAgentProject,
+  readPackageName,
+  resolveAgentProject,
+} from "../src/cli/project-root.js";
+import { loadAgentEnv } from "../src/load-env.js";
+
+loadAgentEnv();
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function flag(name: string): boolean {
+  return args.includes(name);
+}
+
+function optionValue(flagName: string): string | undefined {
+  const index = args.indexOf(flagName);
+  if (index < 0) return undefined;
+  const value = args[index + 1];
+  if (!value || value.startsWith("-")) return undefined;
+  return value;
+}
+
+function initTargetDir(): string {
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith("-")) {
+      if (arg === "--template") i++;
+      continue;
+    }
+    return arg;
+  }
+  return process.cwd();
+}
+
+async function cmdInit(): Promise<void> {
+  const template = optionValue("--template");
+  const npm = flag("--npm");
+  const target = initTargetDir();
+  const project = await runPlasmInit(target, { template, npm: npm || undefined });
+  console.log(formatInitSuccess(project, { template, npm: npm || undefined }));
+}
+
+async function cmdInfo(): Promise<void> {
+  const project = await requireAgentProject();
+  const packageName = await readPackageName(project.projectRoot);
+  const info = await collectProjectInfo({
+    projectRoot: project.projectRoot,
+    agentRoot: project.agentRoot,
+    packageName,
+  });
+  if (flag("--json")) {
+    console.log(JSON.stringify(info, null, 2));
+    return;
+  }
+  console.log(formatPlasmInfoHuman(info));
+}
+
+async function cmdLink(): Promise<void> {
+  const project = await requireAgentProject();
+  const result = await runPlasmLink(project.projectRoot);
+  for (const line of result.messages) console.log(line);
+  if (!result.linked && !result.envPulled) process.exitCode = 1;
+}
+
+async function cmdBuild(): Promise<void> {
+  const project = await requireAgentProject();
+  const result = await runPlasmBuild(project);
+  console.log(`Built ${result.stubs.length} stub(s)`);
+  console.log(`manifest: ${result.manifestPath}`);
+  for (const stub of result.stubs) {
+    console.log(`  - ${stub.entryId} → ${path.relative(project.projectRoot, stub.outPath)}`);
+  }
+}
+
+async function cmdDev(): Promise<void> {
+  const project = await requireAgentProject();
+  if (flag("--interactive")) {
+    const handle = await startDevServerForProject({
+      project,
+      tui: flag("--no-tui") ? false : "auto",
+    });
+    installDevServerShutdown(handle);
+    return;
+  }
+  await startNitroDevForProject(project);
+}
+
+async function cmdChat(): Promise<void> {
+  const urlFlag = args.find((a, i) => args[i - 1] === "--url");
+  const baseUrl = urlFlag ?? process.env.PLASM_DEV_URL ?? "http://127.0.0.1:3000";
+  await runDevTui({ baseUrl });
+}
+
+async function main(): Promise<void> {
+  if (!command || command === "--help" || command === "-h") {
+    console.log(`plasm-agent — @plasm_lang/vercel-agent CLI
+
+Commands:
+  init [dir] [--template NAME] [--npm]  Scaffold agent project (templates: mcp-radar)
+  info [--json] Project + catalog diagnostics
+  link          vercel link + env pull (AI Gateway key)
+  build         CGS stubs + .plasm/discovery/manifest.json
+  dev [--interactive] [--no-tui]  Nitro dev (Vercel routing parity; default). --interactive for TUI/sessions.
+  chat [--url URL]  Terminal client for a running dev server
+`);
+    return;
+  }
+
+  switch (command) {
+    case "init":
+      await cmdInit();
+      break;
+    case "info": {
+      const resolved = await resolveAgentProject();
+      if (!resolved) {
+        console.error("No agent project found. Run `plasm-agent init` first.");
+        process.exitCode = 1;
+        return;
+      }
+      await cmdInfo();
+      break;
+    }
+    case "link":
+      await cmdLink();
+      break;
+    case "build":
+      await cmdBuild();
+      break;
+    case "dev":
+      await cmdDev();
+      break;
+    case "chat":
+      await cmdChat();
+      break;
+    default:
+      console.error(`Unknown command: ${command}`);
+      process.exitCode = 1;
+  }
+}
+
+await main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/scripts/register-plasm-loader.mjs

@@ -0,0 +1,6 @@
+import { register } from "node:module";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const root = path.dirname(fileURLToPath(import.meta.url));
+register(pathToFileURL(path.join(root, "resolve-ts-extension.mjs")));

package/scripts/run-plasm-cli.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * Run TypeScript via tsx (works on Node 20–26 and Vercel build).
+ * With no .ts first arg, runs plasm-cli.ts.
+ */
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const require = createRequire(import.meta.url);
+const packageRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const args = process.argv.slice(2);
+
+const scriptArg = args[0];
+const isScriptEntry = scriptArg?.endsWith(".ts");
+const entry = isScriptEntry
+  ? path.resolve(packageRoot, scriptArg)
+  : path.join(packageRoot, "scripts", "plasm-cli.ts");
+const entryArgs = isScriptEntry ? args.slice(1) : args;
+
+function runNode(nodeArgs) {
+  const result = spawnSync(process.execPath, [...nodeArgs, entry, ...entryArgs], {
+    stdio: "inherit",
+    env: process.env,
+  });
+  process.exit(result.status ?? 1);
+}
+
+try {
+  const tsxCli = require.resolve("tsx/cli");
+  runNode([tsxCli]);
+} catch {
+  const plasmNode = path.join(packageRoot, "scripts", "plasm-node.mjs");
+  const result = spawnSync(
+    process.execPath,
+    ["--experimental-strip-types", "--experimental-transform-types", plasmNode, entry, ...entryArgs],
+    { stdio: "inherit", env: process.env },
+  );
+  process.exit(result.status ?? 1);
+}

package/src/cli/init-scaffold.ts

@@ -0,0 +1,198 @@
+import { access, cp, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { frameworkPackageVersion } from "../package-version.js";
+import type { ResolvedAgentProject } from "./project-root.js";
+
+export interface InitOptions {
+  template?: string;
+  /** Use npm semver deps instead of monorepo file: links (default: auto-detect). */
+  npm?: boolean;
+}
+
+const SKIP_TEMPLATE_DIRS = new Set(["node_modules", ".plasm", ".nitro", ".output", "server"]);
+const SKIP_TEMPLATE_FILES = new Set(["package-lock.json", "vercel-build.ts"]);
+
+function plasmAgentPackageRoot(): string {
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+}
+
+function scaffoldRoot(): string {
+  return path.join(plasmAgentPackageRoot(), "templates", "scaffold");
+}
+
+function resolveTemplateDir(template: string): string {
+  const dir = path.join(plasmAgentPackageRoot(), "templates", template);
+  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 exists(p: string): Promise<boolean> {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function copyTemplate(templateRoot: string, projectRoot: string): Promise<void> {
+  await cp(templateRoot, projectRoot, {
+    recursive: true,
+    filter: (src) => src === templateRoot || shouldCopyTemplateEntry(src, templateRoot),
+  });
+}
+
+async function copyScaffoldFile(relativePath: string, projectRoot: string): Promise<void> {
+  const src = path.join(scaffoldRoot(), relativePath);
+  const dest = path.join(projectRoot, relativePath);
+  await mkdir(path.dirname(dest), { recursive: true });
+  await cp(src, dest);
+}
+
+export async function writeDeployScaffold(
+  projectRoot: string,
+  template?: string,
+): Promise<void> {
+  const vercelJsonName =
+    template === "mcp-radar" ? "vercel.mcp-radar.json" : "vercel.default.json";
+  await copyScaffoldFile("api/[[...path]].ts", projectRoot);
+  await copyScaffoldFile("routes/[...path].ts", projectRoot);
+  await copyScaffoldFile("nitro.config.ts", projectRoot);
+  await copyScaffoldFile(".vercelignore", projectRoot);
+  const publicIndex =
+    template === "mcp-radar" ? "public/index.mcp-radar.html" : "public/index.html";
+  const publicDest = path.join(projectRoot, "public", "index.html");
+  await mkdir(path.dirname(publicDest), { recursive: true });
+  await cp(path.join(scaffoldRoot(), publicIndex), publicDest);
+  await cp(
+    path.join(scaffoldRoot(), vercelJsonName),
+    path.join(projectRoot, "vercel.json"),
+  );
+}
+
+function monorepoEngineRoot(packageRoot: string): string {
+  return path.resolve(packageRoot, "../plasm-engine");
+}
+
+export async function isMonorepoDevPackage(packageRoot: string): Promise<boolean> {
+  return exists(path.join(monorepoEngineRoot(packageRoot), "package.json"));
+}
+
+export async function patchProjectPackageJson(
+  projectRoot: string,
+  packageRoot: string,
+  options?: { npm?: boolean },
+): 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>;
+  };
+
+  const version = frameworkPackageVersion();
+  const useNpm =
+    options?.npm === true
+      ? true
+      : options?.npm === false
+        ? false
+        : !(await isMonorepoDevPackage(packageRoot));
+
+  pkg.name = path.basename(projectRoot);
+  if (useNpm) {
+    pkg.dependencies = {
+      ...pkg.dependencies,
+      "@plasm_lang/vercel-agent": `^${version}`,
+      "@plasm_lang/engine": `^${version}`,
+      "@vercel/blob": "^0.27.3",
+      "@vercel/functions": "^3.4.3",
+      "@vercel/kv": "^3.0.0",
+    };
+  } else {
+    pkg.dependencies = {
+      ...pkg.dependencies,
+      "@plasm_lang/vercel-agent": `file:${path.resolve(packageRoot)}`,
+      "@plasm_lang/engine": `file:${monorepoEngineRoot(packageRoot)}`,
+      "@vercel/blob": "^0.27.3",
+      "@vercel/functions": "^3.4.3",
+      "@vercel/kv": "^3.0.0",
+    };
+  }
+
+  pkg.scripts = {
+    build: "plasm-agent build",
+    dev: "plasm-agent dev",
+    "dev:interactive": "plasm-agent dev --interactive",
+    info: "plasm-agent info",
+    deploy: "vercel deploy",
+    ...pkg.scripts,
+  };
+  delete pkg.scripts["vercel-build"];
+
+  pkg.devDependencies = {
+    ...pkg.devDependencies,
+    nitropack: "^2.13.4",
+    tsx: "^4.19.4",
+  };
+
+  await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, "utf8");
+}
+
+export function blankPackageJsonScaffold(): Record<string, unknown> {
+  const version = frameworkPackageVersion();
+  return {
+    name: "my-plasm-agent",
+    private: true,
+    type: "module",
+    scripts: {
+      dev: "plasm-agent dev",
+      "dev:interactive": "plasm-agent dev --interactive",
+      build: "plasm-agent build",
+      info: "plasm-agent info",
+      deploy: "vercel deploy",
+    },
+    dependencies: {
+      "@plasm_lang/vercel-agent": `^${version}`,
+      "@plasm_lang/engine": `^${version}`,
+    },
+    devDependencies: {
+      nitropack: "^2.13.4",
+      tsx: "^4.19.4",
+    },
+  };
+}
+
+export async function runTemplateInit(
+  targetDir: string,
+  template: string,
+  options?: InitOptions,
+): 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(`Unknown template "${template}" or missing source: ${templateRoot}`);
+  }
+  await mkdir(projectRoot, { recursive: true });
+  await copyTemplate(templateRoot, projectRoot);
+  await patchProjectPackageJson(projectRoot, plasmAgentPackageRoot(), { npm: options?.npm });
+  await writeDeployScaffold(projectRoot, template);
+  return { projectRoot, agentRoot };
+}
+
+export { exists, plasmAgentPackageRoot, resolveTemplateDir };