Graphorin

Appearance

Graphorin API reference v0.1.0

Graphorin API reference v0.1.0 ​

Packages ​

PackageDescription
@graphorin/agentAgent runtime for the Graphorin framework: createAgent({...}) factory, the typed model -> tool calls -> model loop, the AgentEvent<TOutput> discriminated event stream, steering / followUp queues, durable HITL approvals via RunState.toJSON / fromJSON, multi-agent handoffs (Agent.toTool, filter library, secrets isolation), agent-level model fallback chain, intra-loop reasoning preservation, post-compaction hook lifecycle, agent-step-level fan-out (Agent.fanOut + evaluatorOptimizer + progress artifacts), per-tool model-tier hint resolution, lateral-leak defense layer (CausalityMonitor + MergeAgentSidewaysInjectionGuard + protocol-guard), inbound-content sanitization preamble injection, and AbortSignal-aware hard-kill / drain cancellation. Created and maintained by Oleksiy Stepurenko.
@graphorin/cliOperator CLI for the Graphorin framework. Phase 14a ships the minimal graphorin binary with three commands: graphorin start (boot the standalone server with lifecycle hooks + pre-bind validation + storage migrations + audit log), graphorin init (interactive prompts for cloud-upload consent, opt-in storage encryption, and one-shot bootstrap-token issuance; --non-interactive accepts every option as flags or env vars), and graphorin migrate (idempotent storage migrations against the configured SQLite store). Phase 15 extends the same binary with doctor, token, secrets, storage, audit, memory, consolidator, triggers, auth, pricing, skills, traces, migrate-export, guard, and telemetry. Created and maintained by Oleksiy Stepurenko.
@graphorin/clientReference TypeScript client for the Graphorin standalone server. Wraps the WebSocket subprotocol graphorin.protocol.v1 (with the optional Server-Sent Events fallback for proxy-restricted environments) behind an ergonomic GraphorinClient class: connect(), subscribe({ target, id }) returning an async-iterable subscription, cancel(runId, opts), resume(runId, directive), ping(), disconnect(). Handles the browser ticket flow (single-use ticket attached as a ticket.<value> Sec-WebSocket-Protocol token), exponential-backoff reconnect with lastEventId resume against the server replay buffer, and Zod-validated frame parsing on both directions. Browser-friendly: zero Node-only dependencies; the only runtime dependencies are @graphorin/protocol and zod. Created and maintained by Oleksiy Stepurenko.
@graphorin/coreCore types, contracts, and utilities for the Graphorin framework. Dependency-free root package every other @graphorin/* package depends on.
@graphorin/embedder-ollamaFirst-class opt-in alternative to @graphorin/embedder-transformersjs for the Graphorin framework. Wraps the local Ollama HTTP API to produce dense embeddings via models such as nomic-embed-text (768-dim, multilingual default), mxbai-embed-large (1024-dim), snowflake-arctic-embed (1024-dim), and bge-m3 (1024-dim). Implements the EmbedderProvider contract with a deterministic configHash that includes the model digest reported by POST /api/show, so a model upgrade in the same Ollama instance produces a different embedder_id and the multi-table per-embedder vec0 layout in @graphorin/store-sqlite triggers a clean migration path.
@graphorin/embedder-transformersjsDefault in-process embedder for the Graphorin framework. Wraps @huggingface/transformers@^4.1.0 to produce dense vectors with the multilingual Xenova/multilingual-e5-base model (768-dim) by default. Implements the EmbedderProvider contract from @graphorin/core/contracts with deterministic configHash, batched embed, lazy model download (cache honours GRAPHORIN_CACHE_DIR), and an actionable error if the model cannot be fetched.
@graphorin/eslint-pluginESLint plugin for projects that build on Graphorin. Ships scaffolds for the eventual public ruleset; full implementations land in later releases.
@graphorin/evalsEval framework for the Graphorin framework. Ships scorer libraries (code/ exact-match, regex, JSON path, predicates; llm/ LLM-judge; prebuilt/ toxicity / factuality / helpfulness), dataset loaders (JSONL, CSV, from-traces, generic iterable), reporters (terminal, markdown, JSON, JUnit XML), a parallel runner with concurrency config, and regression detection that compares the current run against a stored baseline. Builds on the eval primitives shipped from @graphorin/observability (RB-17 / DEC-152 — full orchestrator lives here, post-MVP, decoupled from the core observability bundle so consumers do not pay the dataset / reporter cost when only the inline runner is needed). Created and maintained by Oleksiy Stepurenko.
@graphorin/mcpModel Context Protocol client for the Graphorin framework: stdio + Streamable HTTP + SSE transports, typed MCPClient (listTools / listResources / listPrompts / callTool), toTools() adapter (per-server inbound prompt-injection sanitization, deferred-loading auto-default at the 10-tool threshold, structured-content + outputSchema round-trip with backward-compatible TextContent mirror, per-server result envelope overrides, collision-strategy + per-server priority, per-server preferredModel and side-effect class overrides), pluggable EventStore for resumable streaming sessions (Mcp-Session-Id + Last-Event-ID handshake), OAuth integration backed by @graphorin/security/oauth, typed errors, and library helpers consumed by the upcoming graphorin auth CLI.
@graphorin/memorySix-tier memory system for the Graphorin framework: createMemory() facade with working / session / episodic / semantic / procedural / shared sub-modules, nine memory tools wired into @graphorin/tools, hybrid vector + FTS5 search composed through Reciprocal Rank Fusion (k=60 default) with a pluggable reranker hook, a multi-stage conflict resolution pipeline (exact dedup → embedding three-zone → heuristic regex → subject/predicate → defer-to-deep) with an English locale pack default + plug-in locales, an embedder migration runner with three coexistence policies (lock-on-first / multi-active / auto-migrate), per-record embedder_id enforcement, multi-agent attribution, append-only writes with soft-delete + supersede semantics, default-on bi-temporal storage, AISpan emission for every operation, and tier-aware memory-modification guard wiring.
@graphorin/observabilityObservability primitives for the Graphorin framework: typed AISpan tracer over OpenTelemetry, mandatory withValidation wrapper for every exporter, sensitivity-aware RedactionValidator with built-in PII / secret patterns, GenAI Semantic Conventions conformance helpers, OpenInference span-kind emission, structured logger with span correlation, append-only JSONL exporter for replay, sanitized replay primitives, hierarchical CostTracker, and a minimal inline eval runner alongside a zero-default telemetry stub.
@graphorin/pricingBundled LLM pricing snapshot for the Graphorin framework. Ships per-provider, per-model input / output / cached-read prices alongside provenance metadata, a lookupPrice(...) resolver, snapshot diffing utilities, an opt-in refreshPricing(...) hook (network gated; never automatic), and listMissingModels(...) for trace audits.
@graphorin/protocolWire protocol contract for the Graphorin framework: Zod schemas + TypeScript types for the WebSocket subprotocol graphorin.protocol.v1. Defines the ClientMessage and ServerMessage discriminated unions, the JSON-RPC-shaped control channel (initialize / subscription.subscribe / subscription.unsubscribe / run.cancel / ping), the typed event push frames ({ kind: 'event', subject, type, payload, eventId }), the asynchronous server-initiated error frames ({ kind: 'error', code, message }), the subprotocol negotiation helpers, and the close-code taxonomy (4001 auth.required, 4002 auth.invalid, 4003 auth.revoked, 4004 auth.scope_denied, 4005 rate.limited, 4006 flow.throttled, 4007 server.shutdown, 4008 protocol.violation). Browser-friendly: zero Node-only dependencies; the only runtime dependency is zod. Created and maintained by Oleksiy Stepurenko.
@graphorin/providerVendor-neutral LLM provider layer for the Graphorin framework. Ships the canonical Provider interface, the Vercel AI SDK adapter (default cloud path), three local-LLM adapters (direct Ollama HTTP, llama-server HTTP, and a generic OpenAI-compatible adapter for LMStudio / LocalAI / vLLM / Together-style endpoints), the shared LocalProviderTrust classifier (loopback / private / public-tls / public-cleartext), the canonical-order middleware composer (withTracing / withRetry / withRateLimit / withCostLimit / withCostTracking / withFallback / withRedaction), the pluggable TokenCounter dispatcher (js-tiktoken default plus per-vendor native counters and a heuristic fallback), the per-provider model-tier auto-classifier (fast / balanced / smart), and the production startup hook that fails fast when withRedaction is missing.
@graphorin/provider-llamacpp-nodeIn-process GGUF execution adapter for the Graphorin framework. Wraps node-llama-cpp@^3.5 to load .gguf model files directly into the same Node process — no daemon, no port to manage, no GPU contention with other processes. Declares trust: 'loopback' permanently because the model lives in the same trust boundary as the host process. Ships LlamaCppNativeCounter that wraps model.tokenize() from the loaded GGUF for byte-exact token counts.
@graphorin/reranker-llmLLM-as-reranker adapter for the Graphorin framework. Asks the configured Provider to score (query, passage) pairs against an English (default, locale-agnostic + translatable) scoring prompt; runs scoring in parallel batches via Promise.all(). Defaults: temperature: 0 (deterministic), batch size 5, score scale 0-10. Pluggable scoringPrompt for locale-specific phrasing. Implements the ReRanker contract from @graphorin/memory/search. Created and maintained by Oleksiy Stepurenko.
@graphorin/reranker-transformersjsCross-encoder reranker adapter for the Graphorin framework. Wraps @huggingface/transformers@^4.1.0 to score query / passage pairs in-process via the BAAI BGE family of cross-encoder models. Automatic model selection from the agent locale: 'en' defaults to Xenova/bge-reranker-base (278M); every other locale defaults to BAAI/bge-reranker-v2-m3 (568M, multilingual). FP16 quantization default; FP32 / Q8 opt-in. Lazy-loaded with an optional idle-eviction timer to bound resident memory. Implements the ReRanker contract exposed by @graphorin/memory/search. Created and maintained by Oleksiy Stepurenko.
@graphorin/secret-1passwordReference 1Password secret-resolver adapter for the Graphorin framework. Registers the op:// scheme on top of @graphorin/security's pluggable SecretResolver registry by shelling out to the official 1Password CLI (op read 'op://<vault>/<item>/<field>'). The resolver enforces a strict timeout, validates the URI before invoking the CLI, redacts the resolved value behind a SecretValue, and surfaces actionable errors when the CLI is missing, the user is not signed in, or the requested field is not present. Serves as the canonical template community packages should follow when wiring HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, Bitwarden, or Unix pass as additional SecretResolver implementations. Created and maintained by Oleksiy Stepurenko.
@graphorin/securitySecurity primitives for the Graphorin framework: SecretValue runtime-safe wrapper, SecretRef URI parser, pluggable SecretsStore implementations, per-tool ACL, AsyncLocalStorage-based audit scope tracking, server token authentication (HMAC-SHA256 + pepper + scopes), tamper-evident audit log, four sandbox adapters (none / worker-threads / isolated-vm / docker), tier-based memory-modification guard, declarative input/output guardrails, process-hardening startup helpers, outbound OAuth flows (Authorization Code + PKCE / Device Authorization Grant / Dynamic Client Registration / refresh + revoke), and skills supply-chain helpers (ed25519 SKILL.md signature verification, --ignore-scripts enforcement, allow / deny policy resolver).
@graphorin/serverStandalone server runtime for the Graphorin framework: createServer({...}) factory, Hono HTTP app, REST endpoints (agents / workflows / sessions / memory / skills / mcp / tokens / audit / health / health/secrets / metrics / triggers / runs/:runId/replay / sessions/:id/replay / audit/verify), per-request authentication + scope middleware (HMAC-SHA256 + pepper, server pepper required), brute-force lockout, IETF draft-07 Idempotency-Key middleware with SQLite backing + LRU read cache, deny-by-default CORS, double-submit CSRF for browser flows, sliding-window rate limit, audit middleware that streams every authenticated request through the tamper-evident hash chain, programmatic AgentRegistry / WorkflowRegistry, lifecycle hooks (beforeStart / onReady / beforeShutdown), pre-bind secrets resolution + storage migration runner that fails fast on missing pepper / unresolvable SecretRef / missing encryption peer, graceful SIGTERM drain with state preservation, durable triggers daemon (cron / interval / idle / event survive process restart per the catch-up policy contract), consolidator daemon lifecycle integration with hard stop timeout, per-subsystem health rollup (storage / embedder / secrets / encryption / consolidator / triggers / replay-buffer), Prometheus text exposition /v1/metrics with the canonical graphorin_* metric inventory, scope-enforced replay endpoints (sanitized by default, raw requires traces:read:raw admin scope, every invocation appended to the audit chain), and POST /v1/audit/verify chain integrity check. Created and maintained by Oleksiy Stepurenko.
@graphorin/sessionsHybrid facade-with-state session module for the Graphorin framework: createSession() facade that wraps @graphorin/memory.session for message CRUD (single source of truth), AgentRegistry singleton with register / retire / delete / placeholder semantics, automatic handoff records with input-filter + secrets-inheritance metadata, workflow-run attachments, JSONL session export schema 1.0 (sentinel header + footer, N-2 backwards-compat, lenient-forward-parse, opt-in --hash / --sign / --encrypt), tool-cassette schema 1.0 (graphorin-tool-cassette/1.0) with substitution-vs-live replay policy honouring per-tool sideEffectClass, sanitized-by-default replay with audit + 30-day TTL + traces:read[:sanitized
@graphorin/skillsSkills surface for the Graphorin framework: loader for the SKILL.md packaging format with three-tier progressive disclosure (metadata / body / resources), frontmatter validator implementing the field-resolution algorithm and conflict policy from ADR-043, registry with auto-activation + slash-command activation, supply-chain hardening (signature verification + --ignore-scripts enforcement via @graphorin/security), sandbox-tier propagation for untrusted skills, handoff input-filter declaration recognition, and idempotent migrate-frontmatter library.
@graphorin/store-sqliteDefault SQLite-backed persistence layer for the Graphorin framework. Implements every storage contract from @graphorin/core (MemoryStore, CheckpointStore, SessionStore, TriggerStore, AuthTokenStore, OAuthServerStore, IdempotencyStore) on top of better-sqlite3 with WAL hardening, an atomic migration runner, multi-table per-embedder vec0 vector layout, multilingual FTS5, an optional WorkerPool wrapper for server mode, an idle WAL-checkpoint manager, and a passphrase-resolution / encryption-or-fail-fast hook for the optional @graphorin/store-sqlite-encrypted cipher subpackage.
@graphorin/store-sqlite-encryptedOptional encryption-at-rest sub-pack for the Graphorin framework's default SQLite store. Pulls in better-sqlite3-multiple-ciphers@^12.9.0 (a drop-in fork of better-sqlite3 that bundles SQLite3MultipleCiphers / SQLCipher v4), exposes the encryptDatabase / rekeyDatabase / cipherIntegrityCheck runners that back graphorin storage encrypt / graphorin storage rekey / graphorin storage status, and provides a createEncryptedConnection convenience wrapper around @graphorin/store-sqlite/connection for callers that bypass the CLI. Default cipher: sqlcipher (SQLCipher v4 compatible). Opt-in alternatives: aes256gcm, chacha20. Default OFF; opt-in through graphorin init --encrypted per ADR-030 / DEC-129. Created and maintained by Oleksiy Stepurenko.
@graphorin/toolsTools surface for the Graphorin framework: typed tool({...}) builder backed by Zod schemas, ToolRegistry with strategy-aware collision resolution and deferred-loading support, ToolExecutor with parallel/sequential dispatch, approval flow, sandbox enforcement (via @graphorin/security), per-tool secrets ACL, memory-modification guard wiring, hard-kill cancellation with grace, single-round tool repair, inbound prompt-injection sanitization, four-strategy result truncation, streaming tool execution (progress + partial chunks with bounded backpressure), four-class side-effect taxonomy with idempotency-key callbacks, per-tool model-tier hints, and built-in tool_search for tool retrieval at scale.
@graphorin/triggersBackground-task scheduler for the Graphorin framework. Ships durable cron / interval / idle / event triggers with the same code path in library and server modes, an in-tree 5-field cron parser, per-trigger catch-up policies ('none' default; 'last' or 'all' opt-in), and an AsyncIterable lifecycle event stream so consumers can plug into observability without monkey-patching.
@graphorin/workflowStep-graph workflow engine for the Graphorin framework: createWorkflow({...}) factory, Workflow.execute / resume / getState / listCheckpoints / fork APIs, the Graphorin-named primitives (Directive, Dispatch, pause, LatestValue, AnyValue, Reducer, ListAggregate, Stream, Barrier, Ephemeral), pluggable CheckpointStore-backed durable execution with sync / async / exit durability modes, dynamic parallelism via Dispatch, the per-channel atomic merge resolver, the HITL pause/resume lifecycle (programmatic pause + static pauseAt before/after node lists), the AbortSignal-aware hard-kill / drain cancellation contract, the per-task pending-write log for mid-step recovery, six stream modes (values / updates / messages / tasks / checkpoints / debug / custom), and per-step / per-task / per-checkpoint observability spans (workflow.run, workflow.step, workflow.task, workflow.checkpoint). Created and maintained by Oleksiy Stepurenko.