@graphorin/core

The dependency-free root package every other @graphorin/* package builds on.

@graphorin/core defines the public type system and the cross-package contracts for the Graphorin framework. It contains no runtime: every implementation (sandbox, secrets store, memory store, provider adapters, agent runtime, workflow engine, server, …) lives in a sibling package and depends on the interfaces declared here.

Status: v0.6.1 - type and contract surface for the v0.1 release line.
License: MIT - © 2026 Oleksiy Stepurenko.
Engines: Node.js 22+ (ESM only).
Runtime dependencies: none.
Peer dependency: zod (^3.23 || ^4) - used for schema-typed values (stateSchema, inputSchema, outputSchema, EvalScorer, …). Bring whichever Zod version your application already uses.

Installation

pnpm add @graphorin/core zod

What is in here?

The package is organized into four sub-modules with their own exports sub-paths so that consumers can import only what they need:

Sub-path	Contents
`@graphorin/core`	Re-export of the entire surface (types + contracts + utilities + channels).
`@graphorin/core/types`	Plain TypeScript types: `Message`, `AgentEvent`, `WorkflowEvent`, `RunContext`, `RunState`, `Usage`, …
`@graphorin/core/contracts`	Interfaces consumed by other `@graphorin/*` packages: `Provider`, `MemoryStore`, `Tracer`, `Sandbox`, …
`@graphorin/core/utils`	Tiny dependency-free helpers: `collect`, `mapStream`, `merge`, `withSignal`, `md5`, `xxhash`, …
`@graphorin/core/channels`	Workflow channel types (`LatestValue`, `Reducer`, `Stream`, `Barrier`, `Ephemeral`, `AnyValue`) plus the durable primitives `sleepFor` / `sleepUntil`, `awaitExternal`, and `requestApproval`.

Naming notes

The workflow primitive set in @graphorin/core/channels is Graphorin's own design: Directive for control flow, Dispatch for dynamic tasks, pause(value) for programmatic suspension, the channel kinds LatestValue, Reducer, Stream, Barrier, Ephemeral, AnyValue, and the durable-suspension primitives sleepFor / sleepUntil (durable timers), awaitExternal (awakeables), and requestApproval (persisted approvals) that @graphorin/workflow executes. These names are part of the public API and must not be aliased to terms from other workflow libraries (a dedicated lint rule lands later in the release).
SecretValue is exposed here as an interface, not a class: the runtime implementation lives in @graphorin/security. Downstream packages typing parameters as SecretValue therefore depend only on @graphorin/core.

Stability

Every exported type is annotated with one of two TSDoc tags:

@stable - covered by semver guarantees for the v0.x line.
@experimental - may change between minor versions; a deprecation note in the CHANGELOG.md will accompany every removal.

The vast majority of the surface ships as @stable; the deliberately loose @experimental corners exist because their underlying decision records are still being refined for v0.2.

Versioning

@graphorin/core follows the same lockstep release as the rest of the @graphorin/* packages while the framework is on the 0.x line.