Graphorin

Appearance

Graphorin API reference v0.1.0

Graphorin API reference / @graphorin/server

@graphorin/server ​

Standalone server runtime for the Graphorin framework.

License: MITNode.js: 22+

What ships in v0.1 (Phases 14a + 14b + 14c) ​

@graphorin/server is the optional, first-class server runtime. Phase 14 is feature-complete: it ships the full HTTP surface, the lifecycle plumbing, the auth + scope + idempotency + audit middleware stack, the programmatic createServer({...}) factory consumed by the graphorin start CLI binary in @graphorin/cli, the graphorin.protocol.v1 WebSocket transport with single-use ticket flow + per-subject replay buffer + delivery-layer commentary-phase trace sanitization, the Server-Sent-Events fallback for proxy-restricted clients, the durable triggers + consolidator daemon integration, the per-subsystem health rollup + /v1/health/secrets admin endpoint, the Prometheus /v1/metrics exposition, and the scope-enforced replay + audit verification endpoints.

CapabilityDetail
HTTP serverBuilt on hono@^4.12.0 and @hono/node-server@^1.19.0.
WebSocketBuilt on @hono/node-ws@^1.3.0; subprotocol graphorin.protocol.v1; bearer + ticket auth; per-subject replay buffer (default 1000 events / 5 min TTL); delivery-layer commentary-phase trace sanitization. Schemas live in @graphorin/protocol.
SSE fallbackGET /v1/sessions/:id/events for non-WebSocket-friendly clients (corporate proxies, restricted networks). Same sanitization, same Last-Event-ID resume semantics.
Lifecycle hooksbeforeStart → pre-bind validation → storage migrations → bind → triggers / consolidator daemons start → onReady; SIGTERM → beforeShutdown → daemons stop → drain → exit.
Pre-bind validationResolves every *Ref field via @graphorin/security resolvers before binding the listener; missing pepper / unresolvable SecretRef / missing encryption peer fail fast with typed errors.
REST endpointsAgents (run, stream, state, abort, resume), workflows (execute, resume, state, checkpoints, fork), sessions, memory, skills, MCP, tokens, audit (list, export, verify), the POST /v1/session/ws-ticket browser ticket route, triggers (list, get, fire, disable, prune), replay (runs/:runId/replay, sessions/:id/replay), /health, /health/secrets, /metrics. Every side-effecting endpoint honours an Idempotency-Key per IETF draft-07.
Auth / scopeAuthorization: Bearer kru_<env>_v1_<...> (HMAC-SHA256 + pepper) wired through TokenVerifier from @graphorin/security. Per-route scope grammar <resource>:<action>[:<id>]. WebSocket upgrade honours both bearer and the single-use ticket flow.
IdempotencySQLite-backed idempotency_records + LRU read cache. Replays cached responses with Idempotency-Replayed: true; mismatched payloads return 409.
CORS / CSRF / rate limitDeny-by-default CORS; double-submit CSRF for browser flows; sliding-window per-IP rate limit.
Audit middlewareForwards every authenticated request through appendAudit (@graphorin/security/audit) with attribution, route, status, and duration. POST /v1/audit/verify walks the SHA-256 hash chain and surfaces the integrity status.
Triggers daemonWraps @graphorin/triggers Scheduler; beforeStart loads every persisted trigger_state row + applies the per-trigger catchupPolicy; beforeShutdown stops the scheduler. Cron / interval / idle / event triggers survive process restarts.
Consolidator daemonLifecycle adapter for the @graphorin/memory consolidator runtime. Hard 10-second stop timeout so the daemon never hangs on a stuck phase.
Health rollup/v1/health returns { status, version, uptimeSeconds, checks: { storage, embedder, secrets, encryption, consolidator, triggers, replayBuffer } }. HTTP 200 on 'degraded' (warn); HTTP 503 on 'failing'.
Secrets health/v1/health/secrets (scope secrets:read) returns the active store + fallback chain + downgrade reason per the secrets capability matrix.
Prometheus metrics/v1/metrics text exposition v0.0.4 with graphorin_* prefix discipline. The canonical inventory covers agent runs, tool calls, provider tokens / cost, WAL size, idempotency hit ratio, trigger fires, redaction drops, consolidator queue depth / DLQ / budget, OAuth token freshness, replay buffer size, in-flight runs, server uptime, and a static graphorin_build_info gauge.
Replay endpointsPOST /v1/runs/:runId/replay and POST /v1/sessions/:id/replay enforce traces:read:sanitized (default) or traces:read:raw (admin); every invocation appends an audit chain entry.
Graceful shutdownDrains in-flight runs within the configured timeout (default 30 s), preserves run state via RunStateTracker, propagates AbortSignal cancellation to handlers, tears down WebSocket subscriptions cleanly.
No phone homeZero implicit network calls — verified by the repository-wide pnpm run check-no-network CI check.

Out of scope for Phase 14 ​

  • Multi-tenant runtime — v0.3+.
  • OpenTelemetry metrics export (in addition to Prometheus) — post-MVP.

Install ​

bash
pnpm add @graphorin/server @graphorin/security @graphorin/store-sqlite \
  @graphorin/protocol @graphorin/triggers hono @hono/node-server @hono/node-ws

Other npm-registry-compatible package managers (npm, yarn, bun) work identically; the project itself is developed with pnpm.

Programmatic usage ​

ts
import { createServer, defineConfig } from '@graphorin/server';

const server = await createServer({
  config: defineConfig({
    server: { host: '127.0.0.1', port: 8080 },
    auth: { kind: 'token', pepperRef: 'keyring:graphorin_server_pepper' },
    storage: { path: './.graphorin/data.db', mode: 'server' },
  }),
});

server.agents.register({
  id: 'echo',
  description: 'Echoes its input back to the caller.',
  agent: {
    id: 'echo',
    async run(input) {
      return { input };
    },
  },
});

const { host, port } = await server.start();
console.error(`graphorin listening on http://${host}:${port}/v1`);

CLI ​

The graphorin start / graphorin init / graphorin migrate CLI ships from @graphorin/cli.

Configuration ​

Every field in defineConfig({...}) is optional and falls back to a documented production-ready default. The full schema (Zod) is exported as ServerConfigSchema from @graphorin/server/config so operators can compose validation pipelines on top of the framework.

The most-frequently-touched options:

FieldDefaultNotes
server.host127.0.0.1Bind to 0.0.0.0 only behind a reverse proxy.
server.port8080
server.basePath/v1
server.idempotency.requireKey'warn''enforce' is opt-in for production.
server.idempotency.ttlSeconds8640024 hours.
server.cors.allowOrigins[]Deny by default; pass an explicit allowlist (or ['*']).
server.csrf.enabledtrueBearer-token requests are exempt.
server.rateLimit.perIpRequests60Per minute.
server.shutdown.drainTimeoutMs30000
auth.kind'token'Set to 'none' only for trusted loopback environments.
auth.pepperRef(required for token auth)A SecretRef pointing at the HMAC pepper.
storage.path'./.graphorin/data.db'
storage.encryption.enabledfalseOpt-in SQLCipher v4 via the better-sqlite3-multiple-ciphers peer.
audit.enabledfalseOpt-in mandatory-encrypted audit log per DEC-124.
metrics.enabledtrueMounts /v1/metrics for Prometheus scraping.
metrics.requireAuthfalseOpt into the admin:metrics:read scope for stricter deployments.
health.walWarnThresholdBytes5242880050 MB; storage check flips to 'warn' above this.

Status ​

@graphorin/server is part of the Graphorin framework's v0.1.0 pre-release. Once published, the package follows the lockstep release cadence shared by every @graphorin/* package on the 0.x line.

Project Graphorin · v0.1.0 · MIT License · © 2026 Oleksiy Stepurenko · https://github.com/o-stepper/graphorin

Modules ​

ModuleDescription
@graphorin/server — standalone server runtime for the Graphorin framework.
commentaryDelivery-layer commentary-phase trace sanitization for @graphorin/server.
configStrongly-typed configuration loader for the Graphorin server.
consolidator@graphorin/server/consolidator — Phase 14c lifecycle adapter for the consolidator runtime.
errorsTyped error surface for @graphorin/server. Every server-side configuration / lifecycle / runtime failure that an operator must be able to reason about flows through one of the classes in this module so it carries a stable kind discriminator + hint field pointing the operator at the next remediation step.
health@graphorin/server/health — Phase 14c health + Prometheus metrics surface. Phase 14a's /v1/health is superseded by the extended routes built here when consumers wire the additional probes.
metrics@graphorin/server/metrics — Phase 14c Prometheus exposition layer.
middlewareMiddleware barrel for @graphorin/server. Every entry is a Hono MiddlewareHandler; they are composed by the createServer({...}) factory in a fixed order:
registryRegistry 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.
replay@graphorin/server/replay — Phase 14c scope-enforced replay endpoints + audit integration.
sseServer-Sent Events fallback transport for @graphorin/server.
triggers@graphorin/server/triggers — daemon + REST routes for the triggers scheduler. Phase 14c surface.
ws@graphorin/server/ws — WebSocket protocol implementation for the Graphorin standalone server. Combines the dispatcher (which fans events out to subscribers + applies the delivery-layer commentary sanitization), the in-memory ticket store (browser single-use ticket flow), the per-subject replay buffer, the strict subject grammar parser + scope check, and the @hono/node-ws upgrade handler.