@plasm_lang/vercel-agent 0.3.63

package/src/discovery/project-walker.ts

@@ -0,0 +1,272 @@
+import { access, readFile, readdir, stat } from "node:fs/promises";
+import path from "node:path";
+
+const SLOT_DIRS = [
+  "catalogs",
+  "skills",
+  "channels",
+  "schedules",
+  "hooks",
+  "subagents",
+] as const;
+
+export type AuthoredSlot = (typeof SLOT_DIRS)[number];
+
+export interface DiscoveryDiagnostic {
+  level: "error" | "warning";
+  slot: AuthoredSlot | "instructions" | "agent";
+  path: string;
+  message: string;
+}
+
+export interface DiscoveredCatalog {
+  name: string;
+  path: string;
+  entryId?: string;
+}
+
+export interface DiscoveredNamedFile {
+  name: string;
+  path: string;
+  kind: "typescript" | "markdown";
+}
+
+export interface DiscoveredSubagent {
+  name: string;
+  path: string;
+  agentPath: string;
+}
+
+export interface DiscoveredInstructions {
+  path: string;
+  kind: "markdown" | "typescript";
+}
+
+export interface ProjectDiscovery {
+  agentRoot: string;
+  instructions?: DiscoveredInstructions;
+  catalogs: DiscoveredCatalog[];
+  skills: DiscoveredNamedFile[];
+  channels: DiscoveredNamedFile[];
+  schedules: DiscoveredNamedFile[];
+  hooks: DiscoveredNamedFile[];
+  subagents: DiscoveredSubagent[];
+  diagnostics: DiscoveryDiagnostic[];
+}
+
+async function pathExists(p: string): Promise<boolean> {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function fileKind(filename: string): "typescript" | "markdown" | null {
+  if (filename.endsWith(".ts")) return "typescript";
+  if (filename.endsWith(".md")) return "markdown";
+  return null;
+}
+
+function pathDerivedName(filePath: string): string {
+  return path.basename(filePath, path.extname(filePath));
+}
+
+async function readCatalogEntryId(catalogDir: string): Promise<string | undefined> {
+  const domainPath = path.join(catalogDir, "domain.yaml");
+  if (!(await pathExists(domainPath))) return undefined;
+  const raw = await readFile(domainPath, "utf8");
+  const match = raw.match(/^entry_id:\s*["']?([^"'\n]+)["']?/m);
+  return match?.[1]?.trim();
+}
+
+async function scanNamedFiles(
+  slotDir: string,
+  slot: Exclude<AuthoredSlot, "catalogs" | "subagents">,
+): Promise<DiscoveredNamedFile[]> {
+  if (!(await pathExists(slotDir))) return [];
+  const entries = await readdir(slotDir, { withFileTypes: true });
+  const out: DiscoveredNamedFile[] = [];
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    const kind = fileKind(entry.name);
+    if (!kind) continue;
+    out.push({
+      name: pathDerivedName(entry.name),
+      path: path.join(slotDir, entry.name),
+      kind,
+    });
+  }
+  out.sort((a, b) => a.name.localeCompare(b.name));
+  return out;
+}
+
+async function scanCatalogs(
+  agentRoot: string,
+  diagnostics: DiscoveryDiagnostic[],
+): Promise<DiscoveredCatalog[]> {
+  const catalogsDir = path.join(agentRoot, "catalogs");
+  if (!(await pathExists(catalogsDir))) return [];
+
+  const entries = await readdir(catalogsDir, { withFileTypes: true });
+  const out: DiscoveredCatalog[] = [];
+
+    for (const entry of entries) {
+      const catalogDir = path.join(catalogsDir, entry.name);
+      const dirStat = await stat(catalogDir).catch(() => null);
+      if (!dirStat?.isDirectory()) continue;
+    const domainYaml = path.join(catalogDir, "domain.yaml");
+    const mappingsYaml = path.join(catalogDir, "mappings.yaml");
+
+    if (!(await pathExists(domainYaml))) {
+      diagnostics.push({
+        level: "error",
+        slot: "catalogs",
+        path: catalogDir,
+        message: "catalog directory is missing domain.yaml",
+      });
+      continue;
+    }
+    if (!(await pathExists(mappingsYaml))) {
+      diagnostics.push({
+        level: "error",
+        slot: "catalogs",
+        path: catalogDir,
+        message: "catalog directory is missing mappings.yaml",
+      });
+      continue;
+    }
+
+    const entryId = await readCatalogEntryId(catalogDir);
+    out.push({
+      name: entry.name,
+      path: catalogDir,
+      entryId,
+    });
+  }
+
+  out.sort((a, b) => a.name.localeCompare(b.name));
+  return out;
+}
+
+async function scanSubagents(
+  agentRoot: string,
+  diagnostics: DiscoveryDiagnostic[],
+): Promise<DiscoveredSubagent[]> {
+  const subagentsDir = path.join(agentRoot, "subagents");
+  if (!(await pathExists(subagentsDir))) return [];
+
+  const entries = await readdir(subagentsDir, { withFileTypes: true });
+  const out: DiscoveredSubagent[] = [];
+
+    for (const entry of entries) {
+      const subagentDir = path.join(subagentsDir, entry.name);
+      const dirStat = await stat(subagentDir).catch(() => null);
+      if (!dirStat?.isDirectory()) continue;
+    const agentPath = path.join(subagentDir, "agent.ts");
+    if (!(await pathExists(agentPath))) {
+      diagnostics.push({
+        level: "warning",
+        slot: "subagents",
+        path: subagentDir,
+        message: "subagent directory is missing agent.ts",
+      });
+      continue;
+    }
+    out.push({
+      name: entry.name,
+      path: subagentDir,
+      agentPath,
+    });
+  }
+
+  out.sort((a, b) => a.name.localeCompare(b.name));
+  return out;
+}
+
+async function scanInstructions(
+  agentRoot: string,
+  diagnostics: DiscoveryDiagnostic[],
+): Promise<DiscoveredInstructions | undefined> {
+  const markdownPath = path.join(agentRoot, "instructions.md");
+  const typescriptPath = path.join(agentRoot, "instructions.ts");
+
+  const hasMarkdown = await pathExists(markdownPath);
+  const hasTypescript = await pathExists(typescriptPath);
+
+  if (hasMarkdown && hasTypescript) {
+    diagnostics.push({
+      level: "warning",
+      slot: "instructions",
+      path: agentRoot,
+      message: "both instructions.md and instructions.ts exist; markdown wins",
+    });
+  }
+
+  if (hasMarkdown) {
+    return { path: markdownPath, kind: "markdown" };
+  }
+  if (hasTypescript) {
+    return { path: typescriptPath, kind: "typescript" };
+  }
+
+  diagnostics.push({
+    level: "warning",
+    slot: "instructions",
+    path: agentRoot,
+    message: "no instructions.md or instructions.ts found",
+  });
+  return undefined;
+}
+
+/** Walk `agent/` and collect eve-shaped discovery metadata (catalogs replace tools/). */
+export async function walkAgentProject(agentRoot: string): Promise<ProjectDiscovery> {
+  const resolvedRoot = path.resolve(agentRoot);
+  const rootStat = await stat(resolvedRoot).catch(() => null);
+  const diagnostics: DiscoveryDiagnostic[] = [];
+
+  if (!rootStat?.isDirectory()) {
+    diagnostics.push({
+      level: "error",
+      slot: "agent",
+      path: resolvedRoot,
+      message: "agent root is not a directory",
+    });
+    return {
+      agentRoot: resolvedRoot,
+      catalogs: [],
+      skills: [],
+      channels: [],
+      schedules: [],
+      hooks: [],
+      subagents: [],
+      diagnostics,
+    };
+  }
+
+  const [instructions, catalogs, skills, channels, schedules, hooks, subagents] =
+    await Promise.all([
+      scanInstructions(resolvedRoot, diagnostics),
+      scanCatalogs(resolvedRoot, diagnostics),
+      scanNamedFiles(path.join(resolvedRoot, "skills"), "skills"),
+      scanNamedFiles(path.join(resolvedRoot, "channels"), "channels"),
+      scanNamedFiles(path.join(resolvedRoot, "schedules"), "schedules"),
+      scanNamedFiles(path.join(resolvedRoot, "hooks"), "hooks"),
+      scanSubagents(resolvedRoot, diagnostics),
+    ]);
+
+  return {
+    agentRoot: resolvedRoot,
+    instructions,
+    catalogs,
+    skills,
+    channels,
+    schedules,
+    hooks,
+    subagents,
+    diagnostics,
+  };
+}
+
+export const authoredSlots: readonly AuthoredSlot[] = SLOT_DIRS;

package/src/engine/connect-auth.ts

@@ -0,0 +1,135 @@
+/**
+ * Vercel Connect broker for outbound catalog HTTP (per-request tokens; never stored).
+ */
+
+export type ConnectTokenSubject =
+  | { type: "app" }
+  | { type: "user"; id: string };
+
+export interface ConnectAuthOptions {
+  connector?: string;
+  subject?: ConnectTokenSubject;
+  installationId?: string;
+  scopes?: string[];
+  vercelToken?: string;
+}
+
+/** Raised when Connect requires an end-user OAuth consent flow. */
+export class ConnectAuthorizationRequiredError extends Error {
+  readonly connector: string;
+  readonly authorizationUrl?: string;
+
+  constructor(message: string, connector: string, authorizationUrl?: string) {
+    super(message);
+    this.name = "ConnectAuthorizationRequiredError";
+    this.connector = connector;
+    this.authorizationUrl = authorizationUrl;
+  }
+}
+
+function entryEnvSuffix(entryId: string): string {
+  return entryId.toUpperCase().replace(/[^A-Z0-9]/g, "_");
+}
+
+/** Resolve connector UID for a catalog `entry_id` from env. */
+export function connectorUidForEntry(entryId?: string): string | undefined {
+  const trimmed = entryId?.trim();
+  if (trimmed) {
+    const perEntry =
+      process.env[`PLASM_CONNECTOR_${entryEnvSuffix(trimmed)}`]?.trim() ??
+      process.env[`CONNECTOR_${entryEnvSuffix(trimmed)}`]?.trim();
+    if (perEntry) return perEntry;
+  }
+  return (
+    process.env.PLASM_CONNECTOR_DEFAULT?.trim() ??
+    process.env.CONNECTOR_DEFAULT?.trim()
+  );
+}
+
+function defaultSubject(): ConnectTokenSubject {
+  const type = process.env.PLASM_CONNECT_SUBJECT_TYPE?.trim().toLowerCase();
+  if (type === "user") {
+    const id = process.env.PLASM_CONNECT_USER_ID?.trim();
+    if (!id) {
+      throw new Error(
+        "PLASM_CONNECT_SUBJECT_TYPE=user requires PLASM_CONNECT_USER_ID",
+      );
+    }
+    return { type: "user", id };
+  }
+  return { type: "app" };
+}
+
+function parseScopes(raw?: string): string[] | undefined {
+  const value = raw?.trim();
+  if (!value) return undefined;
+  const parts = value.split(/[\s,]+/).map((s) => s.trim()).filter(Boolean);
+  return parts.length ? parts : undefined;
+}
+
+export function connectAuthOptionsForEntry(entryId?: string): ConnectAuthOptions | undefined {
+  const connector = connectorUidForEntry(entryId);
+  if (!connector) return undefined;
+  return {
+    connector,
+    subject: defaultSubject(),
+    installationId: process.env.PLASM_CONNECT_INSTALLATION_ID?.trim() || undefined,
+    scopes: parseScopes(process.env.PLASM_CONNECT_SCOPES),
+    vercelToken: process.env.VERCEL_OIDC_TOKEN?.trim() || undefined,
+  };
+}
+
+type ConnectModule = typeof import("@vercel/connect");
+
+async function loadConnect(): Promise<ConnectModule> {
+  return import("@vercel/connect");
+}
+
+function isUserAuthRequired(err: unknown): err is { authorizationUrl?: string } {
+  return (
+    err != null &&
+    typeof err === "object" &&
+    (err as { name?: string }).name === "UserAuthorizationRequiredError"
+  );
+}
+
+/** Mint a short-lived Connect access token for `entryId`, or undefined when not configured. */
+export async function resolveConnectBearer(
+  entryId?: string,
+  overrides?: Partial<ConnectAuthOptions>,
+): Promise<string | undefined> {
+  const base = connectAuthOptionsForEntry(entryId);
+  if (!base?.connector) return undefined;
+
+  const connector = overrides?.connector ?? base.connector;
+  const subject = overrides?.subject ?? base.subject ?? { type: "app" as const };
+  const installationId = overrides?.installationId ?? base.installationId;
+  const scopes = overrides?.scopes ?? base.scopes;
+  const vercelToken = overrides?.vercelToken ?? base.vercelToken;
+
+  try {
+    const { getToken } = await loadConnect();
+    return await getToken(
+      connector,
+      {
+        subject,
+        ...(installationId ? { installationId } : {}),
+        ...(scopes ? { scopes } : {}),
+      },
+      vercelToken ? { vercelToken } : undefined,
+    );
+  } catch (err: unknown) {
+    if (isUserAuthRequired(err)) {
+      const url =
+        typeof (err as { authorizationUrl?: string }).authorizationUrl === "string"
+          ? (err as { authorizationUrl: string }).authorizationUrl
+          : undefined;
+      throw new ConnectAuthorizationRequiredError(
+        `Vercel Connect authorization required for connector ${connector}`,
+        connector,
+        url,
+      );
+    }
+    throw err;
+  }
+}

package/src/engine/create-host-transport.ts

@@ -0,0 +1,7 @@
+import { createDefaultHostTransport } from "./host-transport.js";
+import type { HostTransportFn } from "./napi-binding.js";
+
+/** Production host transport: env bearer → Vercel Connect `getToken()` → fetch. */
+export function createProductionHostTransport(): HostTransportFn {
+  return createDefaultHostTransport({ useConnect: true });
+}

package/src/engine/fixture-mock-transport.ts

@@ -0,0 +1,54 @@
+/**
+ * Dev mock HTTP for fixture catalogs (`http://example.test` backends).
+ * Enables full `plasm_run` smoke without a live API.
+ */
+
+import type { HostTransportFn } from "./napi-binding.js";
+
+/** Mock product list/get responses for `execute_tiny` fixture paths. */
+export function createFixtureMockTransport(): HostTransportFn {
+  return async (request) => {
+    const path = (() => {
+      try {
+        return new URL(request.url).pathname;
+      } catch {
+        return request.url;
+      }
+    })();
+
+    if (path.includes("/products/") && path !== "/products" && !path.includes("/search")) {
+      return {
+        status: 200,
+        body: JSON.stringify({ id: "p1", name: "Widget", category_id: "c1" }),
+      };
+    }
+    if (path.includes("/products")) {
+      return {
+        status: 200,
+        body: JSON.stringify([{ id: "p1", name: "Widget", category_id: "c1" }]),
+      };
+    }
+    if (path.includes("/categories")) {
+      return {
+        status: 200,
+        body: JSON.stringify({ id: "c1", name: "Gadgets" }),
+      };
+    }
+
+    return {
+      status: 404,
+      body: JSON.stringify({ error: `fixture mock: unhandled path ${path}` }),
+    };
+  };
+}
+
+export function fixtureMockTransportEnabled(): boolean {
+  const flag = process.env.PLASM_AGENT_MOCK_HTTP?.trim();
+  if (flag === "1" || flag === "true") return true;
+  if (flag === "0" || flag === "false") return false;
+  // Default on for local dev when no outbound bearer is configured.
+  return !(
+    process.env.PLASM_BEARER?.trim() ||
+    process.env.PLASM_AUTH_BEARER?.trim()
+  );
+}

package/src/engine/host-transport-bridge.ts

@@ -0,0 +1,32 @@
+/**
+ * NAPI bridge: Rust threadsafe transport awaits a JavaScript Promise return.
+ */
+
+import type { HostTransportFn, HostTransportRequest, HostTransportResponse } from "./napi-binding.js";
+
+function isPromise<T>(value: unknown): value is Promise<T> {
+  return (
+    value != null &&
+    typeof value === "object" &&
+    "then" in value &&
+    typeof (value as Promise<T>).then === "function"
+  );
+}
+
+/** Normalize sync or async host transport for `@plasm_lang/engine` `runPlanLive`. */
+export function toNapiHostTransport(
+  transport: HostTransportFn,
+): (request: HostTransportRequest) => Promise<HostTransportResponse> {
+  return async (request) => {
+    const out = transport(request);
+    const resolved = isPromise<HostTransportResponse>(out) ? await out : await Promise.resolve(out);
+    if (resolved.status == null || resolved.body == null) {
+      throw new Error("host transport response must include `status` and `body`");
+    }
+    return {
+      status: resolved.status,
+      body: resolved.body,
+      nextUrl: resolved.nextUrl,
+    };
+  };
+}

package/src/engine/host-transport.ts

@@ -0,0 +1,84 @@
+/**
+ * Default outbound HTTP transport for local dev: `fetch` + bearer from env.
+ */
+
+import type { HostTransportFn, HostTransportRequest } from "./napi-binding.js";
+import { resolveConnectBearer } from "./connect-auth.js";
+import { plasmSpans } from "../telemetry/plasm-spans.js";
+
+export type HostTransportOptions = {
+  bearer?: string;
+  fetchImpl?: typeof fetch;
+  /** When true (default), resolve Vercel Connect tokens after env bearer misses. */
+  useConnect?: boolean;
+};
+
+function bearerFromEnv(entryId?: string): string | undefined {
+  const keys = [
+    entryId ? `PLASM_${entryId.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_BEARER` : undefined,
+    "PLASM_BEARER",
+    "PLASM_AUTH_BEARER",
+  ].filter(Boolean) as string[];
+  for (const key of keys) {
+    const value = process.env[key]?.trim();
+    if (value) return value;
+  }
+  return undefined;
+}
+
+export function createDefaultHostTransport(options?: HostTransportOptions): HostTransportFn {
+  const fetchImpl = options?.fetchImpl ?? fetch;
+  const bearerOverride = options?.bearer;
+  const useConnect = options?.useConnect ?? true;
+
+  return async (request: HostTransportRequest) => {
+    const host = (() => {
+      try {
+        return new URL(request.url).host;
+      } catch {
+        return request.url;
+      }
+    })();
+
+    return plasmSpans.transportHttp(
+      {
+        entryId: request.entryId,
+        transportHost: host,
+      },
+      async (span) => {
+        const headers = new Headers(request.headers ?? {});
+        if (!headers.has("authorization")) {
+          let bearer = bearerOverride ?? bearerFromEnv(request.entryId);
+          if (!bearer && useConnect) {
+            bearer = await resolveConnectBearer(request.entryId);
+          }
+          if (bearer) {
+            headers.set("authorization", bearer.startsWith("Bearer ") ? bearer : `Bearer ${bearer}`);
+          }
+        }
+        if (request.body != null && !headers.has("content-type")) {
+          headers.set("content-type", "application/json; charset=utf-8");
+        }
+
+        const init: RequestInit = {
+          method: request.method,
+          headers,
+        };
+        if (request.body != null && request.method !== "GET" && request.method !== "HEAD") {
+          init.body = request.body;
+        }
+
+        const response = await fetchImpl(request.url, init);
+        const text = await response.text();
+        const nextUrl = response.headers.get("link")?.match(/<([^>]+)>;\s*rel="?next"?/i)?.[1];
+
+        span.setAttribute("plasm.transport.status", response.status);
+        return {
+          status: response.status,
+          body: text,
+          nextUrl: nextUrl ?? undefined,
+        };
+      },
+    );
+  };
+}