@justjoshn/pi-pstack 0.0.0-stage → 0.15.36-pi.7

package/src/subscriptions/supervisor-main.ts

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+
+import { PACKAGE_ROOT } from '../paths.ts';
+import { createSupervisor } from './supervisor.ts';
+
+function usage(): never {
+  console.error('Usage: pstack-routines-supervisor --workspace <cwd>');
+  process.exit(2);
+}
+
+function parseArgs(argv: string[]): { workspace: string } {
+  let workspace: string | undefined;
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--workspace') {
+      workspace = argv[index + 1];
+      index += 1;
+      continue;
+    }
+    if (arg === '--help' || arg === '-h') usage();
+    console.error(`Unknown argument: ${arg}`);
+    usage();
+  }
+  if (workspace === undefined || workspace.trim() === '') usage();
+  return { workspace: resolve(workspace) };
+}
+
+/** Spawns a headless Pi print run; resolves only when the child exits 0. */
+function runFresh(prompt: string, name: string, meta: { subscriptionId: string; cwd: string }): Promise<void> {
+  return new Promise((resolvePromise, reject) => {
+    const raw: unknown = JSON.parse(process.env['PI_PSTACK_PI_COMMAND'] ?? '["pi"]');
+    if (!Array.isArray(raw) || raw.length === 0 || !raw.every((part) => typeof part === 'string' && part !== '')) {
+      reject(new Error('Invalid Pi command supplied to the subscription supervisor.'));
+      return;
+    }
+    const [executable, ...prefix] = raw as string[];
+    if (executable === undefined) {
+      reject(new Error(`Could not spawn fire for "${name}" (${meta.subscriptionId}): no pi command`));
+      return;
+    }
+    const child = spawn(executable, [...prefix, '--mode', 'json', '-e', PACKAGE_ROOT, '-p', '--', prompt], {
+      cwd: meta.cwd,
+      env: process.env,
+      stdio: 'ignore',
+    });
+    child.once('error', (error) => reject(new Error(`Could not spawn fire for "${name}" (${meta.subscriptionId}): ${error.message}`)));
+    child.once('exit', (code, signal) => {
+      if (signal != null) {
+        reject(new Error(`Fire for "${name}" (${meta.subscriptionId}) exited from signal ${signal}`));
+        return;
+      }
+      if (code !== 0) {
+        reject(new Error(`Fire for "${name}" (${meta.subscriptionId}) exited with code ${code ?? 'null'}`));
+        return;
+      }
+      resolvePromise();
+    });
+  });
+}
+
+async function main(): Promise<void> {
+  const { workspace } = parseArgs(process.argv.slice(2));
+  const supervisor = createSupervisor({ workspaceCwd: workspace, runFresh, isDaemon: true });
+  const result = await supervisor.start();
+  if (!result.started) {
+    console.log(`pstack-routines-supervisor already running for ${workspace} (pid ${result.pid}).`);
+    process.exit(0);
+  }
+  console.log(`pstack-routines-supervisor started for ${workspace} (pid ${process.pid}).`);
+  await new Promise<void>((resolve) => {
+    const shutdown = () => {
+      supervisor.stop();
+      resolve();
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    process.on('SIGHUP', () => {
+      void supervisor.reconcile();
+    });
+  });
+}
+
+main().catch((error: unknown) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+});

package/src/subscriptions/supervisor.ts

@@ -0,0 +1,271 @@
+import { randomUUID } from 'node:crypto';
+
+import { routinesDir } from '../paths.ts';
+import { cronMatches, parseCron } from './cron.ts';
+import { acceptEvent, acquireSupervisorLock, alive, canonicalPath, clearError, expireDesired, finishFresh, isDesired, readLock, readRegistry, recordError, releaseSupervisorLock, startFresh, writeArm } from './durable-store.ts';
+import type { DurableSubscription, StoredSubscription } from './durable-types.ts';
+import { defaultGhRunner, fetchPrs, type GhRunner, type PrSnapshot, pollChanges } from './github.ts';
+import { credentialFile, DEFAULT_ROUTINES_PORT, ensureCredentials, RoutineServer, type WebhookEvent, webhookEventBlock } from './webhook.ts';
+
+const MAX_STEP_MS = 24 * 24 * 3_600_000;
+const MINUTE_MS = 60_000;
+export type RunFresh = (prompt: string, name: string, meta: { subscriptionId: string; cwd: string }) => Promise<void> | void;
+export interface SupervisorOptions {
+  workspaceCwd: string;
+  runFresh: RunFresh;
+  now?: () => number;
+  routinesPort?: number;
+  routinesDir?: string;
+  pollIntervalMs?: number;
+  gh?: GhRunner;
+  reconcileIntervalMs?: number;
+  onAccepted?: () => void;
+  isDaemon?: boolean;
+  ownerSessionId?: string;
+}
+type TimerConfig = Extract<DurableSubscription['config'], { kind: 'timer' }>;
+type Armed = { sub: StoredSubscription; timers: Set<ReturnType<typeof setTimeout>>; baseline?: Map<number, PrSnapshot>; polling?: boolean };
+
+function envPort(): number {
+  const raw = process.env['PSTACK_ROUTINES_PORT'];
+  const port = raw === undefined || raw === '' ? DEFAULT_ROUTINES_PORT : Number(raw);
+  return Number.isInteger(port) && port >= 0 && port < 65536 ? port : DEFAULT_ROUTINES_PORT;
+}
+export function delayFireIndex(createdAt: number, delaySeconds: number, at: number): number {
+  return Math.floor(Math.max(0, at - createdAt) / (Math.max(1, delaySeconds) * 1_000));
+}
+export function timerClaimKey(sub: DurableSubscription, config: TimerConfig, at: number): string {
+  if (config.once) return `${sub.id}:once`;
+  return `${sub.id}:${config.cron === undefined ? delayFireIndex(sub.createdAt, config.delaySeconds ?? 1, at) : Math.floor(at / MINUTE_MS)}`;
+}
+
+export function createSupervisor(options: SupervisorOptions) {
+  const cwd = canonicalPath(options.workspaceCwd);
+  const now = options.now ?? Date.now;
+  const gh = options.gh ?? defaultGhRunner;
+  const pollMs = options.pollIntervalMs ?? MINUTE_MS;
+  const dir = options.routinesDir ?? routinesDir();
+  const server = new RoutineServer(options.routinesPort ?? envPort());
+  const armed = new Map<string, Armed>();
+  const isDaemon = options.isDaemon ?? true;
+  let active = false;
+  let epoch: string | undefined;
+  let watchTimer: ReturnType<typeof setTimeout> | undefined;
+  let reconciling: Promise<void> | undefined;
+
+  const owns = (entry: Armed) => active && armed.get(entry.sub.id) === entry;
+  const at = (entry: Armed, when: number, fn: () => void) => {
+    const handle = setTimeout(
+      () => {
+        entry.timers.delete(handle);
+        if (!owns(entry)) return;
+        if (now() < when) at(entry, when, fn);
+        else fn();
+      },
+      Math.min(Math.max(0, when - now()), MAX_STEP_MS),
+    );
+    handle.unref?.();
+    entry.timers.add(handle);
+  };
+  const disarm = (entry: Armed) => {
+    for (const handle of entry.timers) clearTimeout(handle);
+    entry.timers.clear();
+    if (entry.sub.config.kind === 'webhook') {
+      server.routes.delete(entry.sub.config.slug);
+      if (server.routes.size === 0) server.close(false);
+    }
+  };
+  const error = (id: string, cause: unknown) => recordError(cwd, id, cause);
+  const offlineFresh = () => {
+    if (!active) return;
+    const registry = readRegistry(cwd);
+    const eligible = registry.pending.filter((event) => {
+      if (event.claim !== undefined && alive(event.claim.pid)) return false;
+      if (event.retryAt !== undefined && now() < event.retryAt) return false;
+      const sub = registry.subscriptions.find((s) => s.id === event.subscriptionId);
+      if (sub === undefined || sub.lifecycle === 'cancelled' || sub.config.kind !== 'timer' || sub.config.strategy !== 'new_session') return false;
+      if (!isDaemon && (options.ownerSessionId === undefined || sub.ownerSessionId !== options.ownerSessionId)) return false;
+      return true;
+    });
+    for (const event of eligible) {
+      const claim = startFresh(
+        cwd,
+        event.id,
+        undefined,
+        () => active,
+        (sub, pending) => options.runFresh(pending.content, sub.name, { subscriptionId: sub.id, cwd }),
+      );
+      if (claim !== undefined)
+        void claim.result
+          .then(
+            () => finishFresh(cwd, event.id, claim.token),
+            (cause: unknown) => finishFresh(cwd, event.id, claim.token, cause),
+          )
+          .catch((cause: unknown) => {
+            console.error(`Subscription delivery status failed. ${String(cause)}`);
+          });
+    }
+  };
+  const accepted = () => {
+    options.onAccepted?.();
+    offlineFresh();
+  };
+  const fireTimer = (entry: Armed, config: TimerConfig) => {
+    if (!owns(entry)) return;
+    try {
+      const prompt = config.strategy === 'wake_self' ? `[timer] ${entry.sub.name}\n\n${config.prompt}` : config.prompt;
+      if (acceptEvent(cwd, entry.sub.id, timerClaimKey(entry.sub, config, now()), prompt, now()) === 'accepted') accepted();
+    } catch (cause) {
+      error(entry.sub.id, cause);
+    }
+  };
+  const armTimer = (entry: Armed, config: TimerConfig) => {
+    if (config.cron !== undefined) {
+      const schedule = parseCron(config.cron);
+      const tick = () => {
+        if (cronMatches(schedule, new Date(now()))) fireTimer(entry, config);
+        const current = readRegistry(cwd).subscriptions.find((sub) => sub.id === entry.sub.id);
+        if (current !== undefined && isDesired(current, now())) at(entry, (Math.floor(now() / MINUTE_MS) + 1) * MINUTE_MS, tick);
+      };
+      at(entry, (Math.floor(now() / MINUTE_MS) + 1) * MINUTE_MS, tick);
+    } else {
+      const period = (config.delaySeconds ?? 1) * 1_000;
+      const next = () => (config.once ? entry.sub.createdAt + period : entry.sub.createdAt + (Math.floor(Math.max(0, now() - entry.sub.createdAt) / period) + 1) * period);
+      const fire = () => {
+        fireTimer(entry, config);
+        const current = readRegistry(cwd).subscriptions.find((sub) => sub.id === entry.sub.id);
+        if (current !== undefined && isDesired(current, now())) at(entry, config.once ? now() + 1_000 : next(), fire);
+      };
+      at(entry, next(), fire);
+    }
+  };
+  const onWebhook =
+    (entry: Armed, prompt: string) =>
+    async (event: WebhookEvent): Promise<boolean> => {
+      if (!owns(entry)) return false;
+      const content = [`[routine] ${entry.sub.name}`, prompt, webhookEventBlock(event)].join('\n\n');
+      const result = acceptEvent(cwd, entry.sub.id, event.eventId, content, now());
+      if (result === 'inactive') return false;
+      if (result === 'accepted') accepted();
+      return true;
+    };
+  const poll = async (entry: Armed, target: Extract<DurableSubscription['config'], { kind: 'github' }>['target']) => {
+    if (entry.polling || !owns(entry)) return;
+    entry.polling = true;
+    try {
+      const after = await fetchPrs(gh, target);
+      if (!owns(entry)) return;
+      if (entry.baseline !== undefined) {
+        const blocks = await pollChanges(gh, target, entry.baseline, after);
+        if (!owns(entry)) return;
+        if (blocks.length > 0 && acceptEvent(cwd, entry.sub.id, randomUUID(), [`[github] ${entry.sub.name}`, ...blocks].join('\n\n'), now()) === 'accepted') accepted();
+      }
+      entry.baseline = after;
+      clearError(cwd, entry.sub.id);
+    } finally {
+      entry.polling = false;
+    }
+  };
+  const arm = async (entry: Armed): Promise<string | undefined> => {
+    if (entry.sub.ownerSessionId === undefined) throw new Error('Owner session ID unavailable. Recreate this subscription.');
+    at(entry, entry.sub.expiresAt, () => {
+      expireDesired(cwd, now());
+      void reconcile().catch((cause: unknown) => error(entry.sub.id, cause));
+    });
+    const config = entry.sub.config;
+    if (config.kind === 'timer') armTimer(entry, config);
+    else if (config.kind === 'webhook') {
+      server.routes.set(config.slug, { slug: config.slug, credentialFile: ensureCredentials(dir, config.slug), onEvent: onWebhook(entry, config.prompt) });
+      return await server.url(config.slug);
+    } else {
+      const loop = () => {
+        void poll(entry, config.target).then(
+          () => {
+            if (owns(entry)) at(entry, now() + pollMs, loop);
+          },
+          (cause: unknown) => {
+            error(entry.sub.id, cause);
+            if (owns(entry)) at(entry, now() + pollMs, loop);
+          },
+        );
+      };
+      loop();
+    }
+    return undefined;
+  };
+  const reconcile = (): Promise<void> => {
+    if (!active) return Promise.resolve();
+    if (reconciling !== undefined) return reconciling;
+    reconciling = (async () => {
+      const registry = readRegistry(cwd);
+      if (registry.subscriptions.some((sub) => sub.lifecycle === 'active' && sub.expiresAt <= now())) expireDesired(cwd, now());
+      const desired = registry.subscriptions.filter((sub) => isDesired(sub, now()));
+      for (const [id, entry] of armed)
+        if (!desired.some((sub) => sub.id === id && sub.revision === entry.sub.revision)) {
+          disarm(entry);
+          armed.delete(id);
+        }
+      for (const sub of desired) {
+        if (!active) return;
+        if (armed.has(sub.id)) continue;
+        const entry: Armed = { sub, timers: new Set() };
+        armed.set(sub.id, entry);
+        try {
+          const url = await arm(entry);
+          if (!owns(entry) || epoch === undefined) continue;
+          clearError(cwd, sub.id);
+          writeArm(cwd, { state: 'ready', subscriptionId: sub.id, revision: sub.revision, epoch, ...(url === undefined ? {} : { url }) });
+        } catch (cause) {
+          disarm(entry);
+          armed.delete(sub.id);
+          if (!active || epoch === undefined) return;
+          const message = cause instanceof Error ? cause.message : String(cause);
+          error(sub.id, cause);
+          writeArm(cwd, { state: 'error', subscriptionId: sub.id, revision: sub.revision, epoch, message });
+        }
+      }
+      offlineFresh();
+    })().finally(() => {
+      reconciling = undefined;
+    });
+    return reconciling;
+  };
+  const watch = () => {
+    if (!active) return;
+    watchTimer = setTimeout(() => {
+      void reconcile()
+        .catch((cause: unknown) => console.error(`Subscription supervisor reconcile failed. ${String(cause)}`))
+        .finally(watch);
+    }, options.reconcileIntervalMs ?? 250);
+  };
+  return {
+    start: async (): Promise<{ started: boolean; alreadyRunning?: boolean; pid?: number }> => {
+      const lock = acquireSupervisorLock(cwd);
+      if (!lock.acquired) return { started: false, alreadyRunning: true, pid: lock.pid };
+      epoch = readLock(cwd)?.epoch;
+      active = true;
+      try {
+        await reconcile();
+        watch();
+        return { started: true };
+      } catch (cause) {
+        active = false;
+        releaseSupervisorLock(cwd, process.pid, epoch);
+        throw cause;
+      }
+    },
+    reconcile,
+    stop: () => {
+      active = false;
+      if (watchTimer !== undefined) clearTimeout(watchTimer);
+      for (const entry of armed.values()) disarm(entry);
+      armed.clear();
+      server.close();
+      if (epoch !== undefined) releaseSupervisorLock(cwd, process.pid, epoch);
+      epoch = undefined;
+    },
+    isListening: () => server.isListening(),
+    credentialFile: (slug: string) => credentialFile(dir, slug),
+  };
+}
+export type Supervisor = ReturnType<typeof createSupervisor>;

package/src/subscriptions/webhook.ts

@@ -0,0 +1,222 @@
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { join } from 'node:path';
+
+export const DEFAULT_ROUTINES_PORT = 47913;
+export const MAX_BODY_BYTES = 64 * 1024;
+const HOST = '127.0.0.1';
+const KEY = /^[0-9a-f]{64}$/;
+
+export function routineSlug(name: string): string {
+  const slug = name
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  if (slug === '') throw new Error(`Routine name "${name}" has no letters or digits to make a slug from.`);
+  return slug.slice(0, 64).replace(/-+$/, '');
+}
+
+export function credentialFile(routinesDir: string, slug: string): string {
+  return join(routinesDir, slug, 'credentials.json');
+}
+
+function readKey(file: string): string | undefined {
+  try {
+    const key = (JSON.parse(readFileSync(file, 'utf8')) as { key?: unknown } | null)?.key;
+    return typeof key === 'string' && KEY.test(key) ? key : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+const errno = (error: unknown) => (typeof error === 'object' && error !== null && 'code' in error ? String((error as { code: unknown }).code) : undefined);
+const pause = (ms: number) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+
+/** The routine's sender key file, created with a fresh key unless a valid one is already there. Returns the path only. */
+export function ensureCredentials(routinesDir: string, slug: string): string {
+  const file = credentialFile(routinesDir, slug);
+  mkdirSync(join(routinesDir, slug), { recursive: true, mode: 0o700 });
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    const key = readKey(file);
+    if (key !== undefined) {
+      chmodSync(file, 0o600);
+      return file;
+    }
+    if (!existsSync(file)) {
+      try {
+        writeFileSync(file, `${JSON.stringify({ key: randomBytes(32).toString('hex') })}\n`, { flag: 'wx', mode: 0o600 });
+        chmodSync(file, 0o600);
+        return file;
+      } catch (error) {
+        if (errno(error) !== 'EEXIST') throw error;
+      }
+    }
+    if (attempt < 4) pause(5);
+  }
+  if (readKey(file) !== undefined) {
+    chmodSync(file, 0o600);
+    return file;
+  }
+  writeFileSync(file, `${JSON.stringify({ key: randomBytes(32).toString('hex') })}\n`, { mode: 0o600 });
+  chmodSync(file, 0o600);
+  return file;
+}
+
+const digest = (text: string) => createHash('sha256').update(text).digest();
+
+/** Constant-time: both sides are hashed first, so length differences do not leak either. */
+export function keyMatches(presented: string | undefined, expected: string | undefined): boolean {
+  if (presented === undefined || expected === undefined) return false;
+  return timingSafeEqual(digest(presented), digest(expected));
+}
+
+function presentedKey(request: IncomingMessage): string | undefined {
+  const header = request.headers['x-automation-key'];
+  if (typeof header === 'string' && header !== '') return header.trim();
+  const bearer = /^Bearer\s+(\S+)\s*$/i.exec(request.headers.authorization ?? '');
+  return bearer?.[1];
+}
+
+export interface WebhookEvent {
+  eventId: string;
+  headers: Record<string, string>;
+  bodyDigest: string;
+  body: string;
+  timestampMs: number;
+}
+
+/** JSON whose `<` is escaped, so a body cannot close the surrounding tag; it still parses to the same value. */
+const tagSafeJson = (value: unknown) => JSON.stringify(value, null, 2).replace(/</g, '\\u003c');
+
+export function webhookEventBlock(event: WebhookEvent): string {
+  return ['<webhook_event>', tagSafeJson({ headers: event.headers, body_digest: event.bodyDigest, body: event.body, timestamp_ms: event.timestampMs }), '</webhook_event>'].join('\n');
+}
+
+export interface RoutineRoute {
+  slug: string;
+  credentialFile: string;
+  onEvent: (event: WebhookEvent) => Promise<boolean>;
+}
+
+const reply = (response: ServerResponse, status: number, message: string) => {
+  response.writeHead(status, { 'content-type': 'application/json', connection: 'close' });
+  response.end(`${JSON.stringify(status === 200 ? { ok: true } : { error: message })}\n`);
+};
+
+/** One local listener for every routine of this process. Routes are looked up per request, so they can change while it runs. */
+export class RoutineServer {
+  private server: Server | undefined;
+  private listening: Promise<number> | undefined;
+  private readonly closing = new Set<Server>();
+  readonly routes = new Map<string, RoutineRoute>();
+  private readonly port: number;
+
+  constructor(port: number) {
+    this.port = port;
+  }
+
+  /** Starts the listener once and resolves to its port. */
+  start(): Promise<number> {
+    this.listening ??= new Promise<number>((resolve, reject) => {
+      const server = createServer((request, response) => this.handle(request, response));
+      server.once('error', (error: NodeJS.ErrnoException) => {
+        this.listening = undefined;
+        this.server = undefined;
+        reject(new Error(error.code === 'EADDRINUSE' ? `Port ${this.port} on ${HOST} is in use (another Pi process may own the routines listener). Set PSTACK_ROUTINES_PORT to a free port.` : `Routines listener failed: ${error.message}`));
+      });
+      server.listen(this.port, HOST, () => {
+        server.unref();
+        resolve((server.address() as AddressInfo).port);
+      });
+      this.server = server;
+    });
+    return this.listening;
+  }
+
+  async url(slug: string): Promise<string> {
+    return `http://${HOST}:${await this.start()}/routines/${slug}`;
+  }
+
+  isListening(): boolean {
+    return this.server?.listening === true;
+  }
+
+  close(force = true): void {
+    const server = this.server;
+    if (server !== undefined) {
+      this.closing.add(server);
+      server.close(() => this.closing.delete(server));
+    }
+    if (force) for (const closing of this.closing) closing.closeAllConnections();
+    this.server = undefined;
+    this.listening = undefined;
+  }
+
+  private handle(request: IncomingMessage, response: ServerResponse): void {
+    const slug = /^\/routines\/([a-z0-9-]+)\/?$/.exec(new URL(request.url ?? '/', 'http://localhost').pathname)?.[1];
+    const route = slug === undefined ? undefined : this.routes.get(slug);
+    if (route === undefined) {
+      reply(response, 404, 'No such routine.');
+      return;
+    }
+    if (request.method !== 'POST') {
+      response.setHeader('allow', 'POST');
+      reply(response, 405, 'Use POST.');
+      return;
+    }
+    if (!keyMatches(presentedKey(request), readKey(route.credentialFile))) {
+      reply(response, 401, 'Wrong or missing sender key.');
+      return;
+    }
+    if (Number(request.headers['content-length'] ?? 0) > MAX_BODY_BYTES) {
+      reply(response, 413, `Body over ${MAX_BODY_BYTES} bytes.`);
+      return;
+    }
+    const chunks: Buffer[] = [];
+    let size = 0;
+    let done = false;
+    request.on('data', (chunk: Buffer) => {
+      if (done) return;
+      size += chunk.length;
+      if (size > MAX_BODY_BYTES) {
+        done = true;
+        response.writeHead(413, { 'content-type': 'application/json', connection: 'close' });
+        response.write(`${JSON.stringify({ error: `Body over ${MAX_BODY_BYTES} bytes.` })}\n`);
+        request.once('end', () => response.end());
+        request.resume();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    request.on('end', async () => {
+      if (done) return;
+      done = true;
+      const raw = Buffer.concat(chunks);
+      const body = raw.toString('utf8');
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(body);
+      } catch {
+        parsed = undefined;
+      }
+      if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return reply(response, 400, 'Body must be a JSON object.');
+      const headers: Record<string, string> = {};
+      for (const name of ['content-type', 'user-agent'] as const) {
+        const header = request.headers[name];
+        if (typeof header === 'string') headers[name] = header;
+      }
+      if (this.routes.get(route.slug) !== route) return reply(response, 404, 'No such routine.');
+      try {
+        const accepted = await route.onEvent({ eventId: randomUUID(), headers, bodyDigest: createHash('sha256').update(raw).digest('hex'), body, timestampMs: Date.now() });
+        reply(response, accepted ? 200 : 404, accepted ? 'ok' : 'No such routine.');
+      } catch {
+        reply(response, 503, 'Could not durably accept this event. Retry later.');
+      }
+    });
+  }
+}

package/src/task/agents.ts

@@ -0,0 +1,55 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+import { parseFrontmatter } from '@earendil-works/pi-coding-agent';
+import { AGENTS_DIR } from '../paths.ts';
+
+/** A subagent type from an agent file: name, description, model, readonly, is_background, prompt body. */
+export interface AgentDefinition {
+  type: string;
+  description: string;
+  model?: string;
+  readonly: boolean;
+  background: boolean;
+  prompt: string;
+  file?: string;
+}
+
+export const GENERAL_PURPOSE: AgentDefinition = {
+  type: 'generalPurpose',
+  description: 'General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. Use when a search or task needs several steps of its own.',
+  readonly: false,
+  background: false,
+  prompt: '',
+};
+
+function parseAgentFile(file: string): AgentDefinition {
+  const { frontmatter, body } = parseFrontmatter(readFileSync(file, 'utf8'));
+  const name = frontmatter['name'];
+  const description = frontmatter['description'];
+  const model = frontmatter['model'];
+  return {
+    type: typeof name === 'string' && name.trim() !== '' ? name.trim() : basename(file, '.md'),
+    description: typeof description === 'string' ? description.trim() : '',
+    ...(typeof model === 'string' && model.trim() !== '' ? { model: model.trim() } : {}),
+    readonly: frontmatter['readonly'] === true,
+    background: frontmatter['is_background'] === true,
+    prompt: body.trim(),
+    file,
+  };
+}
+
+/** generalPurpose first, then every `*.md` agent file in `dir` sorted by file name. */
+export function loadAgentDefinitions(dir: string = AGENTS_DIR): AgentDefinition[] {
+  const files = readdirSync(dir)
+    .filter((name) => name.endsWith('.md'))
+    .toSorted();
+  return [GENERAL_PURPOSE, ...files.map((name) => parseAgentFile(join(dir, name)))];
+}
+
+export function findAgent(agents: readonly AgentDefinition[], type: string | undefined): AgentDefinition {
+  const wanted = type ?? GENERAL_PURPOSE.type;
+  const agent = agents.find((candidate) => candidate.type === wanted);
+  if (agent) return agent;
+  throw new Error(`Unknown subagent_type "${wanted}". Available subagent types: ${agents.map((candidate) => candidate.type).join(', ')}.`);
+}