@plasm_lang/vercel-agent 0.3.82 → 0.3.84

package/README.md

@@ -154,7 +154,7 @@ npm run agent -- "your prompt"   # requires AI_GATEWAY_API_KEY (Vercel AI Gatewa
 
 ### Dev server (`plasm-agent dev`)
 
-**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.
+**Default:** `plasm-agent dev` runs programmatic **Nitro v3** (same host as Vercel). `plasm-agent build` emits **`.vercel/output`** on Vercel (Build Output API) or **`.plasm/nitro-output`** locally, plus **`.plasm/agent-summary.json`** for Agent Observability.
 
 ```bash
 plasm-agent dev                    # Nitro (default)

package/agent/hooks/trace-log.ts

@@ -4,7 +4,7 @@ export default defineHook({
   name: "trace-log",
   on: ["run:complete", "plan:commit"],
   handler: (_ctx, detail) => {
-    const event = detail?.planCommitRef ? "plan:commit" : "run:complete";
+    const event = detail?.runRef ? "plan:commit" : "run:complete";
     console.log(`[plasm:hook:trace-log] ${event}`, detail ?? {});
   },
 });

package/agent/instructions.md

@@ -6,7 +6,7 @@ You operate external APIs through **Plasm catalogs**, not ad-hoc REST tools.
 
 1. **`discover_capabilities`** — when you do not know which `api` / `entity` to use (optional).
 2. **`plasm_context`** — open or extend a session with `{api, entity}` seeds. Returns **`logical_session_ref`** + teaching TSV (`e#`, `m#`, `p#`, `r#`).
-3. **`plasm`** — dry-run a Plasm **program** using symbols from the teaching TSV. Returns **`plan_commit_ref`** (`pcN`).
+3. **`plasm`** — dry-run a Plasm **program** using symbols from the teaching TSV. Returns **`run_ref`** (`pcN`).
 4. **`plasm_run`** — live execute the reviewed plan (`pcN` only — never resend the program).
 
 ## Session discipline

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasm_lang/vercel-agent",
-  "version": "0.3.82",
+  "version": "0.3.84",
   "description": "Catalog-native TypeScript agent framework (Plasm CGS/CML, Vercel AI SDK, Nitro-oriented)",
   "license": "GPL-3.0-or-later",
   "repository": {
@@ -63,17 +63,21 @@
   "dependencies": {
     "@ai-sdk/otel": "^1.0.3",
     "@opentelemetry/api": "^1.9.0",
-    "@plasm_lang/engine": "^0.3.82",
+    "@plasm_lang/engine": "^0.3.84",
     "@vercel/blob": "^0.27.3",
     "@vercel/connect": "^0.2.6",
     "@vercel/kv": "^3.0.0",
+    "@vercel/otel": "^1.14.2",
+    "@workflow/nitro": "^4.1.1",
     "@workflow/world-postgres": "^4.2.0",
     "ai": "^6.0.0",
+    "esbuild": "^0.25.12",
     "js-yaml": "^4.1.0",
+    "nitro": "^3.0.260610-beta",
     "pg": "^8.22.0",
+    "tsx": "^4.19.4",
     "workflow": "^4.5.0",
-    "zod": "^3.25.76",
-    "tsx": "^4.19.4"
+    "zod": "^3.25.76"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",

package/scripts/plasm-cli.ts

@@ -85,6 +85,12 @@ async function cmdBuild(): Promise<void> {
   const result = await runPlasmBuild(project);
   console.log(`Built ${result.stubs.length} stub(s)`);
   console.log(`manifest: ${result.manifestPath}`);
+  if (result.outputDir) {
+    console.log(`nitro output: ${result.outputDir}${result.vercelOutput ? " (vercel build output)" : ""}`);
+  }
+  if (result.agentSummaryPath) {
+    console.log(`agent summary: ${result.agentSummaryPath}`);
+  }
   for (const stub of result.stubs) {
     console.log(`  - ${stub.entryId} → ${path.relative(project.projectRoot, stub.outPath)}`);
   }

package/src/archive/paths.ts

@@ -4,7 +4,10 @@ import type { ArchivePaths } from "./types.js";
 
 /** Resolve local trace/run archive roots from env or agent defaults. */
 export function resolveArchivePaths(agentRoot: string): ArchivePaths {
-  const archivesDir = path.join(agentRoot, ".plasm", "archives");
+  const archivesDir =
+    process.env.VERCEL === "1"
+      ? path.join("/tmp", "plasm-archives", path.basename(path.resolve(agentRoot)))
+      : path.join(agentRoot, ".plasm", "archives");
   const traceRoot =
     process.env.PLASM_TRACE_ARCHIVE_DIR?.trim() ||
     path.join(archivesDir, "traces");

package/src/authoring/slot-loader.ts

@@ -1,4 +1,4 @@
-import { readFile } from "node:fs/promises";
+import { access, readFile } from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
@@ -45,6 +45,10 @@ export interface LoadedProjectSlots {
 export interface LoadAuthoredSlotsOptions {
   discovery: ProjectDiscovery;
   importCacheBust?: number;
+  agentRoot?: string;
+  projectRoot?: string;
+  /** agentRoot-relative source → projectRoot-relative compiled `.mjs` from build manifest. */
+  compiledSlots?: Record<string, string>;
 }
 
 type SlotName = "channels" | "schedules" | "hooks" | "skills";
@@ -58,8 +62,52 @@ function slotDiagnostic(
   return { level, slot, path: filePath, message };
 }
 
-async function importSlotModule(filePath: string, cacheBust: number): Promise<unknown> {
-  const url = `${pathToFileURL(filePath).href}?t=${cacheBust}`;
+async function pathExists(p: string): Promise<boolean> {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function resolveSlotImportPath(
+  filePath: string,
+  options: LoadAuthoredSlotsOptions,
+): Promise<string> {
+  const agentRoot = path.resolve(options.agentRoot ?? options.discovery.agentRoot);
+  const relFromAgent = path.relative(agentRoot, filePath);
+  const fromManifest = options.compiledSlots?.[relFromAgent];
+  if (fromManifest && options.projectRoot) {
+    const compiled = path.join(options.projectRoot, fromManifest);
+    if (await pathExists(compiled)) return compiled;
+  }
+  const mirror = path.join(
+    agentRoot,
+    ".plasm",
+    "compiled",
+    relFromAgent.replace(/\.ts$/, ".mjs"),
+  );
+  if (await pathExists(mirror)) return mirror;
+  return filePath;
+}
+
+async function importSlotModule(
+  filePath: string,
+  cacheBust: number,
+  options: LoadAuthoredSlotsOptions,
+): Promise<unknown> {
+  const agentRoot = path.resolve(options.agentRoot ?? options.discovery.agentRoot);
+  const relFromAgent = path.relative(agentRoot, filePath);
+  const preloaded = (
+    globalThis as typeof globalThis & { __PLASM_PRELOADED_SLOTS?: Record<string, unknown> }
+  ).__PLASM_PRELOADED_SLOTS?.[relFromAgent];
+  if (preloaded !== undefined) {
+    return (preloaded as { default?: unknown }).default ?? preloaded;
+  }
+
+  const resolved = await resolveSlotImportPath(filePath, options);
+  const url = `${pathToFileURL(resolved).href}?t=${cacheBust}`;
   const mod = await import(url);
   return mod.default ?? mod;
 }
@@ -85,9 +133,10 @@ async function loadTypescriptSlot<T extends ChannelDefinition | ScheduleDefiniti
   slot: SlotName,
   expected: "channel" | "schedule" | "hook" | "skill",
   cacheBust: number,
+  options: LoadAuthoredSlotsOptions,
 ): Promise<{ definition: T } | { diagnostic: DiscoveryDiagnostic }> {
   try {
-    const exported = await importSlotModule(filePath, cacheBust);
+    const exported = await importSlotModule(filePath, cacheBust, options);
     const actual = classifySlotExport(exported);
     if (actual !== expected) {
       const helper =
@@ -147,6 +196,7 @@ export async function loadAuthoredSlots(
       "channels",
       EXPECTED_KIND.channels,
       cacheBust,
+      options,
     );
     if ("diagnostic" in result) {
       diagnostics.push(result.diagnostic);
@@ -163,6 +213,7 @@ export async function loadAuthoredSlots(
       "schedules",
       EXPECTED_KIND.schedules,
       cacheBust,
+      options,
     );
     if ("diagnostic" in result) {
       diagnostics.push(result.diagnostic);
@@ -179,6 +230,7 @@ export async function loadAuthoredSlots(
       "hooks",
       EXPECTED_KIND.hooks,
       cacheBust,
+      options,
     );
     if ("diagnostic" in result) {
       diagnostics.push(result.diagnostic);
@@ -198,6 +250,7 @@ export async function loadAuthoredSlots(
       "skills",
       "skill",
       cacheBust,
+      options,
     );
     if ("diagnostic" in result) {
       diagnostics.push(result.diagnostic);

package/src/cli/build.ts

@@ -1,21 +1,33 @@
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, writeFile, readFile } from "node:fs/promises";
 import path from "node:path";
 
+import { compileAuthoredSlots } from "./compile-authored-slots.js";
+import type { ResolvedAgentProject } from "./project-root.js";
 import { isNativeEngineAvailable } from "../engine/napi-binding.js";
 import { walkAgentProject } from "../discovery/project-walker.js";
 import { generateAllStubs } from "../stubs/generator.js";
-import type { ResolvedAgentProject } from "./project-root.js";
+import { buildPlasmApplication } from "../nitro/build-application.js";
+import { readPackageName } from "./project-root.js";
 
 export interface PlasmBuildResult {
   stubsDir: string;
   discoveryDir: string;
   manifestPath: string;
   stubs: Array<{ entryId: string; catalogCgsHash: string; outPath: string }>;
+  outputDir?: string;
+  agentSummaryPath?: string;
+  vercelOutput?: boolean;
 }
 
 export async function runPlasmBuild(project: ResolvedAgentProject): Promise<PlasmBuildResult> {
   const stubs = await generateAllStubs(project.agentRoot);
   const discovery = await walkAgentProject(project.agentRoot);
+  const { compiledSlots } = await compileAuthoredSlots(
+    project.projectRoot,
+    project.agentRoot,
+    discovery,
+  );
+
   const discoveryDir = path.join(project.agentRoot, ".plasm", "discovery");
   await mkdir(discoveryDir, { recursive: true });
   const manifestPath = path.join(discoveryDir, "manifest.json");
@@ -24,6 +36,7 @@ export async function runPlasmBuild(project: ResolvedAgentProject): Promise<Plas
     builtAt: new Date().toISOString(),
     projectRoot: project.projectRoot,
     agentRoot: project.agentRoot,
+    compiledSlots,
     stubs: stubs.map((s) => ({
       entryId: s.entryId,
       catalogCgsHash: s.catalogCgsHash,
@@ -45,10 +58,36 @@ export async function runPlasmBuild(project: ResolvedAgentProject): Promise<Plas
     },
   };
   await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+
+  const packageName = await readPackageName(project.projectRoot);
+  const appBuild = await buildPlasmApplication({
+    projectRoot: project.projectRoot,
+    agentRoot: project.agentRoot,
+    discovery,
+    compiledSlots,
+    packageName: packageName ?? undefined,
+  });
+
   return {
     stubsDir: path.join(project.agentRoot, ".plasm", "stubs"),
     discoveryDir,
     manifestPath,
     stubs,
+    outputDir: appBuild.outputDir,
+    agentSummaryPath: appBuild.agentSummaryPath,
+    vercelOutput: appBuild.vercelOutput,
   };
 }
+
+export async function readBuildManifest(agentRoot: string): Promise<{
+  compiledSlots?: Record<string, string>;
+  projectRoot?: string;
+} | null> {
+  const manifestPath = path.join(agentRoot, ".plasm", "discovery", "manifest.json");
+  try {
+    const raw = await readFile(manifestPath, "utf8");
+    return JSON.parse(raw) as { compiledSlots?: Record<string, string>; projectRoot?: string };
+  } catch {
+    return null;
+  }
+}

package/src/cli/compile-authored-slots.ts

@@ -0,0 +1,79 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import * as esbuild from "esbuild";
+
+import type { ProjectDiscovery } from "../discovery/project-walker.js";
+
+const ESBUILD_BANNER =
+  'import { createRequire as __createRequire } from "module"; const require = __createRequire(import.meta.url);';
+
+export type CompiledSlotMap = Record<string, string>;
+
+export interface CompileAuthoredSlotsResult {
+  /** agentRoot-relative source path → projectRoot-relative compiled `.mjs`. */
+  compiledSlots: CompiledSlotMap;
+  compiledDir: string;
+}
+
+function slotFiles(
+  discovery: ProjectDiscovery,
+): Array<{ filePath: string }> {
+  const out: Array<{ filePath: string }> = [];
+  for (const file of discovery.channels) {
+    if (file.kind === "typescript") out.push({ filePath: file.path });
+  }
+  for (const file of discovery.schedules) {
+    if (file.kind === "typescript") out.push({ filePath: file.path });
+  }
+  for (const file of discovery.hooks) {
+    if (file.kind === "typescript") out.push({ filePath: file.path });
+  }
+  return out;
+}
+
+/** Compile authored TS slots to `.plasm/compiled/` for Vercel runtime (no dynamic `.ts` import). */
+export async function compileAuthoredSlots(
+  projectRoot: string,
+  agentRoot: string,
+  discovery: ProjectDiscovery,
+): Promise<CompileAuthoredSlotsResult> {
+  const compiledRoot = path.join(agentRoot, ".plasm", "compiled");
+  await mkdir(compiledRoot, { recursive: true });
+
+  const compiledSlots: CompiledSlotMap = {};
+
+  await Promise.all(
+    slotFiles(discovery).map(async ({ filePath }) => {
+      const relFromAgent = path.relative(agentRoot, filePath);
+      const outFile = path.join(
+        agentRoot,
+        ".plasm",
+        "compiled",
+        relFromAgent.replace(/\.ts$/, ".mjs"),
+      );
+      await mkdir(path.dirname(outFile), { recursive: true });
+
+      await esbuild.build({
+        entryPoints: [filePath],
+        bundle: true,
+        platform: "node",
+        target: "node22",
+        format: "esm",
+        outfile: outFile,
+        banner: { js: ESBUILD_BANNER },
+        logLevel: "silent",
+      });
+
+      compiledSlots[relFromAgent] = path.relative(projectRoot, outFile);
+    }),
+  );
+
+  await writeFile(
+    path.join(compiledRoot, "package.json"),
+    `${JSON.stringify({ type: "module" }, null, 2)}\n`,
+    "utf8",
+  );
+
+  return { compiledSlots, compiledDir: compiledRoot };
+}

package/src/cli/init-scaffold.ts

@@ -11,7 +11,7 @@ export interface InitOptions {
   npm?: boolean;
 }
 
-const SKIP_TEMPLATE_DIRS = new Set(["node_modules", ".plasm", ".nitro", ".output", "server"]);
+const SKIP_TEMPLATE_DIRS = new Set(["node_modules", ".plasm", ".nitro", ".output"]);
 const SKIP_TEMPLATE_FILES = new Set(["package-lock.json", "vercel-build.ts"]);
 
 function plasmAgentPackageRoot(): string {
@@ -65,9 +65,7 @@ export async function writeDeployScaffold(
 ): 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("agent/instrumentation.ts", projectRoot);
   await copyScaffoldFile(".vercelignore", projectRoot);
   const publicIndex =
     template === "mcp-radar" ? "public/index.mcp-radar.html" : "public/index.html";
@@ -119,6 +117,7 @@ export async function patchProjectPackageJson(
       "@vercel/blob": "^0.27.3",
       "@vercel/functions": "^3.4.3",
       "@vercel/kv": "^3.0.0",
+      "@vercel/otel": "^1.5.0",
     };
   } else {
     pkg.dependencies = {
@@ -128,6 +127,7 @@ export async function patchProjectPackageJson(
       "@vercel/blob": "^0.27.3",
       "@vercel/functions": "^3.4.3",
       "@vercel/kv": "^3.0.0",
+      "@vercel/otel": "^1.5.0",
     };
   }
 
@@ -143,9 +143,9 @@ export async function patchProjectPackageJson(
 
   pkg.devDependencies = {
     ...pkg.devDependencies,
-    nitropack: "^2.13.4",
     tsx: "^4.19.4",
   };
+  delete pkg.devDependencies?.nitropack;
 
   await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, "utf8");
 }
@@ -168,7 +168,6 @@ export function blankPackageJsonScaffold(): Record<string, unknown> {
       "@plasm_lang/engine": `^${version}`,
     },
     devDependencies: {
-      nitropack: "^2.13.4",
       tsx: "^4.19.4",
     },
   };

package/src/cli/init.ts

@@ -89,7 +89,9 @@ capabilities:
       path: /items
 `;
 
-const ENV_EXAMPLE = `# Vercel AI Gateway (run \`plasm-agent link\` to pull from a linked project)
+const ENV_EXAMPLE = `# Vercel AI Gateway
+# On Vercel: OIDC auth is automatic — no key required for gateway model slugs.
+# Local / self-host: run \`plasm-agent link\` or set AI_GATEWAY_API_KEY.
 AI_GATEWAY_API_KEY=
 
 # Vercel Cron auth (production)

package/src/cli/nitro-dev.ts

@@ -1,69 +1,30 @@
-import { spawn, type ChildProcess } from "node:child_process";
-import { access } from "node:fs/promises";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-import { nitroDevNodeOptions } from "./node-dev-imports.js";
+import { compileAuthoredSlots } from "./compile-authored-slots.js";
+import { walkAgentProject } from "../discovery/project-walker.js";
+import { generateAllStubs } from "../stubs/generator.js";
+import { startPlasmNitroDev } from "../nitro/build-application.js";
 import type { ResolvedAgentProject } from "./project-root.js";
 
-function plasmAgentPackageRoot(): string {
-  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
-}
-
-async function assertNitroScaffold(projectRoot: string): Promise<void> {
-  const required = [
-    path.join(projectRoot, "nitro.config.ts"),
-    path.join(projectRoot, "routes", "[...path].ts"),
-  ];
-  for (const filePath of required) {
-    try {
-      await access(filePath);
-    } catch {
-      throw new Error(
-        `Missing ${path.relative(projectRoot, filePath)} — run \`plasm-agent init\` to scaffold Nitro dev`,
-      );
-    }
-  }
-}
-
-function nitroBin(projectRoot: string): string {
-  return path.join(projectRoot, "node_modules", ".bin", "nitro");
-}
-
 export async function startNitroDevForProject(project: ResolvedAgentProject): Promise<void> {
-  await assertNitroScaffold(project.projectRoot);
-
-  const nodeOptions = nitroDevNodeOptions(plasmAgentPackageRoot());
-
-  const bin = nitroBin(project.projectRoot);
-  try {
-    await access(bin);
-  } catch {
-    throw new Error(
-      "nitropack is not installed — run `npm install` in the project root (init adds nitropack as a devDependency)",
-    );
-  }
-
-  const child: ChildProcess = spawn(bin, ["dev"], {
-    cwd: project.projectRoot,
-    env: {
-      ...process.env,
-      NODE_OPTIONS: nodeOptions,
-    },
-    stdio: "inherit",
+  await generateAllStubs(project.agentRoot);
+  const discovery = await walkAgentProject(project.agentRoot);
+  const { compiledSlots } = await compileAuthoredSlots(
+    project.projectRoot,
+    project.agentRoot,
+    discovery,
+  );
+
+  const server = await startPlasmNitroDev({
+    projectRoot: project.projectRoot,
+    agentRoot: project.agentRoot,
+    discovery,
+    compiledSlots,
   });
 
-  const wait = new Promise<number>((resolve, reject) => {
-    child.on("error", reject);
-    child.on("close", (code) => resolve(code ?? 0));
+  await new Promise<void>((resolve) => {
+    const shutdown = () => {
+      void server.close().finally(() => resolve());
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
   });
-
-  for (const signal of ["SIGINT", "SIGTERM"] as const) {
-    process.on(signal, () => {
-      child.kill(signal);
-    });
-  }
-
-  const exitCode = await wait;
-  process.exit(exitCode);
 }

package/src/gateway-model.ts

@@ -11,10 +11,20 @@ function ensureGatewayApiKey(): void {
   }
 }
 
-/** Whether `resolveGatewayModel` can run (API key or mapped alias present). */
+/** Hosted Vercel Functions (OIDC gateway auth available without an API key). */
+export function isVercelHosted(): boolean {
+  return (
+    process.env.VERCEL === "1" ||
+    Boolean(process.env.VERCEL_DEPLOYMENT_ID?.trim()) ||
+    Boolean(process.env.VERCEL_ENV?.trim())
+  );
+}
+
+/** Whether `resolveGatewayModel` can run (API key, alias, or Vercel OIDC). */
 export function isGatewayConfigured(): boolean {
   ensureGatewayApiKey();
-  return Boolean(process.env.AI_GATEWAY_API_KEY?.trim());
+  if (Boolean(process.env.AI_GATEWAY_API_KEY?.trim())) return true;
+  return isVercelHosted();
 }
 
 /** Resolve a Gateway model slug (`provider/model`) to an AI SDK `LanguageModel`. */
@@ -29,15 +39,16 @@ export function resolveGatewayModel(
   }
 
   ensureGatewayApiKey();
-  if (!process.env.AI_GATEWAY_API_KEY?.trim()) {
+  if (!isGatewayConfigured()) {
     throw new Error(
       [
-        "Vercel AI Gateway requires AI_GATEWAY_API_KEY.",
-        "Create one in the Vercel dashboard (AI → Gateway → API Keys) and add it to plasm-oss/.env.",
-        "Local dev: `vercel env pull` from a linked project also works.",
+        "Vercel AI Gateway is not configured.",
+        "On Vercel: link the project — gateway model ids authenticate via OIDC (no API key).",
+        "Off Vercel: set AI_GATEWAY_API_KEY or run `plasm-agent link`.",
       ].join(" "),
     );
   }
 
+  // On Vercel without an explicit key, @ai-sdk/gateway uses @vercel/oidc automatically.
   return gateway(slug);
 }

package/src/index.ts

@@ -132,6 +132,11 @@ export { createDefaultHostTransport } from "./engine/host-transport.js";
 export type { HostTransportOptions } from "./engine/host-transport.js";
 export { createProductionHostTransport, createStubHostTransport } from "./engine/create-host-transport.js";
 export { loadAgentEnv } from "./load-env.js";
+export {
+  isGatewayConfigured,
+  isVercelHosted,
+  resolveGatewayModel,
+} from "./gateway-model.js";
 export {
   connectorUidForEntry,
   connectAuthOptionsForEntry,

package/src/instrumentation.ts

@@ -12,7 +12,7 @@ export const PlasmSpanAttributes = {
   INTENT: "plasm.intent",
   LOGICAL_SESSION_REF: "plasm.logical_session_ref",
   CATALOG_CGS_HASH: "plasm.catalog_cgs_hash",
-  PLAN_COMMIT_REF: "plasm.plan_commit_ref",
+  RUN_REF: "plasm.run_ref",
   RUN_ID: "plasm.run_id",
   ENTRY_ID: "plasm.entry_id",
   TOOL_NAME: "plasm.tool.name",