@plasm_lang/vercel-agent 0.3.82 → 0.3.85

package/src/nitro/agent-summary.ts

@@ -0,0 +1,133 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import type { LoadedProjectSlots } from "../authoring/slot-loader.js";
+import { listChannelRoutes } from "../authoring/channel-dispatch.js";
+import { exportScheduleCronManifest } from "../authoring/schedule-manager.js";
+import type { AgentDefinition } from "../define-agent.js";
+import type { ProjectDiscovery } from "../discovery/project-walker.js";
+import { frameworkPackageVersion } from "../package-version.js";
+import { plasmAgentSummaryPath } from "./paths.js";
+
+export const VERCEL_PLASM_AGENT_SUMMARY_KIND = "vercel-plasm-agent-summary";
+export const VERCEL_PLASM_AGENT_SUMMARY_VERSION = 3;
+
+export interface PlasmAgentSummaryPayload {
+  kind: typeof VERCEL_PLASM_AGENT_SUMMARY_KIND;
+  schemaVersion: typeof VERCEL_PLASM_AGENT_SUMMARY_VERSION;
+  generatorVersion: string;
+  agent: {
+    name: string;
+    description: string | null;
+    modelId: string;
+  };
+  instructions: {
+    logicalPath: string;
+    sourceKind: string;
+    markdown: string | null;
+  } | null;
+  schedules: Array<{ name: string; cron: string; logicalPath: string }>;
+  tools: Array<{ name: string; description: string; logicalPath: string }>;
+  skills: Array<{ name: string; description: string; logicalPath: string; sourceKind: string }>;
+  connections: [];
+  channels: Array<{
+    name: string;
+    method: string;
+    urlPath: string;
+    type: string;
+    logicalPath: string;
+  }>;
+  sandbox: null;
+  subagents: Array<{ name: string; description: string; logicalPath: string }>;
+  diagnostics: { errors: number; warnings: number };
+}
+
+function normalizeChannelKind(method: string): string {
+  if (method === "WEBSOCKET") return "websocket";
+  return "http";
+}
+
+export function buildPlasmAgentSummary(options: {
+  projectRoot: string;
+  agentRoot: string;
+  packageName?: string;
+  definition: AgentDefinition;
+  discovery: ProjectDiscovery;
+  loadedSlots: import("../authoring/slot-loader.js").LoadedProjectSlots;
+  generatorVersion?: string;
+}): PlasmAgentSummaryPayload {
+  const { projectRoot, agentRoot, packageName, definition, discovery, loadedSlots } = options;
+  const rel = (p: string) => path.relative(projectRoot, p);
+
+  const instructions =
+    discovery.instructions === undefined
+      ? null
+      : {
+          logicalPath: rel(discovery.instructions.path),
+          sourceKind: discovery.instructions.kind,
+          markdown: null,
+        };
+
+  const channels = loadedSlots.channels.flatMap((channel) =>
+    channel.definition.routes.map((route) => ({
+      name: path.basename(channel.sourcePath, path.extname(channel.sourcePath)),
+      method: route.method,
+      urlPath: route.path,
+      type: normalizeChannelKind(route.method),
+      logicalPath: rel(channel.sourcePath),
+    })),
+  );
+
+  const scheduleManifest = exportScheduleCronManifest(loadedSlots.schedules);
+
+  const diagnostics = [...loadedSlots.diagnostics, ...discovery.diagnostics];
+
+  return {
+    kind: VERCEL_PLASM_AGENT_SUMMARY_KIND,
+    schemaVersion: VERCEL_PLASM_AGENT_SUMMARY_VERSION,
+    generatorVersion: options.generatorVersion ?? frameworkPackageVersion(),
+    agent: {
+      name: packageName ?? path.basename(path.dirname(agentRoot)),
+      description: null,
+      modelId: definition.model,
+    },
+    instructions,
+    schedules: scheduleManifest.crons.map((cron) => ({
+      name: cron.name,
+      cron: cron.schedule,
+      logicalPath: rel(
+        loadedSlots.schedules.find((s) => s.definition.name === cron.name)?.sourcePath ??
+          path.join(agentRoot, "schedules", `${cron.name}.ts`),
+      ),
+    })),
+    tools: [],
+    skills: loadedSlots.skills.map((skill) => ({
+      name: skill.definition.name,
+      description: skill.definition.description ?? "",
+      logicalPath: rel(skill.sourcePath),
+      sourceKind: skill.sourcePath.endsWith(".md") ? "markdown" : "typescript",
+    })),
+    connections: [],
+    channels,
+    sandbox: null,
+    subagents: discovery.subagents.map((sub) => ({
+      name: sub.name,
+      description: "",
+      logicalPath: rel(sub.path),
+    })),
+    diagnostics: {
+      errors: diagnostics.filter((d) => d.level === "error").length,
+      warnings: diagnostics.filter((d) => d.level === "warning").length,
+    },
+  };
+}
+
+export async function emitPlasmAgentSummary(options: {
+  projectRoot: string;
+  summary: PlasmAgentSummaryPayload;
+}): Promise<string> {
+  const outPath = plasmAgentSummaryPath(options.projectRoot);
+  await mkdir(path.dirname(outPath), { recursive: true });
+  await writeFile(outPath, `${JSON.stringify(options.summary, null, 2)}\n`, "utf8");
+  return outPath;
+}

package/src/nitro/build-application.ts

@@ -0,0 +1,98 @@
+import path from "node:path";
+
+import type { CompiledSlotMap } from "../cli/compile-authored-slots.js";
+import { loadAuthoredSlots } from "../authoring/slot-loader.js";
+import type { ProjectDiscovery } from "../discovery/project-walker.js";
+import { buildPlasmAgentSummary, emitPlasmAgentSummary } from "./agent-summary.js";
+import { buildNitroOutput } from "./build-nitro-output.js";
+import { createPlasmNitro } from "./create-plasm-nitro.js";
+import { patchVercelOutputConfig } from "./patch-vercel-config.js";
+import { copyVercelFunctionAssets } from "./copy-vercel-function-assets.js";
+import { isVercelBuildEnvironment, vercelOutputDir } from "./paths.js";
+import { preparePlasmHost } from "./prepare-host.js";
+import { writePlasmNitroCatchAllRoute } from "./write-nitro-entry.js";
+
+export interface PlasmApplicationBuildResult {
+  outputDir: string;
+  agentSummaryPath: string;
+  vercelOutput: boolean;
+}
+
+export async function buildPlasmApplication(options: {
+  projectRoot: string;
+  agentRoot: string;
+  discovery: ProjectDiscovery;
+  compiledSlots: CompiledSlotMap;
+  packageName?: string;
+}): Promise<PlasmApplicationBuildResult> {
+  const { projectRoot, agentRoot, discovery, compiledSlots, packageName } = options;
+
+  const host = await preparePlasmHost({
+    projectRoot,
+    agentRoot,
+    compiledSlots,
+    discovery,
+  });
+
+  await writePlasmNitroCatchAllRoute(projectRoot, compiledSlots);
+
+  const nitro = await createPlasmNitro(host, false);
+  try {
+    const outputDir = await buildNitroOutput(nitro);
+
+    if (isVercelBuildEnvironment()) {
+      await copyVercelFunctionAssets({ projectRoot, agentRoot });
+      await patchVercelOutputConfig(projectRoot, host);
+    }
+
+    const loadedSlots = await loadAuthoredSlots({
+      discovery,
+      agentRoot,
+      projectRoot,
+      compiledSlots,
+    });
+
+    const summary = buildPlasmAgentSummary({
+      projectRoot,
+      agentRoot,
+      packageName,
+      definition: host.definition,
+      discovery,
+      loadedSlots,
+    });
+    const agentSummaryPath = await emitPlasmAgentSummary({ projectRoot, summary });
+
+    const vercelOutput = isVercelBuildEnvironment();
+    const resolvedOutput = vercelOutput ? vercelOutputDir(projectRoot) : outputDir;
+
+    return {
+      outputDir: resolvedOutput,
+      agentSummaryPath,
+      vercelOutput,
+    };
+  } finally {
+    await nitro.close();
+  }
+}
+
+export async function startPlasmNitroDev(options: {
+  projectRoot: string;
+  agentRoot: string;
+  discovery: ProjectDiscovery;
+  compiledSlots: CompiledSlotMap;
+}): Promise<Awaited<ReturnType<typeof import("nitro/builder").createDevServer>>> {
+  const { createDevServer } = await import("nitro/builder");
+
+  const host = await preparePlasmHost(options);
+  await writePlasmNitroCatchAllRoute(options.projectRoot, options.compiledSlots);
+
+  const nitro = await createPlasmNitro(host, true);
+  const server = createDevServer(nitro);
+
+  const port = Number(process.env.PORT ?? 3000);
+  const listenHost = process.env.HOST ?? "127.0.0.1";
+  server.listen({ port, hostname: listenHost });
+  console.log(`[plasm-agent] Nitro dev → http://${listenHost}:${port}`);
+
+  return server;
+}

package/src/nitro/build-nitro-output.ts

@@ -0,0 +1,14 @@
+import { build, copyPublicAssets, prepare, prerender } from "nitro/builder";
+import type { Nitro } from "nitro/types";
+
+export async function buildNitroOutput(nitro: Nitro): Promise<string> {
+  await prepare(nitro);
+  await copyPublicAssets(nitro);
+  await prerender(nitro);
+  await build(nitro);
+  const outDir = nitro.options.output.dir;
+  if (!outDir) {
+    throw new Error("Nitro build completed without output.dir");
+  }
+  return outDir;
+}

package/src/nitro/copy-vercel-function-assets.ts

@@ -0,0 +1,31 @@
+import { access, cp } from "node:fs/promises";
+import path from "node:path";
+
+import { vercelOutputDir } from "./paths.js";
+
+async function pathExists(p: string): Promise<boolean> {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Copy agent project files into the Vercel serverless bundle (runtime slot discovery). */
+export async function copyVercelFunctionAssets(options: {
+  projectRoot: string;
+  agentRoot: string;
+}): Promise<void> {
+  const funcDir = path.join(vercelOutputDir(options.projectRoot), "functions", "__server.func");
+  if (!(await pathExists(funcDir))) {
+    return;
+  }
+
+  await cp(options.agentRoot, path.join(funcDir, "agent"), { recursive: true });
+
+  const libDir = path.join(options.projectRoot, "lib");
+  if (await pathExists(libDir)) {
+    await cp(libDir, path.join(funcDir, "lib"), { recursive: true });
+  }
+}

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

@@ -0,0 +1,111 @@
+import path from "node:path";
+import { access } from "node:fs/promises";
+
+import workflowNitro from "@workflow/nitro";
+import { createNitro } from "nitro/builder";
+import type { Nitro, NitroConfig } from "nitro/types";
+
+import type { PreparedPlasmHost } from "./prepare-host.js";
+import {
+  isVercelBuildEnvironment,
+  plasmNitroBuildDir,
+  plasmNitroOutputDir,
+  plasmNitroRoutesDir,
+  vercelOutputDir,
+} from "./paths.js";
+import { createPlasmVercelOptions } from "./vercel-build-output-config.js";
+
+const SERVER_TRACE_DEPS = [
+  "@plasm_lang/engine",
+  "@plasm_lang/vercel-agent",
+  "@vercel/functions",
+  "@vercel/blob",
+  "@vercel/kv",
+  "@vercel/otel",
+];
+
+function resolveNitroPreset(dev: boolean): NitroConfig["preset"] {
+  if (dev) return "nitro-dev";
+  if (isVercelBuildEnvironment()) return "vercel";
+  return "node-server";
+}
+
+async function publicDirExists(projectRoot: string): Promise<boolean> {
+  try {
+    await access(path.join(projectRoot, "public"));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function createPlasmNitro(
+  host: PreparedPlasmHost,
+  dev: boolean,
+): Promise<Nitro> {
+  const preset = resolveNitroPreset(dev);
+  const isVercel = preset === "vercel";
+  const plasmVercel = createPlasmVercelOptions(isVercel);
+
+  const modules: NitroConfig["modules"] = [];
+  if (host.workflowEnabled) {
+    modules.push(workflowNitro);
+  }
+
+  const traceDeps = [...new Set([...SERVER_TRACE_DEPS, ...host.externalDeps])];
+
+  const catchAllHandler = path.join(plasmNitroRoutesDir(host.projectRoot), "[[path]].ts");
+
+  const publicAssets = (await publicDirExists(host.projectRoot))
+    ? [
+        {
+          dir: path.join(host.projectRoot, "public"),
+          baseURL: "/",
+          maxAge: 3600,
+        },
+      ]
+    : [];
+
+  const vercelConfig = plasmVercel?.config ?? { version: 3 as const };
+  const config: NitroConfig = {
+    rootDir: host.projectRoot,
+    buildDir: plasmNitroBuildDir(host.projectRoot),
+    preset,
+    dev,
+    serverDir: false,
+    ignore: ["api/**", "server/**", "routes/**", "nitro.config.ts"],
+    handlers: [{ route: "/**", handler: catchAllHandler }],
+    publicAssets,
+    modules,
+    traceDeps: [
+      ...traceDeps,
+      "./agent/**",
+      "./lib/**",
+      "./agent/.plasm/compiled/**",
+      "./agent/.plasm/stubs/**",
+    ],
+    vercel: isVercel
+      ? {
+          entryFormat: "node",
+          functions: {
+            maxDuration: 300,
+            environment: {
+              PLASM_RUN_ARTIFACTS_DIR: "/tmp/plasm-archives/runs",
+              PLASM_TRACE_ARCHIVE_DIR: "/tmp/plasm-archives/traces",
+            },
+          },
+          config: {
+            ...vercelConfig,
+            crons: host.scheduleCrons,
+          },
+        }
+      : undefined,
+    output: isVercel
+      ? { dir: vercelOutputDir(host.projectRoot) }
+      : dev
+        ? undefined
+        : { dir: plasmNitroOutputDir(host.projectRoot) },
+  };
+
+  return createNitro(config, dev ? { watch: true } : undefined);
+}

package/src/nitro/patch-vercel-config.ts

@@ -0,0 +1,37 @@
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { frameworkPackageVersion } from "../package-version.js";
+import type { PreparedPlasmHost } from "./prepare-host.js";
+import { vercelOutputDir } from "./paths.js";
+
+interface VercelOutputConfig {
+  version?: number;
+  framework?: { name?: string; version?: string };
+  crons?: Array<{ path: string; schedule: string }>;
+  [key: string]: unknown;
+}
+
+/** Merge Plasm crons + framework metadata into Nitro-emitted config.json. */
+export async function patchVercelOutputConfig(
+  projectRoot: string,
+  host: PreparedPlasmHost,
+): Promise<void> {
+  const configPath = path.join(vercelOutputDir(projectRoot), "config.json");
+  let config: VercelOutputConfig;
+  try {
+    config = JSON.parse(await readFile(configPath, "utf8")) as VercelOutputConfig;
+  } catch {
+    return;
+  }
+
+  config.version = 3;
+  config.framework = {
+    version: frameworkPackageVersion(),
+  };
+  if (host.scheduleCrons.length > 0) {
+    config.crons = host.scheduleCrons;
+  }
+
+  await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}

package/src/nitro/paths.ts

@@ -0,0 +1,30 @@
+import path from "node:path";
+
+export const PLASM_NITRO_BUILD_DIR = ".plasm/nitro";
+export const PLASM_NITRO_ROUTES_DIR = ".plasm/nitro/routes";
+export const PLASM_NITRO_OUTPUT_DIR = ".plasm/nitro-output";
+export const PLASM_AGENT_SUMMARY_PATH = ".plasm/agent-summary.json";
+
+export function plasmNitroBuildDir(projectRoot: string): string {
+  return path.join(projectRoot, PLASM_NITRO_BUILD_DIR);
+}
+
+export function plasmNitroRoutesDir(projectRoot: string): string {
+  return path.join(projectRoot, PLASM_NITRO_ROUTES_DIR);
+}
+
+export function plasmNitroOutputDir(projectRoot: string): string {
+  return path.join(projectRoot, PLASM_NITRO_OUTPUT_DIR);
+}
+
+export function plasmAgentSummaryPath(projectRoot: string): string {
+  return path.join(projectRoot, PLASM_AGENT_SUMMARY_PATH);
+}
+
+export function vercelOutputDir(projectRoot: string): string {
+  return path.join(projectRoot, ".vercel", "output");
+}
+
+export function isVercelBuildEnvironment(): boolean {
+  return process.env.VERCEL === "1" || process.env.VERCEL === "true";
+}

package/src/nitro/prepare-host.ts

@@ -0,0 +1,69 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import type { CompiledSlotMap } from "../cli/compile-authored-slots.js";
+import { loadAuthoredSlots } from "../authoring/slot-loader.js";
+import type { AgentDefinition } from "../define-agent.js";
+import { walkAgentProject, type ProjectDiscovery } from "../discovery/project-walker.js";
+import { exportScheduleCronManifest } from "../authoring/schedule-manager.js";
+import { projectUsesWorkflowDirectives } from "./workflow-directives.js";
+
+export interface PreparedPlasmHost {
+  projectRoot: string;
+  agentRoot: string;
+  definition: AgentDefinition;
+  discovery: ProjectDiscovery;
+  compiledSlots: CompiledSlotMap;
+  scheduleCrons: Array<{ path: string; schedule: string }>;
+  externalDeps: string[];
+  workflowEnabled: boolean;
+}
+
+async function loadAgentDefinition(agentRoot: string): Promise<AgentDefinition> {
+  const agentPath = path.join(agentRoot, "agent.ts");
+  const mod = (await import(`${pathToFileURL(agentPath).href}?v=${Date.now()}`)) as {
+    default: AgentDefinition;
+  };
+  if (!mod.default?.model) {
+    throw new Error(`agent/agent.ts must default-export defineAgent({ model: ... })`);
+  }
+  return mod.default;
+}
+
+export async function preparePlasmHost(options: {
+  projectRoot: string;
+  agentRoot: string;
+  compiledSlots: CompiledSlotMap;
+  discovery: ProjectDiscovery;
+}): Promise<PreparedPlasmHost> {
+  const { projectRoot, agentRoot, compiledSlots, discovery } = options;
+  const definition = await loadAgentDefinition(agentRoot);
+
+  const loadedSlots = await loadAuthoredSlots({
+    discovery,
+    agentRoot,
+    projectRoot,
+    compiledSlots,
+  });
+
+  const scheduleCrons = exportScheduleCronManifest(loadedSlots.schedules).crons.map((c) => ({
+    path: c.path,
+    schedule: c.schedule,
+  }));
+
+  const externalDeps = definition.build?.externalDependencies ?? [];
+  const workflowConfigured = definition.experimental?.workflow !== undefined;
+  const workflowEnabled =
+    workflowConfigured && (await projectUsesWorkflowDirectives(projectRoot));
+
+  return {
+    projectRoot,
+    agentRoot,
+    definition,
+    discovery,
+    compiledSlots,
+    scheduleCrons,
+    externalDeps,
+    workflowEnabled,
+  };
+}

package/src/nitro/vercel-build-output-config.ts

@@ -0,0 +1,18 @@
+import { frameworkPackageVersion } from "../package-version.js";
+
+export function createPlasmVercelOptions(enabled: boolean):
+  | {
+      config: {
+        version: 3;
+        framework: { version: string };
+      };
+    }
+  | undefined {
+  if (!enabled) return undefined;
+  return {
+    config: {
+      version: 3,
+      framework: { version: frameworkPackageVersion() },
+    },
+  };
+}

package/src/nitro/workflow-directives.ts

@@ -0,0 +1,43 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+
+const WORKFLOW_MARKERS = ["use workflow", "use step", "'use workflow'", '"use workflow"'];
+
+async function walkTsFiles(dir: string): Promise<string[]> {
+  const out: string[] = [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name === ".plasm") continue;
+      out.push(...(await walkTsFiles(full)));
+      continue;
+    }
+    if (entry.name.endsWith(".ts") || entry.name.endsWith(".tsx")) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+/** True when authored sources contain Workflow SDK directives (needs @workflow/nitro). */
+export async function projectUsesWorkflowDirectives(projectRoot: string): Promise<boolean> {
+  const roots = [
+    path.join(projectRoot, "agent"),
+    path.join(projectRoot, "lib"),
+  ];
+  for (const root of roots) {
+    for (const file of await walkTsFiles(root)) {
+      const source = await readFile(file, "utf8");
+      if (WORKFLOW_MARKERS.some((marker) => source.includes(marker))) {
+        return true;
+      }
+    }
+  }
+  return false;
+}

package/src/nitro/write-nitro-entry.ts

@@ -0,0 +1,87 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import type { CompiledSlotMap } from "../cli/compile-authored-slots.js";
+import { plasmNitroRoutesDir } from "./paths.js";
+
+function slotImportId(relFromAgent: string): string {
+  return relFromAgent.replace(/[^a-zA-Z0-9]+/g, "_");
+}
+
+/** Generate Nitro catch-all route that boots PlasmApp (eve-style programmatic host). */
+export async function writePlasmNitroCatchAllRoute(
+  projectRoot: string,
+  compiledSlots: CompiledSlotMap = {},
+): Promise<string> {
+  const routesDir = plasmNitroRoutesDir(projectRoot);
+  await mkdir(routesDir, { recursive: true });
+  const routePath = path.join(routesDir, "[[path]].ts");
+
+  const slotImports = Object.entries(compiledSlots)
+    .map(([relFromAgent, projectRelOut]) => {
+      const id = slotImportId(relFromAgent);
+      const importPath = `../../../${projectRelOut.replace(/\\/g, "/")}`;
+      return `import __slot_${id} from "${importPath}";`;
+    })
+    .join("\n");
+
+  const slotEntries = Object.keys(compiledSlots)
+    .map((relFromAgent) => {
+      const id = slotImportId(relFromAgent);
+      return `  ${JSON.stringify(relFromAgent)}: __slot_${id},`;
+    })
+    .join("\n");
+
+  const preloadBlock =
+    Object.keys(compiledSlots).length > 0
+      ? `
+${slotImports}
+
+(globalThis as typeof globalThis & {
+  __PLASM_PRELOADED_SLOTS?: Record<string, unknown>;
+}).__PLASM_PRELOADED_SLOTS = {
+${slotEntries}
+};
+`
+      : "";
+
+  const source = `import path from "node:path";
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import agentDefinition from "../../../agent/agent.js";
+import { createPlasmApp, vercelPlasmHandler } from "@plasm_lang/vercel-agent/server";
+
+import "../../../agent/instrumentation.js";
+${preloadBlock}
+const agentRoot = path.join(process.cwd(), "agent");
+
+let appPromise: ReturnType<typeof createPlasmApp> | undefined;
+
+async function plasmApp() {
+  appPromise ??= createPlasmApp({
+    agentRoot,
+    definition: agentDefinition,
+    mode: "prod",
+    sessions: false,
+  });
+  return appPromise;
+}
+
+/** Nitro wraps routes with \`toEventHandler\` — node req/res live on \`event.node\`. */
+type NitroNodeEvent = {
+  node: { req: IncomingMessage; res: ServerResponse };
+};
+
+export default async (event: NitroNodeEvent) => {
+  const app = await plasmApp();
+  const { req, res } = event.node;
+  await new Promise<void>((resolve, reject) => {
+    res.once("finish", () => resolve());
+    res.once("error", reject);
+    void vercelPlasmHandler(app)(req, res).catch(reject);
+  });
+};
+`;
+  await writeFile(routePath, source, "utf8");
+  return routePath;
+}