@plasm_lang/vercel-agent 0.3.63

package/src/authoring/subagent-loader.ts

@@ -0,0 +1,121 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import {
+  createAgentFromDefinition,
+  defineAgent,
+  type AgentDefinition,
+} from "../define-agent.js";
+import type { ProjectDiscovery, DiscoveryDiagnostic } from "../discovery/project-walker.js";
+import type { PlasmAgent } from "../runtime/plasm-agent.js";
+import type { LoadedProjectSlots } from "./slot-loader.js";
+
+export interface LoadedSubagent {
+  name: string;
+  agentRoot: string;
+  sourcePath: string;
+  definition: AgentDefinition;
+  agent: PlasmAgent;
+}
+
+export interface SubagentRegistry {
+  list(): LoadedSubagent[];
+  get(name: string): LoadedSubagent | undefined;
+  delegate(name: string, message: string): Promise<{ text: string; steps: number }>;
+}
+
+export interface LoadSubagentsOptions {
+  discovery: ProjectDiscovery;
+  parentSlots?: LoadedProjectSlots;
+  tenantScope?: string;
+  maxSteps?: number;
+  telemetry?: boolean;
+  importCacheBust?: number;
+}
+
+function isAgentDefinition(value: unknown): value is AgentDefinition {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as AgentDefinition).model === "string"
+  );
+}
+
+export async function loadSubagents(
+  options: LoadSubagentsOptions,
+): Promise<{ subagents: LoadedSubagent[]; diagnostics: DiscoveryDiagnostic[] }> {
+  const cacheBust = options.importCacheBust ?? Date.now();
+  const diagnostics: DiscoveryDiagnostic[] = [];
+  const subagents: LoadedSubagent[] = [];
+
+  for (const entry of options.discovery.subagents) {
+    try {
+      const url = `${pathToFileURL(entry.agentPath).href}?t=${cacheBust}`;
+      const mod = await import(url);
+      const exported = mod.default ?? mod;
+      if (!isAgentDefinition(exported)) {
+        diagnostics.push({
+          level: "error",
+          slot: "subagents",
+          path: entry.agentPath,
+          message: "agent.ts default export must be defineAgent() result",
+        });
+        continue;
+      }
+
+      const agent = await createAgentFromDefinition(exported, {
+        agentRoot: entry.path,
+        tenantScope: options.tenantScope,
+        maxSteps: options.maxSteps,
+        telemetry: options.telemetry,
+        loadedSlots: options.parentSlots,
+      });
+
+      subagents.push({
+        name: entry.name,
+        agentRoot: entry.path,
+        sourcePath: entry.agentPath,
+        definition: exported,
+        agent,
+      });
+    } catch (err) {
+      diagnostics.push({
+        level: "error",
+        slot: "subagents",
+        path: entry.agentPath,
+        message: `failed to load subagent: ${String(err)}`,
+      });
+    }
+  }
+
+  subagents.sort((a, b) => a.name.localeCompare(b.name));
+  return { subagents, diagnostics };
+}
+
+export function createSubagentRegistry(subagents: LoadedSubagent[]): SubagentRegistry {
+  const byName = new Map(subagents.map((s) => [s.name, s]));
+  return {
+    list: () => [...subagents],
+    get: (name: string) => byName.get(name),
+    async delegate(name: string, message: string) {
+      const sub = byName.get(name);
+      if (!sub) {
+        throw new Error(`unknown subagent: ${name}`);
+      }
+      const result = await sub.agent.generate(message);
+      return { text: result.text, steps: result.steps.length };
+    },
+  };
+}
+
+export function summarizeSubagents(
+  subagents: LoadedSubagent[],
+  agentRoot: string,
+): Array<{ name: string; path: string; model: string }> {
+  const rel = (p: string) => path.relative(agentRoot, p);
+  return subagents.map((s) => ({
+    name: s.name,
+    path: rel(s.agentRoot),
+    model: s.definition.model,
+  }));
+}

package/src/catalog/loader.ts

@@ -0,0 +1,71 @@
+import { access, readFile, readdir, stat } from "node:fs/promises";
+import path from "node:path";
+
+import { z } from "zod";
+
+export const CatalogManifestSchema = z.object({
+  entryId: z.string(),
+  label: z.string().optional(),
+  cgsHash: z.string().optional(),
+});
+
+export type CatalogManifest = z.infer<typeof CatalogManifestSchema>;
+
+export interface LoadedCatalog {
+  rootDir: string;
+  manifest: CatalogManifest;
+}
+
+export interface CatalogLoader {
+  discover(agentRoot: string): Promise<LoadedCatalog[]>;
+}
+
+async function pathExists(p: string): Promise<boolean> {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readEntryId(catalogDir: string): Promise<string> {
+  const domainPath = path.join(catalogDir, "domain.yaml");
+  const raw = await readFile(domainPath, "utf8");
+  const match = raw.match(/^entry_id:\s*["']?([^"'\n]+)["']?/m);
+  if (match?.[1]) return match[1].trim();
+  return path.basename(catalogDir);
+}
+
+export class FilesystemCatalogLoader implements CatalogLoader {
+  async discover(agentRoot: string): Promise<LoadedCatalog[]> {
+    const catalogsDir = path.join(agentRoot, "catalogs");
+    if (!(await pathExists(catalogsDir))) {
+      return [];
+    }
+    const entries = await readdir(catalogsDir, { withFileTypes: true });
+    const loaded: LoadedCatalog[] = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+      const rootDir = path.join(catalogsDir, entry.name);
+      try {
+        const info = await stat(rootDir);
+        if (!info.isDirectory()) continue;
+      } catch {
+        continue;
+      }
+      const domainYaml = path.join(rootDir, "domain.yaml");
+      const mappingsYaml = path.join(rootDir, "mappings.yaml");
+      if (!(await pathExists(domainYaml)) || !(await pathExists(mappingsYaml))) {
+        continue;
+      }
+      const entryId = await readEntryId(rootDir);
+      loaded.push({
+        rootDir,
+        manifest: { entryId, label: entry.name },
+      });
+    }
+    loaded.sort((a, b) => a.manifest.entryId.localeCompare(b.manifest.entryId));
+    return loaded;
+  }
+}

package/src/cli/build.ts

@@ -0,0 +1,54 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+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";
+
+export interface PlasmBuildResult {
+  stubsDir: string;
+  discoveryDir: string;
+  manifestPath: string;
+  stubs: Array<{ entryId: string; catalogCgsHash: string; outPath: string }>;
+}
+
+export async function runPlasmBuild(project: ResolvedAgentProject): Promise<PlasmBuildResult> {
+  const stubs = await generateAllStubs(project.agentRoot);
+  const discovery = await walkAgentProject(project.agentRoot);
+  const discoveryDir = path.join(project.agentRoot, ".plasm", "discovery");
+  await mkdir(discoveryDir, { recursive: true });
+  const manifestPath = path.join(discoveryDir, "manifest.json");
+  const native = isNativeEngineAvailable();
+  const manifest = {
+    builtAt: new Date().toISOString(),
+    projectRoot: project.projectRoot,
+    agentRoot: project.agentRoot,
+    stubs: stubs.map((s) => ({
+      entryId: s.entryId,
+      catalogCgsHash: s.catalogCgsHash,
+      outPath: path.relative(project.projectRoot, s.outPath),
+    })),
+    discovery: {
+      agentRoot: discovery.agentRoot,
+      catalogs: discovery.catalogs,
+      skills: discovery.skills,
+      channels: discovery.channels,
+      schedules: discovery.schedules,
+      hooks: discovery.hooks,
+      subagents: discovery.subagents,
+      diagnostics: discovery.diagnostics,
+    },
+    engine: {
+      native,
+      mode: native ? "napi" : "stub",
+    },
+  };
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+  return {
+    stubsDir: path.join(project.agentRoot, ".plasm", "stubs"),
+    discoveryDir,
+    manifestPath,
+    stubs,
+  };
+}

package/src/cli/dev.ts

@@ -0,0 +1,60 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import type { ResolvedAgentProject } from "./project-root.js";
+import { startDevServer, type DevServerHandle } from "../dev/server.js";
+
+export interface StartDevServerForProjectOptions {
+  project: ResolvedAgentProject;
+  port?: number;
+  host?: string;
+  tenantScope?: string;
+  maxSteps?: number;
+  telemetry?: boolean;
+  /** `auto` attaches TUI when stdin is a TTY. Pass `false` for headless server only. */
+  tui?: boolean | "auto";
+}
+
+function shouldAttachTui(tui?: boolean | "auto"): boolean {
+  if (tui === false) return false;
+  if (tui === true) return true;
+  return Boolean(process.stdin.isTTY && !process.env.PLASM_DEV_NO_TUI);
+}
+
+export async function startDevServerForProject(
+  options: StartDevServerForProjectOptions,
+): Promise<DevServerHandle> {
+  const agentModule = path.join(options.project.agentRoot, "agent.ts");
+  const mod = await import(pathToFileURL(agentModule).href);
+  const definition = mod.default;
+  if (!definition) {
+    throw new Error(`No default export in ${agentModule}`);
+  }
+
+  const handle = await startDevServer({
+    agentRoot: options.project.agentRoot,
+    definition,
+    port: options.port ?? Number(process.env.PORT ?? 3000),
+    host: options.host ?? process.env.PLASM_DEV_HOST ?? "127.0.0.1",
+    tenantScope: options.tenantScope ?? process.env.PLASM_TENANT_SCOPE ?? "local",
+    maxSteps: options.maxSteps ?? 20,
+    telemetry: options.telemetry ?? process.env.PLASM_AGENT_TELEMETRY !== "0",
+  });
+
+  if (shouldAttachTui(options.tui)) {
+    const { runDevTui } = await import("../dev/client/repl.js");
+    await runDevTui({ baseUrl: handle.url });
+    await handle.close();
+    process.exit(0);
+  }
+
+  return handle;
+}
+
+export function installDevServerShutdown(handle: DevServerHandle): void {
+  for (const signal of ["SIGINT", "SIGTERM"] as const) {
+    process.on(signal, () => {
+      void handle.close().finally(() => process.exit(0));
+    });
+  }
+}

package/src/cli/info.ts

@@ -0,0 +1,12 @@
+export {
+  collectProjectInfo,
+  collectProjectInfo as collectPlasmInfo,
+  formatPlasmInfoHuman,
+  FRAMEWORK_NAME,
+  FRAMEWORK_VERSION,
+  PLASM_LANGUAGE_TOOLS,
+  type CatalogInfoEntry,
+  type CollectProjectInfoOptions,
+  type ProjectInfoPayload,
+  type ProjectInfoRoutes,
+} from "../project-info.js";

package/src/cli/init.ts

@@ -0,0 +1,372 @@
+import { access, cp, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { FRAMEWORK_VERSION } from "../project-info.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 };
+}
+
+const AGENT_TS = `import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { createAgentFromProject, defineAgent } from "@plasm_lang/vercel-agent";
+import { loadAgentEnv } from "@plasm_lang/vercel-agent";
+
+loadAgentEnv();
+
+const agentRoot = path.dirname(fileURLToPath(import.meta.url));
+
+const agentDefinition = defineAgent({
+  model: process.env.PLASM_AGENT_MODEL ?? "anthropic/claude-sonnet-4.6",
+  compaction: { thresholdPercent: 0.75 },
+  experimental: { skills: true },
+});
+
+export default agentDefinition;
+
+export async function createPlasmAgent() {
+  return createAgentFromProject(agentDefinition, {
+    agentRoot,
+    tenantScope: process.env.PLASM_TENANT_SCOPE ?? "local",
+    maxSteps: 20,
+    telemetry: process.env.PLASM_AGENT_TELEMETRY !== "0",
+  });
+}
+`;
+
+const INSTRUCTIONS_MD = `# Catalog-native Plasm agent
+
+Use **discover_capabilities → plasm_context → plasm → plasm_run** for catalog-backed work.
+Keep one stable \`intent\` per user goal.
+`;
+
+const DOMAIN_YAML = `version: 1
+auth:
+  scheme: none
+http_backend: http://example.test
+entities:
+  Item:
+    id_field: id
+    description: Starter entity
+    fields:
+      id:
+        required: true
+        value_ref: nv_item_id
+      name:
+        required: false
+        value_ref: nv_item_name
+    relations: {}
+capabilities:
+  item_list:
+    description: List items
+    kind: query
+    entity: Item
+    provides:
+    - id
+    - name
+values:
+  nv_item_id:
+    type: string
+    string_semantics: short
+  nv_item_name:
+    type: string
+    string_semantics: short
+`;
+
+const MAPPINGS_YAML = `version: 1
+capabilities:
+  item_list:
+    transport:
+      kind: http
+      method: GET
+      path: /items
+`;
+
+const ENV_EXAMPLE = `# Vercel AI Gateway (run \`plasm-agent link\` to pull from a linked project)
+AI_GATEWAY_API_KEY=
+
+# Vercel Cron auth (production)
+CRON_SECRET=
+
+# Durable state on Vercel (optional locally)
+KV_REST_API_URL=
+KV_REST_API_TOKEN=
+BLOB_READ_WRITE_TOKEN=
+PLASM_STATE_BACKEND=kv
+PLASM_ARCHIVE_BACKEND=vercel
+
+# Optional overrides
+PLASM_AGENT_MODEL=anthropic/claude-sonnet-4.6
+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,
+): Promise<ResolvedAgentProject> {
+  if (options?.template) {
+    return runTemplateInit(targetDir, options.template);
+  }
+
+  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}`);
+  }
+
+  await mkdir(path.join(agentRoot, "catalogs", "starter"), { recursive: true });
+  await mkdir(path.join(agentRoot, "skills"), { recursive: true });
+  await mkdir(path.join(agentRoot, "channels"), { recursive: true });
+  await mkdir(path.join(agentRoot, "schedules"), { recursive: true });
+  await mkdir(path.join(agentRoot, "hooks"), { recursive: true });
+  await mkdir(path.join(projectRoot, "evals"), { recursive: true });
+
+  await writeFile(path.join(agentRoot, "agent.ts"), AGENT_TS, "utf8");
+  await writeFile(path.join(agentRoot, "instructions.md"), INSTRUCTIONS_MD, "utf8");
+  await writeFile(path.join(agentRoot, "catalogs", "starter", "domain.yaml"), DOMAIN_YAML, "utf8");
+  await writeFile(path.join(agentRoot, "catalogs", "starter", "mappings.yaml"), MAPPINGS_YAML, "utf8");
+  await writeFile(path.join(projectRoot, ".env.example"), ENV_EXAMPLE, "utf8");
+
+  if (!(await exists(path.join(projectRoot, "package.json")))) {
+    await writeFile(
+      path.join(projectRoot, "package.json"),
+      `${JSON.stringify(packageJsonScaffold(), null, 2)}\n`,
+      "utf8",
+    );
+    await patchBootstrapPackageJson(projectRoot, plasmAgentPackageRoot());
+  }
+
+  await writeVercelScaffold(projectRoot);
+
+  return { projectRoot, agentRoot };
+}
+
+export function formatInitSuccess(
+  project: ResolvedAgentProject,
+  options?: InitOptions,
+): string {
+  if (options?.template === "mcp-radar") {
+    return [
+      `Initialized MCP Radar agent from template at ${project.projectRoot}`,
+      "",
+      "Next:",
+      `  cd ${project.projectRoot}`,
+      "  npm install",
+      "  plasm-agent link          # pull AI_GATEWAY_API_KEY from Vercel",
+      "  plasm-agent build",
+      "  npm run smoke:channel",
+      "  plasm-agent dev           # local dev server + TUI",
+      "  vercel deploy             # production (channels + cron)",
+    ].join("\n");
+  }
+
+  return [
+    `Initialized Plasm agent project at ${project.projectRoot}`,
+    "",
+    "Next:",
+    `  cd ${project.projectRoot}`,
+    "  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)",
+    "  vercel deploy         # production on Vercel",
+  ].join("\n");
+}