@graphorin/core 0.6.0 → 0.7.0

package/src/contracts/tracer.ts

@@ -0,0 +1,219 @@
+/**
+ * Framework-known discriminators for typed observability spans.
+ *
+ * The list mirrors the span taxonomy documented for the observability
+ * layer; concrete implementations live in `@graphorin/observability`.
+ * Promoting a frequently-used custom span kind (see
+ * {@link CustomSpanType}) into this union is an additive minor change.
+ *
+ * @stable
+ */
+export type KnownSpanType =
+  | 'agent.run'
+  | 'agent.step'
+  | 'agent.handoff'
+  | 'agent.suspend'
+  | 'agent.resume'
+  | 'provider.generate'
+  | 'provider.stream'
+  | 'tool.execute'
+  | 'tool.approval'
+  | 'memory.read.working'
+  | 'memory.read.session'
+  | 'memory.read.episodic'
+  | 'memory.read.semantic'
+  | 'memory.read.procedural'
+  | 'memory.read.shared'
+  | 'memory.write.working'
+  | 'memory.write.session'
+  | 'memory.write.episodic'
+  | 'memory.write.semantic'
+  | 'memory.write.procedural'
+  | 'memory.write.shared'
+  | 'memory.search.working'
+  | 'memory.search.session'
+  | 'memory.search.episodic'
+  | 'memory.search.semantic'
+  | 'memory.search.procedural'
+  | 'memory.search.shared'
+  | 'memory.consolidate.light'
+  | 'memory.consolidate.standard'
+  | 'memory.consolidate.deep'
+  | 'memory.consolidate.reflect'
+  | 'memory.consolidate.learned-context'
+  | 'memory.search.insight'
+  | 'memory.read.insight'
+  | 'memory.write.insight'
+  | 'memory.conflict'
+  | 'memory.embed'
+  | 'workflow.run'
+  | 'workflow.step'
+  | 'workflow.task'
+  | 'workflow.checkpoint'
+  | 'skill.activate'
+  | 'skill.load'
+  | 'mcp.connect'
+  | 'mcp.call'
+  | 'mcp.list-tools';
+
+/**
+ * Namespaced escape hatch for user-defined span kinds (W-126): any
+ * string under the `x.` prefix, e.g. `'x.acme.rerank'`. The prefix
+ * keeps typo-safety for the known literals - `'memory.serch.semantic'`
+ * is still a compile error because it does not start with `x.` -
+ * which is why this is a template-literal type and not `string & {}`.
+ *
+ * Convention: `x.<vendor>.<operation>`. Backends and analytics must
+ * tolerate unknown span-type strings (the same policy events already
+ * follow). When a custom kind becomes common, promote it into
+ * {@link KnownSpanType} (additive minor).
+ *
+ * @stable
+ */
+export type CustomSpanType = `x.${string}`;
+
+/**
+ * Discriminator union for typed observability spans: every
+ * {@link KnownSpanType} literal plus the {@link CustomSpanType}
+ * namespaced escape. Exhaustive switches over `SpanType` need a
+ * default branch for the custom domain.
+ *
+ * @stable
+ */
+export type SpanType = KnownSpanType | CustomSpanType;
+
+/**
+ * Status of a finished span. Mirrors the OTel status convention with
+ * `'ok' | 'error'` short forms instead of the verbose tristate.
+ *
+ * @stable
+ */
+export type SpanStatus = 'ok' | 'error' | 'cancelled';
+
+/**
+ * Free-form attributes attached to a span.
+ *
+ * @stable
+ */
+export type SpanAttributes = Readonly<Record<string, SpanAttributeValue>>;
+
+/** @stable */
+export type SpanAttributeValue =
+  | string
+  | number
+  | boolean
+  | null
+  | ReadonlyArray<string>
+  | ReadonlyArray<number>
+  | ReadonlyArray<boolean>;
+
+/**
+ * W-094: sensitivity opts for {@link AISpan.addEvent}. Event attributes
+ * used to be un-taggable, so a default-`'public'` export floor dropped
+ * ALL of them - including `exception.type` from `recordException`.
+ *
+ * @stable
+ */
+export interface AddEventOptions {
+  /** Default tier applied to every attribute of this event. */
+  readonly sensitivity?: import('../types/sensitivity.js').Sensitivity;
+  /** Per-attribute overrides; win over {@link AddEventOptions.sensitivity}. */
+  readonly sensitivityByAttribute?: Readonly<
+    Record<string, import('../types/sensitivity.js').Sensitivity>
+  >;
+}
+
+/**
+ * Typed span. Generic over `SpanType` so consumers can specialize a
+ * function on a particular span kind without losing the discriminator.
+ *
+ * @stable
+ */
+export interface AISpan<T extends SpanType = SpanType> {
+  readonly type: T;
+  readonly id: string;
+  readonly traceId: string;
+  readonly parentId?: string;
+  /** Add or replace attributes. Repeated calls are merged (last write wins). */
+  setAttributes(attrs: SpanAttributes): void;
+  /**
+   * Append a span event (attribute-bearing time-stamped marker). The
+   * optional `opts` (W-094) tags the event's attributes with a
+   * sensitivity tier so the validation exporter can pass safe ones
+   * through the default-deny floor - untagged attributes keep being
+   * dropped below the floor.
+   */
+  addEvent(name: string, attrs?: SpanAttributes, opts?: AddEventOptions): void;
+  /** Record an exception. Multiple calls are kept in the span event log. */
+  recordException(err: unknown): void;
+  /** Set the terminal status. */
+  setStatus(status: SpanStatus, message?: string): void;
+  /** End the span. Idempotent. */
+  end(): void;
+}
+
+/**
+ * Span constructor parameters.
+ *
+ * @stable
+ */
+export interface StartSpanOptions<T extends SpanType = SpanType> {
+  readonly type: T;
+  readonly attrs?: SpanAttributes;
+  readonly parent?: AISpan;
+}
+
+/**
+ * Pluggable tracer. Implementations live in `@graphorin/observability`.
+ * The interface intentionally mirrors a subset of the OTel API so that
+ * adapter code is a thin pass-through.
+ *
+ * @stable
+ */
+export interface Tracer {
+  startSpan<T extends SpanType>(opts: StartSpanOptions<T>): AISpan<T>;
+  /**
+   * Convenience wrapper: start a span, run `fn` inside, and call
+   * `setStatus('ok' | 'error')` + `end()` based on the outcome.
+   */
+  span<T extends SpanType, R>(
+    opts: StartSpanOptions<T>,
+    fn: (span: AISpan<T>) => R | Promise<R>,
+  ): Promise<R>;
+  /** Force-flush any pending spans. */
+  shutdown(): Promise<void>;
+}
+
+/**
+ * Minimal no-op tracer. Useful as a typed default when downstream code
+ * needs a non-null `Tracer` without taking the observability dependency.
+ *
+ * @stable
+ */
+export const NOOP_TRACER: Tracer = {
+  startSpan<T extends SpanType>(opts: StartSpanOptions<T>): AISpan<T> {
+    const span: AISpan<T> = {
+      type: opts.type,
+      id: '',
+      traceId: '',
+      setAttributes(): void {},
+      addEvent(): void {},
+      recordException(): void {},
+      setStatus(): void {},
+      end(): void {},
+    };
+    return span;
+  },
+  async span<T extends SpanType, R>(
+    opts: StartSpanOptions<T>,
+    fn: (span: AISpan<T>) => R | Promise<R>,
+  ): Promise<R> {
+    const span = this.startSpan(opts);
+    try {
+      return await fn(span);
+    } finally {
+      span.end();
+    }
+  },
+  async shutdown(): Promise<void> {},
+};

package/src/contracts/trigger-store.ts

@@ -0,0 +1,40 @@
+/**
+ * Persisted trigger state row. Lives in the `trigger_state` table per
+ * the durable-trigger contract: library and server modes share a single
+ * code path.
+ *
+ * @stable
+ */
+export interface TriggerState {
+  readonly id: string;
+  readonly kind: 'cron' | 'interval' | 'idle' | 'event';
+  readonly spec: string;
+  readonly callbackRef: string;
+  /** ISO-8601 of the next scheduled fire. */
+  readonly nextFireAt?: string;
+  /** ISO-8601 of the most recent fire. */
+  readonly lastFiredAt?: string;
+  /** Number of consecutive missed fires. */
+  readonly missedFires: number;
+  readonly disabled: boolean;
+  readonly catchupPolicy: 'none' | 'last' | 'all';
+  readonly maxCatchupRuns: number;
+  readonly catchupWindowMs: number;
+  readonly tags?: ReadonlyArray<string>;
+  readonly createdAt: string;
+  readonly updatedAt?: string;
+}
+
+/**
+ * Pluggable persistent storage for triggers. Default impl lives in
+ * `@graphorin/store-sqlite`.
+ *
+ * @stable
+ */
+export interface TriggerStore {
+  upsert(state: TriggerState): Promise<void>;
+  get(id: string): Promise<TriggerState | null>;
+  list(): Promise<ReadonlyArray<TriggerState>>;
+  remove(id: string): Promise<void>;
+  recordFire(id: string, firedAt: string, nextFireAt?: string): Promise<void>;
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+/**
+ * @graphorin/core - types, contracts, and utilities for the Graphorin
+ * framework. Dependency-free root package every other `@graphorin/*`
+ * package depends on.
+ *
+ * The full documentation lives in the package `README.md` and the
+ * sub-module barrels (`./types`, `./contracts`, `./utils`, `./channels`).
+ *
+ * @packageDocumentation
+ */
+
+import pkg from '../package.json' with { type: 'json' };
+
+/**
+ * Canonical version constant, derived from `package.json` at build
+ * time so a release bump never has to edit source.
+ */
+export const VERSION: string = pkg.version;
+
+export * from './channels/index.js';
+export * from './contracts/index.js';
+export * from './types/index.js';
+export * from './utils/index.js';

package/src/types/agent-event-wire.ts

@@ -0,0 +1,193 @@
+/**
+ * JSON-safe wire projection of {@link AgentEvent} (W-046).
+ *
+ * Three `AgentEvent` variants carry payloads that `JSON.stringify`
+ * corrupts: `file.generated` (`data: Uint8Array`),
+ * `tool.execute.partial` (binary `ContentChunk`) and - the bulk -
+ * `agent.end`, whose `result.state: RunState` embeds multimodal
+ * messages and tool-outcome `contentParts`. The wire twins below
+ * project those payloads through the binary codec so a server can
+ * `JSON.stringify` any event without silently mangling it.
+ *
+ * `AgentResult.output` (`TOutput`) is assumed JSON-safe already
+ * (a string, or a value parsed from JSON structured output) - the
+ * projection does not touch it.
+ *
+ * @packageDocumentation
+ */
+
+import {
+  base64ToBytes,
+  bytesToBase64,
+  type EncodedBytes,
+  fromJsonSafeRunState,
+  toJsonSafeRunState,
+  type WireRunState,
+} from '../utils/binary-json.js';
+import type {
+  AgentEndEvent,
+  AgentEvent,
+  AgentResult,
+  FileGeneratedEvent,
+  SubagentEvent,
+  ToolExecutePartialEvent,
+} from './agent-event.js';
+import type { ContentChunk } from './tool.js';
+
+/** Wire twin of the binary {@link ContentChunk} variant. @stable */
+export type WireContentChunk =
+  | Exclude<ContentChunk, { readonly kind: 'image' }>
+  | { readonly kind: 'image'; readonly data: EncodedBytes; readonly mediaType: string };
+
+/** Wire twin of `FileGeneratedEvent`. @stable */
+export interface WireFileGeneratedEvent extends Omit<FileGeneratedEvent, 'data'> {
+  readonly data: EncodedBytes;
+}
+
+/** Wire twin of {@link ToolExecutePartialEvent}. @stable */
+export interface WireToolExecutePartialEvent extends Omit<ToolExecutePartialEvent, 'chunk'> {
+  readonly chunk: WireContentChunk;
+}
+
+/**
+ * Wire twin of {@link AgentEndEvent}: `result.state` is the JSON-safe
+ * {@link WireRunState} projection.
+ *
+ * @stable
+ */
+export interface WireAgentEndEvent<TOutput = string>
+  extends Omit<AgentEndEvent<TOutput>, 'result'> {
+  readonly result: Omit<AgentResult<TOutput>, 'state'> & { readonly state: WireRunState };
+}
+
+/**
+ * JSON-safe twin of {@link AgentEvent}: the three binary-bearing
+ * variants are replaced by their wire twins, every other variant
+ * passes through structurally unchanged.
+ *
+ * This is the actual payload shape a server puts on the wire (inside
+ * the `{ eventId, subject, type, payload }` envelope) - see
+ * {@link toWireAgentEvent}.
+ *
+ * @stable
+ */
+/**
+ * Wire twin of {@link SubagentEvent} (W-036): the wrapped child event
+ * projects recursively - a forwarded child `agent.end` carries a full
+ * `RunState` of its own.
+ *
+ * @stable
+ */
+export interface WireSubagentEvent extends Omit<SubagentEvent, 'event'> {
+  readonly event: WireAgentEvent<unknown>;
+}
+
+export type WireAgentEvent<TOutput = string> =
+  | Exclude<
+      AgentEvent<TOutput>,
+      FileGeneratedEvent | ToolExecutePartialEvent | AgentEndEvent<TOutput> | SubagentEvent
+    >
+  | WireFileGeneratedEvent
+  | WireToolExecutePartialEvent
+  | WireSubagentEvent
+  | WireAgentEndEvent<TOutput>;
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Registry-hosted agents are structurally typed and may emit an
+ * `agent.end` without a full `result.state` (e.g. plain `{ status,
+ * output }`). Only a state that actually carries the walked arrays is
+ * projected; anything else passes through untouched.
+ */
+function hasProjectableState(result: unknown): result is { state: { messages: unknown[] } } {
+  if (!isRecord(result)) return false;
+  const state = result.state;
+  return isRecord(state) && Array.isArray(state.messages) && Array.isArray(state.steps);
+}
+
+function encodeBytesField(data: Uint8Array | EncodedBytes): EncodedBytes {
+  if (data instanceof Uint8Array) return { enc: 'base64', data: bytesToBase64(data) };
+  return data;
+}
+
+function decodeBytesField(data: EncodedBytes | Uint8Array | unknown): Uint8Array {
+  if (data instanceof Uint8Array) return data;
+  if (isRecord(data) && data.enc === 'base64' && typeof data.data === 'string') {
+    return base64ToBytes(data.data);
+  }
+  // Unrecoverable legacy shape - degrade to empty bytes rather than throw.
+  return new Uint8Array(0);
+}
+
+/**
+ * Project an {@link AgentEvent} into its JSON-safe {@link WireAgentEvent}
+ * twin. Idempotent: projecting an already-wire event returns an
+ * equivalent value. Events of unknown `type` pass through untouched.
+ *
+ * @stable
+ */
+export function toWireAgentEvent<TOutput = string>(
+  ev: AgentEvent<TOutput> | WireAgentEvent<TOutput>,
+): WireAgentEvent<TOutput> {
+  switch (ev.type) {
+    case 'file.generated':
+      return { ...ev, data: encodeBytesField(ev.data) };
+    case 'tool.execute.partial': {
+      const chunk = ev.chunk;
+      if (chunk.kind === 'image') {
+        return { ...ev, chunk: { ...chunk, data: encodeBytesField(chunk.data) } };
+      }
+      return ev as WireAgentEvent<TOutput>;
+    }
+    case 'agent.end':
+      if (!hasProjectableState(ev.result)) return ev as WireAgentEvent<TOutput>;
+      return {
+        ...ev,
+        result: { ...ev.result, state: toJsonSafeRunState(ev.result.state) },
+      };
+    case 'subagent.event':
+      // W-036: the wrapped child event projects recursively.
+      return { ...ev, event: toWireAgentEvent(ev.event) };
+    default:
+      return ev as WireAgentEvent<TOutput>;
+  }
+}
+
+/**
+ * Inverse of {@link toWireAgentEvent}: decode base64 envelopes back
+ * into `Uint8Array` / `URL` instances. Exposed for `@graphorin/client`
+ * consumers that want runtime types back after `JSON.parse`.
+ *
+ * @stable
+ */
+export function fromWireAgentEvent<TOutput = string>(
+  ev: WireAgentEvent<TOutput> | AgentEvent<TOutput>,
+): AgentEvent<TOutput> {
+  switch (ev.type) {
+    case 'file.generated':
+      return { ...ev, data: decodeBytesField(ev.data) };
+    case 'tool.execute.partial': {
+      const chunk = ev.chunk;
+      if (chunk.kind === 'image') {
+        return { ...ev, chunk: { ...chunk, data: decodeBytesField(chunk.data) } };
+      }
+      return ev as AgentEvent<TOutput>;
+    }
+    case 'agent.end':
+      if (!hasProjectableState(ev.result)) return ev as AgentEvent<TOutput>;
+      return {
+        ...ev,
+        result: {
+          ...ev.result,
+          state: fromJsonSafeRunState(ev.result.state as unknown as WireRunState),
+        },
+      } as AgentEvent<TOutput>;
+    case 'subagent.event':
+      return { ...ev, event: fromWireAgentEvent(ev.event) } as AgentEvent<TOutput>;
+    default:
+      return ev as AgentEvent<TOutput>;
+  }
+}