@graphorin/server 0.6.1 → 0.7.0

package/src/sse/events.ts

@@ -0,0 +1,303 @@
+/**
+ * Server-Sent Events fallback for non-WebSocket-friendly clients.
+ *
+ * The endpoint is unidirectional: the server pushes
+ * `ServerMessage` event frames; control-plane operations
+ * (subscribe / unsubscribe / abort / resume) go through REST.
+ *
+ * Unlike the WS surface, the SSE responder is not multiplexed -
+ * one HTTP request per session subject. Reconnection is handled by
+ * the standard EventSource `Last-Event-ID` mechanism: when the
+ * client supplies the header on resume, the responder walks the
+ * dispatcher's replay buffer from that cursor.
+ *
+ * @packageDocumentation
+ */
+
+import {
+  isEventFrame,
+  isLifecycleFrame,
+  type ServerEventFrame,
+  type ServerMessage,
+  ServerMessageSchema,
+} from '@graphorin/protocol';
+import type { Context, MiddlewareHandler } from 'hono';
+import { Hono } from 'hono';
+import { stream } from 'hono/streaming';
+import type { StreamingApi } from 'hono/utils/stream';
+
+import {
+  createDeliveryCommentarySanitizer,
+  type DeliveryCommentaryConfig,
+  type DeliveryCommentarySanitizer,
+} from '../commentary/index.js';
+import type { ServerVariables } from '../internal/context.js';
+import { createScopeMiddleware } from '../middleware/scope.js';
+import type { WsDispatcher } from '../ws/dispatcher.js';
+
+/**
+ * Stable shape consumed by {@link createSseRoutes}.
+ *
+ * @stable
+ */
+export interface SseRoutesDeps {
+  /**
+   * Cap on the per-connection SSE delivery queue (IP-9). A consumer
+   * that stops reading past this many buffered frames is closed
+   * instead of growing the queue without bound. Default 1000.
+   */
+  readonly perConnectionQueueLimit?: number;
+  readonly dispatcher: WsDispatcher;
+  readonly commentary?: DeliveryCommentaryConfig;
+  /**
+   * How long the SSE responder waits between heartbeat comments to
+   * keep proxies / load balancers from closing the idle connection.
+   * Default `15_000` ms.
+   */
+  readonly keepAliveMs?: number;
+  readonly now?: () => number;
+}
+
+/**
+ * Build the SSE event-stream router. Mounts
+ * `GET /sessions/:id/events` (the canonical path documented in the
+ * runtime spec); operators that want a different path should mount
+ * the router under a custom prefix.
+ *
+ * @stable
+ */
+export function createSseRoutes(deps: SseRoutesDeps): Hono<{ Variables: ServerVariables }> {
+  const sanitizer: DeliveryCommentarySanitizer =
+    deps.dispatcher.sanitizer.applyToEvents.length > 0
+      ? deps.dispatcher.sanitizer
+      : createDeliveryCommentarySanitizer(deps.commentary);
+  const keepAliveMs = deps.keepAliveMs ?? 15_000;
+
+  const app = new Hono<{ Variables: ServerVariables }>();
+  app.get(
+    '/:id/events',
+    // W-107: per-resource, mirroring the WS subject gate - a token
+    // scoped to one session streams it over the browser SSE fallback.
+    createScopeMiddleware((_path, params) => `sessions:read:${params.id}`),
+    sseHandler(deps.dispatcher, sanitizer, keepAliveMs, deps.perConnectionQueueLimit ?? 1000),
+  );
+  return app;
+}
+
+function sseHandler(
+  dispatcher: WsDispatcher,
+  sanitizer: DeliveryCommentarySanitizer,
+  keepAliveMs: number,
+  perConnectionQueueLimit: number,
+): MiddlewareHandler<{ Variables: ServerVariables }> {
+  return async (c: Context<{ Variables: ServerVariables }>) => {
+    const sessionId = c.req.param('id');
+    if (sessionId === undefined || sessionId.length === 0) {
+      return c.json(
+        { error: 'session-id-required', message: 'Path parameter :id is required.' },
+        400,
+      );
+    }
+    const subject = `session:${sessionId}/events`;
+    const sinceEventId = c.req.header('last-event-id') ?? c.req.header('Last-Event-ID');
+
+    c.header('Content-Type', 'text/event-stream; charset=utf-8');
+    c.header('Cache-Control', 'no-cache, no-transform');
+    c.header('Connection', 'keep-alive');
+    c.header('X-Accel-Buffering', 'no');
+
+    return stream(c, async (writer) => {
+      const replay = dispatcher.replayBuffer.replay(subject, sinceEventId);
+      let lastEventId: string | undefined;
+      for (const frame of replay.events) {
+        const sanitized = sanitizer.sanitize({ ...frame, subscriptionId: 'sse' }, 'sse');
+        await writeFrame(writer as StreamingApi, sanitized);
+        lastEventId = sanitized.eventId;
+      }
+      if (replay.droppedCount > 0) {
+        await writeReplayMarker(writer as StreamingApi, replay.droppedCount, lastEventId);
+      }
+      // Live tail - register a synthetic subscription so the
+      // dispatcher fans new events into this connection. The
+      // dispatcher already validates + sanitizes every frame; here we
+      // just write the bytes onto the wire.
+      const subscriberId = `sse-${Math.random().toString(36).slice(2, 10)}`;
+      const subscriptionId = `${subscriberId}-sub`;
+      const authState = c.get('state').auth;
+      // IP-13: the anonymous (auth.kind='none') principal carries `admin:*` in
+      // grantedScopes, so the dispatcher's per-subject scope check still passes.
+      const grantedScopes =
+        authState.kind === 'token' || authState.kind === 'anonymous' ? authState.grantedScopes : [];
+      const tokenId =
+        authState.kind === 'token'
+          ? authState.token.tokenId
+          : authState.kind === 'anonymous'
+            ? 'anonymous'
+            : 'sse-anon';
+      let queue: ServerMessage[] = [];
+      let closedByBackpressure = false;
+      const queueLimit = perConnectionQueueLimit;
+      let resumeNotify: (() => void) | undefined;
+      const notify = (): void => {
+        if (resumeNotify !== undefined) {
+          const fn = resumeNotify;
+          resumeNotify = undefined;
+          fn();
+        }
+      };
+      const handle = {
+        id: subscriberId,
+        tokenId,
+        // The strict-mode subscribe path enforces scope; the outer
+        // middleware gates this handler per-resource
+        // (`sessions:read:<sessionId>`, W-107) and the dispatcher's
+        // per-subject check requires the same grant - the two layers
+        // are consistent for session-scoped tokens.
+        grantedScopes,
+        send: (frame: ServerMessage) => {
+          // IP-9: bound the queue - a stalled consumer is closed, not
+          // buffered into the heap forever.
+          if (queue.length >= queueLimit) {
+            closedByBackpressure = true;
+            queue = [];
+            notify();
+            return;
+          }
+          queue.push(frame);
+          notify();
+        },
+        close: () => {
+          queue = [];
+          notify();
+        },
+      };
+      const reg = dispatcher.registerSubscriber(handle);
+      const result = dispatcher.subscribe({
+        subscriberId,
+        subject,
+        subscriptionId,
+        ...(lastEventId !== undefined ? { sinceEventId: lastEventId } : {}),
+      });
+      if (!result.ok) {
+        reg.unregister();
+        await writer.write(
+          encodeSse({
+            event: 'error',
+            data: JSON.stringify({
+              error: 'sse-subscribe-failed',
+              reason: result.reason,
+            }),
+          }),
+        );
+        await writer.close();
+        return;
+      }
+      const heartbeat = setInterval(() => {
+        // Fire-and-forget heartbeat comment - clients ignore comment
+        // lines (RFC 6455 § 9.1).
+        writer.write(': keep-alive\n\n').catch(() => undefined);
+      }, keepAliveMs);
+      let aborted = false;
+      const onAbort = (): void => {
+        aborted = true;
+        notify();
+      };
+      c.req.raw.signal.addEventListener('abort', onAbort, { once: true });
+      try {
+        while (!aborted) {
+          if (closedByBackpressure) {
+            // IP-9: the consumer stalled past the queue cap - close the
+            // stream with a terminal lifecycle frame instead of
+            // buffering unboundedly.
+            await writer.write(
+              encodeSse({
+                event: 'lifecycle',
+                data: JSON.stringify({
+                  kind: 'lifecycle',
+                  subscriptionId,
+                  status: 'failed',
+                  reason: 'flow.throttled',
+                }),
+              }),
+            );
+            aborted = true;
+            continue;
+          }
+          if (queue.length > 0) {
+            const next = queue.shift();
+            if (next === undefined) continue;
+            if (isEventFrame(next)) {
+              await writeFrame(writer as StreamingApi, next);
+            } else if (isLifecycleFrame(next)) {
+              await writer.write(
+                encodeSse({
+                  event: 'lifecycle',
+                  data: JSON.stringify(next),
+                }),
+              );
+              if (
+                next.status === 'completed' ||
+                next.status === 'aborted' ||
+                next.status === 'failed'
+              ) {
+                aborted = true;
+              }
+            }
+            continue;
+          }
+          await new Promise<void>((resolve) => {
+            resumeNotify = resolve;
+          });
+        }
+      } finally {
+        clearInterval(heartbeat);
+        c.req.raw.signal.removeEventListener('abort', onAbort);
+        dispatcher.unsubscribe(subscriptionId);
+        reg.unregister();
+      }
+    });
+  };
+}
+
+async function writeFrame(writer: StreamingApi, frame: ServerEventFrame): Promise<void> {
+  const validated = ServerMessageSchema.safeParse(frame);
+  if (!validated.success) return;
+  await writer.write(
+    encodeSse({
+      event: frame.type,
+      id: frame.eventId,
+      data: JSON.stringify(frame),
+    }),
+  );
+}
+
+async function writeReplayMarker(
+  writer: StreamingApi,
+  droppedCount: number,
+  lastEventId: string | undefined,
+): Promise<void> {
+  await writer.write(
+    encodeSse({
+      ...(lastEventId !== undefined ? { id: lastEventId } : {}),
+      event: 'replay-marker',
+      data: JSON.stringify({
+        v: '1',
+        kind: 'replay-marker',
+        subscriptionId: 'sse',
+        eventId: lastEventId ?? `evt-replay-${Date.now().toString(36)}`,
+        droppedCount,
+      }),
+    }),
+  );
+}
+
+function encodeSse(frame: { event?: string; id?: string; data: string }): string {
+  let out = '';
+  if (frame.event !== undefined) out += `event: ${frame.event}\n`;
+  if (frame.id !== undefined) out += `id: ${frame.id}\n`;
+  for (const line of frame.data.split('\n')) {
+    out += `data: ${line}\n`;
+  }
+  out += '\n';
+  return out;
+}

package/src/sse/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Server-Sent Events fallback transport for `@graphorin/server`.
+ *
+ * @packageDocumentation
+ */
+
+export { createSseRoutes, type SseRoutesDeps } from './events.js';

package/src/tools-audit-bridge.ts

@@ -0,0 +1,120 @@
+/**
+ * W-051: bridge the `@graphorin/tools` audit-event bus (`onToolAudit`,
+ * which `@graphorin/mcp` also emits into) into the server's
+ * tamper-evident audit log. Without this, a shadow-mode
+ * `tool:dataflow:flagged` was invisible to an operator unless they
+ * hand-wired a subscriber - which no guide showed.
+ *
+ * Mirrors `commentary/audit-bridge.ts`: writes serialise through one
+ * promise tail so concurrent events never race `appendAudit`'s seq
+ * chain, a failed write is isolated (warn, never throw into the
+ * emitter), and `drain()` lets shutdown/tests await in-flight writes.
+ *
+ * Volume control (`config.audit.toolEvents`):
+ * - `'security'` (default): only the security-significant subset -
+ *   dataflow flagged/blocked/declassified, sanitization hits/blocks,
+ *   approval lifecycle, collisions, cap-disabled. High-frequency
+ *   `tool:execute:*` chatter stays OUT of the Merkle chain.
+ * - `'all'`: every tool audit event, including per-call execute
+ *   start/end/error (bounded by call volume - size the chain
+ *   accordingly).
+ * - `'off'`: bridge disabled.
+ *
+ * @packageDocumentation
+ */
+
+import { type AuditDb, type AuditEntryInput, appendAudit } from '@graphorin/security/audit';
+import { onToolAudit, type ToolAuditEvent } from '@graphorin/tools/audit';
+
+/** Volume policy for the tool-audit bridge. @stable */
+export type ToolEventsAuditPolicy = 'security' | 'all' | 'off';
+
+/**
+ * The `'security'` allowlist: decisions an operator reviews, not
+ * per-call chatter.
+ */
+const SECURITY_ACTIONS: ReadonlySet<string> = new Set([
+  'tool:dataflow:flagged',
+  'tool:dataflow:blocked',
+  'tool:dataflow:declassified',
+  'tool:result:sanitization:hit',
+  'tool:result:sanitization:blocked',
+  'tool:approval:requested',
+  'tool:approval:granted',
+  'tool:approval:denied',
+  'tool:collision:detected',
+  'tool:collision:priority-resolved',
+  'tool:collision:auto-prefix-applied',
+  'tool:collision:manual-rejected',
+  'tool:collision:suppressed',
+  'tool:result:cap-disabled',
+]);
+
+/** Translate a tools audit event into an audit-chain entry. */
+export function toolAuditEventToAuditInput(event: ToolAuditEvent): AuditEntryInput {
+  const context: AuditEntryInput['context'] = {
+    ...(event.context?.runId !== undefined ? { runId: event.context.runId } : {}),
+    ...(event.context?.sessionId !== undefined ? { sessionId: event.context.sessionId } : {}),
+  };
+  return {
+    actor: { kind: event.actor.kind, id: event.actor.id },
+    action: event.action,
+    target: event.target,
+    decision: event.decision,
+    ts: event.ts,
+    ...(Object.keys(context).length > 0 ? { context } : {}),
+    metadata: {
+      ...(event.metadata ?? {}),
+      ...(event.context?.stepNumber !== undefined ? { stepNumber: event.context.stepNumber } : {}),
+      ...(event.context?.toolCallId !== undefined ? { toolCallId: event.context.toolCallId } : {}),
+    },
+  };
+}
+
+/** Handle returned by {@link bridgeToolAuditToAudit}. @stable */
+export interface ToolAuditBridge {
+  /** Unsubscribe from the tool-audit bus. */
+  readonly stop: () => void;
+  /** Resolve once every queued audit write has settled. */
+  readonly drain: () => Promise<void>;
+}
+
+/**
+ * Subscribe the audit chain to the tools audit bus. Returns a handle
+ * whose `stop()` MUST run on shutdown (the bus is process-global).
+ *
+ * @stable
+ */
+export function bridgeToolAuditToAudit(
+  db: AuditDb,
+  options: {
+    readonly policy?: ToolEventsAuditPolicy;
+    readonly onWriteError?: (event: ToolAuditEvent, error: unknown) => void;
+  } = {},
+): ToolAuditBridge {
+  const policy = options.policy ?? 'security';
+  if (policy === 'off') {
+    return { stop: () => {}, drain: async () => {} };
+  }
+  const onWriteError = options.onWriteError ?? defaultOnWriteError;
+  let tail: Promise<unknown> = Promise.resolve();
+  const stop = onToolAudit((event) => {
+    if (policy === 'security' && !SECURITY_ACTIONS.has(event.action)) return;
+    const input = toolAuditEventToAuditInput(event);
+    tail = tail.then(() => appendAudit(db, input)).catch((error) => onWriteError(event, error));
+  });
+  return {
+    stop,
+    drain: async () => {
+      await tail;
+    },
+  };
+}
+
+function defaultOnWriteError(event: ToolAuditEvent, error: unknown): void {
+  console.warn(
+    `[graphorin/server] WARN: failed to write a tool audit entry (${event.action}): ${
+      error instanceof Error ? error.message : String(error)
+    }`,
+  );
+}

package/src/triggers/daemon.ts

@@ -0,0 +1,198 @@
+/**
+ * Trigger scheduler integration with the server lifecycle.
+ *
+ * The daemon wraps a `Scheduler` from `@graphorin/triggers` and binds
+ * its `start()` / `stop()` calls to the `beforeStart` / `beforeShutdown`
+ * lifecycle hooks. On `start()`, every persisted trigger is loaded
+ * from `trigger_state` (durable) and the per-trigger `catchupPolicy`
+ * is honoured so cron / interval / idle / event triggers survive
+ * process restarts as documented in the runtime spec.
+ *
+ * The daemon never invokes user callbacks itself - those run inside
+ * the `Scheduler`. The daemon only owns lifecycle + observability.
+ *
+ * @packageDocumentation
+ */
+
+import type { CatchupPolicy, Scheduler, SchedulerEvent } from '@graphorin/triggers';
+
+/**
+ * Snapshot exposed via {@link TriggersDaemon.status} + the
+ * `/v1/health` aggregator. Counts split by `disabled` so the health
+ * endpoint can flag a deployment that disabled every cron trigger.
+ *
+ * @stable
+ */
+export interface TriggersDaemonStatus {
+  readonly running: boolean;
+  readonly active: number;
+  readonly disabled: number;
+  readonly deferred: number;
+  /** Last fire timestamp across the entire pool (ISO-8601). */
+  readonly lastFireAt?: string;
+}
+
+/**
+ * Aggregate counters surfaced through the Prometheus
+ * `/v1/metrics` exposition. Updated incrementally as the scheduler
+ * publishes lifecycle events.
+ *
+ * @stable
+ */
+export interface TriggersDaemonMetrics {
+  readonly fires: ReadonlyMap<string, { readonly success: number; readonly error: number }>;
+  readonly catchupApplied: number;
+  readonly libModeWarnings: number;
+}
+
+/**
+ * @stable
+ */
+export interface CreateTriggersDaemonOptions {
+  readonly scheduler: Scheduler;
+  /**
+   * Optional logger. Defaults to the standard error stream so the
+   * daemon never depends on the framework logger directly.
+   */
+  readonly warn?: (message: string) => void;
+}
+
+/**
+ * Stateful handle returned by {@link createTriggersDaemon}. The
+ * `start()` / `stop()` methods are wired into
+ * `LifecycleHooks.beforeStart` / `beforeShutdown` by `createServer`.
+ *
+ * @stable
+ */
+export interface TriggersDaemon {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  status(): Promise<TriggersDaemonStatus>;
+  metrics(): TriggersDaemonMetrics;
+  readonly scheduler: Scheduler;
+}
+
+/**
+ * @stable
+ */
+export function createTriggersDaemon(options: CreateTriggersDaemonOptions): TriggersDaemon {
+  const fires = new Map<string, { success: number; error: number }>();
+  let catchupApplied = 0;
+  let libModeWarnings = 0;
+  let lastFireAtMs: number | undefined;
+  let running = false;
+  let pump: Promise<void> | undefined;
+
+  const warn = options.warn ?? ((m: string) => process.stderr.write(`${m}\n`));
+
+  function recordFire(id: string, kind: 'success' | 'error'): void {
+    const entry = fires.get(id) ?? { success: 0, error: 0 };
+    entry[kind] += 1;
+    fires.set(id, entry);
+    lastFireAtMs = Date.now();
+  }
+
+  async function pumpEvents(): Promise<void> {
+    try {
+      for await (const event of options.scheduler.events()) {
+        observe(event);
+      }
+    } catch (err) {
+      warn(`[graphorin/server] triggers daemon event pump aborted: ${describeError(err)}`);
+    }
+  }
+
+  function observe(event: SchedulerEvent): void {
+    switch (event.type) {
+      case 'fire-end':
+        recordFire(event.id, 'success');
+        return;
+      case 'fire-error':
+        recordFire(event.id, 'error');
+        warn(
+          `[graphorin/server] triggers daemon: trigger '${event.id}' failed after ${event.durationMs}ms: ${describeError(event.error)}`,
+        );
+        return;
+      case 'catchup-applied':
+        catchupApplied += event.missed;
+        return;
+      case 'lib-mode-warning':
+        libModeWarnings += 1;
+        return;
+      default:
+        return;
+    }
+  }
+
+  return {
+    get scheduler() {
+      return options.scheduler;
+    },
+    async start() {
+      if (running) return;
+      running = true;
+      pump = pumpEvents();
+      await options.scheduler.start();
+    },
+    async stop() {
+      if (!running) return;
+      running = false;
+      await options.scheduler.stop();
+      if (pump !== undefined) {
+        try {
+          await pump;
+        } catch {
+          // Best-effort during stop().
+        }
+        pump = undefined;
+      }
+    },
+    async status() {
+      const all = await options.scheduler.list();
+      let active = 0;
+      let disabled = 0;
+      let deferred = 0;
+      for (const t of all) {
+        if (t.disabled) disabled += 1;
+        else active += 1;
+        if (t.missedFires > 0) deferred += 1;
+      }
+      const out: {
+        -readonly [K in keyof TriggersDaemonStatus]?: TriggersDaemonStatus[K];
+      } = {
+        running,
+        active,
+        disabled,
+        deferred,
+      };
+      if (lastFireAtMs !== undefined) {
+        out.lastFireAt = new Date(lastFireAtMs).toISOString();
+      }
+      return Object.freeze(out as TriggersDaemonStatus);
+    },
+    metrics() {
+      return Object.freeze({
+        fires: new Map(fires),
+        catchupApplied,
+        libModeWarnings,
+      });
+    },
+  };
+}
+
+/**
+ * Resolve the catch-up policy default for triggers that did not
+ * declare one explicitly. Returns `'none'` per DEC-150 (personal-
+ * assistant friendly).
+ *
+ * @stable
+ */
+export function defaultCatchupPolicy(): CatchupPolicy {
+  return 'none';
+}
+
+function describeError(err: unknown): string {
+  if (err === null || err === undefined) return 'unknown';
+  if (err instanceof Error) return err.message;
+  return String(err);
+}

package/src/triggers/index.ts

@@ -0,0 +1,16 @@
+/**
+ * `@graphorin/server/triggers` - daemon + REST routes for the
+ * triggers scheduler. Phase 14c surface.
+ *
+ * @packageDocumentation
+ */
+
+export {
+  type CreateTriggersDaemonOptions,
+  createTriggersDaemon,
+  defaultCatchupPolicy,
+  type TriggersDaemon,
+  type TriggersDaemonMetrics,
+  type TriggersDaemonStatus,
+} from './daemon.js';
+export { createTriggersRoutes, type TriggersRoutesDeps } from './routes.js';