@plasm_lang/vercel-agent 0.3.63

package/src/state/define-state.ts

@@ -0,0 +1,57 @@
+import type { AgentWorkflowWorldDefinition } from "../define-agent.js";
+import type { SymbolRegistrySnapshot } from "../symbol-registry.js";
+import type { AgentSessionState, SessionStore } from "../session-state.js";
+import { FsStateAdapter } from "./fs-state-adapter.js";
+import { KvStateAdapter } from "./kv-state-adapter.js";
+import { PostgresStateAdapter } from "./postgres-state-adapter.js";
+
+export type StateBackend = "fs" | "kv" | "postgres";
+
+export interface AgentStateStore extends SessionStore {
+  backend(): StateBackend;
+  getSymbolRegistry(tenantId: string): Promise<SymbolRegistrySnapshot | null>;
+  putSymbolRegistry(tenantId: string, snapshot: SymbolRegistrySnapshot): Promise<void>;
+}
+
+export function resolveStateBackend(
+  world?: AgentWorkflowWorldDefinition,
+): StateBackend {
+  const explicit = process.env.PLASM_STATE_BACKEND?.trim().toLowerCase();
+  if (explicit === "fs" || explicit === "kv" || explicit === "postgres") {
+    return explicit;
+  }
+  if (process.env.KV_REST_API_URL?.trim() || process.env.PLASM_KV_REST_API_URL?.trim()) {
+    return "kv";
+  }
+  if (
+    process.env.WORKFLOW_POSTGRES_URL?.trim() ||
+    process.env.DATABASE_URL?.trim() ||
+    process.env.PLASM_STATE_POSTGRES_URL?.trim()
+  ) {
+    if (world?.type === "postgres") return "postgres";
+    if (!world?.type && process.env.PLASM_STATE_BACKEND?.trim() === "postgres") {
+      return "postgres";
+    }
+  }
+  if (world?.type === "kv") return "kv";
+  if (world?.type === "postgres") return "postgres";
+  return "fs";
+}
+
+export function createAgentStateStore(options: {
+  agentRoot: string;
+  tenantScope?: string;
+  backend?: StateBackend;
+  world?: AgentWorkflowWorldDefinition;
+}): AgentStateStore {
+  const backend = options.backend ?? resolveStateBackend(options.world);
+  const tenantScope = options.tenantScope ?? "local";
+  switch (backend) {
+    case "kv":
+      return new KvStateAdapter(options.agentRoot, tenantScope);
+    case "postgres":
+      return new PostgresStateAdapter(tenantScope);
+    default:
+      return new FsStateAdapter(options.agentRoot, tenantScope);
+  }
+}

package/src/state/fs-state-adapter.ts

@@ -0,0 +1,72 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import type { SymbolRegistrySnapshot } from "../symbol-registry.js";
+import {
+  LocalSessionStore,
+  type AgentSessionState,
+} from "../session-state.js";
+import type { AgentStateStore, StateBackend } from "./define-state.js";
+
+function intentKey(intent: string): string {
+  return Buffer.from(intent, "utf8").toString("base64url");
+}
+
+export class FsStateAdapter implements AgentStateStore {
+  private readonly sessions: LocalSessionStore;
+
+  constructor(
+    private readonly agentRoot: string,
+    private readonly tenantScope: string,
+  ) {
+    this.sessions = new LocalSessionStore(agentRoot);
+  }
+
+  backend(): StateBackend {
+    return "fs";
+  }
+
+  async get(intent: string): Promise<AgentSessionState | null> {
+    return this.sessions.get(intent);
+  }
+
+  async put(state: AgentSessionState): Promise<void> {
+    await this.sessions.put(state);
+  }
+
+  async listIntents(): Promise<string[]> {
+    return this.sessions.listIntents();
+  }
+
+  private symbolsPath(): string {
+    return path.join(this.agentRoot, ".plasm", "symbols.json");
+  }
+
+  async getSymbolRegistry(tenantId: string): Promise<SymbolRegistrySnapshot | null> {
+    void tenantId;
+    try {
+      const raw = await readFile(this.symbolsPath(), "utf8");
+      return JSON.parse(raw) as SymbolRegistrySnapshot;
+    } catch {
+      return null;
+    }
+  }
+
+  async putSymbolRegistry(
+    tenantId: string,
+    snapshot: SymbolRegistrySnapshot,
+  ): Promise<void> {
+    void tenantId;
+    const file = this.symbolsPath();
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, JSON.stringify(snapshot, null, 2), "utf8");
+  }
+}
+
+export function sessionKvKey(tenantId: string, intent: string): string {
+  return `plasm:${tenantId}:session:${intentKey(intent)}`;
+}
+
+export function symbolsKvKey(tenantId: string): string {
+  return `plasm:${tenantId}:symbols`;
+}

package/src/state/kv-state-adapter.ts

@@ -0,0 +1,62 @@
+import type { SymbolRegistrySnapshot } from "../symbol-registry.js";
+import type { AgentSessionState } from "../session-state.js";
+import type { AgentStateStore, StateBackend } from "./define-state.js";
+import { sessionKvKey, symbolsKvKey } from "./fs-state-adapter.js";
+
+type KvClient = {
+  get<T>(key: string): Promise<T | null>;
+  set(key: string, value: unknown): Promise<unknown>;
+  keys(pattern: string): Promise<string[]>;
+};
+
+async function loadKv(): Promise<KvClient> {
+  const mod = await import("@vercel/kv");
+  return mod.kv as KvClient;
+}
+
+export class KvStateAdapter implements AgentStateStore {
+  constructor(
+    private readonly agentRoot: string,
+    private readonly tenantScope: string,
+  ) {
+    void this.agentRoot;
+  }
+
+  backend(): StateBackend {
+    return "kv";
+  }
+
+  async get(intent: string): Promise<AgentSessionState | null> {
+    const kv = await loadKv();
+    return kv.get<AgentSessionState>(sessionKvKey(this.tenantScope, intent));
+  }
+
+  async put(state: AgentSessionState): Promise<void> {
+    const kv = await loadKv();
+    await kv.set(sessionKvKey(this.tenantScope, state.intent), state);
+  }
+
+  async listIntents(): Promise<string[]> {
+    const kv = await loadKv();
+    const keys = await kv.keys(`plasm:${this.tenantScope}:session:*`);
+    const intents: string[] = [];
+    for (const key of keys) {
+      const state = await kv.get<AgentSessionState>(key);
+      if (state?.intent) intents.push(state.intent);
+    }
+    return intents;
+  }
+
+  async getSymbolRegistry(tenantId: string): Promise<SymbolRegistrySnapshot | null> {
+    const kv = await loadKv();
+    return kv.get<SymbolRegistrySnapshot>(symbolsKvKey(tenantId));
+  }
+
+  async putSymbolRegistry(
+    tenantId: string,
+    snapshot: SymbolRegistrySnapshot,
+  ): Promise<void> {
+    const kv = await loadKv();
+    await kv.set(symbolsKvKey(tenantId), snapshot);
+  }
+}

package/src/state/postgres-state-adapter.ts

@@ -0,0 +1,116 @@
+import type { SymbolRegistrySnapshot } from "../symbol-registry.js";
+import type { AgentSessionState } from "../session-state.js";
+import type { AgentStateStore, StateBackend } from "./define-state.js";
+
+function postgresUrl(): string {
+  return (
+    process.env.PLASM_STATE_POSTGRES_URL?.trim() ||
+    process.env.WORKFLOW_POSTGRES_URL?.trim() ||
+    process.env.DATABASE_URL?.trim() ||
+    ""
+  );
+}
+
+const SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS plasm_agent_state (
+  tenant_id TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  state_key TEXT NOT NULL,
+  payload JSONB NOT NULL,
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (tenant_id, kind, state_key)
+);
+`;
+
+type PgPool = {
+  query(sql: string, params?: unknown[]): Promise<{ rows: Array<Record<string, unknown>> }>;
+  end(): Promise<void>;
+};
+
+let sharedPool: PgPool | null = null;
+
+async function pool(): Promise<PgPool> {
+  if (sharedPool) return sharedPool;
+  const url = postgresUrl();
+  if (!url) {
+    throw new Error(
+      "Postgres state backend requires PLASM_STATE_POSTGRES_URL, WORKFLOW_POSTGRES_URL, or DATABASE_URL",
+    );
+  }
+  const pg = await import("pg");
+  const Pool = pg.default?.Pool ?? pg.Pool;
+  sharedPool = new Pool({ connectionString: url }) as PgPool;
+  await sharedPool.query(SCHEMA_SQL);
+  return sharedPool;
+}
+
+function intentKey(intent: string): string {
+  return Buffer.from(intent, "utf8").toString("base64url");
+}
+
+export class PostgresStateAdapter implements AgentStateStore {
+  constructor(private readonly tenantScope: string) {}
+
+  backend(): StateBackend {
+    return "postgres";
+  }
+
+  async get(intent: string): Promise<AgentSessionState | null> {
+    const db = await pool();
+    const result = await db.query(
+      `SELECT payload FROM plasm_agent_state
+       WHERE tenant_id = $1 AND kind = 'session' AND state_key = $2`,
+      [this.tenantScope, intentKey(intent)],
+    );
+    const row = result.rows[0]?.payload;
+    return row ? (row as AgentSessionState) : null;
+  }
+
+  async put(state: AgentSessionState): Promise<void> {
+    const db = await pool();
+    await db.query(
+      `INSERT INTO plasm_agent_state (tenant_id, kind, state_key, payload, updated_at)
+       VALUES ($1, 'session', $2, $3::jsonb, NOW())
+       ON CONFLICT (tenant_id, kind, state_key)
+       DO UPDATE SET payload = EXCLUDED.payload, updated_at = NOW()`,
+      [this.tenantScope, intentKey(state.intent), JSON.stringify(state)],
+    );
+  }
+
+  async listIntents(): Promise<string[]> {
+    const db = await pool();
+    const result = await db.query(
+      `SELECT payload FROM plasm_agent_state
+       WHERE tenant_id = $1 AND kind = 'session'`,
+      [this.tenantScope],
+    );
+    return result.rows
+      .map((row) => (row.payload as AgentSessionState | undefined)?.intent)
+      .filter((intent): intent is string => Boolean(intent));
+  }
+
+  async getSymbolRegistry(tenantId: string): Promise<SymbolRegistrySnapshot | null> {
+    const db = await pool();
+    const result = await db.query(
+      `SELECT payload FROM plasm_agent_state
+       WHERE tenant_id = $1 AND kind = 'symbols' AND state_key = 'registry'`,
+      [tenantId],
+    );
+    const row = result.rows[0]?.payload;
+    return row ? (row as SymbolRegistrySnapshot) : null;
+  }
+
+  async putSymbolRegistry(
+    tenantId: string,
+    snapshot: SymbolRegistrySnapshot,
+  ): Promise<void> {
+    const db = await pool();
+    await db.query(
+      `INSERT INTO plasm_agent_state (tenant_id, kind, state_key, payload, updated_at)
+       VALUES ($1, 'symbols', 'registry', $2::jsonb, NOW())
+       ON CONFLICT (tenant_id, kind, state_key)
+       DO UPDATE SET payload = EXCLUDED.payload, updated_at = NOW()`,
+      [tenantId, JSON.stringify(snapshot)],
+    );
+  }
+}

package/src/stubs/capability-invoke-shape.ts

@@ -0,0 +1,135 @@
+import type {
+  CapabilityIntrospectionJson,
+  InputFieldSchemaJson,
+  InputTypeJson,
+} from "./catalog-introspection.js";
+
+export type CapabilityInvokeShape =
+  | "RootQuery"
+  | "ScopedQuery"
+  | "GetById"
+  | "SearchText"
+  | "SearchFiltered"
+  | "RootCreate"
+  | "ScopedUpdate"
+  | "ScopedAction"
+  | "ScopedDelete"
+  | "MethodObject"
+  | "MethodUnion";
+
+export function inputTypeRoot(input: InputTypeJson | undefined): InputTypeJson | undefined {
+  return input;
+}
+
+export function objectFieldsFromCap(
+  cap: CapabilityIntrospectionJson,
+): InputFieldSchemaJson[] {
+  const schema = cap.input_schema?.input_type;
+  if (!schema || schema.type !== "object") return [];
+  return schema.fields ?? [];
+}
+
+function hasScopeOrFilterParams(fields: InputFieldSchemaJson[]): boolean {
+  return fields.some((f) => {
+    const role = f.role ?? "filter";
+    return role === "scope" || role === "filter";
+  });
+}
+
+function searchParam(fields: InputFieldSchemaJson[]): InputFieldSchemaJson | undefined {
+  return fields.find((f) => (f.role ?? "filter") === "search") ?? fields[0];
+}
+
+function nonSearchParams(fields: InputFieldSchemaJson[]): InputFieldSchemaJson[] {
+  const search = searchParam(fields);
+  return fields.filter((f) => f !== search);
+}
+
+export function classifyInvokeShape(cap: CapabilityIntrospectionJson): CapabilityInvokeShape {
+  const kind = cap.kind.toLowerCase();
+  const inputType = cap.input_schema?.input_type;
+
+  if (inputType?.type === "union") {
+    return "MethodUnion";
+  }
+
+  const fields = objectFieldsFromCap(cap);
+
+  switch (kind) {
+    case "query":
+      return hasScopeOrFilterParams(fields) ? "ScopedQuery" : "RootQuery";
+    case "get":
+      return "GetById";
+    case "search": {
+      const extra = nonSearchParams(fields);
+      return extra.length > 0 ? "SearchFiltered" : "SearchText";
+    }
+    case "create":
+      return "RootCreate";
+    case "update":
+      return "ScopedUpdate";
+    case "action":
+      return "ScopedAction";
+    case "delete":
+      return "ScopedDelete";
+    default:
+      return "MethodObject";
+  }
+}
+
+export function capabilityReturnsVoid(cap: CapabilityIntrospectionJson): boolean {
+  if (cap.output_schema?.type === "side_effect") return true;
+  if (cap.kind.toLowerCase() === "delete" && cap.provides.length === 0) return true;
+  return false;
+}
+
+export function capabilityReturnsScalar(cap: CapabilityIntrospectionJson): boolean {
+  const kind = cap.kind.toLowerCase();
+  return kind === "get";
+}
+
+export function capabilityNeedsInput(
+  cap: CapabilityIntrospectionJson,
+  shape: CapabilityInvokeShape,
+  idField?: string,
+): boolean {
+  if (shape === "RootQuery") return false;
+  if (shape === "GetById" || shape === "ScopedUpdate" || shape === "ScopedAction" || shape === "ScopedDelete") {
+    return true;
+  }
+  const fields = objectFieldsFromCap(cap);
+  if (fields.length > 0) return true;
+  if (shape === "ScopedQuery" || shape === "SearchText" || shape === "SearchFiltered") {
+    return fields.some((f) => f.required);
+  }
+  void idField;
+  return false;
+}
+
+/** Body fields for dotted-arg emission (excludes scoped receiver id). */
+export function invokeBodyFields(
+  cap: CapabilityIntrospectionJson,
+  shape: CapabilityInvokeShape,
+  entityIdField: string,
+): InputFieldSchemaJson[] {
+  const fields = objectFieldsFromCap(cap);
+  switch (shape) {
+    case "GetById":
+    case "ScopedUpdate":
+    case "ScopedAction":
+    case "ScopedDelete":
+      return fields.filter((f) => f.name !== entityIdField);
+    case "SearchText":
+    case "SearchFiltered": {
+      const search = searchParam(fields);
+      return fields.filter((f) => f !== search);
+    }
+    default:
+      return fields;
+  }
+}
+
+export function searchFieldName(cap: CapabilityIntrospectionJson): string | undefined {
+  const fields = objectFieldsFromCap(cap);
+  return searchParam(fields)?.name;
+}

package/src/stubs/catalog-client.ts

@@ -0,0 +1,170 @@
+import type { HostTransportFn } from "../engine/napi-binding.js";
+import { createProductionHostTransport } from "../engine/create-host-transport.js";
+import {
+  createEngine,
+  type DryRunResult,
+  type PlasmEngine,
+} from "../engine/napi-binding.js";
+import { createDefaultHostTransport } from "../engine/host-transport.js";
+import { createFixtureMockTransport } from "../engine/fixture-mock-transport.js";
+import type { ProgramBuilder, ProgramBuilderOptions } from "./program-builder.js";
+import { createProgramBuilder } from "./program-builder.js";
+
+export interface CatalogClientOptions extends ProgramBuilderOptions {
+  engine?: PlasmEngine;
+  intent?: string;
+  transport?: HostTransportFn;
+}
+
+export interface StubInvokeOptions {
+  transport?: HostTransportFn;
+  engine?: PlasmEngine;
+}
+
+const sessionInit = new WeakMap<ProgramBuilder, Promise<void>>();
+
+/** Load catalog + register deterministic `e#` symbols for program execution (not agent teaching). */
+export async function ensureStubSession(builder: ProgramBuilder): Promise<void> {
+  const existing = sessionInit.get(builder);
+  if (existing) return existing;
+
+  const task = (async () => {
+    const catalogRoot = builder.catalogRoot;
+    const engine = builder.engine ?? createEngine();
+    if (catalogRoot) {
+      await engine.loadCatalog({
+        rootDir: catalogRoot,
+        manifest: { entryId: builder.entryId },
+      });
+    }
+    const entities = [...(builder.stubEntities ?? [])].sort((a, b) => a.localeCompare(b));
+    if (!entities.length) return;
+    await engine.synthesizeTeaching(
+      "",
+      entities.map((entity) => ({ api: builder.entryId, entity })),
+    );
+  })();
+  sessionInit.set(builder, task);
+  return task;
+}
+
+/** @deprecated Use {@link ensureStubSession}. */
+export async function ensureCatalogLoaded(builder: ProgramBuilder): Promise<void> {
+  return ensureStubSession(builder);
+}
+
+export function createCatalogClient(options: CatalogClientOptions): ProgramBuilder {
+  return createProgramBuilder({
+    entryId: options.entryId,
+    cgsHash: options.cgsHash,
+    engine: options.engine ?? createEngine(),
+    logicalSessionRef: options.logicalSessionRef,
+    agentSessionId: options.agentSessionId,
+    catalogRoot: options.catalogRoot,
+    stubEntities: options.stubEntities,
+  });
+}
+
+export interface ExecuteRowsResult<TRow> {
+  planCommitRef: string;
+  summary: string;
+  rows: TRow[];
+}
+
+/** Plasm string literal from a TypeScript string (safe quoting). */
+export function plasmLiteral(value: string): string {
+  return JSON.stringify(value);
+}
+
+/** Plasm numeric literal from a TypeScript number. */
+export function plasmNumber(value: number | undefined): string {
+  if (value === undefined || Number.isNaN(value)) return "0";
+  return String(value);
+}
+
+/** Plasm boolean literal. */
+export function plasmBoolean(value: boolean | undefined): string {
+  return value ? "true" : "false";
+}
+
+export interface DottedArgSpec {
+  key: string;
+  value: unknown;
+  kind?: "literal" | "number" | "boolean" | "select";
+  optional?: boolean;
+}
+
+/** Build `key=value` dotted arg list for Plasm invoke (omits undefined optional keys). */
+export function buildDottedArgs(specs: DottedArgSpec[]): string {
+  const parts: string[] = [];
+  for (const { key, value, kind = "literal", optional } of specs) {
+    if (optional && value === undefined) continue;
+    const emit =
+      kind === "number"
+        ? plasmNumber(value as number)
+        : kind === "boolean"
+          ? plasmBoolean(value as boolean)
+          : plasmLiteral(String(value ?? ""));
+    parts.push(`${key}=${emit}`);
+  }
+  return parts.join(", ");
+}
+
+function parseRowsJson<TRow>(rowsJson: string | undefined): TRow[] {
+  if (!rowsJson?.trim()) return [];
+  const parsed = JSON.parse(rowsJson) as unknown;
+  if (Array.isArray(parsed)) return parsed as TRow[];
+  if (parsed && typeof parsed === "object" && Array.isArray((parsed as { results?: unknown }).results)) {
+    return (parsed as { results: TRow[] }).results;
+  }
+  return [];
+}
+
+function extractRowsFromLive(live: {
+  rowsJson?: string;
+  message?: string;
+}): unknown[] {
+  if (live.rowsJson) {
+    return parseRowsJson(live.rowsJson);
+  }
+  return [];
+}
+
+/** Dry-run then live-execute a program; parse entity rows from NAPI output. */
+export async function executeRows<TRow>(
+  builder: ProgramBuilder,
+  program: string,
+  options?: StubInvokeOptions,
+): Promise<ExecuteRowsResult<TRow>> {
+  await ensureStubSession(builder);
+  const bound = builder.program(program);
+  const dry: DryRunResult = await bound.dryRun();
+  const transport =
+    options?.transport ??
+    (process.env.PLASM_STUB_USE_MOCK_TRANSPORT === "1"
+      ? createFixtureMockTransport()
+      : createProductionHostTransport());
+
+  if (typeof bound.run !== "function") {
+    throw new Error("executeRows: program builder missing run()");
+  }
+  const live = (await bound.run(dry.planCommitRef, transport)) as {
+    rowsJson?: string;
+    message?: string;
+  };
+  const rows = extractRowsFromLive(live) as TRow[];
+  return {
+    planCommitRef: dry.planCommitRef,
+    summary: dry.summary,
+    rows,
+  };
+}
+
+/** Dry-run only — plan review without live HTTP. */
+export async function dryRunProgram(
+  builder: ProgramBuilder,
+  program: string,
+): Promise<DryRunResult> {
+  await ensureStubSession(builder);
+  return builder.program(program).dryRun();
+}

package/src/stubs/catalog-hash.ts

@@ -0,0 +1,11 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { computeCatalogCgsHash } from "./generator.js";
+
+/** Live CGS digest from authored `domain.yaml` + `mappings.yaml` on disk. */
+export async function resolveCatalogLiveHash(catalogDir: string): Promise<string> {
+  const domainYaml = await readFile(path.join(catalogDir, "domain.yaml"), "utf8");
+  const mappingsYaml = await readFile(path.join(catalogDir, "mappings.yaml"), "utf8");
+  return computeCatalogCgsHash(domainYaml, mappingsYaml);
+}