@plasm_lang/vercel-agent 0.3.63

package/src/cli/link.ts

@@ -0,0 +1,68 @@
+import { spawn } from "node:child_process";
+
+function runCommand(
+  command: string,
+  args: string[],
+  cwd: string,
+): Promise<{ code: number; stdout: string; stderr: string }> {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: process.env,
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("close", (code) => {
+      resolve({ code: code ?? 1, stdout, stderr });
+    });
+  });
+}
+
+async function commandExists(command: string): Promise<boolean> {
+  const probe = process.platform === "win32" ? "where" : "which";
+  const result = await runCommand(probe, [command], process.cwd());
+  return result.code === 0;
+}
+
+export interface PlasmLinkResult {
+  linked: boolean;
+  envPulled: boolean;
+  messages: string[];
+}
+
+export async function runPlasmLink(projectRoot: string): Promise<PlasmLinkResult> {
+  const messages: string[] = [];
+  const hasVercel = await commandExists("vercel");
+  if (!hasVercel) {
+    messages.push(
+      "Vercel CLI not found. Install with `npm i -g vercel` or set AI_GATEWAY_API_KEY manually.",
+    );
+    return { linked: false, envPulled: false, messages };
+  }
+
+  messages.push("Running `vercel link` (interactive)…");
+  const link = await runCommand("vercel", ["link"], projectRoot);
+  if (link.code !== 0) {
+    messages.push("vercel link failed or was cancelled.");
+    if (link.stderr.trim()) messages.push(link.stderr.trim());
+    return { linked: false, envPulled: false, messages };
+  }
+  messages.push("vercel link complete.");
+
+  messages.push("Running `vercel env pull .env.local`…");
+  const pull = await runCommand("vercel", ["env", "pull", ".env.local"], projectRoot);
+  if (pull.code !== 0) {
+    messages.push("vercel env pull failed — set AI_GATEWAY_API_KEY in .env.local manually.");
+    if (pull.stderr.trim()) messages.push(pull.stderr.trim());
+    return { linked: true, envPulled: false, messages };
+  }
+  messages.push("Pulled environment to .env.local");
+  return { linked: true, envPulled: true, messages };
+}

package/src/cli/project-root.ts

@@ -0,0 +1,57 @@
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+
+export interface ResolvedAgentProject {
+  /** Directory containing `agent/agent.ts`. */
+  projectRoot: string;
+  agentRoot: string;
+}
+
+async function exists(p: string): Promise<boolean> {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Walk up from `startDir` to find `agent/agent.ts`. */
+export async function resolveAgentProject(
+  startDir: string = process.cwd(),
+): Promise<ResolvedAgentProject | null> {
+  let current = path.resolve(startDir);
+  for (let depth = 0; depth < 12; depth += 1) {
+    const agentRoot = path.join(current, "agent");
+    const agentTs = path.join(agentRoot, "agent.ts");
+    if (await exists(agentTs)) {
+      return { projectRoot: current, agentRoot };
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return null;
+}
+
+export async function requireAgentProject(
+  startDir?: string,
+): Promise<ResolvedAgentProject> {
+  const resolved = await resolveAgentProject(startDir);
+  if (!resolved) {
+    throw new Error(
+      "No agent project found. Run from a directory with agent/agent.ts or use `plasm-agent init`.",
+    );
+  }
+  return resolved;
+}
+
+export async function readPackageName(projectRoot: string): Promise<string | undefined> {
+  try {
+    const raw = await readFile(path.join(projectRoot, "package.json"), "utf8");
+    const parsed = JSON.parse(raw) as { name?: string };
+    return parsed.name;
+  } catch {
+    return undefined;
+  }
+}

package/src/define-agent.ts

@@ -0,0 +1,150 @@
+import path from "node:path";
+
+import type { LoadedProjectSlots } from "./authoring/slot-loader.js";
+import { loadAuthoredSlots } from "./authoring/slot-loader.js";
+import type { SubagentRegistry } from "./authoring/subagent-loader.js";
+import {
+  createSubagentRegistry,
+  loadSubagents,
+} from "./authoring/subagent-loader.js";
+import { walkAgentProject } from "./discovery/project-walker.js";
+import { PlasmAgent, type PlasmAgentConfig } from "./runtime/plasm-agent.js";
+import type { AgentRuntimeConfig } from "./runtime/agent-runtime.js";
+import { bootstrapWorkflowWorld } from "./workflow/world-bootstrap.js";
+
+/** Context-window compaction (eve-shaped; harness wiring is phase 7+). */
+export interface AgentCompactionConfig {
+  thresholdPercent?: number;
+  model?: string;
+}
+
+/** Provider-specific generation knobs passed through to AI SDK calls. */
+export interface AgentModelOptions {
+  temperature?: number;
+  maxOutputTokens?: number;
+  topP?: number;
+  topK?: number;
+  [key: string]: unknown;
+}
+
+/** Workflow SDK world adapter (local dev vs durable Postgres vs Vercel-managed). */
+export interface AgentWorkflowWorldDefinition {
+  type?: "local" | "postgres" | "vercel" | "kv";
+  [key: string]: unknown;
+}
+
+export interface AgentWorkflowDefinition {
+  world?: AgentWorkflowWorldDefinition;
+}
+
+export interface AgentBuildConfig {
+  /** Packages the bundler must not inline (NAPI prebuilds, native addons). */
+  externalDependencies?: string[];
+}
+
+export interface AgentExperimentalConfig {
+  workflow?: AgentWorkflowDefinition;
+  /** `true` (default) = skill index + read_skill tool; `"inline"` = inject full bodies. */
+  skills?: boolean | "inline";
+}
+
+/** Authored agent runtime config (`agent/agent.ts`). Identity comes from the filesystem. */
+export interface AgentDefinition {
+  model: string;
+  compaction?: AgentCompactionConfig;
+  modelOptions?: AgentModelOptions;
+  experimental?: AgentExperimentalConfig;
+  build?: AgentBuildConfig;
+}
+
+export interface CreateAgentFromDefinitionOptions {
+  agentRoot: string;
+  tenantScope?: string;
+  maxSteps?: number;
+  telemetry?: boolean;
+  hostTransport?: AgentRuntimeConfig["hostTransport"];
+  loadedSlots?: LoadedProjectSlots;
+  subagentRegistry?: SubagentRegistry;
+  getAuthoringContext?: PlasmAgentConfig["getAuthoringContext"];
+}
+
+export interface ResolvedAgentDefinition extends AgentDefinition {
+  agentRoot: string;
+}
+
+/** Eve-compatible helper: default-export the frozen definition from `agent/agent.ts`. */
+export function defineAgent(definition: AgentDefinition): Readonly<AgentDefinition> {
+  return Object.freeze({ ...definition });
+}
+
+export function resolveAgentDefinition(
+  definition: AgentDefinition,
+  agentRoot: string,
+): ResolvedAgentDefinition {
+  return Object.freeze({
+    ...definition,
+    agentRoot: path.resolve(agentRoot),
+  });
+}
+
+export function createPlasmAgentConfig(
+  definition: AgentDefinition,
+  options: CreateAgentFromDefinitionOptions,
+): PlasmAgentConfig {
+  return {
+    model: definition.model,
+    agentRoot: path.resolve(options.agentRoot),
+    tenantScope: options.tenantScope,
+    maxSteps: options.maxSteps,
+    telemetry: options.telemetry,
+    hostTransport: options.hostTransport,
+    compaction: definition.compaction,
+    modelOptions: definition.modelOptions,
+    build: definition.build,
+    experimental: definition.experimental,
+    stateWorld: definition.experimental?.workflow?.world,
+    loadedSkills: options.loadedSlots?.skills.map((s) => s.definition),
+    hookRunner: options.loadedSlots?.hookRunner,
+    subagentRegistry: options.subagentRegistry,
+    getAuthoringContext: options.getAuthoringContext,
+  };
+}
+
+export async function createAgentFromDefinition(
+  definition: AgentDefinition,
+  options: CreateAgentFromDefinitionOptions,
+): Promise<PlasmAgent> {
+  await bootstrapWorkflowWorld(definition.experimental?.workflow);
+  const agent = new PlasmAgent(createPlasmAgentConfig(definition, options));
+  await agent.bootstrap();
+  return agent;
+}
+
+/** Walk agent/, load slots + subagents, then bootstrap the root agent. */
+export async function createAgentFromProject(
+  definition: AgentDefinition,
+  options: CreateAgentFromDefinitionOptions & { importCacheBust?: number },
+): Promise<PlasmAgent> {
+  const agentRoot = path.resolve(options.agentRoot);
+  const discovery = await walkAgentProject(agentRoot);
+  const loadedSlots = await loadAuthoredSlots({
+    discovery,
+    importCacheBust: options.importCacheBust,
+  });
+  const { subagents, diagnostics } = await loadSubagents({
+    discovery,
+    parentSlots: loadedSlots,
+    tenantScope: options.tenantScope,
+    maxSteps: options.maxSteps,
+    telemetry: options.telemetry,
+    importCacheBust: options.importCacheBust,
+  });
+  loadedSlots.diagnostics.push(...diagnostics);
+
+  return createAgentFromDefinition(definition, {
+    ...options,
+    agentRoot,
+    loadedSlots,
+    subagentRegistry: createSubagentRegistry(subagents),
+  });
+}

package/src/dev/client/ansi.ts

@@ -0,0 +1,36 @@
+export const ANSI = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+  magenta: "\x1b[35m",
+  blue: "\x1b[34m",
+} as const;
+
+export function supportsColor(): boolean {
+  if (process.env.NO_COLOR !== undefined) return false;
+  return Boolean(process.stdout.isTTY);
+}
+
+export function paint(text: string, ...styles: string[]): string {
+  if (!supportsColor()) return text;
+  return `${styles.join("")}${text}${ANSI.reset}`;
+}
+
+export function wrap(text: string, width = 78): string[] {
+  const lines: string[] = [];
+  for (const raw of text.split(/\r?\n/)) {
+    let line = raw;
+    while (line.length > width) {
+      let breakAt = line.lastIndexOf(" ", width);
+      if (breakAt <= 0) breakAt = width;
+      lines.push(line.slice(0, breakAt).trimEnd());
+      line = line.slice(breakAt).trimStart();
+    }
+    lines.push(line);
+  }
+  return lines;
+}

package/src/dev/client/http-session.ts

@@ -0,0 +1,180 @@
+import type { ProjectInfoPayload } from "../../project-info.js";
+
+export type SessionEventType = "turn:start" | "turn:step" | "turn:finish" | "turn:error";
+
+export interface ParsedSessionEvent {
+  id?: string;
+  type: SessionEventType;
+  at?: string;
+  message?: string;
+  toolsUsed?: string[];
+  text?: string | null;
+  steps?: number;
+  usage?: unknown;
+  finishReason?: string | null;
+}
+
+export interface SessionTurnResponse {
+  sessionId: string;
+  continuationToken: string;
+  status?: string;
+  text?: string;
+  steps?: number;
+  usage?: unknown;
+  error?: string;
+  message?: string;
+}
+
+export interface DevSessionRef {
+  sessionId: string;
+  continuationToken: string;
+}
+
+export interface SendTurnOptions {
+  /** When false, POST returns immediately; attach SSE for live step events. Default true. */
+  wait?: boolean;
+  onEvent?: (event: ParsedSessionEvent) => void;
+}
+
+function parseSseBlock(block: string): ParsedSessionEvent | null {
+  const lines = block.split("\n");
+  let eventType: SessionEventType | undefined;
+  let data = "";
+  for (const line of lines) {
+    if (line.startsWith("event: ")) eventType = line.slice(7).trim() as SessionEventType;
+    if (line.startsWith("data: ")) data += line.slice(6);
+  }
+  if (!eventType || !data) return null;
+  try {
+    const parsed = JSON.parse(data) as Record<string, unknown>;
+    return {
+      id: typeof parsed.id === "string" ? parsed.id : undefined,
+      type: eventType,
+      at: typeof parsed.at === "string" ? parsed.at : undefined,
+      message: typeof parsed.message === "string" ? parsed.message : undefined,
+      toolsUsed: Array.isArray(parsed.toolsUsed)
+        ? parsed.toolsUsed.filter((t): t is string => typeof t === "string")
+        : undefined,
+      text: typeof parsed.text === "string" ? parsed.text : parsed.text === null ? null : undefined,
+      steps: typeof parsed.steps === "number" ? parsed.steps : undefined,
+      usage: parsed.usage,
+      finishReason:
+        typeof parsed.finishReason === "string"
+          ? parsed.finishReason
+          : parsed.finishReason === null
+            ? null
+            : undefined,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export async function consumeSessionStream(
+  streamUrl: string,
+  onEvent: (event: ParsedSessionEvent) => void,
+  signal?: AbortSignal,
+): Promise<ParsedSessionEvent | null> {
+  const res = await fetch(streamUrl, { signal });
+  if (!res.ok || !res.body) {
+    throw new Error(`stream ${res.status}`);
+  }
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let terminal: ParsedSessionEvent | null = null;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    const blocks = buffer.split("\n\n");
+    buffer = blocks.pop() ?? "";
+    for (const block of blocks) {
+      const event = parseSseBlock(block);
+      if (!event) continue;
+      onEvent(event);
+      if (event.type === "turn:finish" || event.type === "turn:error") {
+        terminal = event;
+      }
+    }
+  }
+  if (buffer.trim()) {
+    const event = parseSseBlock(buffer);
+    if (event) {
+      onEvent(event);
+      if (event.type === "turn:finish" || event.type === "turn:error") terminal = event;
+    }
+  }
+  return terminal;
+}
+
+export class DevHttpSessionClient {
+  constructor(readonly baseUrl: string) {}
+
+  async fetchInfo(): Promise<ProjectInfoPayload> {
+    const res = await fetch(`${this.baseUrl}/plasm/v1/info`);
+    if (!res.ok) throw new Error(`info ${res.status}`);
+    return res.json() as Promise<ProjectInfoPayload>;
+  }
+
+  async sendTurn(
+    message: string,
+    session: DevSessionRef | null,
+    options: SendTurnOptions = {},
+  ): Promise<{ session: DevSessionRef; response: SessionTurnResponse }> {
+    const wait = options.wait ?? true;
+    const path = session
+      ? `${this.baseUrl}/plasm/v1/session/${session.sessionId}`
+      : `${this.baseUrl}/plasm/v1/session`;
+    const body = session
+      ? { message, continuationToken: session.continuationToken, wait }
+      : { message, wait };
+
+    if (!wait) {
+      const postRes = await fetch(path, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+      });
+      const json = (await postRes.json()) as SessionTurnResponse;
+      if (!json.sessionId || !json.continuationToken) {
+        throw new Error(json.message ?? json.error ?? `session ${postRes.status}`);
+      }
+      const ref = { sessionId: json.sessionId, continuationToken: json.continuationToken };
+      if (postRes.status >= 400) {
+        return { session: ref, response: json };
+      }
+      const terminal = await consumeSessionStream(
+        `${this.baseUrl}/plasm/v1/session/${ref.sessionId}/stream`,
+        (ev) => options.onEvent?.(ev),
+      );
+      const response: SessionTurnResponse = {
+        ...json,
+        text: terminal?.text ?? json.text,
+        steps: terminal?.steps ?? json.steps,
+        error: terminal?.type === "turn:error" ? "turn_failed" : json.error,
+        message: terminal?.message ?? json.message,
+        status: terminal?.type === "turn:error" ? "error" : "idle",
+      };
+      return { session: ref, response };
+    }
+
+    const res = await fetch(path, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    const json = (await res.json()) as SessionTurnResponse;
+    if (!json.sessionId || !json.continuationToken) {
+      throw new Error(json.message ?? json.error ?? `session ${res.status}`);
+    }
+    const ref = { sessionId: json.sessionId, continuationToken: json.continuationToken };
+    if (options.onEvent) {
+      await consumeSessionStream(
+        `${this.baseUrl}/plasm/v1/session/${ref.sessionId}/stream`,
+        options.onEvent,
+      );
+    }
+    return { session: ref, response: json };
+  }
+}

package/src/dev/client/repl.ts

@@ -0,0 +1,92 @@
+import * as readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+
+import { DevHttpSessionClient, type DevSessionRef } from "./http-session.js";
+import {
+  handleSlashCommand,
+  printAssistant,
+  printBanner,
+  printError,
+  printLines,
+  printMeta,
+  printStep,
+  printUserLine,
+  type SlashResult,
+} from "./slash.js";
+import type { ProjectInfoPayload } from "../../project-info.js";
+
+export interface DevTuiOptions {
+  baseUrl: string;
+}
+
+function applySlash(result: SlashResult): "quit" | "clear" | "handled" | "none" {
+  if (result.kind === "quit") return "quit";
+  if (result.kind === "clear_session") return "clear";
+  if (result.kind === "print") {
+    printLines(result.lines);
+    return "handled";
+  }
+  return "none";
+}
+
+export async function runDevTui(options: DevTuiOptions): Promise<void> {
+  const client = new DevHttpSessionClient(options.baseUrl);
+  let info: ProjectInfoPayload | null = null;
+  try {
+    info = await client.fetchInfo();
+  } catch (err) {
+    printError(`could not reach ${options.baseUrl}: ${String(err)}`);
+    return;
+  }
+
+  printBanner(options.baseUrl, info);
+  let session: DevSessionRef | null = null;
+  const rl = readline.createInterface({ input, output, terminal: true });
+
+  try {
+    while (true) {
+      const line = (await rl.question("› ")).trim();
+      if (!line) continue;
+
+      if (line.startsWith("/")) {
+        const slash = handleSlashCommand(line, { info, session, baseUrl: options.baseUrl });
+        const action = applySlash(slash);
+        if (action === "quit") break;
+        if (action === "clear") {
+          session = null;
+          printMeta("new session");
+        }
+        continue;
+      }
+
+      printUserLine(line);
+      try {
+        const { session: next, response } = await client.sendTurn(line, session, {
+          wait: false,
+          onEvent: (ev) => {
+            if (ev.type === "turn:step" && ev.toolsUsed?.length) {
+              printStep(ev.toolsUsed);
+            }
+            if (ev.type === "turn:error") {
+              printError(ev.message ?? "turn failed");
+            }
+          },
+        });
+        session = next;
+        if (response.error) {
+          printError(response.message ?? response.error);
+        } else if (response.text) {
+          printAssistant(response.text);
+        }
+        if (response.steps !== undefined) {
+          printMeta(`${response.steps} step(s)`);
+        }
+      } catch (err) {
+        printError(String(err));
+      }
+      console.log("");
+    }
+  } finally {
+    rl.close();
+  }
+}

package/src/dev/client/slash.ts

@@ -0,0 +1,119 @@
+import type { ProjectInfoPayload } from "../../project-info.js";
+import { ANSI, paint, wrap } from "./ansi.js";
+import type { DevSessionRef } from "./http-session.js";
+
+export interface SlashContext {
+  info: ProjectInfoPayload | null;
+  session: DevSessionRef | null;
+  baseUrl: string;
+}
+
+export type SlashResult =
+  | { kind: "continue" }
+  | { kind: "clear_session" }
+  | { kind: "quit" }
+  | { kind: "print"; lines: string[] };
+
+const HELP_LINES = [
+  "Slash commands:",
+  "  /help       this list",
+  "  /info       project + catalog summary",
+  "  /model      current agent model",
+  "  /channels   HTTP channel routes",
+  "  /catalogs   loaded catalogs",
+  "  /new        start a fresh session",
+  "  /quit       exit",
+];
+
+export function handleSlashCommand(input: string, ctx: SlashContext): SlashResult {
+  const cmd = input.trim().toLowerCase();
+  if (cmd === "/help" || cmd === "/?") {
+    return { kind: "print", lines: HELP_LINES };
+  }
+  if (cmd === "/quit" || cmd === "/exit" || cmd === "/q") {
+    return { kind: "quit" };
+  }
+  if (cmd === "/new") {
+    return { kind: "clear_session" };
+  }
+  if (cmd === "/info") {
+    if (!ctx.info) return { kind: "print", lines: ["info unavailable — server not reachable"] };
+    const i = ctx.info;
+    const lines = [
+      `${i.framework}  status=${i.status}`,
+      `project: ${i.projectRoot}`,
+      `gateway: ${i.gateway.configured ? "configured" : "missing"}`,
+      `catalogs: ${i.discovery.catalogs.length}  channels: ${i.discovery.channels.length}`,
+      `skills: ${i.discovery.skills.length}  subagents: ${i.loadedSlots.subagents.length}`,
+    ];
+    if (ctx.session) {
+      lines.push(`session: ${ctx.session.sessionId.slice(0, 8)}…`);
+    }
+    return { kind: "print", lines };
+  }
+  if (cmd === "/model") {
+    const model = ctx.info?.dev?.model ?? "(unknown — start dev server or /info)";
+    return { kind: "print", lines: [`model: ${String(model)}`] };
+  }
+  if (cmd === "/channels") {
+    const routes = ctx.info?.dev?.routes.channels ?? [];
+    if (!routes.length) return { kind: "print", lines: ["no channels loaded"] };
+    return {
+      kind: "print",
+      lines: routes.map((r) => `  ${r.method} ${r.path}`),
+    };
+  }
+  if (cmd === "/catalogs") {
+    const catalogs = ctx.info?.catalogs ?? [];
+    if (!catalogs.length) return { kind: "print", lines: ["no catalogs"] };
+    return {
+      kind: "print",
+      lines: catalogs.map((c) => {
+        const fresh = c.stubFresh?.fresh ? "fresh" : c.stubFresh ? "stale" : "missing";
+        return `  ${c.name}  stub=${fresh}`;
+      }),
+    };
+  }
+  return { kind: "print", lines: [`unknown command ${cmd} — try /help`] };
+}
+
+export function printBanner(baseUrl: string, info: ProjectInfoPayload | null): void {
+  const title = paint("plasm-agent dev", ANSI.bold, ANSI.cyan);
+  const url = paint(baseUrl, ANSI.dim);
+  console.log(`\n${title}  ${url}`);
+  if (info?.dev?.model) {
+    console.log(paint(`model: ${String(info.dev.model)}`, ANSI.dim));
+  }
+  console.log(paint("Type a message or /help.  /quit to exit.", ANSI.dim));
+  console.log("");
+}
+
+export function printUserLine(text: string): void {
+  console.log(paint("you › ", ANSI.bold, ANSI.green) + text);
+}
+
+export function printAssistant(text: string): void {
+  const prefix = paint("agent › ", ANSI.bold, ANSI.magenta);
+  for (const line of wrap(text)) {
+    console.log(prefix + line);
+  }
+}
+
+export function printMeta(text: string): void {
+  console.log(paint(text, ANSI.dim));
+}
+
+export function printError(text: string): void {
+  console.log(paint(`error: ${text}`, ANSI.red));
+}
+
+export function printStep(tools: string[]): void {
+  if (!tools.length) return;
+  console.log(paint(`  · tools: ${tools.join(", ")}`, ANSI.blue));
+}
+
+export function printLines(lines: string[]): void {
+  for (const line of lines) {
+    console.log(paint(line, ANSI.yellow));
+  }
+}