@plasm_lang/vercel-agent 0.3.63

package/src/archive/local-run-archive.ts

@@ -0,0 +1,90 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import type { PlanArchiveSnapshot, RunSnapshot } from "./types.js";
+
+function safeFilename(value: string): string {
+  if (!value || value.includes("..") || value.includes("/") || value.includes("\\")) {
+    throw new Error("invalid archive filename");
+  }
+  return value;
+}
+
+export class LocalRunArchive {
+  constructor(private readonly root: string) {}
+
+  private plansDir(): string {
+    return path.join(this.root, "plans");
+  }
+
+  private runsDir(): string {
+    return path.join(this.root, "runs");
+  }
+
+  async ensureRoot(): Promise<void> {
+    await mkdir(this.plansDir(), { recursive: true });
+    await mkdir(this.runsDir(), { recursive: true });
+  }
+
+  async writePlanArchive(snapshot: PlanArchiveSnapshot): Promise<void> {
+    await this.ensureRoot();
+    const file = path.join(this.plansDir(), `${safeFilename(snapshot.plan_commit_ref)}.json`);
+    await writeFile(file, JSON.stringify(snapshot, null, 2), "utf8");
+  }
+
+  async writeRunSnapshot(snapshot: RunSnapshot): Promise<void> {
+    await this.ensureRoot();
+    const file = path.join(this.runsDir(), `${safeFilename(snapshot.run_id)}.json`);
+    await writeFile(file, JSON.stringify(snapshot, null, 2), "utf8");
+  }
+
+  async listPlans(limit = 50): Promise<PlanArchiveSnapshot[]> {
+    return this.listJsonDir<PlanArchiveSnapshot>(this.plansDir(), limit);
+  }
+
+  async listRuns(limit = 50): Promise<RunSnapshot[]> {
+    return this.listJsonDir<RunSnapshot>(this.runsDir(), limit);
+  }
+
+  async getPlan(planCommitRef: string): Promise<PlanArchiveSnapshot | null> {
+    return this.readJson<PlanArchiveSnapshot>(
+      path.join(this.plansDir(), `${safeFilename(planCommitRef)}.json`),
+    );
+  }
+
+  async getRun(runId: string): Promise<RunSnapshot | null> {
+    return this.readJson<RunSnapshot>(
+      path.join(this.runsDir(), `${safeFilename(runId)}.json`),
+    );
+  }
+
+  private async listJsonDir<T>(dir: string, limit: number): Promise<T[]> {
+    let files: string[];
+    try {
+      files = await readdir(dir);
+    } catch {
+      return [];
+    }
+    const items: Array<{ at: string; value: T }> = [];
+    for (const file of files.filter((f) => f.endsWith(".json"))) {
+      const value = await this.readJson<T>(path.join(dir, file));
+      if (!value) continue;
+      const at =
+        (value as { archived_at?: string }).archived_at ??
+        (value as { plan_commit_ref?: string }).plan_commit_ref ??
+        file;
+      items.push({ at, value });
+    }
+    items.sort((a, b) => b.at.localeCompare(a.at));
+    return items.slice(0, limit).map((item) => item.value);
+  }
+
+  private async readJson<T>(filePath: string): Promise<T | null> {
+    try {
+      const raw = await readFile(filePath, "utf8");
+      return JSON.parse(raw) as T;
+    } catch {
+      return null;
+    }
+  }
+}

package/src/archive/local-trace-archive.ts

@@ -0,0 +1,91 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import type { TraceDetail, TraceRecord, TraceSummary } from "./types.js";
+
+function safeSegment(value: string): string {
+  if (!value || value.includes("..") || value.includes("/") || value.includes("\\")) {
+    throw new Error("invalid archive path segment");
+  }
+  return value;
+}
+
+export class LocalTraceArchive {
+  constructor(private readonly root: string) {}
+
+  private traceDir(tenantId: string, traceId: string): string {
+    return path.join(this.root, "traces", safeSegment(tenantId), safeSegment(traceId));
+  }
+
+  async ensureRoot(): Promise<void> {
+    await mkdir(this.root, { recursive: true });
+  }
+
+  async appendRecord(
+    tenantId: string,
+    traceId: string,
+    record: TraceRecord,
+  ): Promise<void> {
+    const dir = this.traceDir(tenantId, traceId);
+    await mkdir(dir, { recursive: true });
+    const line = `${JSON.stringify(record)}\n`;
+    await writeFile(path.join(dir, "records.ndjson"), line, { flag: "a" });
+  }
+
+  async persistTrace(detail: TraceDetail): Promise<void> {
+    const dir = this.traceDir(detail.summary.tenant_id, detail.summary.trace_id);
+    await mkdir(dir, { recursive: true });
+    await writeFile(
+      path.join(dir, "summary.json"),
+      JSON.stringify(detail.summary, null, 2),
+      "utf8",
+    );
+    const body = detail.records.map((r) => JSON.stringify(r)).join("\n");
+    const suffix = body.length > 0 ? "\n" : "";
+    await writeFile(path.join(dir, "records.ndjson"), `${body}${suffix}`, "utf8");
+  }
+
+  async listTraces(tenantId: string, limit = 50): Promise<TraceSummary[]> {
+    const dir = path.join(this.root, "traces", safeSegment(tenantId));
+    let entries: string[];
+    try {
+      entries = await readdir(dir);
+    } catch {
+      return [];
+    }
+    const summaries: TraceSummary[] = [];
+    for (const traceId of entries) {
+      try {
+        const raw = await readFile(path.join(dir, traceId, "summary.json"), "utf8");
+        summaries.push(JSON.parse(raw) as TraceSummary);
+      } catch {
+        continue;
+      }
+    }
+    summaries.sort((a, b) => b.started_at_ms - a.started_at_ms);
+    return summaries.slice(0, limit);
+  }
+
+  async getTrace(tenantId: string, traceId: string): Promise<TraceDetail | null> {
+    const dir = this.traceDir(tenantId, traceId);
+    let summaryRaw: string;
+    try {
+      summaryRaw = await readFile(path.join(dir, "summary.json"), "utf8");
+    } catch {
+      return null;
+    }
+    const summary = JSON.parse(summaryRaw) as TraceSummary;
+    let records: TraceRecord[] = [];
+    try {
+      const ndjson = await readFile(path.join(dir, "records.ndjson"), "utf8");
+      records = ndjson
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => JSON.parse(line) as TraceRecord);
+    } catch {
+      records = [];
+    }
+    return { summary, records };
+  }
+}

package/src/archive/paths.ts

@@ -0,0 +1,15 @@
+import path from "node:path";
+
+import type { ArchivePaths } from "./types.js";
+
+/** Resolve local trace/run archive roots from env or agent defaults. */
+export function resolveArchivePaths(agentRoot: string): ArchivePaths {
+  const archivesDir = path.join(agentRoot, ".plasm", "archives");
+  const traceRoot =
+    process.env.PLASM_TRACE_ARCHIVE_DIR?.trim() ||
+    path.join(archivesDir, "traces");
+  const runRoot =
+    process.env.PLASM_RUN_ARTIFACTS_DIR?.trim() ||
+    path.join(archivesDir, "runs");
+  return { traceRoot, runRoot };
+}

package/src/archive/postgres-kv-adapter.ts

@@ -0,0 +1,72 @@
+import type { KvArchiveIndexAdapter } from "./types.js";
+
+function postgresUrl(): string {
+  return (
+    process.env.PLASM_ARCHIVE_POSTGRES_URL?.trim() ||
+    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_archive_index (
+  index_key TEXT PRIMARY KEY,
+  index_value TEXT NOT NULL,
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+`;
+
+type PgPool = {
+  query(sql: string, params?: unknown[]): Promise<{ rows: Array<Record<string, unknown>> }>;
+};
+
+let sharedPool: PgPool | null = null;
+
+async function pool(): Promise<PgPool> {
+  if (sharedPool) return sharedPool;
+  const url = postgresUrl();
+  if (!url) {
+    throw new Error("Postgres archive index requires DATABASE_URL or WORKFLOW_POSTGRES_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;
+}
+
+export class PostgresArchiveIndexAdapter implements KvArchiveIndexAdapter {
+  async set(key: string, value: string): Promise<void> {
+    const db = await pool();
+    await db.query(
+      `INSERT INTO plasm_agent_archive_index (index_key, index_value, updated_at)
+       VALUES ($1, $2, NOW())
+       ON CONFLICT (index_key) DO UPDATE
+       SET index_value = EXCLUDED.index_value, updated_at = NOW()`,
+      [key, value],
+    );
+  }
+
+  async get(key: string): Promise<string | null> {
+    const db = await pool();
+    const result = await db.query(
+      `SELECT index_value FROM plasm_agent_archive_index WHERE index_key = $1`,
+      [key],
+    );
+    const value = result.rows[0]?.index_value;
+    return typeof value === "string" ? value : null;
+  }
+
+  async list(prefix: string): Promise<string[]> {
+    const db = await pool();
+    const result = await db.query(
+      `SELECT index_key FROM plasm_agent_archive_index WHERE index_key LIKE $1`,
+      [`${prefix}%`],
+    );
+    return result.rows
+      .map((row) => row.index_key)
+      .filter((key): key is string => typeof key === "string");
+  }
+}

package/src/archive/prod-archive-store.ts

@@ -0,0 +1,143 @@
+import { LocalArchiveStore } from "./index.js";
+import type {
+  BlobArchiveAdapter,
+  KvArchiveIndexAdapter,
+  PlanArchiveSnapshot,
+  RunSnapshot,
+  TraceDetail,
+  TraceRecord,
+  TraceSummary,
+} from "./types.js";
+
+function blobKey(kind: "plan" | "run" | "trace", id: string): string {
+  return `plasm/archives/${kind}/${id}.json`;
+}
+
+function indexKey(kind: "plan" | "run" | "trace", id: string): string {
+  return `plasm:index:${kind}:${id}`;
+}
+
+/** Durable archive store: local FS cache + Blob bodies + KV/Postgres index. */
+export class ProdArchiveStore {
+  readonly local: LocalArchiveStore;
+
+  constructor(
+    agentRoot: string,
+    private readonly blob: BlobArchiveAdapter,
+    private readonly index: KvArchiveIndexAdapter,
+  ) {
+    this.local = LocalArchiveStore.fromAgentRoot(agentRoot);
+  }
+
+  get paths() {
+    return this.local.paths;
+  }
+
+  async bootstrap(): Promise<void> {
+    await this.local.bootstrap();
+  }
+
+  private async putJson(key: string, value: unknown): Promise<void> {
+    await this.blob.put(key, JSON.stringify(value));
+  }
+
+  private async getJson<T>(key: string): Promise<T | null> {
+    const bytes = await this.blob.get(key);
+    if (!bytes) return null;
+    return JSON.parse(Buffer.from(bytes).toString("utf8")) as T;
+  }
+
+  async recordToolEvent(
+    tenantId: string,
+    traceId: string,
+    kind: string,
+    name: string,
+    attributes?: Record<string, string | number | boolean>,
+  ): Promise<void> {
+    await this.local.recordToolEvent(tenantId, traceId, kind, name, attributes);
+  }
+
+  async finalizeTrace(detail: TraceDetail): Promise<void> {
+    await this.local.finalizeTrace(detail);
+    const key = blobKey("trace", detail.summary.trace_id);
+    await this.putJson(key, detail);
+    await this.index.set(indexKey("trace", detail.summary.trace_id), key);
+  }
+
+  async writePlanArchive(snapshot: PlanArchiveSnapshot): Promise<void> {
+    await this.local.writePlanArchive(snapshot);
+    const key = blobKey("plan", snapshot.plan_commit_ref);
+    await this.putJson(key, snapshot);
+    await this.index.set(indexKey("plan", snapshot.plan_commit_ref), key);
+  }
+
+  async writeRunSnapshot(snapshot: RunSnapshot): Promise<void> {
+    await this.local.writeRunSnapshot(snapshot);
+    const key = blobKey("run", snapshot.run_id);
+    await this.putJson(key, snapshot);
+    await this.index.set(indexKey("run", snapshot.run_id), key);
+  }
+
+  async listTraces(tenantId: string, limit = 50): Promise<TraceSummary[]> {
+    const keys = await this.index.list("plasm:index:trace:");
+    const items: TraceSummary[] = [];
+    for (const idx of keys) {
+      const blobRef = await this.index.get(idx);
+      if (!blobRef) continue;
+      const detail = await this.getJson<TraceDetail>(blobRef);
+      if (detail?.summary) items.push(detail.summary);
+    }
+    if (items.length) {
+      items.sort((a, b) => b.started_at_ms - a.started_at_ms);
+      return items.slice(0, limit);
+    }
+    return this.local.listTraces(tenantId, limit);
+  }
+
+  async getTrace(tenantId: string, traceId: string): Promise<TraceDetail | null> {
+    const blobRef = await this.index.get(indexKey("trace", traceId));
+    if (blobRef) {
+      const detail = await this.getJson<TraceDetail>(blobRef);
+      if (detail) return detail;
+    }
+    return this.local.getTrace(tenantId, traceId);
+  }
+
+  async listPlans(limit = 50): Promise<PlanArchiveSnapshot[]> {
+    const keys = await this.index.list("plasm:index:plan:");
+    const items: PlanArchiveSnapshot[] = [];
+    for (const idx of keys) {
+      const blobRef = await this.index.get(idx);
+      if (!blobRef) continue;
+      const plan = await this.getJson<PlanArchiveSnapshot>(blobRef);
+      if (plan) items.push(plan);
+    }
+    if (items.length) {
+      items.sort((a, b) => b.archived_at.localeCompare(a.archived_at));
+      return items.slice(0, limit);
+    }
+    return this.local.listPlans(limit);
+  }
+
+  async listRuns(limit = 50): Promise<RunSnapshot[]> {
+    const keys = await this.index.list("plasm:index:run:");
+    const items: RunSnapshot[] = [];
+    for (const idx of keys) {
+      const blobRef = await this.index.get(idx);
+      if (!blobRef) continue;
+      const run = await this.getJson<RunSnapshot>(blobRef);
+      if (run) items.push(run);
+    }
+    if (items.length) {
+      items.sort((a, b) => b.archived_at.localeCompare(a.archived_at));
+      return items.slice(0, limit);
+    }
+    return this.local.listRuns(limit);
+  }
+
+  async listArchives(limit?: number) {
+    return this.local.listArchives(limit);
+  }
+}
+
+export type { TraceRecord };

package/src/archive/resolve-backend.ts

@@ -0,0 +1,60 @@
+import type { AgentWorkflowWorldDefinition } from "../define-agent.js";
+import { LocalArchiveStore } from "./index.js";
+import { PostgresArchiveIndexAdapter } from "./postgres-kv-adapter.js";
+import { ProdArchiveStore } from "./prod-archive-store.js";
+import { VercelBlobArchiveAdapter } from "./vercel-blob-adapter.js";
+import { VercelKvArchiveIndexAdapter } from "./vercel-kv-adapter.js";
+import type { BlobArchiveAdapter, KvArchiveIndexAdapter } from "./types.js";
+
+export type ArchiveBackend = "local" | "vercel" | "postgres";
+
+export function resolveArchiveBackend(
+  world?: AgentWorkflowWorldDefinition,
+): ArchiveBackend {
+  const explicit = process.env.PLASM_ARCHIVE_BACKEND?.trim().toLowerCase();
+  if (explicit === "local" || explicit === "vercel" || explicit === "postgres") {
+    return explicit;
+  }
+  if (
+    process.env.BLOB_READ_WRITE_TOKEN?.trim() ||
+    process.env.PLASM_RUN_ARTIFACTS_URL?.trim()
+  ) {
+    if (process.env.KV_REST_API_URL?.trim() || process.env.PLASM_KV_REST_API_URL?.trim()) {
+      return "vercel";
+    }
+  }
+  if (world?.type === "postgres") return "postgres";
+  return "local";
+}
+
+function resolveBlobAdapter(): BlobArchiveAdapter | undefined {
+  if (process.env.BLOB_READ_WRITE_TOKEN?.trim()) {
+    return new VercelBlobArchiveAdapter();
+  }
+  return undefined;
+}
+
+function resolveIndexAdapter(
+  backend: ArchiveBackend,
+): KvArchiveIndexAdapter | undefined {
+  if (backend === "vercel") {
+    return new VercelKvArchiveIndexAdapter();
+  }
+  if (backend === "postgres") {
+    return new PostgresArchiveIndexAdapter();
+  }
+  return undefined;
+}
+
+export function createArchiveStore(
+  agentRoot: string,
+  options?: { backend?: ArchiveBackend; world?: AgentWorkflowWorldDefinition },
+): LocalArchiveStore | ProdArchiveStore {
+  const backend = options?.backend ?? resolveArchiveBackend(options?.world);
+  const blob = resolveBlobAdapter();
+  const index = resolveIndexAdapter(backend);
+  if (backend !== "local" && blob && index) {
+    return new ProdArchiveStore(agentRoot, blob, index);
+  }
+  return LocalArchiveStore.fromAgentRoot(agentRoot);
+}

package/src/archive/run-id.ts

@@ -0,0 +1,23 @@
+import { createHash } from "node:crypto";
+
+export interface RunIdBundle {
+  catalogCgsHash: string;
+  planCommitRef: string;
+  program: string;
+  entryId?: string;
+  requestFingerprints?: string[];
+}
+
+/** Deterministic `pr` + 64 hex run id aligned with OSS wire form. */
+export function computeRunId(bundle: RunIdBundle): string {
+  const canonical = JSON.stringify({
+    v: 1,
+    catalog_cgs_hash: bundle.catalogCgsHash,
+    plan_commit_ref: bundle.planCommitRef,
+    program: bundle.program,
+    entry_id: bundle.entryId ?? null,
+    request_fingerprints: [...(bundle.requestFingerprints ?? [])].sort(),
+  });
+  const digest = createHash("sha256").update(canonical).digest("hex");
+  return `pr${digest}`;
+}

package/src/archive/types.ts

@@ -0,0 +1,75 @@
+export interface TraceSummary {
+  trace_id: string;
+  tenant_id: string;
+  logical_session_id?: string;
+  logical_session_ref?: string;
+  intent?: string;
+  status: "completed" | "live";
+  started_at_ms: number;
+  ended_at_ms?: number;
+  project_slug: string;
+  totals?: {
+    tool_calls?: number;
+    model_calls?: number;
+  };
+}
+
+export interface TraceDetail {
+  summary: TraceSummary;
+  records: TraceRecord[];
+}
+
+export interface TraceRecord {
+  at_ms: number;
+  kind: string;
+  name: string;
+  attributes?: Record<string, string | number | boolean>;
+}
+
+export interface PlanArchiveSnapshot {
+  plan_commit_ref: string;
+  program: string;
+  catalog_cgs_hash: string;
+  entry_id?: string;
+  logical_session_ref?: string;
+  intent?: string;
+  comp_json?: unknown;
+  archived_at: string;
+}
+
+export interface RunSnapshot {
+  run_id: string;
+  plan_commit_ref: string;
+  catalog_cgs_hash: string;
+  entry_id?: string;
+  logical_session_ref?: string;
+  intent?: string;
+  ok: boolean;
+  message: string;
+  results?: unknown[];
+  _meta?: {
+    plasm?: {
+      steps?: unknown[];
+      request_fingerprints?: string[];
+    };
+  };
+  archived_at: string;
+}
+
+export interface ArchivePaths {
+  traceRoot: string;
+  runRoot: string;
+}
+
+/** Production Blob adapter (Vercel Blob / S3-compatible). */
+export interface BlobArchiveAdapter {
+  put(key: string, body: string | Uint8Array): Promise<void>;
+  get(key: string): Promise<Uint8Array | null>;
+}
+
+/** Production KV / Postgres index adapter for archive listings. */
+export interface KvArchiveIndexAdapter {
+  set(key: string, value: string): Promise<void>;
+  get(key: string): Promise<string | null>;
+  list(prefix: string): Promise<string[]>;
+}

package/src/archive/vercel-blob-adapter.ts

@@ -0,0 +1,21 @@
+import type { BlobArchiveAdapter } from "./types.js";
+
+export class VercelBlobArchiveAdapter implements BlobArchiveAdapter {
+  async put(key: string, body: string | Uint8Array): Promise<void> {
+    const { put } = await import("@vercel/blob");
+    const payload = typeof body === "string" ? body : Buffer.from(body);
+    await put(key, payload, {
+      access: "public",
+      addRandomSuffix: false,
+    });
+  }
+
+  async get(key: string): Promise<Uint8Array | null> {
+    const { head } = await import("@vercel/blob");
+    const meta = await head(key).catch(() => null);
+    if (!meta?.url) return null;
+    const response = await fetch(meta.url);
+    if (!response.ok) return null;
+    return new Uint8Array(await response.arrayBuffer());
+  }
+}

package/src/archive/vercel-kv-adapter.ts

@@ -0,0 +1,24 @@
+import type { KvArchiveIndexAdapter } from "./types.js";
+
+export class VercelKvArchiveIndexAdapter implements KvArchiveIndexAdapter {
+  private async kv() {
+    const mod = await import("@vercel/kv");
+    return mod.kv;
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    const kv = await this.kv();
+    await kv.set(key, value);
+  }
+
+  async get(key: string): Promise<string | null> {
+    const kv = await this.kv();
+    const value = await kv.get<string>(key);
+    return value ?? null;
+  }
+
+  async list(prefix: string): Promise<string[]> {
+    const kv = await this.kv();
+    return kv.keys(`${prefix}*`);
+  }
+}

package/src/authoring/channel-dispatch.ts

@@ -0,0 +1,44 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import type { AuthoringContext } from "./context.js";
+import type { LoadedChannel } from "./slot-loader.js";
+
+function sendJson(res: ServerResponse, status: number, payload: unknown): void {
+  const body = JSON.stringify(payload, null, 2);
+  res.statusCode = status;
+  res.setHeader("content-type", "application/json; charset=utf-8");
+  res.end(body);
+}
+
+export function tryHandleChannelRoute(
+  req: IncomingMessage,
+  res: ServerResponse,
+  channels: LoadedChannel[],
+  ctx: AuthoringContext,
+): boolean {
+  const method = (req.method ?? "GET").toUpperCase();
+  const pathname = new URL(req.url ?? "/", "http://localhost").pathname;
+
+  for (const channel of channels) {
+    for (const route of channel.definition.routes) {
+      if (route.method !== method || route.path !== pathname) continue;
+      void Promise.resolve(route.handler(req, res, ctx)).catch((err: unknown) => {
+        if (!res.writableEnded) {
+          sendJson(res, 500, { error: "channel_handler_error", message: String(err) });
+        }
+      });
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export function listChannelRoutes(channels: LoadedChannel[]): Array<{ method: string; path: string }> {
+  return channels.flatMap((channel) =>
+    channel.definition.routes.map((route) => ({
+      method: route.method,
+      path: route.path,
+    })),
+  );
+}