@graphorin/server 0.6.0 → 0.7.0

package/src/registry/index.ts

@@ -0,0 +1,278 @@
+/**
+ * Registry plumbing that lets the server route handlers locate user-
+ * defined agents, workflows, sessions, memory, skills, and MCP
+ * server bindings without taking a hard peer dependency on every
+ * sibling package.
+ *
+ * Every entry is keyed by string id; lookups never throw - callers
+ * receive `undefined` and the route handler decides how to surface
+ * the miss (typically a 404 with a typed error body).
+ *
+ * W-053: compatibility of `ServerAgentLike` / `ServerWorkflowLike` with
+ * the real `Agent` / `Workflow` surfaces is gated at compile time by
+ * `tests/registry-contract.types.test.ts` - a drift in either direction
+ * fails the server package's typecheck, not a user's runtime. When a
+ * mismatch appears, fix THESE structural types (they are the copy), not
+ * the source interfaces.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Minimal shape the server needs from an `Agent`. Compatible with
+ * the `Agent` interface from `@graphorin/agent` but kept
+ * structurally so we avoid the peer dependency.
+ *
+ * @stable
+ */
+export interface ServerAgentLike {
+  readonly id: string;
+  run(
+    input: unknown,
+    options?: {
+      readonly signal?: AbortSignal;
+      readonly sessionId?: string;
+      readonly userId?: string;
+    },
+  ): Promise<unknown>;
+  /**
+   * Streaming surface (IP-2). `@graphorin/agent` agents satisfy this
+   * structurally; `POST /agents/:id/stream` consumes it and emits
+   * every event onto the run's WS subject. Optional so plain
+   * run-only fixtures keep working (they emit a single terminal frame).
+   */
+  stream?(
+    input: unknown,
+    options?: {
+      readonly signal?: AbortSignal;
+      readonly sessionId?: string;
+      readonly userId?: string;
+    },
+  ): AsyncIterable<unknown>;
+}
+
+/**
+ * Minimal shape the server needs from a `Workflow`. Mirrors the
+ * `Workflow` surface from `@graphorin/workflow`.
+ *
+ * @stable
+ */
+export interface ServerWorkflowLike {
+  readonly name: string;
+  execute(
+    input: unknown,
+    options?: { readonly signal?: AbortSignal; readonly threadId?: string },
+  ): AsyncIterable<unknown>;
+  resume?(
+    threadId: string,
+    directive?: { readonly resume?: unknown },
+    opts?: { readonly signal?: AbortSignal },
+  ): AsyncIterable<unknown>;
+  /** W-119: replay a failed/aborted thread (`POST /:id/retry`). */
+  retry?(threadId: string, opts?: { readonly signal?: AbortSignal }): AsyncIterable<unknown>;
+  /** W-119: fire a due durable timer (`POST /:id/tick`). */
+  tick?(
+    threadId: string,
+    opts?: { readonly now?: number },
+  ): Promise<{ readonly fired: boolean; readonly nextWakeAt: number | null }>;
+  /**
+   * W-119: resolve a NAMED awakeable/approval (`POST /:id/resume` with
+   * `name`) - `approve` is the same primitive under the hood.
+   */
+  resolveAwakeable?(
+    threadId: string,
+    name: string,
+    value?: unknown,
+    opts?: { readonly signal?: AbortSignal },
+  ): AsyncIterable<unknown>;
+  /** W-119: fork a new thread from a checkpoint (`POST /:id/fork`). */
+  fork?(threadId: string, fromCheckpointId: string): Promise<{ readonly newThreadId: string }>;
+  getState?(threadId: string): Promise<unknown>;
+  listCheckpoints?(threadId: string): Promise<ReadonlyArray<unknown>>;
+  /** W-005: per-thread checkpoint erasure (`DELETE /:id/threads/:threadId`). */
+  deleteThread?(threadId: string): Promise<void>;
+}
+
+/**
+ * Snapshot record returned by {@link AgentRegistry.list}.
+ *
+ * @stable
+ */
+export interface AgentSummary {
+  readonly id: string;
+  readonly description?: string;
+  readonly tags?: ReadonlyArray<string>;
+}
+
+/**
+ * Snapshot record returned by {@link WorkflowRegistry.list}.
+ *
+ * @stable
+ */
+export interface WorkflowSummary {
+  readonly id: string;
+  readonly description?: string;
+  readonly tags?: ReadonlyArray<string>;
+}
+
+/**
+ * Internal registry entry - pairs the user-supplied object with the
+ * metadata routes serve to clients.
+ *
+ * @internal
+ */
+interface AgentEntry {
+  readonly id: string;
+  readonly agent: ServerAgentLike;
+  readonly description?: string;
+  readonly tags?: ReadonlyArray<string>;
+}
+
+/**
+ * @internal
+ */
+interface WorkflowEntry {
+  readonly id: string;
+  readonly workflow: ServerWorkflowLike;
+  readonly description?: string;
+  readonly tags?: ReadonlyArray<string>;
+}
+
+/**
+ * Registration descriptor accepted by {@link AgentRegistry.register}.
+ *
+ * @stable
+ */
+export interface AgentRegistration {
+  readonly id: string;
+  readonly agent: ServerAgentLike;
+  readonly description?: string;
+  readonly tags?: ReadonlyArray<string>;
+}
+
+/**
+ * Registration descriptor accepted by {@link WorkflowRegistry.register}.
+ *
+ * @stable
+ */
+export interface WorkflowRegistration {
+  readonly id: string;
+  readonly workflow: ServerWorkflowLike;
+  readonly description?: string;
+  readonly tags?: ReadonlyArray<string>;
+}
+
+/**
+ * Read/write registry for agents the server should expose. Every
+ * mutation is synchronous and the lookup is `O(1)`.
+ *
+ * The class is intentionally tiny - extension points (e.g. lazy
+ * factory loading, per-tenant scoping) live in higher-level packages
+ * and consume this surface as a primitive.
+ *
+ * @stable
+ */
+export class AgentRegistry {
+  readonly #entries: Map<string, AgentEntry> = new Map();
+
+  register(entry: AgentRegistration): void {
+    this.#entries.set(entry.id, {
+      id: entry.id,
+      agent: entry.agent,
+      ...(entry.description !== undefined ? { description: entry.description } : {}),
+      ...(entry.tags !== undefined ? { tags: Object.freeze(entry.tags.slice()) } : {}),
+    });
+  }
+
+  unregister(id: string): boolean {
+    return this.#entries.delete(id);
+  }
+
+  get(id: string): ServerAgentLike | undefined {
+    return this.#entries.get(id)?.agent;
+  }
+
+  has(id: string): boolean {
+    return this.#entries.has(id);
+  }
+
+  list(): ReadonlyArray<AgentSummary> {
+    return Object.freeze(
+      [...this.#entries.values()].map((entry) =>
+        Object.freeze({
+          id: entry.id,
+          ...(entry.description !== undefined ? { description: entry.description } : {}),
+          ...(entry.tags !== undefined ? { tags: entry.tags } : {}),
+        }),
+      ),
+    );
+  }
+
+  describe(id: string): AgentSummary | undefined {
+    const entry = this.#entries.get(id);
+    if (entry === undefined) return undefined;
+    return Object.freeze({
+      id: entry.id,
+      ...(entry.description !== undefined ? { description: entry.description } : {}),
+      ...(entry.tags !== undefined ? { tags: entry.tags } : {}),
+    });
+  }
+
+  size(): number {
+    return this.#entries.size;
+  }
+}
+
+/**
+ * @stable
+ */
+export class WorkflowRegistry {
+  readonly #entries: Map<string, WorkflowEntry> = new Map();
+
+  register(entry: WorkflowRegistration): void {
+    this.#entries.set(entry.id, {
+      id: entry.id,
+      workflow: entry.workflow,
+      ...(entry.description !== undefined ? { description: entry.description } : {}),
+      ...(entry.tags !== undefined ? { tags: Object.freeze(entry.tags.slice()) } : {}),
+    });
+  }
+
+  unregister(id: string): boolean {
+    return this.#entries.delete(id);
+  }
+
+  get(id: string): ServerWorkflowLike | undefined {
+    return this.#entries.get(id)?.workflow;
+  }
+
+  has(id: string): boolean {
+    return this.#entries.has(id);
+  }
+
+  list(): ReadonlyArray<WorkflowSummary> {
+    return Object.freeze(
+      [...this.#entries.values()].map((entry) =>
+        Object.freeze({
+          id: entry.id,
+          ...(entry.description !== undefined ? { description: entry.description } : {}),
+          ...(entry.tags !== undefined ? { tags: entry.tags } : {}),
+        }),
+      ),
+    );
+  }
+
+  describe(id: string): WorkflowSummary | undefined {
+    const entry = this.#entries.get(id);
+    if (entry === undefined) return undefined;
+    return Object.freeze({
+      id: entry.id,
+      ...(entry.description !== undefined ? { description: entry.description } : {}),
+      ...(entry.tags !== undefined ? { tags: entry.tags } : {}),
+    });
+  }
+
+  size(): number {
+    return this.#entries.size;
+  }
+}

package/src/replay/index.ts

@@ -0,0 +1,14 @@
+/**
+ * `@graphorin/server/replay` - Phase 14c scope-enforced replay
+ * endpoints + audit integration.
+ *
+ * @packageDocumentation
+ */
+
+export {
+  createReplayRoutes,
+  type ReplayApi,
+  type ReplayMode,
+  type ReplayResponse,
+  type ReplayRoutesDeps,
+} from './routes.js';

package/src/replay/routes.ts

@@ -0,0 +1,255 @@
+/**
+ * Replay endpoints with scope enforcement.
+ *
+ *   POST   /v1/runs/:runId/replay
+ *   POST   /v1/sessions/:id/replay
+ *
+ * Scope rules:
+ *   - `raw: false` (default) → require `traces:read:sanitized`.
+ *   - `raw: true`            → require `traces:read:raw` (admin).
+ *
+ * Every successful invocation appends a `trace.replay.accessed` audit
+ * entry. The audit write is best-effort: a missing `AuditDb` does not
+ * block the replay.
+ *
+ * The actual replay stream is consumer-supplied - the framework
+ * accepts a `ReplayApi` from the operator that knows how to load
+ * trace events for a `runId` / `sessionId`. Phase 14c only owns the
+ * scope check + audit + transport.
+ *
+ * @packageDocumentation
+ */
+
+import { type AuditDb, appendAudit } from '@graphorin/security/audit';
+import { type ParsedScope, parseScope, scopeMatches } from '@graphorin/security/auth';
+import { Hono } from 'hono';
+import type { ContentfulStatusCode } from 'hono/utils/http-status';
+import { z } from 'zod';
+
+import type { AuthState, ServerVariables } from '../internal/context.js';
+
+/** @stable */
+export type ReplayMode = 'sanitized' | 'raw';
+
+/** @stable */
+export interface ReplayApi {
+  loadRunReplay(input: {
+    readonly runId: string;
+    readonly mode: ReplayMode;
+    readonly fromMessageId?: string;
+    readonly provider?: string;
+  }): Promise<ReplayResponse>;
+  loadSessionReplay(input: {
+    readonly sessionId: string;
+    readonly mode: ReplayMode;
+    readonly fromMessageId?: string;
+    readonly provider?: string;
+  }): Promise<ReplayResponse>;
+}
+
+/** @stable */
+export interface ReplayResponse {
+  readonly events: ReadonlyArray<unknown>;
+  readonly truncated?: boolean;
+  readonly nextCursor?: string;
+}
+
+const SCOPE_SANITIZED: ParsedScope = parseScope('traces:read:sanitized');
+const SCOPE_RAW: ParsedScope = parseScope('traces:read:raw');
+
+const ReplayRequestSchema = z
+  .object({
+    raw: z.boolean().optional(),
+    fromMessageId: z.string().min(1).optional(),
+    provider: z.string().min(1).optional(),
+  })
+  .strict()
+  .default({});
+
+/**
+ * @stable
+ */
+export interface ReplayRoutesDeps {
+  readonly replay: ReplayApi;
+  readonly auditDb?: AuditDb;
+  readonly now?: () => number;
+}
+
+/**
+ * @stable
+ */
+export function createReplayRoutes(deps: ReplayRoutesDeps): Hono<{ Variables: ServerVariables }> {
+  const app = new Hono<{ Variables: ServerVariables }>();
+  const now = deps.now ?? Date.now;
+
+  app.post('/runs/:runId/replay', async (c) => {
+    const runId = c.req.param('runId');
+    const body = ReplayRequestSchema.safeParse(await safelyParseJson(c));
+    if (!body.success) {
+      return c.json(buildValidationError('Invalid replay body.', body.error.issues), 400);
+    }
+    const mode: ReplayMode = body.data.raw === true ? 'raw' : 'sanitized';
+    const auth = c.get('state').auth;
+    const scopeError = enforceReplayScope(auth, mode);
+    if (scopeError !== undefined) {
+      await maybeAppendAudit(deps.auditDb, {
+        actor: auditActor(auth),
+        action: 'replay:skipped',
+        target: `run:${runId}`,
+        decision: 'denied',
+        ts: now(),
+        metadata: { mode, reason: scopeError.code },
+      });
+      return c.json(scopeError.body, scopeError.status);
+    }
+    const replay = await deps.replay.loadRunReplay({
+      runId,
+      mode,
+      ...(body.data.fromMessageId !== undefined ? { fromMessageId: body.data.fromMessageId } : {}),
+      ...(body.data.provider !== undefined ? { provider: body.data.provider } : {}),
+    });
+    await maybeAppendAudit(deps.auditDb, {
+      actor: auditActor(auth),
+      action: 'replay:accessed',
+      target: `run:${runId}`,
+      decision: 'success',
+      ts: now(),
+      metadata: { mode, eventCount: replay.events.length },
+    });
+    return c.json(serializeReplay(replay, mode));
+  });
+
+  app.post('/sessions/:id/replay', async (c) => {
+    const sessionId = c.req.param('id');
+    const body = ReplayRequestSchema.safeParse(await safelyParseJson(c));
+    if (!body.success) {
+      return c.json(buildValidationError('Invalid replay body.', body.error.issues), 400);
+    }
+    const mode: ReplayMode = body.data.raw === true ? 'raw' : 'sanitized';
+    const auth = c.get('state').auth;
+    const scopeError = enforceReplayScope(auth, mode);
+    if (scopeError !== undefined) {
+      await maybeAppendAudit(deps.auditDb, {
+        actor: auditActor(auth),
+        action: 'replay:skipped',
+        target: `session:${sessionId}`,
+        decision: 'denied',
+        ts: now(),
+        metadata: { mode, reason: scopeError.code },
+      });
+      return c.json(scopeError.body, scopeError.status);
+    }
+    const replay = await deps.replay.loadSessionReplay({
+      sessionId,
+      mode,
+      ...(body.data.fromMessageId !== undefined ? { fromMessageId: body.data.fromMessageId } : {}),
+      ...(body.data.provider !== undefined ? { provider: body.data.provider } : {}),
+    });
+    await maybeAppendAudit(deps.auditDb, {
+      actor: auditActor(auth),
+      action: 'replay:accessed',
+      target: `session:${sessionId}`,
+      decision: 'success',
+      ts: now(),
+      metadata: { mode, eventCount: replay.events.length },
+    });
+    return c.json(serializeReplay(replay, mode));
+  });
+
+  return app;
+}
+
+interface ScopeRefusal {
+  readonly code: 'auth-required' | 'scope-denied';
+  readonly status: ContentfulStatusCode;
+  readonly body: { readonly error: string; readonly message: string; readonly hint?: string };
+}
+
+function enforceReplayScope(auth: AuthState, mode: ReplayMode): ScopeRefusal | undefined {
+  // IP-13: both a verified token and the no-auth anonymous principal carry a
+  // `grantedScopes` set; only a genuinely unauthenticated request is refused.
+  if (auth.kind === 'unauthenticated') {
+    return {
+      code: 'auth-required',
+      status: 401,
+      body: {
+        error: 'auth-required',
+        message: 'Authentication required for replay endpoints.',
+      },
+    };
+  }
+  const required = mode === 'raw' ? SCOPE_RAW : SCOPE_SANITIZED;
+  for (const scope of auth.grantedScopes) {
+    if (scopeMatches(scope, required)) return undefined;
+  }
+  return {
+    code: 'scope-denied',
+    status: 403,
+    body: {
+      error: 'scope-denied',
+      message: `Token lacks required scope '${required.raw}'.`,
+      hint: `Mint a token with the '${required.raw}' (or admin:*) scope.`,
+    },
+  };
+}
+
+function auditActor(auth: AuthState): {
+  readonly kind: 'token' | 'system';
+  readonly id: string;
+  readonly label?: string;
+} {
+  if (auth.kind === 'token') {
+    return {
+      kind: 'token',
+      id: auth.token.tokenId,
+      ...(auth.token.label !== undefined ? { label: auth.token.label } : {}),
+    };
+  }
+  // IP-13: attribute no-auth replays to the synthetic 'anonymous' principal.
+  return { kind: 'system', id: auth.kind === 'anonymous' ? 'anonymous' : 'unauthenticated' };
+}
+
+async function maybeAppendAudit(
+  auditDb: AuditDb | undefined,
+  entry: Parameters<typeof appendAudit>[1],
+): Promise<void> {
+  if (auditDb === undefined) return;
+  try {
+    await appendAudit(auditDb, entry);
+  } catch {
+    // Best-effort - replay must not be blocked by audit failures.
+  }
+}
+
+function serializeReplay(replay: ReplayResponse, mode: ReplayMode): Record<string, unknown> {
+  return {
+    mode,
+    events: [...replay.events],
+    ...(replay.truncated === true ? { truncated: true } : {}),
+    ...(replay.nextCursor !== undefined ? { nextCursor: replay.nextCursor } : {}),
+  };
+}
+
+function buildValidationError(
+  message: string,
+  issues: ReadonlyArray<{
+    readonly path: ReadonlyArray<string | number>;
+    readonly message: string;
+  }>,
+): Record<string, unknown> {
+  return {
+    error: 'config-invalid',
+    message,
+    issues: issues.map((i) => ({ path: i.path, message: i.message })),
+  };
+}
+
+async function safelyParseJson(c: {
+  readonly req: { readonly json: () => Promise<unknown> };
+}): Promise<unknown> {
+  try {
+    return await c.req.json();
+  } catch {
+    return {};
+  }
+}