@plasm_lang/vercel-agent 0.3.77 → 0.3.80

package/src/cli/init.ts

@@ -1,105 +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"]);
-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>;
-  };
-  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",
-    info: "plasm-agent info",
-    deploy: "vercel deploy",
-    ...pkg.scripts,
-    eval: `${nodeRunner} scripts/run-evals.ts`,
-    "smoke:channel": `${nodeRunner} scripts/smoke-channel.ts`,
-  };
-  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);
-  return { projectRoot, agentRoot };
-}
+export type { InitOptions } from "./init-scaffold.js";
 
 const AGENT_TS = `import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -196,113 +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 PACKAGE_JSON_TEMPLATE = {
-  name: "my-plasm-agent",
-  private: true,
-  type: "module",
-  scripts: {
-    dev: "plasm-agent dev",
-    build: "plasm-agent build",
-    "vercel-build": "plasm-agent build",
-    info: "plasm-agent info",
-    deploy: "vercel deploy",
-  },
-  dependencies: {} as Record<string, string>,
-};
-
-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",
-  );
-}
-
-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);
@@ -328,20 +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 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 [
@@ -353,7 +163,8 @@ export function formatInitSuccess(
       "  plasm-agent link          # pull AI_GATEWAY_API_KEY from Vercel",
       "  plasm-agent build",
       "  npm run smoke:channel",
-      "  plasm-agent dev           # local dev server + TUI",
+      "  plasm-agent dev           # Nitro dev server (Vercel routing parity)",
+      "  plasm-agent dev --interactive  # optional TUI + sessions + hot reload",
       "  vercel deploy             # production (channels + cron)",
     ].join("\n");
   }
@@ -366,7 +177,8 @@ export function formatInitSuccess(
     "  npm install",
     "  plasm-agent link      # pull AI_GATEWAY_API_KEY from Vercel",
     "  plasm-agent build     # generate CGS stubs + discovery manifest",
-    "  plasm-agent dev       # HTTP dev server (sessions + SSE)",
+    "  plasm-agent dev       # Nitro dev server (Vercel routing parity)",
+    "  plasm-agent dev --interactive  # optional TUI + sessions",
     "  vercel deploy         # production on Vercel",
   ].join("\n");
 }

package/src/cli/nitro-dev.ts

@@ -0,0 +1,69 @@
+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 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",
+  });
+
+  const wait = new Promise<number>((resolve, reject) => {
+    child.on("error", reject);
+    child.on("close", (code) => resolve(code ?? 0));
+  });
+
+  for (const signal of ["SIGINT", "SIGTERM"] as const) {
+    process.on(signal, () => {
+      child.kill(signal);
+    });
+  }
+
+  const exitCode = await wait;
+  process.exit(exitCode);
+}

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/engine/create-host-transport.ts

@@ -1,6 +1,13 @@
 import { createDefaultHostTransport } from "./host-transport.js";
+import { connectAuthOptionsForEntry } from "./connect-auth.js";
 import type { HostTransportFn } from "./napi-binding.js";
 
+/** Outbound HTTP for CGS stub live execute: Connect only when configured for the catalog. */
+export function createStubHostTransport(entryId?: string): HostTransportFn {
+  const useConnect = connectAuthOptionsForEntry(entryId)?.connector != null;
+  return createDefaultHostTransport({ useConnect });
+}
+
 /** Production host transport: env bearer → Vercel Connect `getToken()` → fetch. */
 export function createProductionHostTransport(): HostTransportFn {
   return createDefaultHostTransport({ useConnect: true });

package/src/index.ts

@@ -130,7 +130,7 @@ export type {
 export { StubPlasmEngine, NapiPlasmEngine, createEngine, isNativeEngineAvailable } from "./engine/napi-binding.js";
 export { createDefaultHostTransport } from "./engine/host-transport.js";
 export type { HostTransportOptions } from "./engine/host-transport.js";
-export { createProductionHostTransport } from "./engine/create-host-transport.js";
+export { createProductionHostTransport, createStubHostTransport } from "./engine/create-host-transport.js";
 export { loadAgentEnv } from "./load-env.js";
 export {
   connectorUidForEntry,

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/src/stubs/catalog-client.ts

@@ -1,5 +1,5 @@
 import type { HostTransportFn } from "../engine/napi-binding.js";
-import { createProductionHostTransport } from "../engine/create-host-transport.js";
+import { createStubHostTransport } from "../engine/create-host-transport.js";
 import {
   createEngine,
   type DryRunResult,
@@ -143,7 +143,7 @@ export async function executeRows<TRow>(
     options?.transport ??
     (process.env.PLASM_STUB_USE_MOCK_TRANSPORT === "1"
       ? createFixtureMockTransport()
-      : createProductionHostTransport());
+      : createStubHostTransport(builder.entryId));
 
   if (typeof bound.run !== "function") {
     throw new Error("executeRows: program builder missing run()");

package/src/tools/harness-tools.ts

@@ -1,58 +1,59 @@
-import { tool } from "ai";
+import { tool, type ToolSet } from "ai";
 import { z } from "zod";
 
 import type { SkillDefinition } from "../authoring/define-skill.js";
 import type { SubagentRegistry } from "../authoring/subagent-loader.js";
+import { toolInput } from "./tool-input.js";
+
+const readSkillInputSchema = z.object({
+  name: z.string().min(1).describe("Skill name from the index"),
+});
 
 export function createHarnessTools(options: {
   skills?: SkillDefinition[];
   subagents?: SubagentRegistry;
-}) {
+}): ToolSet {
+  const tools: ToolSet = {};
   const skillByName = new Map((options.skills ?? []).map((s) => [s.name, s]));
 
-  const readSkill =
-    skillByName.size > 0
-      ? {
-          read_skill: tool({
-            description:
-              "Load full text for a filesystem skill by name. Use when the skill index in the system prompt is not enough.",
-            inputSchema: z.object({
-              name: z.string().min(1).describe("Skill name from the index"),
-            }),
-            execute: async ({ name }: { name: string }) => {
-              const skill = skillByName.get(name);
-              if (!skill) {
-                return `Unknown skill "${name}". Available: ${[...skillByName.keys()].join(", ")}`;
-              }
-              return skill.body.trim();
-            },
-          }),
+  if (skillByName.size > 0) {
+    tools.read_skill = tool({
+      description:
+        "Load full text for a filesystem skill by name. Use when the skill index in the system prompt is not enough.",
+      inputSchema: toolInput(readSkillInputSchema),
+      execute: async ({ name }: { name: string }) => {
+        const skill = skillByName.get(name);
+        if (!skill) {
+          return `Unknown skill "${name}". Available: ${[...skillByName.keys()].join(", ")}`;
         }
-      : {};
+        return skill.body.trim();
+      },
+    });
+  }
 
   const subagentNames = options.subagents?.list().map((s) => s.name) ?? [];
-  const delegateSubagent =
-    subagentNames.length > 0 && options.subagents
-      ? {
-          delegate_subagent: tool({
-            description:
-              "Delegate a sub-task to a filesystem-isolated child agent. Each subagent has its own catalogs and session scope.",
-            inputSchema: z.object({
-              name: z
-                .string()
-                .min(1)
-                .describe(`Subagent name. One of: ${subagentNames.join(", ")}`),
-              message: z.string().min(1).describe("User message for the child agent turn"),
-            }),
-            execute: async ({ name, message }: { name: string; message: string }) => {
-              const result = await options.subagents!.delegate(name, message);
-              return `${result.text}\n\n(steps: ${result.steps})`;
-            },
-          }),
-        }
-      : {};
+  if (subagentNames.length > 0 && options.subagents) {
+    const subagents = options.subagents;
+    tools.delegate_subagent = tool({
+      description:
+        "Delegate a sub-task to a filesystem-isolated child agent. Each subagent has its own catalogs and session scope.",
+      inputSchema: toolInput(
+        z.object({
+          name: z
+            .string()
+            .min(1)
+            .describe(`Subagent name. One of: ${subagentNames.join(", ")}`),
+          message: z.string().min(1).describe("User message for the child agent turn"),
+        }),
+      ),
+      execute: async ({ name, message }: { name: string; message: string }) => {
+        const result = await subagents.delegate(name, message);
+        return `${result.text}\n\n(steps: ${result.steps})`;
+      },
+    });
+  }
 
-  return { ...readSkill, ...delegateSubagent };
+  return tools;
 }
 
 export function renderSkillIndex(skills: SkillDefinition[]): string {