@plasm_lang/vercel-agent 0.3.63

package/agent/.plasm/stubs/execute_tiny.ts

@@ -0,0 +1,107 @@
+/** @generated catalog_cgs_hash=aee3d865ff02b2ac8f0c168915a63dfe8f57c87f00fab3e03c87fcec72f5eb84 entry_id=execute_tiny generated_at=2026-06-21T20:30:39.128Z */
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  createCatalogClient,
+  buildDottedArgs,
+  executeRows,
+  plasmBoolean,
+  plasmLiteral,
+  plasmNumber,
+  type StubInvokeOptions,
+} from "@plasm_lang/vercel-agent";
+
+export const catalogCgsHash = "aee3d865ff02b2ac8f0c168915a63dfe8f57c87f00fab3e03c87fcec72f5eb84";
+export const entryId = "execute_tiny";
+
+const catalogRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../../catalogs/execute_tiny",
+);
+
+const stubEntities = ["Category","Product"] as const;
+
+const builder = createCatalogClient({
+  entryId,
+  cgsHash: catalogCgsHash,
+  catalogRoot,
+  stubEntities: [...stubEntities],
+});
+
+type Brand<B extends string, T> = T & { readonly __brand: B };
+export type CategoryId = Brand<"CategoryId", string>;
+export type RefCategory = CategoryId;
+export type ProductId = Brand<"ProductId", string>;
+export type RefProduct = ProductId;
+
+export type Category = {
+  id: string;
+  name?: string;
+};
+
+export type Product = {
+  id: string;
+  name?: string;
+  category_id?: string;
+};
+
+export type CategoryGetInput = {
+  id: RefCategory;
+};
+
+export type ProductGetInput = {
+  id: RefProduct;
+};
+
+export type ProductSearchInput = {
+  q: string;
+};
+
+/** category_get */
+export async function category_get(input: CategoryGetInput, options?: StubInvokeOptions): Promise<Category> {
+  const program = `e1(${plasmLiteral(input.id)})`;
+  const result = await executeRows<Category>(builder, program, options);
+  const row = result.rows[0];
+  if (!row) throw new Error("category_get: empty result");
+  return row;
+}
+
+/** product_get */
+export async function product_get(input: ProductGetInput, options?: StubInvokeOptions): Promise<Product> {
+  const program = `e2(${plasmLiteral(input.id)})`;
+  const result = await executeRows<Product>(builder, program, options);
+  const row = result.rows[0];
+  if (!row) throw new Error("product_get: empty result");
+  return row;
+}
+
+/** product_list */
+export async function product_list(options?: StubInvokeOptions): Promise<Product[]> {
+  const program = "e2";
+  const result = await executeRows<Product>(builder, program, options);
+  return result.rows;
+}
+
+/** product_search */
+export async function product_search(input: ProductSearchInput, options?: StubInvokeOptions): Promise<Product[]> {
+  const program = `e2~${plasmLiteral(input.q)}`;
+  const result = await executeRows<Product>(builder, program, options);
+  return result.rows;
+}
+
+export const execute_tiny = {
+  Category: {
+      category_get,
+    },
+  Product: {
+      product_get,
+      product_list,
+      product_search,
+    },
+  builder,
+  catalogCgsHash,
+  entryId,
+} as const;
+
+export default execute_tiny;

package/agent/agent.ts

@@ -0,0 +1,52 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  createAgentFromProject,
+  defineAgent,
+} from "../src/define-agent.js";
+import {
+  createFixtureMockTransport,
+  fixtureMockTransportEnabled,
+} from "../src/engine/fixture-mock-transport.js";
+import { createProductionHostTransport } from "../src/engine/create-host-transport.js";
+import { loadAgentEnv } from "../src/load-env.js";
+
+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,
+  },
+  modelOptions: {
+    temperature: 0.2,
+  },
+  experimental: {
+    workflow: {
+      world: {
+        type: "local",
+      },
+    },
+    skills: true,
+  },
+  build: {
+    externalDependencies: ["@plasm_lang/engine"],
+  },
+});
+
+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",
+    hostTransport: fixtureMockTransportEnabled()
+      ? createFixtureMockTransport()
+      : createProductionHostTransport(),
+  });
+}

package/agent/catalogs/README.md

@@ -0,0 +1,15 @@
+# Catalogs
+
+Author CGS (`domain.yaml`) + CML (`mappings.yaml`) here — the **single source of capability**.
+
+v1 layout: one subdirectory per API (`catalogs/<entry_id>/`).
+
+For a working example, symlink or copy from the repo-wide catalog tree:
+
+```bash
+ln -s ../../../apis/pokeapi catalogs/pokeapi
+```
+
+Catalogs are **platform-independent data** (not native cdylib plugins). The framework loads YAML/JSON and pins `catalog_cgs_hash` at session open.
+
+See `skills/plasm-authoring/` in the plasm-oss root for authoring doctrine.

package/agent/channels/execute-tiny-webhook.ts

@@ -0,0 +1,59 @@
+import { createFixtureMockTransport } from "../../src/engine/fixture-mock-transport.js";
+import { defineChannel } from "../../src/authoring/define-channel.js";
+import { dryRunProgram } from "../../src/stubs/catalog-client.js";
+
+import executeTiny from "../.plasm/stubs/execute_tiny.js";
+
+function readJsonBody(req: import("node:http").IncomingMessage): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    let body = "";
+    req.on("data", (chunk) => {
+      body += chunk;
+    });
+    req.on("end", () => {
+      if (!body.trim()) {
+        resolve({});
+        return;
+      }
+      try {
+        resolve(JSON.parse(body));
+      } catch (err) {
+        reject(err);
+      }
+    });
+    req.on("error", reject);
+  });
+}
+
+export default defineChannel({
+  name: "execute-tiny-webhook",
+  routes: [
+    {
+      method: "POST",
+      path: "/channel/execute-tiny/products",
+      handler: async (req, res) => {
+        const body = (await readJsonBody(req)) as { dryRun?: boolean };
+        const useDryRun = body.dryRun !== false;
+
+        if (useDryRun) {
+          const dry = await dryRunProgram(executeTiny.builder, "e2");
+          res.statusCode = 200;
+          res.setHeader("content-type", "application/json; charset=utf-8");
+          res.end(
+            JSON.stringify({
+              mode: "dry_run",
+              planCommitRef: dry.planCommitRef,
+            }),
+          );
+          return;
+        }
+
+        const mock = createFixtureMockTransport();
+        const rows = await executeTiny.Product.product_list({ transport: mock });
+        res.statusCode = 200;
+        res.setHeader("content-type", "application/json; charset=utf-8");
+        res.end(JSON.stringify({ mode: "live", count: rows.length, rows }));
+      },
+    },
+  ],
+});

package/agent/channels/health.ts

@@ -0,0 +1,16 @@
+import { defineChannel } from "../../src/authoring/define-channel.js";
+
+export default defineChannel({
+  name: "health",
+  routes: [
+    {
+      method: "GET",
+      path: "/channel/health",
+      handler: (_req, res) => {
+        res.statusCode = 200;
+        res.setHeader("content-type", "application/json; charset=utf-8");
+        res.end(JSON.stringify({ status: "ok", channel: "health" }));
+      },
+    },
+  ],
+});

package/agent/hooks/trace-log.ts

@@ -0,0 +1,10 @@
+import { defineHook } from "../../src/authoring/define-hook.js";
+
+export default defineHook({
+  name: "trace-log",
+  on: ["run:complete", "plan:commit"],
+  handler: (_ctx, detail) => {
+    const event = detail?.planCommitRef ? "plan:commit" : "run:complete";
+    console.log(`[plasm:hook:trace-log] ${event}`, detail ?? {});
+  },
+});

package/agent/instructions.md

@@ -0,0 +1,25 @@
+# Catalog-native Plasm agent
+
+You operate external APIs through **Plasm catalogs**, not ad-hoc REST tools.
+
+## Tool order
+
+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`).
+4. **`plasm_run`** — live execute the reviewed plan (`pcN` only — never resend the program).
+
+## Session discipline
+
+- **One user goal → one stable `intent` string → one `logical_session_ref`.**
+- Do not rotate `intent` per message (e.g. `"msg 3: sort moves"` breaks symbol reuse).
+- Copy symbols from the **left column** of teaching TSV into programs — never invent `e#` / `p#` values.
+- Federated catalogs: use opaque symbols from the table; never bare homonym wire names.
+
+## Programs
+
+- Plasm source text, not JSON.
+- Prefer bind → filter/sort/limit → few final roots.
+- Pass `binding.content` to string/message params when row-to-text templates are used.
+
+When the user asks a question, discover or extend context as needed, plan with `plasm`, then run with `plasm_run` after the plan looks correct.

package/agent/schedules/ping.ts

@@ -0,0 +1,13 @@
+import { defineSchedule } from "../../src/authoring/define-schedule.js";
+import { dryRunProgram } from "../../src/stubs/catalog-client.js";
+
+import executeTiny from "../.plasm/stubs/execute_tiny.js";
+
+export default defineSchedule({
+  name: "ping",
+  cron: "*/5 * * * *",
+  handler: async () => {
+    const dry = await dryRunProgram(executeTiny.builder, "e2");
+    console.log(`[plasm:schedule:ping] product_list dry-run ${dry.planCommitRef}`);
+  },
+});

package/agent/skills/plasm-authoring.md

@@ -0,0 +1,8 @@
+# Plasm authoring
+
+Progressive-disclosure skill for catalog-native agents.
+
+- Author capability once in `catalogs/<api>/domain.yaml` + `mappings.yaml`.
+- Run `npm run build:stubs` to emit typed clients under `.plasm/stubs/`.
+- Channels and schedules call stubs directly (deterministic program API).
+- The model loop uses `discover_capabilities` → `plasm_context` → `plasm` → `plasm_run`.

package/agent/subagents/tiny/agent.ts

@@ -0,0 +1,28 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  createAgentFromDefinition,
+  defineAgent,
+} from "../../../src/define-agent.js";
+
+const agentRoot = path.dirname(fileURLToPath(import.meta.url));
+
+const agentDefinition = defineAgent({
+  model: process.env.PLASM_AGENT_MODEL ?? "anthropic/claude-sonnet-4.6",
+  modelOptions: { temperature: 0.1 },
+  experimental: {
+    workflow: { world: { type: "local" } },
+  },
+});
+
+export default agentDefinition;
+
+export async function createTinySubagent() {
+  return createAgentFromDefinition(agentDefinition, {
+    agentRoot,
+    tenantScope: process.env.PLASM_TENANT_SCOPE ?? "local",
+    maxSteps: 10,
+    telemetry: false,
+  });
+}

package/bin/plasm-agent.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const runner = path.join(packageRoot, "scripts", "plasm-node.mjs");
+const cli = path.join(packageRoot, "scripts", "plasm-cli.ts");
+
+const child = spawn(
+  process.execPath,
+  ["--experimental-strip-types", "--experimental-transform-types", runner, cli, ...process.argv.slice(2)],
+  { stdio: "inherit", env: process.env },
+);
+
+child.on("exit", (code) => {
+  process.exit(code ?? 0);
+});

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@plasm_lang/vercel-agent",
+  "version": "0.3.63",
+  "description": "Catalog-native TypeScript agent framework (Plasm CGS/CML, Vercel AI SDK, Nitro-oriented)",
+  "license": "GPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PlasmTools/plasm-core.git",
+    "directory": "packages/plasm-agent"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./instrumentation": "./src/instrumentation.ts",
+    "./operator": "./src/operator/routes.ts",
+    "./agent": "./agent/agent.ts"
+  },
+  "bin": {
+    "plasm-agent": "./bin/plasm-agent.mjs"
+  },
+  "files": [
+    "src",
+    "bin",
+    "scripts/plasm-node.mjs",
+    "scripts/resolve-ts-extension.mjs",
+    "agent",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "plasm-agent": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/plasm-cli.ts",
+    "build:engine": "npm run build --prefix ../plasm-engine",
+    "build:stubs": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/build-stubs.ts",
+    "smoke:tools": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/smoke-agent-tools.ts",
+    "smoke:async-transport": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/smoke-async-transport.ts",
+    "smoke:operator": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/smoke-operator.ts",
+    "smoke:stubs": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/smoke-stubs.ts",
+    "smoke:stubs:matrix": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/smoke-stubs-matrix.ts",
+    "eval": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/run-evals.ts",
+    "eval:catalog": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/run-catalog-eval.ts",
+    "smoke:hot-reload": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/smoke-hot-reload.ts",
+    "smoke:sessions": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/smoke-sessions.ts",
+    "smoke:tui-async": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/smoke-tui-async.ts",
+    "smoke:bootstrap": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/smoke-bootstrap-devx.ts",
+    "smoke:vercel-handler": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/smoke-vercel-handler.ts",
+    "agent": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/run-agent.ts",
+    "dev": "node --experimental-strip-types --experimental-transform-types scripts/plasm-node.mjs scripts/dev-server.ts",
+    "plasm:dev": "npm run dev"
+  },
+  "dependencies": {
+    "@ai-sdk/otel": "^1.0.0-beta.6",
+    "@opentelemetry/api": "^1.9.0",
+    "@plasm_lang/engine": "^0.3.63",
+    "@vercel/blob": "^0.27.3",
+    "@vercel/connect": "^0.2.6",
+    "@vercel/kv": "^3.0.0",
+    "@workflow/world-postgres": "^4.2.0",
+    "ai": "^6.0.0",
+    "js-yaml": "^4.1.0",
+    "pg": "^8.22.0",
+    "workflow": "^4.5.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.9.3",
+    "@types/pg": "^8.20.0",
+    "typescript": "^5.8.2"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/scripts/plasm-node.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { register } from "node:module";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const scriptsDir = path.dirname(fileURLToPath(import.meta.url));
+
+register(pathToFileURL(path.join(scriptsDir, "resolve-ts-extension.mjs")));
+
+const entry = process.argv[2];
+if (!entry) {
+  console.error("usage: plasm-node.mjs <entry.ts> [args...]");
+  process.exit(1);
+}
+
+// Forward CLI args to the entry script (argv[0]=node, argv[1]=entry path).
+process.argv = [process.argv[0], path.resolve(process.cwd(), entry), ...process.argv.slice(3)];
+
+await import(pathToFileURL(path.resolve(process.cwd(), entry)));

package/scripts/resolve-ts-extension.mjs

@@ -0,0 +1,18 @@
+/**
+ * Resolve `.js` import specifiers to sibling `.ts` sources for no-build dev runs.
+ */
+export async function resolve(specifier, context, nextResolve) {
+  try {
+    return await nextResolve(specifier, context);
+  } catch (error) {
+    if (typeof specifier === "string" && specifier.endsWith(".js")) {
+      const tsSpecifier = `${specifier.slice(0, -3)}.ts`;
+      try {
+        return await nextResolve(tsSpecifier, context);
+      } catch {
+        // fall through
+      }
+    }
+    throw error;
+  }
+}

package/src/archive/adapters.ts

@@ -0,0 +1,27 @@
+import type { BlobArchiveAdapter, KvArchiveIndexAdapter } from "./types.js";
+
+/** Stub Blob adapter for production wiring (Vercel Blob / object_store URL). */
+export class UnimplementedBlobArchiveAdapter implements BlobArchiveAdapter {
+  async put(): Promise<void> {
+    throw new Error("BlobArchiveAdapter not configured — set PLASM_RUN_ARTIFACTS_URL in prod");
+  }
+
+  async get(): Promise<Uint8Array | null> {
+    throw new Error("BlobArchiveAdapter not configured — set PLASM_RUN_ARTIFACTS_URL in prod");
+  }
+}
+
+/** Stub KV index adapter for production archive listings. */
+export class UnimplementedKvArchiveIndexAdapter implements KvArchiveIndexAdapter {
+  async set(): Promise<void> {
+    throw new Error("KvArchiveIndexAdapter not configured");
+  }
+
+  async get(): Promise<string | null> {
+    throw new Error("KvArchiveIndexAdapter not configured");
+  }
+
+  async list(): Promise<string[]> {
+    throw new Error("KvArchiveIndexAdapter not configured");
+  }
+}

package/src/archive/index.ts

@@ -0,0 +1,99 @@
+import { LocalRunArchive } from "./local-run-archive.js";
+import { LocalTraceArchive } from "./local-trace-archive.js";
+import { resolveArchivePaths } from "./paths.js";
+import type {
+  ArchivePaths,
+  PlanArchiveSnapshot,
+  RunSnapshot,
+  TraceDetail,
+  TraceRecord,
+  TraceSummary,
+} from "./types.js";
+
+export class LocalArchiveStore {
+  readonly paths: ArchivePaths;
+  readonly traces: LocalTraceArchive;
+  readonly runs: LocalRunArchive;
+
+  constructor(agentRoot: string, paths?: ArchivePaths) {
+    this.paths = paths ?? resolveArchivePaths(agentRoot);
+    this.traces = new LocalTraceArchive(this.paths.traceRoot);
+    this.runs = new LocalRunArchive(this.paths.runRoot);
+  }
+
+  static fromAgentRoot(agentRoot: string, tenantId?: string): LocalArchiveStore {
+    void tenantId;
+    return new LocalArchiveStore(agentRoot);
+  }
+
+  async bootstrap(): Promise<void> {
+    await Promise.all([this.traces.ensureRoot(), this.runs.ensureRoot()]);
+  }
+
+  async recordToolEvent(
+    tenantId: string,
+    traceId: string,
+    kind: string,
+    name: string,
+    attributes?: Record<string, string | number | boolean>,
+  ): Promise<void> {
+    const record: TraceRecord = {
+      at_ms: Date.now(),
+      kind,
+      name,
+      attributes,
+    };
+    await this.traces.appendRecord(tenantId, traceId, record);
+  }
+
+  async finalizeTrace(detail: TraceDetail): Promise<void> {
+    await this.traces.persistTrace(detail);
+  }
+
+  async writePlanArchive(snapshot: PlanArchiveSnapshot): Promise<void> {
+    await this.runs.writePlanArchive(snapshot);
+  }
+
+  async writeRunSnapshot(snapshot: RunSnapshot): Promise<void> {
+    await this.runs.writeRunSnapshot(snapshot);
+  }
+
+  async listTraces(tenantId: string, limit?: number): Promise<TraceSummary[]> {
+    return this.traces.listTraces(tenantId, limit);
+  }
+
+  async getTrace(tenantId: string, traceId: string): Promise<TraceDetail | null> {
+    return this.traces.getTrace(tenantId, traceId);
+  }
+
+  async listPlans(limit?: number) {
+    return this.runs.listPlans(limit);
+  }
+
+  async listRuns(limit?: number) {
+    return this.runs.listRuns(limit);
+  }
+
+  async listArchives(limit?: number) {
+    const [plans, runs] = await Promise.all([this.listPlans(limit), this.listRuns(limit)]);
+    return { plans, runs, paths: this.paths };
+  }
+}
+
+export { resolveArchivePaths } from "./paths.js";
+export { computeRunId } from "./run-id.js";
+export type { RunIdBundle } from "./run-id.js";
+export {
+  UnimplementedBlobArchiveAdapter,
+  UnimplementedKvArchiveIndexAdapter,
+} from "./adapters.js";
+export type {
+  ArchivePaths,
+  BlobArchiveAdapter,
+  KvArchiveIndexAdapter,
+  PlanArchiveSnapshot,
+  RunSnapshot,
+  TraceDetail,
+  TraceRecord,
+  TraceSummary,
+} from "./types.js";