@plasm_lang/vercel-agent 0.3.63

package/src/authoring/context.ts

@@ -0,0 +1,34 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import type { PlasmAgent } from "../runtime/plasm-agent.js";
+
+export interface AuthoringContext {
+  agentRoot: string;
+  getAgent: () => Promise<PlasmAgent>;
+  /** Dynamic import of a generated stub module by catalog `entry_id`. */
+  importStub: (entryId: string) => Promise<unknown>;
+}
+
+export interface CreateAuthoringContextOptions {
+  agentRoot: string;
+  getAgent: () => Promise<PlasmAgent>;
+  importCacheBust?: number;
+}
+
+export function createAuthoringContext(
+  options: CreateAuthoringContextOptions,
+): AuthoringContext {
+  const agentRoot = path.resolve(options.agentRoot);
+  const bust = options.importCacheBust ?? Date.now();
+
+  return {
+    agentRoot,
+    getAgent: options.getAgent,
+    importStub: async (entryId: string) => {
+      const stubPath = path.join(agentRoot, ".plasm", "stubs", `${entryId}.ts`);
+      const url = `${pathToFileURL(stubPath).href}?t=${bust}`;
+      return import(url);
+    },
+  };
+}

package/src/authoring/define-channel.ts

@@ -0,0 +1,83 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import type { AuthoringContext } from "./context.js";
+
+export const PLASM_CHANNEL_KIND = "channel" as const;
+
+export type HttpMethod =
+  | "GET"
+  | "POST"
+  | "PUT"
+  | "PATCH"
+  | "DELETE"
+  | "HEAD"
+  | "OPTIONS";
+
+export type ChannelHandler = (
+  req: IncomingMessage,
+  res: ServerResponse,
+  ctx: AuthoringContext,
+) => void | Promise<void>;
+
+export interface ChannelRoute {
+  method: HttpMethod;
+  path: string;
+  handler: ChannelHandler;
+}
+
+export interface ChannelDefinition {
+  readonly __plasmSlotKind: typeof PLASM_CHANNEL_KIND;
+  name: string;
+  routes: ChannelRoute[];
+}
+
+export interface DefineChannelInput {
+  name: string;
+  routes: ChannelRoute[];
+}
+
+const RESERVED_PATH_PREFIXES = ["/plasm/", "/operator"] as const;
+
+export function validateChannelRoute(route: ChannelRoute): string | null {
+  if (!route.path.startsWith("/")) {
+    return `channel route path must start with '/': ${route.path}`;
+  }
+  for (const prefix of RESERVED_PATH_PREFIXES) {
+    if (route.path === prefix.replace(/\/$/, "") || route.path.startsWith(prefix)) {
+      return `channel route conflicts with reserved prefix ${prefix}: ${route.path}`;
+    }
+  }
+  return null;
+}
+
+/** Nitro-shaped HTTP channel (deterministic ingress; call stubs, not plasm_context). */
+export function defineChannel(input: DefineChannelInput): ChannelDefinition {
+  if (!input.name?.trim()) {
+    throw new Error("defineChannel: name is required");
+  }
+  if (!input.routes?.length) {
+    throw new Error("defineChannel: at least one route is required");
+  }
+  const routes = input.routes.map((route) => ({
+    ...route,
+    method: route.method.toUpperCase() as HttpMethod,
+    path: route.path.trim(),
+  }));
+  for (const route of routes) {
+    const err = validateChannelRoute(route);
+    if (err) throw new Error(`defineChannel(${input.name}): ${err}`);
+  }
+  return Object.freeze({
+    __plasmSlotKind: PLASM_CHANNEL_KIND,
+    name: input.name.trim(),
+    routes,
+  });
+}
+
+export function isChannelDefinition(value: unknown): value is ChannelDefinition {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as ChannelDefinition).__plasmSlotKind === PLASM_CHANNEL_KIND
+  );
+}

package/src/authoring/define-hook.ts

@@ -0,0 +1,51 @@
+import type { AuthoringContext } from "./context.js";
+
+export const PLASM_HOOK_KIND = "hook" as const;
+
+export type HookEvent = "agent:start" | "agent:step" | "plan:commit" | "run:complete";
+
+export type HookHandler = (
+  ctx: AuthoringContext,
+  detail?: Record<string, unknown>,
+) => void | Promise<void>;
+
+export interface HookDefinition {
+  readonly __plasmSlotKind: typeof PLASM_HOOK_KIND;
+  name: string;
+  on: HookEvent | HookEvent[];
+  handler: HookHandler;
+}
+
+export interface DefineHookInput {
+  name: string;
+  on: HookEvent | HookEvent[];
+  handler: HookHandler;
+}
+
+/** Lifecycle hook (trace/archive side effects). */
+export function defineHook(input: DefineHookInput): HookDefinition {
+  if (!input.name?.trim()) {
+    throw new Error("defineHook: name is required");
+  }
+  const events = Array.isArray(input.on) ? input.on : [input.on];
+  if (!events.length) {
+    throw new Error("defineHook: on requires at least one event");
+  }
+  if (typeof input.handler !== "function") {
+    throw new Error("defineHook: handler must be a function");
+  }
+  return Object.freeze({
+    __plasmSlotKind: PLASM_HOOK_KIND,
+    name: input.name.trim(),
+    on: input.on,
+    handler: input.handler,
+  });
+}
+
+export function isHookDefinition(value: unknown): value is HookDefinition {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as HookDefinition).__plasmSlotKind === PLASM_HOOK_KIND
+  );
+}

package/src/authoring/define-schedule.ts

@@ -0,0 +1,64 @@
+import type { AuthoringContext } from "./context.js";
+
+export const PLASM_SCHEDULE_KIND = "schedule" as const;
+
+export type ScheduleHandler = (ctx: AuthoringContext) => void | Promise<void>;
+
+export interface ScheduleDefinition {
+  readonly __plasmSlotKind: typeof PLASM_SCHEDULE_KIND;
+  name: string;
+  cron: string;
+  handler: ScheduleHandler;
+}
+
+export interface DefineScheduleInput {
+  name: string;
+  cron: string;
+  handler: ScheduleHandler;
+}
+
+/** Cron schedule (Workflow-friendly; dev server uses a minimal every-N-minutes timer). */
+export function defineSchedule(input: DefineScheduleInput): ScheduleDefinition {
+  if (!input.name?.trim()) {
+    throw new Error("defineSchedule: name is required");
+  }
+  if (!input.cron?.trim()) {
+    throw new Error("defineSchedule: cron is required");
+  }
+  if (typeof input.handler !== "function") {
+    throw new Error("defineSchedule: handler must be a function");
+  }
+  return Object.freeze({
+    __plasmSlotKind: PLASM_SCHEDULE_KIND,
+    name: input.name.trim(),
+    cron: input.cron.trim(),
+    handler: input.handler,
+  });
+}
+
+export function isScheduleDefinition(value: unknown): value is ScheduleDefinition {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as ScheduleDefinition).__plasmSlotKind === PLASM_SCHEDULE_KIND
+  );
+}
+
+/** Parse every-N-minutes or every-N-hours cron into interval ms; returns null when unsupported. */
+export function cronIntervalMs(cron: string): number | null {
+  const everyMinutes = cron.match(/^\*\/(\d+)\s+\*\s+\*\s+\*\s+\*$/);
+  if (everyMinutes) {
+    const minutes = Number(everyMinutes[1]);
+    if (Number.isFinite(minutes) && minutes > 0) {
+      return minutes * 60_000;
+    }
+  }
+  const everyHours = cron.match(/^0\s+\*\/(\d+)\s+\*\s+\*\s+\*$/);
+  if (everyHours) {
+    const hours = Number(everyHours[1]);
+    if (Number.isFinite(hours) && hours > 0) {
+      return hours * 3_600_000;
+    }
+  }
+  return null;
+}

package/src/authoring/define-skill.ts

@@ -0,0 +1,38 @@
+export const PLASM_SKILL_KIND = "skill" as const;
+
+export interface SkillDefinition {
+  readonly __plasmSlotKind: typeof PLASM_SKILL_KIND;
+  name: string;
+  description?: string;
+  body: string;
+}
+
+export interface DefineSkillInput {
+  name: string;
+  description?: string;
+  body: string;
+}
+
+/** Eve-shaped skill definition (markdown body for progressive disclosure). */
+export function defineSkill(input: DefineSkillInput): SkillDefinition {
+  if (!input.name?.trim()) {
+    throw new Error("defineSkill: name is required");
+  }
+  if (!input.body?.trim()) {
+    throw new Error("defineSkill: body is required");
+  }
+  return Object.freeze({
+    __plasmSlotKind: PLASM_SKILL_KIND,
+    name: input.name.trim(),
+    description: input.description?.trim(),
+    body: input.body,
+  });
+}
+
+export function isSkillDefinition(value: unknown): value is SkillDefinition {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as SkillDefinition).__plasmSlotKind === PLASM_SKILL_KIND
+  );
+}

package/src/authoring/hook-runner.ts

@@ -0,0 +1,18 @@
+import type { AuthoringContext } from "./context.js";
+import type { HookDefinition, HookEvent } from "./define-hook.js";
+
+export class HookRunner {
+  constructor(private readonly hooks: HookDefinition[]) {}
+
+  async emit(
+    event: HookEvent,
+    ctx: AuthoringContext,
+    detail?: Record<string, unknown>,
+  ): Promise<void> {
+    for (const hook of this.hooks) {
+      const events = Array.isArray(hook.on) ? hook.on : [hook.on];
+      if (!events.includes(event)) continue;
+      await hook.handler(ctx, detail);
+    }
+  }
+}

package/src/authoring/schedule-manager.ts

@@ -0,0 +1,118 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import type { AuthoringContext } from "./context.js";
+import { cronIntervalMs } from "./define-schedule.js";
+import type { LoadedSchedule } from "./slot-loader.js";
+import { resolveWorkflowWorldType } from "../workflow/world-bootstrap.js";
+import type { AgentWorkflowDefinition } from "../define-agent.js";
+
+export interface ScheduleHandle {
+  stop(): void;
+}
+
+export interface ScheduleCronManifest {
+  crons: Array<{ path: string; schedule: string; name: string }>;
+}
+
+export function exportScheduleCronManifest(schedules: LoadedSchedule[]): ScheduleCronManifest {
+  return {
+    crons: schedules.map((schedule) => ({
+      name: schedule.definition.name,
+      path: `/internal/cron/${schedule.definition.name}`,
+      schedule: schedule.definition.cron,
+    })),
+  };
+}
+
+function authorizeCronRequest(req: IncomingMessage): boolean {
+  const secret = process.env.CRON_SECRET?.trim();
+  if (!secret) return process.env.NODE_ENV !== "production";
+  const auth = req.headers.authorization ?? "";
+  return auth === `Bearer ${secret}`;
+}
+
+export function tryHandleScheduleCronRoute(
+  req: IncomingMessage,
+  res: ServerResponse,
+  schedules: LoadedSchedule[],
+  ctx: AuthoringContext,
+): boolean {
+  const method = (req.method ?? "GET").toUpperCase();
+  const pathname = new URL(req.url ?? "/", "http://localhost").pathname;
+  const match = pathname.match(/^\/internal\/cron\/([^/]+)$/);
+  if (method !== "GET" || !match) return false;
+
+  if (!authorizeCronRequest(req)) {
+    res.statusCode = 401;
+    res.end("Unauthorized");
+    return true;
+  }
+
+  const name = match[1]!;
+  const schedule = schedules.find((s) => s.definition.name === name);
+  if (!schedule) {
+    res.statusCode = 404;
+    res.setHeader("content-type", "application/json; charset=utf-8");
+    res.end(JSON.stringify({ error: "schedule_not_found", name }));
+    return true;
+  }
+
+  void Promise.resolve(schedule.definition.handler(ctx))
+    .then(() => {
+      res.statusCode = 200;
+      res.setHeader("content-type", "application/json; charset=utf-8");
+      res.end(JSON.stringify({ ok: true, schedule: name }));
+    })
+    .catch((err: unknown) => {
+      res.statusCode = 500;
+      res.setHeader("content-type", "application/json; charset=utf-8");
+      res.end(JSON.stringify({ error: "schedule_failed", message: String(err) }));
+    });
+
+  return true;
+}
+
+export function startScheduleTimers(
+  schedules: LoadedSchedule[],
+  ctx: AuthoringContext,
+  workflow?: AgentWorkflowDefinition,
+): ScheduleHandle {
+  const world = resolveWorkflowWorldType(workflow);
+  if (world !== "local") {
+    const manifest = exportScheduleCronManifest(schedules);
+    console.log(
+      `[plasm:schedule] prod world=${world} — register Vercel Cron routes:`,
+      JSON.stringify(manifest.crons, null, 2),
+    );
+    return { stop: () => {} };
+  }
+
+  const timers: ReturnType<typeof setInterval>[] = [];
+
+  for (const schedule of schedules) {
+    const intervalMs = cronIntervalMs(schedule.definition.cron);
+    if (!intervalMs) {
+      console.warn(
+        `[plasm:dev] schedule ${schedule.definition.name}: unsupported cron "${schedule.definition.cron}" (use */N * * * *)`,
+      );
+      continue;
+    }
+
+    const run = () => {
+      void Promise.resolve(schedule.definition.handler(ctx)).catch((err: unknown) => {
+        console.error(`[plasm:dev] schedule ${schedule.definition.name} failed:`, err);
+      });
+    };
+
+    timers.push(setInterval(run, intervalMs));
+    console.log(
+      `[plasm:dev] schedule ${schedule.definition.name} every ${intervalMs / 60_000}m (${schedule.definition.cron})`,
+    );
+  }
+
+  return {
+    stop: () => {
+      for (const timer of timers) clearInterval(timer);
+    },
+  };
+}

package/src/authoring/slot-loader.ts

@@ -0,0 +1,253 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import type { ProjectDiscovery, DiscoveryDiagnostic } from "../discovery/project-walker.js";
+import type { ChannelDefinition } from "./define-channel.js";
+import { isChannelDefinition } from "./define-channel.js";
+import type { HookDefinition } from "./define-hook.js";
+import { isHookDefinition } from "./define-hook.js";
+import type { ScheduleDefinition } from "./define-schedule.js";
+import { isScheduleDefinition } from "./define-schedule.js";
+import type { SkillDefinition } from "./define-skill.js";
+import { isSkillDefinition } from "./define-skill.js";
+import { HookRunner } from "./hook-runner.js";
+
+export interface LoadedChannel {
+  sourcePath: string;
+  definition: ChannelDefinition;
+}
+
+export interface LoadedSchedule {
+  sourcePath: string;
+  definition: ScheduleDefinition;
+}
+
+export interface LoadedHook {
+  sourcePath: string;
+  definition: HookDefinition;
+}
+
+export interface LoadedSkill {
+  sourcePath: string;
+  definition: SkillDefinition;
+}
+
+export interface LoadedProjectSlots {
+  channels: LoadedChannel[];
+  schedules: LoadedSchedule[];
+  hooks: LoadedHook[];
+  skills: LoadedSkill[];
+  hookRunner: HookRunner;
+  diagnostics: DiscoveryDiagnostic[];
+}
+
+export interface LoadAuthoredSlotsOptions {
+  discovery: ProjectDiscovery;
+  importCacheBust?: number;
+}
+
+type SlotName = "channels" | "schedules" | "hooks" | "skills";
+
+function slotDiagnostic(
+  slot: SlotName,
+  filePath: string,
+  message: string,
+  level: DiscoveryDiagnostic["level"] = "error",
+): DiscoveryDiagnostic {
+  return { level, slot, path: filePath, message };
+}
+
+async function importSlotModule(filePath: string, cacheBust: number): Promise<unknown> {
+  const url = `${pathToFileURL(filePath).href}?t=${cacheBust}`;
+  const mod = await import(url);
+  return mod.default ?? mod;
+}
+
+function classifySlotExport(
+  exported: unknown,
+): "channel" | "schedule" | "hook" | "skill" | null {
+  if (isChannelDefinition(exported)) return "channel";
+  if (isScheduleDefinition(exported)) return "schedule";
+  if (isHookDefinition(exported)) return "hook";
+  if (isSkillDefinition(exported)) return "skill";
+  return null;
+}
+
+const EXPECTED_KIND: Record<Exclude<SlotName, "skills">, "channel" | "schedule" | "hook"> = {
+  channels: "channel",
+  schedules: "schedule",
+  hooks: "hook",
+};
+
+async function loadTypescriptSlot<T extends ChannelDefinition | ScheduleDefinition | HookDefinition | SkillDefinition>(
+  filePath: string,
+  slot: SlotName,
+  expected: "channel" | "schedule" | "hook" | "skill",
+  cacheBust: number,
+): Promise<{ definition: T } | { diagnostic: DiscoveryDiagnostic }> {
+  try {
+    const exported = await importSlotModule(filePath, cacheBust);
+    const actual = classifySlotExport(exported);
+    if (actual !== expected) {
+      const helper =
+        expected === "channel"
+          ? "defineChannel"
+          : expected === "schedule"
+            ? "defineSchedule"
+            : expected === "hook"
+              ? "defineHook"
+              : "defineSkill";
+      return {
+        diagnostic: slotDiagnostic(
+          slot,
+          filePath,
+          `default export must be ${helper}() result`,
+        ),
+      };
+    }
+    return { definition: exported as T };
+  } catch (err) {
+    return {
+      diagnostic: slotDiagnostic(slot, filePath, `failed to import: ${String(err)}`),
+    };
+  }
+}
+
+async function loadMarkdownSkill(filePath: string, name: string): Promise<LoadedSkill> {
+  const body = await readFile(filePath, "utf8");
+  const firstLine = body.split("\n").find((line) => line.trim())?.trim() ?? "";
+  const description = firstLine.startsWith("#")
+    ? firstLine.replace(/^#+\s*/, "").trim()
+    : undefined;
+  return {
+    sourcePath: filePath,
+    definition: {
+      __plasmSlotKind: "skill",
+      name,
+      description,
+      body,
+    },
+  };
+}
+
+/** Import authored slots from discovery metadata. */
+export async function loadAuthoredSlots(
+  options: LoadAuthoredSlotsOptions,
+): Promise<LoadedProjectSlots> {
+  const { discovery } = options;
+  const cacheBust = options.importCacheBust ?? Date.now();
+  const diagnostics: DiscoveryDiagnostic[] = [...discovery.diagnostics];
+
+  const channels: LoadedChannel[] = [];
+  for (const file of discovery.channels) {
+    if (file.kind !== "typescript") continue;
+    const result = await loadTypescriptSlot<ChannelDefinition>(
+      file.path,
+      "channels",
+      EXPECTED_KIND.channels,
+      cacheBust,
+    );
+    if ("diagnostic" in result) {
+      diagnostics.push(result.diagnostic);
+      continue;
+    }
+    channels.push({ sourcePath: file.path, definition: result.definition });
+  }
+
+  const schedules: LoadedSchedule[] = [];
+  for (const file of discovery.schedules) {
+    if (file.kind !== "typescript") continue;
+    const result = await loadTypescriptSlot<ScheduleDefinition>(
+      file.path,
+      "schedules",
+      EXPECTED_KIND.schedules,
+      cacheBust,
+    );
+    if ("diagnostic" in result) {
+      diagnostics.push(result.diagnostic);
+      continue;
+    }
+    schedules.push({ sourcePath: file.path, definition: result.definition });
+  }
+
+  const hooks: LoadedHook[] = [];
+  for (const file of discovery.hooks) {
+    if (file.kind !== "typescript") continue;
+    const result = await loadTypescriptSlot<HookDefinition>(
+      file.path,
+      "hooks",
+      EXPECTED_KIND.hooks,
+      cacheBust,
+    );
+    if ("diagnostic" in result) {
+      diagnostics.push(result.diagnostic);
+      continue;
+    }
+    hooks.push({ sourcePath: file.path, definition: result.definition });
+  }
+
+  const skills: LoadedSkill[] = [];
+  for (const file of discovery.skills) {
+    if (file.kind === "markdown") {
+      skills.push(await loadMarkdownSkill(file.path, file.name));
+      continue;
+    }
+    const result = await loadTypescriptSlot<SkillDefinition>(
+      file.path,
+      "skills",
+      "skill",
+      cacheBust,
+    );
+    if ("diagnostic" in result) {
+      diagnostics.push(result.diagnostic);
+      continue;
+    }
+    skills.push({ sourcePath: file.path, definition: result.definition });
+  }
+
+  return {
+    channels,
+    schedules,
+    hooks,
+    skills,
+    hookRunner: new HookRunner(hooks.map((h) => h.definition)),
+    diagnostics,
+  };
+}
+
+export interface LoadedSlotsSummary {
+  skills: Array<{ name: string; path: string; kind: "markdown" | "typescript" }>;
+  channels: Array<{ name: string; path: string; routes: Array<{ method: string; path: string }> }>;
+  schedules: Array<{ name: string; path: string; cron: string }>;
+  hooks: Array<{ name: string; path: string; on: string | string[] }>;
+}
+
+export function summarizeLoadedSlots(
+  slots: LoadedProjectSlots,
+  agentRoot: string,
+): LoadedSlotsSummary {
+  const rel = (p: string) => path.relative(agentRoot, p);
+  return {
+    skills: slots.skills.map((s) => ({
+      name: s.definition.name,
+      path: rel(s.sourcePath),
+      kind: s.sourcePath.endsWith(".md") ? "markdown" : "typescript",
+    })),
+    channels: slots.channels.map((c) => ({
+      name: c.definition.name,
+      path: rel(c.sourcePath),
+      routes: c.definition.routes.map((r) => ({ method: r.method, path: r.path })),
+    })),
+    schedules: slots.schedules.map((s) => ({
+      name: s.definition.name,
+      path: rel(s.sourcePath),
+      cron: s.definition.cron,
+    })),
+    hooks: slots.hooks.map((h) => ({
+      name: h.definition.name,
+      path: rel(h.sourcePath),
+      on: h.definition.on,
+    })),
+  };
+}