@graphorin/server 0.6.1 → 0.7.0

package/src/routes/agents.ts

@@ -0,0 +1,363 @@
+/**
+ * Agent REST routes.
+ *
+ *   GET    /agents                       (scope `agents:read`)
+ *   GET    /agents/:id                   (scope `agents:read`)
+ *   POST   /agents/:id/run               (idempotent; scope `agents:invoke[:id]`)
+ *   POST   /agents/:id/stream            (scope `agents:invoke[:id]`)
+ *   GET    /runs/:runId/state            (scope `agents:read`)
+ *   POST   /runs/:runId/abort            (scope `agents:invoke`)
+ *   POST   /runs/:runId/resume           (idempotent; scope `agents:invoke`)
+ *
+ * Agents are looked up via {@link AgentRegistry}; missing entries
+ * surface a 404 with a typed error body.
+ *
+ * @packageDocumentation
+ */
+
+import { toWireAgentEvent } from '@graphorin/core';
+import type { Context } from 'hono';
+import { Hono } from 'hono';
+import { z } from 'zod';
+import { AgentNotFoundError } from '../errors/index.js';
+import type { ServerVariables } from '../internal/context.js';
+import { newRequestId } from '../internal/ids.js';
+import {
+  checkScope,
+  createAuthenticatedMiddleware,
+  createScopeMiddleware,
+} from '../middleware/scope.js';
+import type { AgentRegistry } from '../registry/index.js';
+import { type RunStateTracker, requiredRunScope } from '../runtime/run-state.js';
+
+/**
+ * @stable
+ */
+export interface AgentRoutesDeps {
+  readonly agents: AgentRegistry;
+  readonly runs: RunStateTracker;
+  readonly newRunId?: () => string;
+  /**
+   * Streaming dispatcher (IP-2). When present, `POST /:id/stream`
+   * actually runs the agent and emits every event onto the
+   * `agent:<id>/runs/<runId>/events` subject.
+   */
+  readonly dispatcher?: import('../ws/dispatcher.js').WsDispatcher;
+}
+
+const RunBodySchema = z
+  .object({
+    input: z.unknown().optional(),
+    sessionId: z.string().min(1).optional(),
+    userId: z.string().min(1).optional(),
+  })
+  .strict()
+  .default({});
+
+/**
+ * @stable
+ */
+export function createAgentRoutes(deps: AgentRoutesDeps): Hono<{ Variables: ServerVariables }> {
+  const app = new Hono<{ Variables: ServerVariables }>();
+  const newRunId = deps.newRunId ?? newRequestId;
+
+  app.get('/', createScopeMiddleware('agents:read'), (c) => c.json({ agents: deps.agents.list() }));
+
+  app.get(
+    '/:id',
+    createScopeMiddleware((_path, params) => `agents:read:${params.id}`),
+    (c) => {
+      const id = c.req.param('id');
+      const summary = deps.agents.describe(id);
+      if (summary === undefined) {
+        return c.json(
+          { error: 'agent-not-found', message: `Agent '${id}' is not registered.` },
+          404,
+        );
+      }
+      return c.json(summary);
+    },
+  );
+
+  app.post(
+    '/:id/run',
+    createScopeMiddleware((_path, params) => `agents:invoke:${params.id}`),
+    async (c) => {
+      const id = c.req.param('id');
+      const agent = deps.agents.get(id);
+      if (agent === undefined) {
+        const err = new AgentNotFoundError(id);
+        return c.json({ error: err.kind, message: err.message }, 404);
+      }
+      const parsed = RunBodySchema.safeParse(await safelyParseJson(c));
+      if (!parsed.success) {
+        return invalidBodyResponse(c, parsed.error);
+      }
+      const runId = newRunId();
+      const sessionId = parsed.data.sessionId;
+      const userId = parsed.data.userId;
+      const tracker = deps.runs.start(runId, {
+        kind: 'agent',
+        agentId: id,
+        ...(sessionId !== undefined ? { sessionId } : {}),
+        ...(userId !== undefined ? { userId } : {}),
+      });
+      try {
+        const callOptions: { signal?: AbortSignal; sessionId?: string; userId?: string } = {
+          signal: tracker.signal,
+        };
+        if (sessionId !== undefined) callOptions.sessionId = sessionId;
+        if (userId !== undefined) callOptions.userId = userId;
+        const result = await agent.run(parsed.data.input ?? '', callOptions);
+        deps.runs.complete(runId, 'completed');
+        return c.json({ runId, status: 'completed', result }, 200);
+      } catch (err) {
+        const aborted = tracker.signal.aborted;
+        deps.runs.complete(runId, aborted ? 'aborted' : 'failed', err);
+        return c.json(
+          {
+            runId,
+            status: aborted ? 'aborted' : 'failed',
+            error: aborted ? 'run-aborted' : 'run-failed',
+            message: err instanceof Error ? err.message : String(err),
+          },
+          aborted ? 408 : 500,
+        );
+      }
+    },
+  );
+
+  app.post(
+    '/:id/stream',
+    createScopeMiddleware((_path, params) => `agents:invoke:${params.id}`),
+    async (c) => {
+      const id = c.req.param('id');
+      if (!deps.agents.has(id)) {
+        const err = new AgentNotFoundError(id);
+        return c.json({ error: err.kind, message: err.message }, 404);
+      }
+      // W-151: validate the body BEFORE any run is registered - the old
+      // handler swallowed a failed parse and launched the agent on an
+      // empty prompt, burning provider tokens behind a 202 that looked
+      // successful. Identical validation to the sibling /run route
+      // (empty/absent bodies stay valid via the schema default).
+      const parsed = RunBodySchema.safeParse(await safelyParseJson(c));
+      if (!parsed.success) {
+        return invalidBodyResponse(c, parsed.error);
+      }
+      const runId = newRunId();
+      const sessionId = parsed.data.sessionId;
+      const userId = parsed.data.userId;
+      const input = parsed.data.input ?? '';
+      // IP-2: actually run the agent. The old handler parsed the input
+      // and threw it away - the run sat 'pending' forever while the 202
+      // advertised subjects nothing would ever emit on.
+      const tracker = deps.runs.start(runId, {
+        kind: 'agent',
+        agentId: id,
+        ...(sessionId !== undefined ? { sessionId } : {}),
+        ...(userId !== undefined ? { userId } : {}),
+      });
+      const subject = `agent:${id}/runs/${runId}/events`;
+      const agent = deps.agents.get(id);
+      if (agent !== undefined) {
+        backgroundStreamAgent(agent, input, {
+          signal: tracker.signal,
+          ...(sessionId !== undefined ? { sessionId } : {}),
+          ...(userId !== undefined ? { userId } : {}),
+          runs: deps.runs,
+          runId,
+          subject,
+          ...(deps.dispatcher !== undefined ? { dispatcher: deps.dispatcher } : {}),
+        });
+      }
+      return c.json(
+        {
+          runId,
+          status: 'running',
+          subscribe: {
+            // The SSE URL previously advertised here pointed at a path
+            // that was never mounted - the WebSocket subject is the
+            // delivery channel (IP-2).
+            websocket: subject,
+          },
+        },
+        202,
+      );
+    },
+  );
+
+  return app;
+}
+
+/**
+ * IP-2: consume the agent's event stream in the background and emit
+ * every event onto the run subject. Falls back to `run(...)` (a single
+ * terminal frame) for registry entries without a `stream` surface.
+ */
+function backgroundStreamAgent(
+  agent: ReturnType<AgentRegistry['get']> & object,
+  input: unknown,
+  opts: {
+    readonly signal: AbortSignal;
+    readonly sessionId?: string;
+    readonly userId?: string;
+    readonly runs: RunStateTracker;
+    readonly runId: string;
+    readonly subject: string;
+    readonly dispatcher?: import('../ws/dispatcher.js').WsDispatcher;
+  },
+): void {
+  const emit = (type: string, payload: unknown): void => {
+    opts.dispatcher?.emit(opts.subject, { type, payload });
+  };
+  void (async () => {
+    try {
+      const callOpts = {
+        signal: opts.signal,
+        ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
+        ...(opts.userId !== undefined ? { userId: opts.userId } : {}),
+      };
+      if (typeof agent.stream === 'function') {
+        for await (const ev of agent.stream(input, callOpts)) {
+          if (opts.signal.aborted) break;
+          const type =
+            typeof (ev as { type?: unknown }).type === 'string'
+              ? (ev as { type: string }).type
+              : 'agent.event';
+          // W-046: binary-bearing variants (file.generated,
+          // tool.execute.partial, agent.end with its full RunState) must
+          // be projected to their JSON-safe wire twins before the
+          // dispatcher stringifies the frame. Unknown types pass through.
+          emit(type, toWireAgentEvent(ev as Parameters<typeof toWireAgentEvent>[0]));
+        }
+      } else {
+        const output = await agent.run(input, callOpts);
+        emit('agent.end', { runId: opts.runId, output });
+      }
+      opts.runs.complete(opts.runId, opts.signal.aborted ? 'aborted' : 'completed');
+    } catch (err) {
+      emit('agent.error', {
+        runId: opts.runId,
+        message: err instanceof Error ? err.message : String(err),
+      });
+      opts.runs.complete(opts.runId, opts.signal.aborted ? 'aborted' : 'failed', err);
+    }
+  })();
+}
+
+/**
+ * Companion router for the `/runs/...` surface. Kept separate so the
+ * `createServer` factory can mount it under the top-level base path
+ * rather than under `/agents`.
+ *
+ * @stable
+ */
+export function createRunRoutes(deps: AgentRoutesDeps): Hono<{ Variables: ServerVariables }> {
+  const app = new Hono<{ Variables: ServerVariables }>();
+
+  // W-107: run control binds to the run's OWNING resource. The
+  // requirement is only known after the snapshot resolves the
+  // descriptor, so the outer gate is authentication-only and the
+  // handlers authorize imperatively: 404 for unknown runs first
+  // (runIds are unguessable newRequestId values and ephemeral - the
+  // ordering is deliberate and matches WS run.cancel), then 403 when
+  // the grant does not cover the owning agent/workflow. Bare
+  // `agents:read`/`agents:invoke` grants keep covering their
+  // per-resource requirements.
+  app.get('/:runId/state', createAuthenticatedMiddleware(), (c) => {
+    const runId = c.req.param('runId');
+    const state = deps.runs.snapshot(runId);
+    if (state === undefined) {
+      return c.json({ error: 'run-not-found', message: `Run '${runId}' is not registered.` }, 404);
+    }
+    const required = requiredRunScope(state, 'read');
+    if (!checkScope(c.get('state').auth, required)) {
+      return c.json(
+        { error: 'scope-denied', message: `Token lacks required scope '${required}'.` },
+        403,
+      );
+    }
+    return c.json(state);
+  });
+
+  app.post('/:runId/abort', createAuthenticatedMiddleware(), (c) => {
+    const runId = c.req.param('runId');
+    const state = deps.runs.snapshot(runId);
+    if (state === undefined) {
+      return c.json({ error: 'run-not-found', message: `Run '${runId}' is not registered.` }, 404);
+    }
+    const required = requiredRunScope(state, 'control');
+    if (!checkScope(c.get('state').auth, required)) {
+      return c.json(
+        { error: 'scope-denied', message: `Token lacks required scope '${required}'.` },
+        403,
+      );
+    }
+    const aborted = deps.runs.abort(runId);
+    if (!aborted) {
+      return c.json({ error: 'run-not-found', message: `Run '${runId}' is not registered.` }, 404);
+    }
+    return c.json({ runId, status: 'aborted' });
+  });
+
+  app.post('/:runId/resume', createAuthenticatedMiddleware(), async (c) => {
+    const runId = c.req.param('runId');
+    const state = deps.runs.snapshot(runId);
+    if (state === undefined) {
+      return c.json({ error: 'run-not-found', message: `Run '${runId}' is not registered.` }, 404);
+    }
+    const requiredResume = requiredRunScope(state, 'control');
+    if (!checkScope(c.get('state').auth, requiredResume)) {
+      return c.json(
+        { error: 'scope-denied', message: `Token lacks required scope '${requiredResume}'.` },
+        403,
+      );
+    }
+    // IP-14: a 202 that persists nothing and resumes nothing is a lie
+    // the client SDK was built on. Until the server can rehydrate the
+    // RunState and re-enter the agent loop (the persisted-approvals
+    // work - Wave 3), the honest answer is 501 with the working
+    // library-side path: `agent.run(result.state, { directive })`
+    // executes approved tools for real (AG-1/AG-9).
+    return c.json(
+      {
+        error: 'resume-not-implemented',
+        runId,
+        status: state.status,
+        message:
+          'Server-side HITL resume is not implemented yet. Resume library-side: ' +
+          'agent.run(result.state, { directive }) - the suspended RunState is on the AgentResult.',
+      },
+      501,
+    );
+  });
+
+  return app;
+}
+
+/**
+ * W-151: byte-identical 400 for an invalid run/stream body - both
+ * sibling routes validate through this one helper.
+ */
+function invalidBodyResponse(
+  c: Context<{ Variables: ServerVariables }>,
+  error: { issues: ReadonlyArray<{ path: ReadonlyArray<PropertyKey>; message: string }> },
+) {
+  return c.json(
+    {
+      error: 'config-invalid',
+      message: 'Invalid run body.',
+      issues: error.issues.map((i) => ({ path: i.path, message: i.message })),
+    },
+    400,
+  );
+}
+
+async function safelyParseJson(c: Context<{ Variables: ServerVariables }>): Promise<unknown> {
+  try {
+    return await c.req.json();
+  } catch {
+    return {};
+  }
+}

package/src/routes/audit.ts

@@ -0,0 +1,207 @@
+/**
+ * Audit-log REST routes.
+ *
+ *   GET    /audit                      (scope `audit:read`)
+ *   POST   /audit/export               (scope `audit:export`)
+ *
+ * The handler delegates to a structurally-typed `AuditApi` so the
+ * server code stays decoupled from any single audit backend.
+ *
+ * @packageDocumentation
+ */
+
+import type { Context } from 'hono';
+import { Hono } from 'hono';
+import { z } from 'zod';
+
+import type { ServerVariables } from '../internal/context.js';
+import { createScopeMiddleware } from '../middleware/scope.js';
+
+/**
+ * @stable
+ */
+export interface AuditApi {
+  list(opts: {
+    readonly limit?: number;
+    readonly fromSeq?: number;
+    /** Inclusive lower bound on the entry timestamp (epoch ms). */
+    readonly fromTs?: number;
+    /** Inclusive upper bound on the entry timestamp (epoch ms). */
+    readonly toTs?: number;
+    /** Restrict to entries whose `action` matches the supplied id. */
+    readonly action?: string;
+  }): Promise<ReadonlyArray<unknown>>;
+  export(opts: {
+    readonly fromSeq?: number;
+    readonly toSeq?: number;
+    readonly format?: 'jsonl' | 'csv';
+  }): Promise<{ readonly bytes: number; readonly format?: 'jsonl' | 'csv' }>;
+  /**
+   * Verify the chain integrity of every audit row in the inclusive
+   * range. Phase 14c surfaces this through `POST /v1/audit/verify`.
+   * Optional - operators that opt out of the audit chain should
+   * leave this method off.
+   */
+  verify?(opts: {
+    readonly fromSeq?: number;
+    readonly toSeq?: number;
+  }): Promise<{ readonly ok: boolean; readonly count?: number; readonly brokenAt?: number }>;
+}
+
+const ISO_OR_EPOCH = z.union([z.coerce.number().int().nonnegative(), z.string().min(1)]);
+
+const ListQuerySchema = z
+  .object({
+    limit: z.coerce.number().int().positive().max(1000).optional(),
+    fromSeq: z.coerce.number().int().nonnegative().optional(),
+    from: ISO_OR_EPOCH.optional(),
+    to: ISO_OR_EPOCH.optional(),
+    action: z.string().min(1).max(256).optional(),
+  })
+  .strict();
+
+function parseTimestamp(input: unknown): number | undefined {
+  if (input === undefined) return undefined;
+  if (typeof input === 'number') return input;
+  const parsed = Date.parse(String(input));
+  return Number.isNaN(parsed) ? undefined : parsed;
+}
+
+const ExportBodySchema = z
+  .object({
+    fromSeq: z.number().int().nonnegative().optional(),
+    toSeq: z.number().int().nonnegative().optional(),
+    format: z.enum(['jsonl', 'csv']).optional(),
+  })
+  .strict()
+  .default({});
+
+/**
+ * @stable
+ */
+export interface AuditRoutesDeps {
+  readonly audit: AuditApi;
+}
+
+/**
+ * @stable
+ */
+export function createAuditRoutes(deps: AuditRoutesDeps): Hono<{ Variables: ServerVariables }> {
+  const app = new Hono<{ Variables: ServerVariables }>();
+
+  app.get('/', createScopeMiddleware('audit:read'), async (c) => {
+    const parsed = ListQuerySchema.safeParse({
+      limit: c.req.query('limit'),
+      fromSeq: c.req.query('fromSeq'),
+      from: c.req.query('from'),
+      to: c.req.query('to'),
+      action: c.req.query('action'),
+    });
+    if (!parsed.success) {
+      return c.json(
+        {
+          error: 'config-invalid',
+          message: 'Invalid audit query.',
+          issues: parsed.error.issues.map((i) => ({ path: i.path, message: i.message })),
+        },
+        400,
+      );
+    }
+    const fromTs = parseTimestamp(parsed.data.from);
+    const toTs = parseTimestamp(parsed.data.to);
+    if (parsed.data.from !== undefined && fromTs === undefined) {
+      return c.json(
+        {
+          error: 'config-invalid',
+          message: `Invalid 'from' timestamp: '${String(parsed.data.from)}' is not parseable.`,
+        },
+        400,
+      );
+    }
+    if (parsed.data.to !== undefined && toTs === undefined) {
+      return c.json(
+        {
+          error: 'config-invalid',
+          message: `Invalid 'to' timestamp: '${String(parsed.data.to)}' is not parseable.`,
+        },
+        400,
+      );
+    }
+    const filters: {
+      limit?: number;
+      fromSeq?: number;
+      fromTs?: number;
+      toTs?: number;
+      action?: string;
+    } = {};
+    if (parsed.data.limit !== undefined) filters.limit = parsed.data.limit;
+    if (parsed.data.fromSeq !== undefined) filters.fromSeq = parsed.data.fromSeq;
+    if (fromTs !== undefined) filters.fromTs = fromTs;
+    if (toTs !== undefined) filters.toTs = toTs;
+    if (parsed.data.action !== undefined) filters.action = parsed.data.action;
+    const entries = await deps.audit.list(filters);
+    return c.json({ entries });
+  });
+
+  app.post('/verify', createScopeMiddleware('audit:verify'), async (c) => {
+    if (deps.audit.verify === undefined) {
+      return c.json(
+        {
+          error: 'not-implemented',
+          message: 'Audit chain verification is not enabled on this deployment.',
+        },
+        501,
+      );
+    }
+    const parsed = ExportBodySchema.safeParse(await safelyParseJson(c));
+    if (!parsed.success) {
+      return c.json(
+        {
+          error: 'config-invalid',
+          message: 'Invalid verify body.',
+          issues: parsed.error.issues.map((i) => ({ path: i.path, message: i.message })),
+        },
+        400,
+      );
+    }
+    const opts: { fromSeq?: number; toSeq?: number } = {};
+    if (parsed.data.fromSeq !== undefined) opts.fromSeq = parsed.data.fromSeq;
+    if (parsed.data.toSeq !== undefined) opts.toSeq = parsed.data.toSeq;
+    const result = await deps.audit.verify(opts);
+    return c.json({ verify: result });
+  });
+
+  app.post('/export', createScopeMiddleware('audit:export'), async (c) => {
+    const parsed = ExportBodySchema.safeParse(await safelyParseJson(c));
+    if (!parsed.success) {
+      return c.json(
+        {
+          error: 'config-invalid',
+          message: 'Invalid export body.',
+          issues: parsed.error.issues.map((i) => ({ path: i.path, message: i.message })),
+        },
+        400,
+      );
+    }
+    const queryFormat = c.req.query('format');
+    const requestedFormat =
+      parsed.data.format ??
+      (queryFormat === 'csv' ? 'csv' : queryFormat === 'jsonl' ? 'jsonl' : undefined);
+    const opts: { fromSeq?: number; toSeq?: number; format?: 'jsonl' | 'csv' } = {};
+    if (parsed.data.fromSeq !== undefined) opts.fromSeq = parsed.data.fromSeq;
+    if (parsed.data.toSeq !== undefined) opts.toSeq = parsed.data.toSeq;
+    if (requestedFormat !== undefined) opts.format = requestedFormat;
+    const result = await deps.audit.export(opts);
+    return c.json({ export: result });
+  });
+
+  return app;
+}
+
+async function safelyParseJson(c: Context<{ Variables: ServerVariables }>): Promise<unknown> {
+  try {
+    return await c.req.json();
+  } catch {
+    return {};
+  }
+}

package/src/routes/auth.ts

@@ -0,0 +1,80 @@
+/**
+ * Auth-related REST routes that exist purely to support the WebSocket
+ * surface in `@graphorin/server/ws`.
+ *
+ *   POST /session/ws-ticket    (scope `agents:invoke`)
+ *
+ * Browser clients call the endpoint with a regular HTTP `Authorization:
+ * Bearer <token>` header to mint a single-use, short-lived ticket; the
+ * ticket value is then attached to the WebSocket upgrade request as a
+ * second `Sec-WebSocket-Protocol` token (`ticket.<value>`). The
+ * server-side WS upgrade handler (see `../ws/upgrade.ts`) consumes the
+ * ticket against the same in-memory store so the round-trip is
+ * race-free.
+ *
+ * @packageDocumentation
+ */
+
+import { Hono } from 'hono';
+
+import type { ServerVariables } from '../internal/context.js';
+import { createAuthenticatedMiddleware } from '../middleware/scope.js';
+import type { WsTicketStore } from '../ws/ticket.js';
+
+/**
+ * Stable shape consumed by {@link createAuthRoutes}.
+ *
+ * @stable
+ */
+export interface AuthRoutesDeps {
+  readonly tickets: WsTicketStore;
+}
+
+/**
+ * Build the auth router. The router is mounted at the same base path
+ * as the rest of the REST surface (defaults to `/v1`).
+ *
+ * @stable
+ */
+export function createAuthRoutes(deps: AuthRoutesDeps): Hono<{ Variables: ServerVariables }> {
+  const app = new Hono<{ Variables: ServerVariables }>();
+
+  // W-107: the ticket ADDS no rights - it carries the principal's own
+  // scopes and every subscribe is per-subject gated on the dispatcher -
+  // so possession of a valid principal is the whole requirement. The
+  // old `agents:invoke` gate locked read-only tokens out of the
+  // browser WS path entirely.
+  app.post('/session/ws-ticket', createAuthenticatedMiddleware(), (c) => {
+    const auth = c.get('state').auth;
+    // IP-13: in the no-auth loopback mode (`auth.kind='none'`) there is no
+    // bearer token, but the anonymous principal is fully authorized - mint a
+    // ticket bound to a synthetic `anonymous` id so a browser client written
+    // for token mode still completes the round-trip.
+    const principal =
+      auth.kind === 'token'
+        ? { tokenId: auth.token.tokenId, scopes: auth.grantedScopes }
+        : auth.kind === 'anonymous'
+          ? { tokenId: 'anonymous', scopes: auth.grantedScopes }
+          : undefined;
+    if (principal === undefined) {
+      return c.json(
+        {
+          error: 'auth-required',
+          message: 'Bearer token required to mint a WS ticket.',
+        },
+        401,
+      );
+    }
+    const ticket = deps.tickets.issue(principal);
+    return c.json(
+      {
+        ticket: ticket.value,
+        expiresAt: ticket.expiresAt,
+        ttlMs: deps.tickets.ttlMs,
+      },
+      201,
+    );
+  });
+
+  return app;
+}

package/src/routes/health.ts

@@ -0,0 +1,42 @@
+/**
+ * `GET /v1/health` - minimal health endpoint kept for backward
+ * compatibility with consumers that wired the Phase 14a route
+ * factory directly. The active server now mounts the extended
+ * Phase 14c routes from `@graphorin/server/health`. New code should
+ * use {@link import('../health/routes.js').createExtendedHealthRoutes}.
+ *
+ * @deprecated Phase 14c. Use `createExtendedHealthRoutes` from
+ *             `@graphorin/server/health` instead. This export
+ *             stays available so existing consumers do not break.
+ *
+ * @packageDocumentation
+ */
+
+import { Hono } from 'hono';
+
+import type { ServerVariables } from '../internal/context.js';
+
+/**
+ * @stable
+ */
+export interface HealthRoutesDeps {
+  readonly version: string;
+  readonly startedAt: number;
+  readonly now?: () => number;
+}
+
+/**
+ * @stable
+ */
+export function createHealthRoutes(deps: HealthRoutesDeps): Hono<{ Variables: ServerVariables }> {
+  const app = new Hono<{ Variables: ServerVariables }>();
+  const now = deps.now ?? Date.now;
+  app.get('/', (c) =>
+    c.json({
+      status: 'ok' as const,
+      version: deps.version,
+      uptimeSeconds: Math.max(0, Math.floor((now() - deps.startedAt) / 1000)),
+    }),
+  );
+  return app;
+}