@plasm_lang/vercel-agent 0.3.91 → 0.3.92

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasm_lang/vercel-agent",
-  "version": "0.3.91",
+  "version": "0.3.92",
   "description": "Catalog-native TypeScript agent framework (Plasm CGS/CML, Vercel AI SDK, Nitro-oriented)",
   "license": "GPL-3.0-or-later",
   "repository": {
@@ -19,6 +19,7 @@
     "./server": "./src/server/plasm-handler.ts",
     "./instrumentation": "./src/instrumentation.ts",
     "./operator": "./src/operator/routes.ts",
+    "./stub-runtime": "./src/stubs/stub-runtime.ts",
     "./agent": "./agent/agent.ts"
   },
   "bin": {
@@ -63,7 +64,7 @@
   "dependencies": {
     "@ai-sdk/otel": "^1.0.3",
     "@opentelemetry/api": "^1.9.0",
-    "@plasm_lang/engine": "^0.3.91",
+    "@plasm_lang/engine": "^0.3.92",
     "@vercel/blob": "^0.27.3",
     "@vercel/connect": "^0.2.6",
     "@vercel/kv": "^3.0.0",

package/src/authoring/context.ts

@@ -14,6 +14,8 @@ export interface CreateAuthoringContextOptions {
   agentRoot: string;
   getAgent: () => Promise<PlasmAgent>;
   importCacheBust?: number;
+  /** Generated stub extension — `.mjs` on Vercel (bundled at build); `.ts` in dev. */
+  stubImportExt?: "ts" | "mjs";
 }
 
 export function createAuthoringContext(
@@ -21,12 +23,13 @@ export function createAuthoringContext(
 ): AuthoringContext {
   const agentRoot = path.resolve(options.agentRoot);
   const bust = options.importCacheBust ?? Date.now();
+  const stubExt = options.stubImportExt ?? "ts";
 
   return {
     agentRoot,
     getAgent: options.getAgent,
     importStub: async (entryId: string) => {
-      const stubPath = path.join(agentRoot, ".plasm", "stubs", `${entryId}.ts`);
+      const stubPath = path.join(agentRoot, ".plasm", "stubs", `${entryId}.${stubExt}`);
       const url = `${pathToFileURL(stubPath).href}?t=${bust}`;
       return import(url);
     },

package/src/cli/build-manifest.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 
 export interface PlasmBuildManifest {
   compiledSlots?: Record<string, string>;
+  compiledStubs?: Record<string, string>;
   projectRoot?: string;
 }
 

package/src/cli/build.ts

@@ -2,6 +2,7 @@ import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 
 import { readBuildManifest } from "./build-manifest.js";
+import { compileGeneratedStubs } from "./compile-generated-stubs.js";
 import { compileAuthoredSlots } from "./compile-authored-slots.js";
 import type { ResolvedAgentProject } from "./project-root.js";
 import { isNativeEngineAvailable } from "../engine/napi-binding.js";
@@ -15,6 +16,7 @@ export interface PlasmBuildResult {
   discoveryDir: string;
   manifestPath: string;
   stubs: Array<{ entryId: string; catalogCgsHash: string; outPath: string }>;
+  compiledStubs: Record<string, string>;
   outputDir?: string;
   agentSummaryPath?: string;
   vercelOutput?: boolean;
@@ -22,6 +24,11 @@ export interface PlasmBuildResult {
 
 export async function runPlasmBuild(project: ResolvedAgentProject): Promise<PlasmBuildResult> {
   const stubs = await generateAllStubs(project.agentRoot);
+  const { compiledStubs } = await compileGeneratedStubs(
+    project.projectRoot,
+    project.agentRoot,
+    stubs,
+  );
   const discovery = await walkAgentProject(project.agentRoot);
   const { compiledSlots } = await compileAuthoredSlots(
     project.projectRoot,
@@ -38,6 +45,7 @@ export async function runPlasmBuild(project: ResolvedAgentProject): Promise<Plas
     projectRoot: project.projectRoot,
     agentRoot: project.agentRoot,
     compiledSlots,
+    compiledStubs,
     stubs: stubs.map((s) => ({
       entryId: s.entryId,
       catalogCgsHash: s.catalogCgsHash,
@@ -74,6 +82,7 @@ export async function runPlasmBuild(project: ResolvedAgentProject): Promise<Plas
     discoveryDir,
     manifestPath,
     stubs,
+    compiledStubs,
     outputDir: appBuild.outputDir,
     agentSummaryPath: appBuild.agentSummaryPath,
     vercelOutput: appBuild.vercelOutput,

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

@@ -71,6 +71,17 @@ export async function compileAuthoredSlots(
           "workflow",
           "workflow/api",
         ],
+        plugins: [
+          {
+            name: "external-workflows",
+            setup(build) {
+              build.onResolve({ filter: /\/workflows\// }, (args) => ({
+                path: args.path,
+                external: true,
+              }));
+            },
+          },
+        ],
         logLevel: "silent",
       });
 

package/src/cli/compile-generated-stubs.ts

@@ -0,0 +1,97 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import * as esbuild from "esbuild";
+
+import type { StubGenerationResult } from "../stubs/generator.js";
+
+const ESBUILD_BANNER =
+  'import { createRequire as __createRequire } from "module"; const require = __createRequire(import.meta.url);';
+
+const STUB_RUNTIME_SOURCE = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../stubs/stub-runtime.ts",
+);
+
+const STUB_RUNTIME_BASENAME = "_stub-runtime.mjs";
+
+/** Native engine stays external; runtime is a shared sibling module on Vercel. */
+const STUB_RUNTIME_EXTERNAL = ["@plasm_lang/engine"];
+
+export interface CompileGeneratedStubsResult {
+  /** entry_id → projectRoot-relative compiled `.mjs` path */
+  compiledStubs: Record<string, string>;
+}
+
+function stubRuntimeExternalPlugin(): esbuild.Plugin {
+  return {
+    name: "stub-runtime-sibling",
+    setup(build) {
+      build.onResolve({ filter: /^\.\/_stub-runtime\.js$/ }, () => ({
+        path: "./_stub-runtime.mjs",
+        external: true,
+      }));
+    },
+  };
+}
+
+async function compileStubRuntime(stubsDir: string): Promise<string> {
+  const runtimePath = path.join(stubsDir, STUB_RUNTIME_BASENAME);
+  await esbuild.build({
+    entryPoints: [STUB_RUNTIME_SOURCE],
+    bundle: true,
+    platform: "node",
+    target: "node22",
+    format: "esm",
+    outfile: runtimePath,
+    banner: { js: ESBUILD_BANNER },
+    external: STUB_RUNTIME_EXTERNAL,
+    logLevel: "silent",
+  });
+  return runtimePath;
+}
+
+/** Compile generated CGS stubs to `.mjs` for serverless dynamic import. */
+export async function compileGeneratedStubs(
+  projectRoot: string,
+  agentRoot: string,
+  stubs: StubGenerationResult[],
+): Promise<CompileGeneratedStubsResult> {
+  const stubsDir = path.join(agentRoot, ".plasm", "stubs");
+  await mkdir(stubsDir, { recursive: true });
+  await compileStubRuntime(stubsDir);
+
+  const compiledStubs: Record<string, string> = {};
+
+  await Promise.all(
+    stubs.map(async (stub) => {
+      const entryId = stub.entryId;
+      const tsPath = stub.outPath;
+      const mjsPath = tsPath.replace(/\.ts$/, ".mjs");
+
+      await esbuild.build({
+        entryPoints: [tsPath],
+        bundle: true,
+        platform: "node",
+        target: "node22",
+        format: "esm",
+        outfile: mjsPath,
+        banner: { js: ESBUILD_BANNER },
+        external: STUB_RUNTIME_EXTERNAL,
+        plugins: [stubRuntimeExternalPlugin()],
+        logLevel: "silent",
+      });
+
+      compiledStubs[entryId] = path.relative(projectRoot, mjsPath);
+    }),
+  );
+
+  await writeFile(
+    path.join(stubsDir, "package.json"),
+    `${JSON.stringify({ type: "module" }, null, 2)}\n`,
+    "utf8",
+  );
+
+  return { compiledStubs };
+};

package/src/nitro/create-plasm-nitro.ts

@@ -44,6 +44,42 @@ async function publicDirExists(projectRoot: string): Promise<boolean> {
   }
 }
 
+async function pathExists(p: string): Promise<boolean> {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function plasmNitroHandlers(
+  projectRoot: string,
+  workflowEnabled: boolean,
+): Promise<NonNullable<NitroConfig["handlers"]>> {
+  const catchAllHandler = path.join(plasmNitroRoutesDir(projectRoot), "[[path]].ts");
+  const handlers: NonNullable<NitroConfig["handlers"]> = [];
+
+  if (workflowEnabled) {
+    const dispatchHandler = path.join(
+      plasmNitroRoutesDir(projectRoot),
+      "internal",
+      "workflow",
+      "dispatch.post.ts",
+    );
+    if (await pathExists(dispatchHandler)) {
+      handlers.push({
+        route: "/internal/workflow/dispatch",
+        handler: dispatchHandler,
+        method: "post",
+      });
+    }
+  }
+
+  handlers.push({ route: "/**", handler: catchAllHandler });
+  return handlers;
+}
+
 export async function createPlasmNitro(
   host: PreparedPlasmHost,
   dev: boolean,
@@ -59,8 +95,6 @@ export async function createPlasmNitro(
 
   const traceDeps = [...new Set([...SERVER_TRACE_DEPS, ...host.externalDeps])];
 
-  const catchAllHandler = path.join(plasmNitroRoutesDir(host.projectRoot), "[[path]].ts");
-
   const publicAssets = (await publicDirExists(host.projectRoot))
     ? [
         {
@@ -80,7 +114,7 @@ export async function createPlasmNitro(
     dev,
     serverDir: false,
     ignore: ["api/**", "server/**", "routes/**", "nitro.config.ts"],
-    handlers: [{ route: "/**", handler: catchAllHandler }],
+    handlers: await plasmNitroHandlers(host.projectRoot, host.workflowEnabled),
     publicAssets,
     modules,
     experimental: {

package/src/nitro/write-workflow-dispatch-route.ts

@@ -11,7 +11,7 @@ export async function writeWorkflowDispatchRoute(projectRoot: string): Promise<s
   const source = `import path from "node:path";
 import type { IncomingMessage, ServerResponse } from "node:http";
 
-import agentDefinition from "../../../../agent/agent.js";
+import agentDefinition from "../../../../../agent/agent.js";
 import { createPlasmApp } from "@plasm_lang/vercel-agent/server";
 
 const agentRoot = path.join(process.cwd(), "agent");
@@ -53,7 +53,7 @@ export default async (event: NitroNodeEvent) => {
     mode: "prod",
     sessions: false,
   });
-  const { runRadar } = await import("../../../../lib/run-radar.js");
+  const { runRadar } = await import("../../../../../lib/run-radar.js");
   const result = await runRadar(app.getAuthoringContext(), { force });
 
   res.statusCode = 200;

package/src/server/plasm-handler.ts

@@ -229,6 +229,7 @@ export async function createPlasmApp(options: PlasmAppOptions): Promise<PlasmApp
       agentRoot,
       getAgent: async () => agent ?? bootstrap(),
       importCacheBust,
+      stubImportExt: mode === "prod" ? "mjs" : "ts",
     });
 
   const bootstrap = async (): Promise<PlasmAgent> => {

package/src/stubs/generator.ts

@@ -59,6 +59,23 @@ export function computeCatalogCgsHash(domainYaml: string, mappingsYaml: string):
   return createHash("sha256").update(domainYaml).update("\n").update(mappingsYaml).digest("hex");
 }
 
+/** Dev-time shim beside generated stubs; prod uses `_stub-runtime.mjs` from compile. */
+export async function writeStubRuntimeShim(outDir: string): Promise<void> {
+  await mkdir(outDir, { recursive: true });
+  const source = `/** @generated plasm-agent stub runtime shim (dev only) */
+export {
+  buildDottedArgs,
+  createCatalogClient,
+  executeRows,
+  plasmBoolean,
+  plasmLiteral,
+  plasmNumber,
+  type StubInvokeOptions,
+} from "@plasm_lang/vercel-agent/stub-runtime";
+`;
+  await writeFile(path.join(outDir, "_stub-runtime.ts"), source, "utf8");
+}
+
 /** Legacy parser — delegates to {@link parseCgsDomain}. */
 export function parseDomainYaml(raw: string, fallbackEntryId: string): ParsedDomain {
   return toLegacyParsedDomain(parseCgsDomain(raw, fallbackEntryId));
@@ -154,7 +171,7 @@ export function renderStubModule(
   bindings?: Map<string, CapabilityBinding>,
 ): string {
   const exportName = toExportName(catalog.entry_id);
-  const clientImport = "@plasm_lang/vercel-agent";
+  const clientImport = "./_stub-runtime.js";
 
   const entityTypes = new Set<string>();
   const inputTypes = new Set<string>();
@@ -288,6 +305,8 @@ export async function generateAllStubs(
   const outDir = path.join(agentRoot, ".plasm", "stubs");
   const { access, readdir, stat } = await import("node:fs/promises");
 
+  await writeStubRuntimeShim(outDir);
+
   const engine = options?.engine ?? createEngine();
 
   let entries;

package/src/stubs/stub-runtime.ts

@@ -0,0 +1,10 @@
+/** Narrow stub import surface — bundled into generated `.mjs` stubs on Vercel. */
+export {
+  buildDottedArgs,
+  createCatalogClient,
+  executeRows,
+  plasmBoolean,
+  plasmLiteral,
+  plasmNumber,
+  type StubInvokeOptions,
+} from "./catalog-client.js";

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

@@ -2,11 +2,17 @@ import type { AuthoringContext } from "@plasm_lang/vercel-agent";
 
 import type { RadarRunOptions } from "./run-radar.js";
 
+/** Must match @workflow/nitro manifest for `workflows/mcp-radar-scan.ts`. */
+const MCP_RADAR_SCAN_WORKFLOW_ID =
+  "workflow//./workflows/mcp-radar-scan//mcpRadarScanWorkflow";
+
 export async function startMcpRadarRun(
   ctx: AuthoringContext,
   options: RadarRunOptions = {},
 ): Promise<unknown> {
   const { start } = await import("workflow/api");
-  const { mcpRadarScanWorkflow } = await import("../workflows/mcp-radar-scan.js");
-  return start(mcpRadarScanWorkflow, [ctx.agentRoot, options.force === true]);
+  return start({ workflowId: MCP_RADAR_SCAN_WORKFLOW_ID }, [
+    ctx.agentRoot,
+    options.force === true,
+  ]);
 }

package/templates/mcp-radar/workflows/mcp-radar-scan.ts

@@ -1,6 +1,8 @@
 function workflowDispatchUrl(): string {
   const explicit = process.env.PLASM_WORKFLOW_DISPATCH_URL?.trim();
   if (explicit) return explicit;
+  const production = process.env.VERCEL_PROJECT_PRODUCTION_URL?.trim();
+  if (production) return `https://${production}/internal/workflow/dispatch`;
   const vercelUrl = process.env.VERCEL_URL?.trim();
   if (vercelUrl) return `https://${vercelUrl}/internal/workflow/dispatch`;
   const port = process.env.PORT ?? "3000";