@plasm_lang/vercel-agent 0.3.63

package/src/runtime/plasm-agent.ts

@@ -0,0 +1,199 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { generateText, stepCountIs, type LanguageModel, type ModelMessage, type ToolSet } from "ai";
+
+import type {
+  AgentBuildConfig,
+  AgentCompactionConfig,
+  AgentExperimentalConfig,
+  AgentModelOptions,
+} from "../define-agent.js";
+import type { AuthoringContext } from "../authoring/context.js";
+import type { HookRunner } from "../authoring/hook-runner.js";
+import type { SkillDefinition } from "../authoring/define-skill.js";
+import type { SubagentRegistry } from "../authoring/subagent-loader.js";
+import { resolveGatewayModel } from "../gateway-model.js";
+import { createAgentTelemetry } from "../instrumentation.js";
+import { maybeCompactMessages } from "../runtime/compaction.js";
+import { AgentRuntime, type AgentRuntimeConfig } from "../runtime/agent-runtime.js";
+import { createHarnessTools, renderSkillIndex } from "../tools/harness-tools.js";
+import { createPlasmTools } from "../tools/plasm-tools.js";
+
+export interface PlasmAgentConfig extends AgentRuntimeConfig {
+  /** AI Gateway model slug, e.g. `anthropic/claude-sonnet-4.6`. */
+  model: string | LanguageModel;
+  instructionsPath?: string;
+  maxSteps?: number;
+  telemetry?: boolean;
+  compaction?: AgentCompactionConfig;
+  modelOptions?: AgentModelOptions;
+  build?: AgentBuildConfig;
+  experimental?: AgentExperimentalConfig;
+  loadedSkills?: SkillDefinition[];
+  hookRunner?: HookRunner;
+  subagentRegistry?: SubagentRegistry;
+  getAuthoringContext?: () => AuthoringContext;
+}
+
+export interface AgentStepEvent {
+  toolCalls?: Array<{ toolName: string }>;
+  text?: string;
+  finishReason?: string;
+}
+
+export interface AgentGenerateOptions {
+  messages?: ModelMessage[];
+  resetConversation?: boolean;
+  onStepFinish?: (step: AgentStepEvent) => void | Promise<void>;
+}
+
+export interface AgentTurnResult {
+  text: string;
+  steps: unknown[];
+  usage: Awaited<ReturnType<typeof generateText>>["usage"];
+}
+
+export class PlasmAgent {
+  readonly runtime: AgentRuntime;
+  private readonly model: string | LanguageModel;
+  private readonly instructionsPath: string;
+  private readonly maxSteps: number;
+  private readonly modelOptions?: AgentModelOptions;
+  private readonly telemetryEnabled: boolean;
+  private readonly loadedSkills: SkillDefinition[];
+  private readonly skillsMode: false | "index" | "inline";
+  private readonly compaction?: AgentCompactionConfig;
+  private readonly hookRunner?: HookRunner;
+  private readonly subagentRegistry?: SubagentRegistry;
+  private readonly getAuthoringContext?: () => AuthoringContext;
+  private conversation: ModelMessage[] = [];
+
+  constructor(config: PlasmAgentConfig) {
+    this.runtime = new AgentRuntime(config);
+    this.model = config.model;
+    this.modelOptions = config.modelOptions;
+    this.instructionsPath =
+      config.instructionsPath ?? path.join(config.agentRoot, "instructions.md");
+    this.maxSteps = config.maxSteps ?? 20;
+    this.telemetryEnabled = config.telemetry ?? true;
+    this.loadedSkills = config.loadedSkills ?? [];
+    this.compaction = config.compaction;
+    const skillsFlag = config.experimental?.skills;
+    if (this.loadedSkills.length === 0 || skillsFlag === false) {
+      this.skillsMode = false;
+    } else if (skillsFlag === "inline") {
+      this.skillsMode = "inline";
+    } else {
+      this.skillsMode = "index";
+    }
+    this.hookRunner = config.hookRunner;
+    this.subagentRegistry = config.subagentRegistry;
+    this.getAuthoringContext = config.getAuthoringContext;
+  }
+
+  async bootstrap(): Promise<void> {
+    await this.runtime.bootstrap();
+  }
+
+  async loadInstructions(): Promise<string> {
+    let base: string;
+    try {
+      base = (await readFile(this.instructionsPath, "utf8")).trim();
+    } catch {
+      base = [
+        "You are a catalog-native Plasm agent.",
+        "Use discover_capabilities → plasm_context → plasm → plasm_run.",
+        "Keep one stable intent per user goal.",
+      ].join("\n");
+    }
+
+    if (this.skillsMode === "inline") {
+      const skillBlock = this.loadedSkills
+        .map((skill) => `## Skill: ${skill.name}\n${skill.body.trim()}`)
+        .join("\n\n");
+      return `${base}\n\n# Skills\n\n${skillBlock}`;
+    }
+
+    if (this.skillsMode === "index") {
+      return `${base}\n\n${renderSkillIndex(this.loadedSkills)}`;
+    }
+
+    return base;
+  }
+
+  async generate(
+    prompt: string,
+    options: AgentGenerateOptions = {},
+  ): Promise<AgentTurnResult> {
+    if (this.hookRunner && this.getAuthoringContext) {
+      await this.hookRunner.emit("agent:start", this.getAuthoringContext(), { prompt });
+    }
+
+    const system = await this.loadInstructions();
+    const plasmTools = createPlasmTools(this.runtime);
+    const harnessTools = createHarnessTools({
+      skills: this.skillsMode === "index" ? this.loadedSkills : undefined,
+      subagents: this.subagentRegistry,
+    });
+    const tools = {
+      ...plasmTools,
+      ...harnessTools,
+    } as ToolSet;
+
+    const telemetry = this.telemetryEnabled
+      ? createAgentTelemetry({ serviceName: "plasm-agent" })
+      : { isEnabled: false };
+    const model = resolveGatewayModel(this.model, this.modelOptions);
+
+    const externalMessages = options.messages !== undefined;
+    let messages: ModelMessage[];
+    if (externalMessages) {
+      messages = options.messages ?? [];
+    } else if (options.resetConversation) {
+      this.conversation = [{ role: "user", content: prompt }];
+      messages = this.conversation;
+    } else {
+      this.conversation.push({ role: "user", content: prompt });
+      messages = this.conversation;
+    }
+
+    messages = await maybeCompactMessages(messages, this.compaction, this.model);
+
+    const generation = {
+      model,
+      system,
+      tools,
+      stopWhen: stepCountIs(this.maxSteps),
+      experimental_telemetry: telemetry,
+      onStepFinish: async (step: AgentStepEvent) => {
+        await options.onStepFinish?.(step);
+        if (!this.hookRunner || !this.getAuthoringContext) return;
+        const toolsUsed = (step.toolCalls ?? []).map((call) => call.toolName);
+        await this.hookRunner.emit("agent:step", this.getAuthoringContext(), { toolsUsed });
+      },
+      ...(this.modelOptions?.temperature !== undefined
+        ? { temperature: this.modelOptions.temperature }
+        : {}),
+      ...(this.modelOptions?.maxOutputTokens !== undefined
+        ? { maxOutputTokens: this.modelOptions.maxOutputTokens }
+        : {}),
+      ...(this.modelOptions?.topP !== undefined ? { topP: this.modelOptions.topP } : {}),
+      ...(this.modelOptions?.topK !== undefined ? { topK: this.modelOptions.topK } : {}),
+    };
+
+    const result = await generateText({
+      ...generation,
+      messages,
+    });
+
+    if (!externalMessages) {
+      this.conversation.push({ role: "assistant", content: result.text });
+    }
+    return {
+      text: result.text,
+      steps: result.steps,
+      usage: result.usage,
+    };
+  }
+}

package/src/server/plasm-handler.ts

@@ -0,0 +1,331 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import path from "node:path";
+
+import type { AgentDefinition } from "../define-agent.js";
+import {
+  createAgentFromDefinition,
+  resolveAgentDefinition,
+} from "../define-agent.js";
+import { createAuthoringContext, type AuthoringContext } from "../authoring/context.js";
+import { tryHandleChannelRoute } from "../authoring/channel-dispatch.js";
+import {
+  loadAuthoredSlots,
+  type LoadedProjectSlots,
+} from "../authoring/slot-loader.js";
+import {
+  createSubagentRegistry,
+  loadSubagents,
+  summarizeSubagents,
+  type SubagentRegistry,
+} from "../authoring/subagent-loader.js";
+import {
+  startScheduleTimers,
+  tryHandleScheduleCronRoute,
+  type ScheduleHandle,
+} from "../authoring/schedule-manager.js";
+import { walkAgentProject, type ProjectDiscovery } from "../discovery/project-walker.js";
+import { collectProjectInfo } from "../project-info.js";
+import type { PlasmAgent } from "../runtime/plasm-agent.js";
+import { DevSessionStore } from "../dev/dev-session.js";
+import { sendJson } from "../dev/http.js";
+import { tryHandleSessionRoutes } from "../dev/session-routes.js";
+import { nitroOperatorHandler } from "../operator/routes.js";
+import { renderOperatorShell } from "../operator/ui-shell.js";
+
+export type PlasmAppMode = "dev" | "prod";
+
+export interface PlasmAppOptions {
+  agentRoot: string;
+  definition: AgentDefinition;
+  mode?: PlasmAppMode;
+  tenantScope?: string;
+  maxSteps?: number;
+  telemetry?: boolean;
+  /** Session SSE routes; default true in dev, false in prod. */
+  sessions?: boolean;
+}
+
+export interface PlasmApp {
+  agentRoot: string;
+  projectRoot: string;
+  definition: AgentDefinition;
+  mode: PlasmAppMode;
+  sessionsEnabled: boolean;
+  reload(): Promise<void>;
+  getAgent(): Promise<PlasmAgent>;
+  getDiscovery(): Promise<ProjectDiscovery>;
+  getLoadedSlots(): Promise<LoadedProjectSlots | undefined>;
+  getSubagents(): Promise<ReturnType<typeof summarizeSubagents>>;
+  getAuthoringContext(): AuthoringContext;
+  sessionStore: DevSessionStore | undefined;
+  handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void>;
+  handleOperatorRequest(req: IncomingMessage, res: ServerResponse): Promise<void>;
+}
+
+export type VercelHandler = (
+  req: IncomingMessage,
+  res: ServerResponse,
+) => void | Promise<void>;
+
+/** Strip `/api` prefix from Vercel catch-all rewrites so routes match dev paths. */
+export function normalizePlasmPathname(url: string | undefined): string {
+  const pathname = new URL(url ?? "/", "http://localhost").pathname;
+  if (pathname === "/api" || pathname === "/api/") return "/";
+  if (pathname.startsWith("/api/")) return pathname.slice(4) || "/";
+  return pathname;
+}
+
+export function rewriteRequestPath(req: IncomingMessage): IncomingMessage {
+  const pathname = normalizePlasmPathname(req.url);
+  const original = req.url ?? "/";
+  const query = original.includes("?") ? original.slice(original.indexOf("?")) : "";
+  const proxy = Object.create(req) as IncomingMessage;
+  Object.defineProperty(proxy, "url", {
+    value: `${pathname}${query}`,
+    writable: true,
+    configurable: true,
+  });
+  return proxy;
+}
+
+export async function handlePlasmRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  app: PlasmApp,
+): Promise<void> {
+  const method = req.method ?? "GET";
+  const url = new URL(req.url ?? "/", "http://localhost");
+
+  if (method === "GET" && url.pathname === "/plasm/v1/health") {
+    sendJson(res, 200, { status: "ok" });
+    return;
+  }
+
+  if (method === "GET" && url.pathname === "/plasm/v1/info") {
+    const discovery = await app.getDiscovery();
+    const loadedSlots = await app.getLoadedSlots();
+    const subagents = await app.getSubagents();
+    if (!loadedSlots) {
+      sendJson(res, 503, { error: "slots_not_ready" });
+      return;
+    }
+    const info = await collectProjectInfo({
+      projectRoot: app.projectRoot,
+      agentRoot: app.agentRoot,
+      cached: { discovery, loadedSlots, subagents },
+      dev:
+        app.mode === "dev"
+          ? {
+              definition: app.definition,
+              sessionCount: app.sessionStore?.list().length ?? 0,
+            }
+          : undefined,
+    });
+    sendJson(res, 200, info);
+    return;
+  }
+
+  const loadedSlots = await app.getLoadedSlots();
+  if (loadedSlots?.schedules.length) {
+    const handledCron = tryHandleScheduleCronRoute(
+      req,
+      res,
+      loadedSlots.schedules,
+      app.getAuthoringContext(),
+    );
+    if (handledCron) return;
+  }
+
+  if (loadedSlots?.channels.length) {
+    const handled = tryHandleChannelRoute(
+      req,
+      res,
+      loadedSlots.channels,
+      app.getAuthoringContext(),
+    );
+    if (handled) return;
+  }
+
+  if (
+    app.sessionsEnabled &&
+    app.sessionStore &&
+    (await tryHandleSessionRoutes(req, res, url, {
+      sessionStore: app.sessionStore,
+      getAgent: app.getAgent,
+    }))
+  ) {
+    return;
+  }
+
+  sendJson(res, 404, { error: "not_found", path: url.pathname });
+}
+
+export async function handlePlasmOperatorRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  app: PlasmApp,
+): Promise<void> {
+  const url = new URL(req.url ?? "/", "http://localhost");
+  if (req.method === "GET" && (url.pathname === "/operator" || url.pathname === "/operator/")) {
+    res.statusCode = 200;
+    res.setHeader("content-type", "text/html; charset=utf-8");
+    res.end(renderOperatorShell("/operator"));
+    return;
+  }
+
+  const operatorHandler = nitroOperatorHandler({
+    agentRoot: app.agentRoot,
+    runtime: undefined,
+  });
+
+  const opReq = {
+    req: { method: req.method, url: url.pathname + url.search },
+    res: {
+      statusCode: 200,
+      end: (body: string) => {
+        res.statusCode = opReq.res.statusCode;
+        res.setHeader("content-type", "application/json; charset=utf-8");
+        res.end(body);
+      },
+    },
+  };
+  await operatorHandler(opReq);
+}
+
+export async function createPlasmApp(options: PlasmAppOptions): Promise<PlasmApp> {
+  const agentRoot = path.resolve(options.agentRoot);
+  const projectRoot = path.dirname(agentRoot);
+  const mode = options.mode ?? "prod";
+  const sessionsEnabled = options.sessions ?? mode === "dev";
+  const definition = resolveAgentDefinition(options.definition, agentRoot);
+  const sessionStore = sessionsEnabled ? new DevSessionStore() : undefined;
+
+  let agent: PlasmAgent | undefined;
+  let discovery: ProjectDiscovery | undefined;
+  let loadedSlots: LoadedProjectSlots | undefined;
+  let subagentRegistry: SubagentRegistry | undefined;
+  let subagentSummary: ReturnType<typeof summarizeSubagents> = [];
+  let scheduleHandle: ScheduleHandle | undefined;
+  let importCacheBust = Date.now();
+
+  const getAuthoringContext = () =>
+    createAuthoringContext({
+      agentRoot,
+      getAgent: async () => agent ?? bootstrap(),
+      importCacheBust,
+    });
+
+  const bootstrap = async (): Promise<PlasmAgent> => {
+    agent = await createAgentFromDefinition(definition, {
+      agentRoot,
+      tenantScope: options.tenantScope,
+      maxSteps: options.maxSteps,
+      telemetry: options.telemetry,
+      loadedSlots,
+      subagentRegistry,
+      getAuthoringContext,
+    });
+    return agent;
+  };
+
+  const refreshDiscovery = async (): Promise<ProjectDiscovery> => {
+    discovery = await walkAgentProject(agentRoot);
+    return discovery;
+  };
+
+  const refreshSlots = async (): Promise<LoadedProjectSlots> => {
+    const currentDiscovery = discovery ?? (await refreshDiscovery());
+    loadedSlots = await loadAuthoredSlots({
+      discovery: currentDiscovery,
+      importCacheBust,
+    });
+    return loadedSlots;
+  };
+
+  const refreshSubagents = async (): Promise<SubagentRegistry> => {
+    const currentDiscovery = discovery ?? (await refreshDiscovery());
+    const loaded = await loadSubagents({
+      discovery: currentDiscovery,
+      parentSlots: loadedSlots,
+      tenantScope: options.tenantScope,
+      maxSteps: options.maxSteps,
+      telemetry: options.telemetry,
+      importCacheBust,
+    });
+    if (loadedSlots) {
+      loadedSlots.diagnostics.push(...loaded.diagnostics);
+    }
+    subagentRegistry = createSubagentRegistry(loaded.subagents);
+    subagentSummary = summarizeSubagents(loaded.subagents, agentRoot);
+    return subagentRegistry;
+  };
+
+  const reload = async (): Promise<void> => {
+    importCacheBust = Date.now();
+    scheduleHandle?.stop();
+    await refreshDiscovery();
+    await refreshSlots();
+    await refreshSubagents();
+    await bootstrap();
+    if (mode === "dev") {
+      scheduleHandle = startScheduleTimers(
+        loadedSlots?.schedules ?? [],
+        getAuthoringContext(),
+        definition.experimental?.workflow,
+      );
+    }
+    if (loadedSlots?.hookRunner) {
+      await loadedSlots.hookRunner.emit("agent:start", getAuthoringContext(), {
+        reason: mode === "dev" ? "hot_reload" : "bootstrap",
+      });
+    }
+  };
+
+  await reload();
+
+  const getAgent = async () => agent ?? bootstrap();
+  const getDiscovery = async () => discovery ?? refreshDiscovery();
+  const getLoadedSlots = async () => loadedSlots ?? refreshSlots();
+  const getSubagents = async () => {
+    if (!subagentRegistry) await refreshSubagents();
+    return subagentSummary;
+  };
+
+  const app: PlasmApp = {
+    agentRoot,
+    projectRoot,
+    definition,
+    mode,
+    sessionsEnabled,
+    reload,
+    getAgent,
+    getDiscovery,
+    getLoadedSlots,
+    getSubagents,
+    getAuthoringContext,
+    sessionStore,
+    handleRequest: (req, res) => handlePlasmRequest(req, res, app),
+    handleOperatorRequest: (req, res) => handlePlasmOperatorRequest(req, res, app),
+  };
+
+  return app;
+}
+
+export function vercelPlasmHandler(app: PlasmApp): VercelHandler {
+  return async (req, res) => {
+    const proxied = rewriteRequestPath(req);
+    const url = new URL(proxied.url ?? "/", "http://localhost");
+    try {
+      if (url.pathname === "/operator" || url.pathname.startsWith("/operator/")) {
+        await app.handleOperatorRequest(proxied, res);
+        return;
+      }
+      await app.handleRequest(proxied, res);
+    } catch (err) {
+      console.error("[plasm:vercel] request error:", err);
+      if (!res.writableEnded) {
+        sendJson(res, 500, { error: "internal_error", message: String(err) });
+      }
+    }
+  };
+}

package/src/session-state.ts

@@ -0,0 +1,135 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import type { SymbolRegistrySnapshot } from "./symbol-registry.js";
+
+export interface ExecuteSessionRef {
+  promptHash: string;
+  sessionId: string;
+}
+
+export interface TeachingWave {
+  entryId: string;
+  entities: string[];
+  tsv: string;
+  at: string;
+}
+
+export interface AgentSessionState {
+  intent: string;
+  logicalSessionRef: string;
+  logicalSessionId: string;
+  tenantScope: string;
+  seeds: Array<{ api: string; entity: string }>;
+  teachingTsv: string;
+  waves: TeachingWave[];
+  symbolRegistry?: SymbolRegistrySnapshot;
+  planCommits: Array<{ ref: string; program: string; at: string }>;
+  updatedAt: string;
+}
+
+export interface SessionStore {
+  get(intent: string): Promise<AgentSessionState | null>;
+  put(state: AgentSessionState): Promise<void>;
+  listIntents(): Promise<string[]>;
+}
+
+function intentKey(intent: string): string {
+  return Buffer.from(intent, "utf8").toString("base64url");
+}
+
+export class LocalSessionStore implements SessionStore {
+  constructor(private readonly rootDir: string) {}
+
+  private sessionDir(): string {
+    return path.join(this.rootDir, ".plasm", "sessions");
+  }
+
+  private sessionPath(intent: string): string {
+    return path.join(this.sessionDir(), `${intentKey(intent)}.json`);
+  }
+
+  private teachingPath(intent: string): string {
+    return path.join(this.sessionDir(), `${intentKey(intent)}.teaching.tsv`);
+  }
+
+  async get(intent: string): Promise<AgentSessionState | null> {
+    try {
+      const raw = await readFile(this.sessionPath(intent), "utf8");
+      return JSON.parse(raw) as AgentSessionState;
+    } catch {
+      return null;
+    }
+  }
+
+  async put(state: AgentSessionState): Promise<void> {
+    const dir = this.sessionDir();
+    await mkdir(dir, { recursive: true });
+    await writeFile(this.sessionPath(state.intent), JSON.stringify(state, null, 2), "utf8");
+    await writeFile(this.teachingPath(state.intent), state.teachingTsv, "utf8");
+  }
+
+  async listIntents(): Promise<string[]> {
+    try {
+      const dir = this.sessionDir();
+      const files = await readdir(dir);
+      const intents: string[] = [];
+      for (const file of files) {
+        if (!file.endsWith(".json")) continue;
+        const raw = await readFile(path.join(dir, file), "utf8");
+        const state = JSON.parse(raw) as AgentSessionState;
+        intents.push(state.intent);
+      }
+      return intents;
+    } catch {
+      return [];
+    }
+  }
+}
+
+export class SessionManager {
+  constructor(
+    readonly store: SessionStore,
+    private readonly tenantScope = "local",
+  ) {}
+
+  tenant(): string {
+    return this.tenantScope;
+  }
+
+  async get(intent: string): Promise<AgentSessionState | null> {
+    return this.store.get(intent);
+  }
+
+  async getByLogicalRef(ref: string): Promise<AgentSessionState | null> {
+    const intents = await this.store.listIntents();
+    for (const intent of intents) {
+      const session = await this.store.get(intent);
+      if (session?.logicalSessionRef === ref) return session;
+    }
+    return null;
+  }
+
+  async getOrCreate(intent: string, logicalSessionRef: string, logicalSessionId: string) {
+    const existing = await this.store.get(intent);
+    if (existing) return existing;
+    const fresh: AgentSessionState = {
+      intent,
+      logicalSessionRef,
+      logicalSessionId,
+      tenantScope: this.tenantScope,
+      seeds: [],
+      teachingTsv: "",
+      waves: [],
+      planCommits: [],
+      updatedAt: new Date().toISOString(),
+    };
+    await this.store.put(fresh);
+    return fresh;
+  }
+
+  async update(state: AgentSessionState): Promise<void> {
+    state.updatedAt = new Date().toISOString();
+    await this.store.put(state);
+  }
+}