@plasm_lang/vercel-agent 0.3.63

package/src/dev/dev-session.ts

@@ -0,0 +1,153 @@
+import { randomUUID } from "node:crypto";
+import type { ModelMessage } from "ai";
+
+import type { PlasmAgent } from "../runtime/plasm-agent.js";
+import type { AgentTurnResult } from "../runtime/plasm-agent.js";
+
+export type SessionEventType =
+  | "turn:start"
+  | "turn:step"
+  | "turn:finish"
+  | "turn:error";
+
+export interface SessionEvent {
+  id: string;
+  type: SessionEventType;
+  at: string;
+  data: Record<string, unknown>;
+}
+
+export interface DevSessionRecord {
+  id: string;
+  continuationToken: string;
+  createdAt: string;
+  updatedAt: string;
+  status: "idle" | "running" | "error";
+  messages: ModelMessage[];
+  events: SessionEvent[];
+  lastText?: string;
+  lastError?: string;
+}
+
+type SessionListener = (event: SessionEvent) => void;
+
+export class DevSessionStore {
+  private readonly sessions = new Map<string, DevSessionRecord>();
+  private readonly listeners = new Map<string, Set<SessionListener>>();
+
+  list(): DevSessionRecord[] {
+    return [...this.sessions.values()];
+  }
+
+  get(sessionId: string): DevSessionRecord | undefined {
+    return this.sessions.get(sessionId);
+  }
+
+  create(): DevSessionRecord {
+    const id = randomUUID();
+    const record: DevSessionRecord = {
+      id,
+      continuationToken: id,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      status: "idle",
+      messages: [],
+      events: [],
+    };
+    this.sessions.set(id, record);
+    return record;
+  }
+
+  subscribe(sessionId: string, listener: SessionListener): () => void {
+    let set = this.listeners.get(sessionId);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(sessionId, set);
+    }
+    set.add(listener);
+    return () => {
+      set?.delete(listener);
+      if (set && set.size === 0) this.listeners.delete(sessionId);
+    };
+  }
+
+  private pushEvent(
+    session: DevSessionRecord,
+    type: SessionEventType,
+    data: Record<string, unknown>,
+  ): SessionEvent {
+    const event: SessionEvent = {
+      id: randomUUID(),
+      type,
+      at: new Date().toISOString(),
+      data,
+    };
+    session.events.push(event);
+    session.updatedAt = event.at;
+    const listeners = this.listeners.get(session.id);
+    if (listeners) {
+      for (const listener of listeners) listener(event);
+    }
+    return event;
+  }
+
+  validateContinuation(sessionId: string, token?: string): DevSessionRecord | null {
+    const session = this.sessions.get(sessionId);
+    if (!session) return null;
+    if (!token || token !== session.continuationToken) return null;
+    return session;
+  }
+
+  async runTurn(
+    session: DevSessionRecord,
+    message: string,
+    agent: PlasmAgent,
+  ): Promise<AgentTurnResult> {
+    if (session.status === "running") {
+      throw new Error("session_busy");
+    }
+
+    session.status = "running";
+    session.messages.push({ role: "user", content: message });
+    this.pushEvent(session, "turn:start", { message });
+
+    try {
+      const result = await agent.generate(message, {
+        messages: [...session.messages],
+        onStepFinish: async (step) => {
+          const toolsUsed = (step.toolCalls ?? []).map((call) => call.toolName);
+          this.pushEvent(session, "turn:step", {
+            toolsUsed,
+            text: step.text ?? null,
+            finishReason: step.finishReason ?? null,
+          });
+        },
+      });
+
+      session.messages.push({ role: "assistant", content: result.text });
+      session.lastText = result.text;
+      session.status = "idle";
+      this.pushEvent(session, "turn:finish", {
+        text: result.text,
+        steps: result.steps.length,
+        usage: result.usage,
+      });
+      return result;
+    } catch (err) {
+      session.status = "error";
+      session.lastError = String(err);
+      this.pushEvent(session, "turn:error", { message: session.lastError });
+      throw err;
+    }
+  }
+}
+
+export function formatSseEvent(event: SessionEvent): string {
+  const payload = JSON.stringify({
+    id: event.id,
+    type: event.type,
+    at: event.at,
+    ...event.data,
+  });
+  return `event: ${event.type}\ndata: ${payload}\n\n`;
+}

package/src/dev/http.ts

@@ -0,0 +1,29 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+export function readJsonBody(req: IncomingMessage): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    let body = "";
+    req.on("data", (chunk) => {
+      body += chunk;
+    });
+    req.on("end", () => {
+      if (!body.trim()) {
+        resolve({});
+        return;
+      }
+      try {
+        resolve(JSON.parse(body));
+      } catch (err) {
+        reject(err);
+      }
+    });
+    req.on("error", reject);
+  });
+}
+
+export 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);
+}

package/src/dev/server.ts

@@ -0,0 +1,147 @@
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import { watch, type FSWatcher } from "node:fs";
+import path from "node:path";
+
+import type { AgentDefinition } from "../define-agent.js";
+import { sendJson } from "./http.js";
+import {
+  createPlasmApp,
+  handlePlasmOperatorRequest,
+  handlePlasmRequest,
+  type PlasmApp,
+} from "../server/plasm-handler.js";
+
+export interface DevServerOptions {
+  agentRoot: string;
+  definition: AgentDefinition;
+  port?: number;
+  host?: string;
+  tenantScope?: string;
+  maxSteps?: number;
+  telemetry?: boolean;
+}
+
+export interface DevServerHandle {
+  server: Server;
+  url: string;
+  close(): Promise<void>;
+  reload(): Promise<void>;
+}
+
+const HOT_RELOAD_PATHS = [
+  "catalogs",
+  "skills",
+  "channels",
+  "schedules",
+  "hooks",
+  "subagents",
+  "instructions.md",
+  "instructions.ts",
+] as const;
+
+function watchHotReload(
+  agentRoot: string,
+  onChange: () => void,
+): FSWatcher[] {
+  const watchers: FSWatcher[] = [];
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const schedule = () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = undefined;
+      onChange();
+    }, 150);
+  };
+
+  for (const relative of HOT_RELOAD_PATHS) {
+    const target = path.join(agentRoot, relative);
+    try {
+      const recursive = !relative.endsWith(".md") && !relative.endsWith(".ts");
+      const watcher = watch(target, { recursive }, schedule);
+      watchers.push(watcher);
+    } catch {
+      // Missing slot at dev start — discovery will report warnings.
+    }
+  }
+
+  return watchers;
+}
+
+async function routeDevRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  app: PlasmApp,
+): Promise<void> {
+  const url = new URL(req.url ?? "/", "http://localhost");
+  if (url.pathname === "/operator" || url.pathname.startsWith("/operator/")) {
+    await handlePlasmOperatorRequest(req, res, app);
+    return;
+  }
+  await handlePlasmRequest(req, res, app);
+}
+
+export async function createDevServer(options: DevServerOptions): Promise<DevServerHandle> {
+  const agentRoot = path.resolve(options.agentRoot);
+
+  const app = await createPlasmApp({
+    agentRoot,
+    definition: options.definition,
+    mode: "dev",
+    tenantScope: options.tenantScope,
+    maxSteps: options.maxSteps,
+    telemetry: options.telemetry,
+    sessions: true,
+  });
+
+  const reload = async (): Promise<void> => {
+    await app.reload();
+  };
+
+  const watchers = watchHotReload(agentRoot, () => {
+    void reload().catch((err) => {
+      console.error("[plasm:dev] hot reload failed:", err);
+    });
+  });
+
+  const host = options.host ?? "127.0.0.1";
+  const port = options.port ?? 3000;
+
+  const server = createServer((req, res) => {
+    void routeDevRequest(req, res, app).catch((err) => {
+      console.error("[plasm:dev] request error:", err);
+      sendJson(res, 500, { error: "internal_error", message: String(err) });
+    });
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, host, () => resolve());
+  });
+
+  const address = server.address();
+  const resolvedPort =
+    typeof address === "object" && address ? address.port : port;
+  const url = `http://${host}:${resolvedPort}`;
+
+  return {
+    server,
+    url,
+    reload,
+    close: () =>
+      new Promise((resolve, reject) => {
+        for (const watcher of watchers) watcher.close();
+        server.close((err) => (err ? reject(err) : resolve()));
+      }),
+  };
+}
+
+export async function startDevServer(options: DevServerOptions): Promise<DevServerHandle> {
+  const handle = await createDevServer(options);
+  console.log(`[plasm:dev] listening on ${handle.url}`);
+  console.log(`[plasm:dev] GET  ${handle.url}/plasm/v1/info`);
+  console.log(`[plasm:dev] POST ${handle.url}/plasm/v1/session`);
+  console.log(`[plasm:dev] GET  ${handle.url}/plasm/v1/session/:id/stream`);
+  console.log(`[plasm:dev] GET  ${handle.url}/operator`);
+  return handle;
+}

package/src/dev/session-routes.ts

@@ -0,0 +1,185 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
+
+import type { PlasmAgent, AgentTurnResult } from "../runtime/plasm-agent.js";
+import { readJsonBody, sendJson } from "./http.js";
+import {
+  DevSessionStore,
+  formatSseEvent,
+  type DevSessionRecord,
+} from "./dev-session.js";
+
+const newSessionBody = z.object({
+  message: z.string().trim().min(1),
+  wait: z.boolean().optional(),
+});
+
+const continueSessionBody = z.object({
+  message: z.string().trim().min(1),
+  continuationToken: z.string().trim().min(1),
+  wait: z.boolean().optional(),
+});
+
+export interface SessionRouteContext {
+  sessionStore: DevSessionStore;
+  getAgent: () => Promise<PlasmAgent>;
+}
+
+function sessionJson(
+  session: DevSessionRecord,
+  extra: Record<string, unknown> = {},
+): Record<string, unknown> {
+  return {
+    sessionId: session.id,
+    continuationToken: session.continuationToken,
+    status: session.status,
+    ...extra,
+  };
+}
+
+async function respondSessionTurn(
+  res: ServerResponse,
+  session: DevSessionRecord,
+  run: () => Promise<AgentTurnResult>,
+): Promise<void> {
+  try {
+    const result = await run();
+    sendJson(res, 200, sessionJson(session, {
+      text: result.text,
+      usage: result.usage,
+      steps: result.steps.length,
+    }));
+  } catch (err) {
+    sendJson(res, 500, sessionJson(session, {
+      error: "turn_failed",
+      message: String(err),
+    }));
+  }
+}
+
+function startAsyncTurn(
+  session: DevSessionRecord,
+  message: string,
+  agent: PlasmAgent,
+  sessionStore: DevSessionStore,
+): void {
+  void sessionStore.runTurn(session, message, agent).catch((err) => {
+    console.error("[plasm:dev] async turn failed:", err);
+  });
+}
+
+function handleSessionStream(
+  res: ServerResponse,
+  session: DevSessionRecord,
+  sessionStore: DevSessionStore,
+): void {
+  res.statusCode = 200;
+  res.setHeader("content-type", "text/event-stream; charset=utf-8");
+  res.setHeader("cache-control", "no-cache");
+  res.setHeader("connection", "keep-alive");
+
+  for (const event of session.events) {
+    res.write(formatSseEvent(event));
+  }
+
+  const terminal = session.status === "idle" || session.status === "error";
+  if (terminal) {
+    res.end();
+    return;
+  }
+
+  let unsubscribe = () => {};
+  unsubscribe = sessionStore.subscribe(session.id, (event) => {
+    res.write(formatSseEvent(event));
+    if (event.type === "turn:finish" || event.type === "turn:error") {
+      unsubscribe();
+      res.end();
+    }
+  });
+  res.on("close", unsubscribe);
+}
+
+/**
+ * Session routes. `wait: false` returns immediately (202) and runs the turn in the background;
+ * clients attach to GET /stream for step events. Default `wait: true` blocks until the turn ends.
+ */
+export async function tryHandleSessionRoutes(
+  req: IncomingMessage,
+  res: ServerResponse,
+  url: URL,
+  ctx: SessionRouteContext,
+): Promise<boolean> {
+  const method = req.method ?? "GET";
+
+  if (method === "POST" && url.pathname === "/plasm/v1/session") {
+    const parsed = newSessionBody.safeParse(await readJsonBody(req));
+    if (!parsed.success) {
+      sendJson(res, 400, { error: "message_required" });
+      return true;
+    }
+
+    const session = ctx.sessionStore.create();
+    const agent = await ctx.getAgent();
+    if (parsed.data.wait === false) {
+      startAsyncTurn(session, parsed.data.message, agent, ctx.sessionStore);
+      sendJson(res, 202, sessionJson(session));
+      return true;
+    }
+
+    await respondSessionTurn(res, session, () =>
+      ctx.sessionStore.runTurn(session, parsed.data.message, agent),
+    );
+    return true;
+  }
+
+  const streamMatch = url.pathname.match(/^\/plasm\/v1\/session\/([^/]+)\/stream$/);
+  if (method === "GET" && streamMatch) {
+    const sessionId = streamMatch[1]!;
+    const session = ctx.sessionStore.get(sessionId);
+    if (!session) {
+      sendJson(res, 404, { error: "session_not_found", sessionId });
+      return true;
+    }
+    handleSessionStream(res, session, ctx.sessionStore);
+    return true;
+  }
+
+  const continueMatch = url.pathname.match(/^\/plasm\/v1\/session\/([^/]+)$/);
+  if (method === "POST" && continueMatch) {
+    const sessionId = continueMatch[1]!;
+    const raw = await readJsonBody(req);
+    const tokenParsed = z.object({ continuationToken: z.string().trim().min(1) }).safeParse(raw);
+    if (!tokenParsed.success) {
+      sendJson(res, 400, { error: "continuation_token_required" });
+      return true;
+    }
+    const messageParsed = continueSessionBody.safeParse(raw);
+    if (!messageParsed.success) {
+      sendJson(res, 400, { error: "message_required" });
+      return true;
+    }
+
+    const session = ctx.sessionStore.validateContinuation(
+      sessionId,
+      messageParsed.data.continuationToken,
+    );
+    if (!session) {
+      sendJson(res, 404, { error: "session_not_found", sessionId });
+      return true;
+    }
+
+    const agent = await ctx.getAgent();
+    if (messageParsed.data.wait === false) {
+      startAsyncTurn(session, messageParsed.data.message, agent, ctx.sessionStore);
+      sendJson(res, 202, sessionJson(session));
+      return true;
+    }
+
+    await respondSessionTurn(res, session, () =>
+      ctx.sessionStore.runTurn(session, messageParsed.data.message, agent),
+    );
+    return true;
+  }
+
+  return false;
+}