@graphorin/core 0.5.0

package/dist/contracts/secret-value.d.ts

@@ -0,0 +1,112 @@
+//#region src/contracts/secret-value.d.ts
+/**
+ * Cross-realm symbol used to brand `SecretValue` instances. Implementations
+ * (e.g. the wrapper class shipped from `@graphorin/security`) attach this
+ * symbol so that `isSecretValue(...)` works across realms (Worker threads,
+ * sandboxes, etc.).
+ *
+ * @stable
+ */
+declare const SECRET_VALUE_BRAND: unique symbol;
+/**
+ * Well-known symbol used by `node:util.inspect()` to format the wrapper.
+ * Re-exported here so downstream packages can reference it without taking
+ * an unconditional dependency on `node:util`.
+ *
+ * Equivalent to `Symbol.for('nodejs.util.inspect.custom')`.
+ *
+ * @stable
+ */
+declare const NODEJS_INSPECT_CUSTOM: unique symbol;
+/**
+ * Runtime-safe wrapper around an opaque secret (API key, token, password).
+ *
+ * The shape declared here is the **interface contract**: the concrete
+ * wrapper class lives in `@graphorin/security`. Downstream packages typing
+ * a parameter as `SecretValue` therefore avoid taking a security
+ * dependency.
+ *
+ * Note: `SecretValue` is **not** a TypeScript branded primitive — it is
+ * a full wrapper class with explicit leakage barriers
+ * (`Symbol.toPrimitive`, `toJSON`, `[nodejs.util.inspect.custom]`, …).
+ * Any conforming implementation must ensure that:
+ *
+ * - String coercion (`String(s)`, `` `${s}` ``, `s + ''`, …) yields a
+ *   redacted placeholder, **not** the underlying value.
+ * - JSON serialization (`JSON.stringify({ apiKey: s })`) yields a
+ *   redacted placeholder.
+ * - Inspector output (`util.inspect(s)`) yields
+ *   `'SecretValue([REDACTED])'`.
+ * - The underlying value is only reachable through `.use(fn)`,
+ *   `.useBuffer(fn)` or the audited `.reveal()` escape hatch.
+ *
+ * @stable
+ */
+interface SecretValue {
+  /** Number of bytes in the wrapped value. Safe to log. */
+  readonly length: number;
+  /**
+   * Run `fn` with the unwrapped string and return its result. Preferred
+   * over `.reveal()` because it scopes the unwrapped value to a single
+   * synchronous / asynchronous turn.
+   */
+  use<T>(fn: (raw: string) => T | Promise<T>): Promise<T>;
+  /**
+   * Run `fn` with the unwrapped value as a `Buffer`. Useful for binary
+   * secrets (encryption keys, HMAC keys) where round-tripping through a
+   * V8 string would defeat the wrapper's hygiene.
+   */
+  useBuffer<T>(fn: (buf: Buffer) => T | Promise<T>): Promise<T>;
+  /**
+   * One-shot reveal as a string. Audited by the implementation. Prefer
+   * `.use(fn)` whenever possible.
+   */
+  reveal(): string;
+  /**
+   * Best-effort zeroization of the underlying buffer. Does not affect
+   * derived V8 strings already created via `.use(fn)` / `.reveal()`.
+   */
+  dispose(): void;
+  /** Cross-realm brand. Implementations set this to `SECRET_VALUE_BRAND`. */
+  readonly [SECRET_VALUE_BRAND]: true;
+  /** Leakage barrier for ToPrimitive coercion. Returns the placeholder. */
+  [Symbol.toPrimitive](hint: string): string | number;
+  /** Leakage barrier for `JSON.stringify(...)`. Returns the placeholder. */
+  toJSON(): string;
+  /**
+   * Leakage barrier for `node:util.inspect(...)`. Returns the placeholder
+   * (`'SecretValue([REDACTED])'`) so that REPL / `console.log` /
+   * structured-logger output never reveals the underlying value.
+   */
+  [NODEJS_INSPECT_CUSTOM](depth?: number, opts?: unknown, inspect?: unknown): string;
+}
+/**
+ * Static helpers expected on every concrete `SecretValue` constructor.
+ *
+ * @stable
+ */
+interface SecretValueStatic {
+  /** Cross-realm safe type guard. */
+  isSecretValue(value: unknown): value is SecretValue;
+  /** Constant-time equality. */
+  timingSafeEquals(a: SecretValue, b: SecretValue): boolean;
+  /** Construct from a plain string. */
+  fromString(raw: string, opts?: SecretValueOptions): SecretValue;
+  /** Construct from a Node.js `Buffer`. */
+  fromBuffer(buf: Buffer, opts?: SecretValueOptions): SecretValue;
+}
+/**
+ * Optional metadata attached to a freshly constructed `SecretValue`.
+ *
+ * @stable
+ */
+interface SecretValueOptions {
+  /** Free-form provenance string for the audit log. */
+  readonly source?: {
+    readonly resolver?: string;
+    readonly ref?: string;
+  };
+}
+//#endregion
+export { NODEJS_INSPECT_CUSTOM, SECRET_VALUE_BRAND, SecretValue, SecretValueOptions, SecretValueStatic };
+//# sourceMappingURL=secret-value.d.ts.map

package/dist/contracts/secret-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-value.d.ts","names":[],"sources":["../../src/contracts/secret-value.ts"],"sourcesContent":[],"mappings":";;AAQA;AAWA;AA0BA;;;;;AAS+C,cA9ClC,kBA8CkC,EAAA,OAAA,MAAA;;;;;;;;;AA2C/C;AAE0C,cAhF7B,qBAgF6B,EAAA,OAAA,MAAA;;;;;;;;;AAc1C;;;;;;;;;;;;;;;;UApEiB,WAAA;;;;;;;;8BASa,IAAI,QAAQ,KAAK,QAAQ;;;;;;yBAO9B,WAAW,IAAI,QAAQ,KAAK,QAAQ;;;;;;;;;;;;YAejD,kBAAA;;;;;;;;;;;;;;;;;UAqBK,iBAAA;;0CAEyB;;sBAEpB,gBAAgB;;iCAEL,qBAAqB;;kBAEpC,eAAe,qBAAqB;;;;;;;UAQrC,kBAAA"}

package/dist/contracts/secret-value.js

@@ -0,0 +1,24 @@
+//#region src/contracts/secret-value.ts
+/**
+* Cross-realm symbol used to brand `SecretValue` instances. Implementations
+* (e.g. the wrapper class shipped from `@graphorin/security`) attach this
+* symbol so that `isSecretValue(...)` works across realms (Worker threads,
+* sandboxes, etc.).
+*
+* @stable
+*/
+const SECRET_VALUE_BRAND = Symbol.for("graphorin.SecretValue");
+/**
+* Well-known symbol used by `node:util.inspect()` to format the wrapper.
+* Re-exported here so downstream packages can reference it without taking
+* an unconditional dependency on `node:util`.
+*
+* Equivalent to `Symbol.for('nodejs.util.inspect.custom')`.
+*
+* @stable
+*/
+const NODEJS_INSPECT_CUSTOM = Symbol.for("nodejs.util.inspect.custom");
+
+//#endregion
+export { NODEJS_INSPECT_CUSTOM, SECRET_VALUE_BRAND };
+//# sourceMappingURL=secret-value.js.map

package/dist/contracts/secret-value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-value.js","names":["SECRET_VALUE_BRAND: unique symbol","NODEJS_INSPECT_CUSTOM: unique symbol"],"sources":["../../src/contracts/secret-value.ts"],"sourcesContent":["/**\n * Cross-realm symbol used to brand `SecretValue` instances. Implementations\n * (e.g. the wrapper class shipped from `@graphorin/security`) attach this\n * symbol so that `isSecretValue(...)` works across realms (Worker threads,\n * sandboxes, etc.).\n *\n * @stable\n */\nexport const SECRET_VALUE_BRAND: unique symbol = Symbol.for('graphorin.SecretValue');\n\n/**\n * Well-known symbol used by `node:util.inspect()` to format the wrapper.\n * Re-exported here so downstream packages can reference it without taking\n * an unconditional dependency on `node:util`.\n *\n * Equivalent to `Symbol.for('nodejs.util.inspect.custom')`.\n *\n * @stable\n */\nexport const NODEJS_INSPECT_CUSTOM: unique symbol = Symbol.for('nodejs.util.inspect.custom');\n\n/**\n * Runtime-safe wrapper around an opaque secret (API key, token, password).\n *\n * The shape declared here is the **interface contract**: the concrete\n * wrapper class lives in `@graphorin/security`. Downstream packages typing\n * a parameter as `SecretValue` therefore avoid taking a security\n * dependency.\n *\n * Note: `SecretValue` is **not** a TypeScript branded primitive — it is\n * a full wrapper class with explicit leakage barriers\n * (`Symbol.toPrimitive`, `toJSON`, `[nodejs.util.inspect.custom]`, …).\n * Any conforming implementation must ensure that:\n *\n * - String coercion (`String(s)`, `` `${s}` ``, `s + ''`, …) yields a\n *   redacted placeholder, **not** the underlying value.\n * - JSON serialization (`JSON.stringify({ apiKey: s })`) yields a\n *   redacted placeholder.\n * - Inspector output (`util.inspect(s)`) yields\n *   `'SecretValue([REDACTED])'`.\n * - The underlying value is only reachable through `.use(fn)`,\n *   `.useBuffer(fn)` or the audited `.reveal()` escape hatch.\n *\n * @stable\n */\nexport interface SecretValue {\n  /** Number of bytes in the wrapped value. Safe to log. */\n  readonly length: number;\n\n  /**\n   * Run `fn` with the unwrapped string and return its result. Preferred\n   * over `.reveal()` because it scopes the unwrapped value to a single\n   * synchronous / asynchronous turn.\n   */\n  use<T>(fn: (raw: string) => T | Promise<T>): Promise<T>;\n\n  /**\n   * Run `fn` with the unwrapped value as a `Buffer`. Useful for binary\n   * secrets (encryption keys, HMAC keys) where round-tripping through a\n   * V8 string would defeat the wrapper's hygiene.\n   */\n  useBuffer<T>(fn: (buf: Buffer) => T | Promise<T>): Promise<T>;\n\n  /**\n   * One-shot reveal as a string. Audited by the implementation. Prefer\n   * `.use(fn)` whenever possible.\n   */\n  reveal(): string;\n\n  /**\n   * Best-effort zeroization of the underlying buffer. Does not affect\n   * derived V8 strings already created via `.use(fn)` / `.reveal()`.\n   */\n  dispose(): void;\n\n  /** Cross-realm brand. Implementations set this to `SECRET_VALUE_BRAND`. */\n  readonly [SECRET_VALUE_BRAND]: true;\n\n  /** Leakage barrier for ToPrimitive coercion. Returns the placeholder. */\n  [Symbol.toPrimitive](hint: string): string | number;\n\n  /** Leakage barrier for `JSON.stringify(...)`. Returns the placeholder. */\n  toJSON(): string;\n\n  /**\n   * Leakage barrier for `node:util.inspect(...)`. Returns the placeholder\n   * (`'SecretValue([REDACTED])'`) so that REPL / `console.log` /\n   * structured-logger output never reveals the underlying value.\n   */\n  [NODEJS_INSPECT_CUSTOM](depth?: number, opts?: unknown, inspect?: unknown): string;\n}\n\n/**\n * Static helpers expected on every concrete `SecretValue` constructor.\n *\n * @stable\n */\nexport interface SecretValueStatic {\n  /** Cross-realm safe type guard. */\n  isSecretValue(value: unknown): value is SecretValue;\n  /** Constant-time equality. */\n  timingSafeEquals(a: SecretValue, b: SecretValue): boolean;\n  /** Construct from a plain string. */\n  fromString(raw: string, opts?: SecretValueOptions): SecretValue;\n  /** Construct from a Node.js `Buffer`. */\n  fromBuffer(buf: Buffer, opts?: SecretValueOptions): SecretValue;\n}\n\n/**\n * Optional metadata attached to a freshly constructed `SecretValue`.\n *\n * @stable\n */\nexport interface SecretValueOptions {\n  /** Free-form provenance string for the audit log. */\n  readonly source?: { readonly resolver?: string; readonly ref?: string };\n}\n"],"mappings":";;;;;;;;;AAQA,MAAaA,qBAAoC,OAAO,IAAI,wBAAwB;;;;;;;;;;AAWpF,MAAaC,wBAAuC,OAAO,IAAI,6BAA6B"}

package/dist/contracts/secrets-store.d.ts

@@ -0,0 +1,87 @@
+import { SessionScope } from "../types/session-scope.js";
+import { SecretRef } from "./secret-ref.js";
+import { SecretValue } from "./secret-value.js";
+
+//#region src/contracts/secrets-store.d.ts
+
+/**
+ * Pluggable secret resolver — turns a parsed `SecretRef` into a live
+ * `SecretValue`. Concrete resolvers live in `@graphorin/security` (env,
+ * keyring, file, encrypted-file, literal, ref, vault) and in optional
+ * adapter packages (`@graphorin/secret-1password`, …).
+ *
+ * @stable
+ */
+interface SecretResolver {
+  /** Lowercased URI scheme handled by this resolver (`'env'`, `'op'`, …). */
+  readonly scheme: string;
+  resolve(ref: SecretRef, ctx?: SecretResolverContext): Promise<SecretValue>;
+}
+/**
+ * Optional context handed to a resolver. Carries the originating tool /
+ * agent identifiers so the audit log can attribute the resolution.
+ *
+ * @stable
+ */
+interface SecretResolverContext {
+  readonly toolName?: string;
+  readonly agentId?: string;
+  readonly runId?: string;
+  readonly signal?: AbortSignal;
+}
+/**
+ * Pluggable secret-managing storage. Concrete implementations live in
+ * `@graphorin/security` (`KeyringSecretsStore`, `EncryptedFileSecretsStore`,
+ * `EnvSecretsStore`, `MemorySecretsStore`).
+ *
+ * The interface is intentionally narrow: every method either returns a
+ * `SecretValue` or a piece of metadata that is safe to log. The raw
+ * value is never returned as a `string` from this surface.
+ *
+ * @stable
+ */
+interface SecretsStore {
+  /** Returns the secret if it exists, `null` otherwise. */
+  get(key: string, scope?: SessionScope): Promise<SecretValue | null>;
+  /**
+   * Returns the secret or throws. Implementations enforce the per-tool
+   * `secretsAllowed` ACL: if the current tool context disallows `key`,
+   * throw `SecretAccessDeniedError`.
+   */
+  require(key: string, scope?: SessionScope): Promise<SecretValue>;
+  /**
+   * Persist a secret. Implementations auto-wrap a plain string into a
+   * `SecretValue` so callers don't have to.
+   */
+  set(key: string, value: string | SecretValue, opts?: SecretsSetOptions): Promise<void>;
+  delete(key: string, scope?: SessionScope): Promise<void>;
+  /** Returns metadata about every key — never the values themselves. */
+  list(scope?: SessionScope): Promise<ReadonlyArray<SecretMetadata>>;
+}
+/**
+ * Optional knobs for `SecretsStore.set(...)`.
+ *
+ * @stable
+ */
+interface SecretsSetOptions {
+  readonly scope?: SessionScope;
+  readonly expiresAt?: string;
+  readonly tags?: ReadonlyArray<string>;
+}
+/**
+ * Public metadata about a stored secret. Safe to log — never carries the
+ * value itself.
+ *
+ * @stable
+ */
+interface SecretMetadata {
+  readonly key: string;
+  readonly createdAt: string;
+  readonly updatedAt?: string;
+  readonly expiresAt?: string;
+  readonly tags?: ReadonlyArray<string>;
+  readonly source?: string;
+}
+//#endregion
+export { SecretMetadata, SecretResolver, SecretResolverContext, SecretsSetOptions, SecretsStore };
+//# sourceMappingURL=secrets-store.d.ts.map

package/dist/contracts/secrets-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets-store.d.ts","names":[],"sources":["../../src/contracts/secrets-store.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAYA;;;;;;AAYiB,UAZA,cAAA,CAYqB;EAkBrB;EAEU,SAAA,MAAA,EAAA,MAAA;EAAuB,OAAA,CAAA,GAAA,EA7BnC,SA6BmC,EAAA,GAAA,CAAA,EA7BlB,qBA6BkB,CAAA,EA7BM,OA6BN,CA7Bc,WA6Bd,CAAA;;;;;;;;AAepB,UAnCb,qBAAA,CAmCa;EAAe,SAAA,QAAA,CAAA,EAAA,MAAA;EAG9B,SAAA,OAAA,CAAA,EAAA,MAAA;EAAqC,SAAA,KAAA,CAAA,EAAA,MAAA;EAAd,SAAA,MAAA,CAAA,EAlClB,WAkCkB;;;AAQtC;AAYA;;;;;;;;;UAxCiB,YAAA;;2BAEU,eAAe,QAAQ;;;;;;+BAOnB,eAAe,QAAQ;;;;;mCAMnB,oBAAoB,oBAAoB;8BAE7C,eAAe;;eAG9B,eAAe,QAAQ,cAAc;;;;;;;UAQnC,iBAAA;mBACE;;kBAED;;;;;;;;UASD,cAAA;;;;;kBAKC"}

package/dist/contracts/session-store.d.ts

@@ -0,0 +1,142 @@
+import { SessionScope } from "../types/session-scope.js";
+import { HandoffRecord } from "../types/handoff.js";
+
+//#region src/contracts/session-store.d.ts
+
+/**
+ * Lightweight session metadata persisted by the sessions package. The
+ * actual `session_messages` rows are owned by `MemoryStore` (single source
+ * of truth — the sessions package delegates message CRUD to memory).
+ *
+ * @stable
+ */
+interface SessionMetadata {
+  readonly id: string;
+  readonly userId: string;
+  readonly agentId: string;
+  readonly title?: string;
+  readonly createdAt: string;
+  readonly updatedAt?: string;
+  readonly closedAt?: string;
+  readonly tags?: ReadonlyArray<string>;
+}
+/**
+ * Agent registry entry. Captures stable metadata about every agent that
+ * ever produced a message — so JSONL exports / replays can resolve a
+ * `Message.agentId` to a human-readable name even after the agent was
+ * renamed or retired.
+ *
+ * @stable
+ */
+interface AgentRegistryEntry {
+  readonly id: string;
+  readonly displayName: string;
+  readonly registeredAt: string;
+  readonly retiredAt?: string;
+  readonly tags?: ReadonlyArray<string>;
+}
+/**
+ * Workflow ↔ session mapping row. Lets the server enumerate the
+ * workflows attached to a session for resume / replay flows.
+ *
+ * @stable
+ */
+interface SessionWorkflowRun {
+  readonly sessionId: string;
+  readonly workflowId: string;
+  readonly threadId: string;
+  readonly attachedAt: string;
+  readonly status: 'running' | 'suspended' | 'completed' | 'failed';
+}
+/**
+ * Session lifecycle audit event. The `@graphorin/sessions` package
+ * appends one row per noteworthy lifecycle step (`created`, `closed`,
+ * `forked`, `replayed`, `cassette-recorded`, `cassette-replayed`,
+ * `commentary-sanitized`, …) plus per-session-handoff. Adapters can
+ * surface the rows verbatim from disk.
+ *
+ * The `metadata` field is intentionally an open record — storage
+ * adapters serialize it as JSON. Callers should keep it small and
+ * never include secret values.
+ *
+ * @stable
+ */
+interface SessionAuditEntry {
+  readonly id: string;
+  readonly sessionId: string;
+  readonly action: string;
+  readonly at: string;
+  readonly actor?: {
+    readonly kind: string;
+    readonly id: string;
+    readonly label?: string;
+  };
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Pluggable session-metadata storage. Implementations live in the
+ * storage adapter packages.
+ *
+ * @stable
+ */
+interface SessionStore {
+  createSession(metadata: SessionMetadata): Promise<void>;
+  getSession(sessionId: string): Promise<SessionMetadata | null>;
+  listSessions(scope: Pick<SessionScope, 'userId' | 'agentId'>): Promise<ReadonlyArray<SessionMetadata>>;
+  updateSession(sessionId: string, patch: Partial<SessionMetadata>): Promise<void>;
+  closeSession(sessionId: string, closedAt: string): Promise<void>;
+  registerAgent(entry: AgentRegistryEntry): Promise<void>;
+  retireAgent(agentId: string, retiredAt: string): Promise<void>;
+  resolveAgent(agentId: string): Promise<AgentRegistryEntry | null>;
+  appendHandoff(sessionId: string, record: HandoffRecord): Promise<void>;
+  listHandoffs(sessionId: string): Promise<ReadonlyArray<HandoffRecord>>;
+  attachWorkflowRun(run: SessionWorkflowRun): Promise<void>;
+  listWorkflowRuns(sessionId: string): Promise<ReadonlyArray<SessionWorkflowRun>>;
+}
+/**
+ * Optional extension surface for storage adapters that expose the
+ * additional capabilities `@graphorin/sessions` consumes.
+ * Adapters that opt out leave the property undefined; the sessions
+ * facade degrades gracefully (delete becomes retire; audit rows are
+ * dropped on the floor with a one-time WARN).
+ *
+ * Implementations: `SqliteSessionStore` (`@graphorin/store-sqlite`).
+ *
+ * @stable
+ */
+interface SessionStoreExt extends SessionStore {
+  /** Hard-delete an agent. Used by `AgentRegistry.delete(...)`. */
+  deleteAgent(agentId: string): Promise<void>;
+  /** List all known agents (including retired ones). */
+  listAgents(): Promise<ReadonlyArray<AgentRegistryEntry>>;
+  /** Update the status of a workflow attachment. */
+  updateWorkflowRunStatus(sessionId: string, workflowId: string, threadId: string, status: SessionWorkflowRun['status']): Promise<void>;
+  /** Append a session-lifecycle audit row. */
+  appendAuditEntry(entry: SessionAuditEntry): Promise<void>;
+  /** List recent audit rows for a session, newest-first. */
+  listAuditEntries(sessionId: string, opts?: {
+    readonly limit?: number;
+  }): Promise<ReadonlyArray<SessionAuditEntry>>;
+  /** Delete audit rows older than the supplied epoch ms. */
+  pruneAuditEntries(beforeEpochMs: number): Promise<number>;
+  /**
+   * Hard-delete a session and cascade its session-owned rows — handoffs,
+   * workflow-run attachments, and audit entries (RP-6). Message rows live in
+   * the `SessionMemoryStore` and are purged separately. A no-op for an unknown
+   * id.
+   */
+  deleteSession(sessionId: string): Promise<void>;
+  /**
+   * Retention sweep (RP-6): hard-delete (cascade) every session matching the
+   * policy. `beforeEpochMs` limits to sessions created before that instant;
+   * `closedOnly` limits to closed sessions. With neither, deletes all sessions.
+   * Returns the number of sessions deleted.
+   */
+  pruneSessions(opts: {
+    readonly beforeEpochMs?: number;
+    readonly closedOnly?: boolean;
+  }): Promise<number>;
+}
+//#endregion
+export { AgentRegistryEntry, SessionAuditEntry, SessionMetadata, SessionStore, SessionStoreExt, SessionWorkflowRun };
+//# sourceMappingURL=session-store.d.ts.map

package/dist/contracts/session-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-store.d.ts","names":[],"sources":["../../src/contracts/session-store.ts"],"sourcesContent":[],"mappings":";;;;;;;AAUA;AAmBA;AAcA;AAqBA;AAmBA;AAC0B,UA1ET,eAAA,CA0ES;EAAkB,SAAA,EAAA,EAAA,MAAA;EACH,SAAA,MAAA,EAAA,MAAA;EAAR,SAAA,OAAA,EAAA,MAAA;EAEjB,SAAA,KAAA,CAAA,EAAA,MAAA;EAAL,SAAA,SAAA,EAAA,MAAA;EACgB,SAAA,SAAA,CAAA,EAAA,MAAA;EAAd,SAAA,QAAA,CAAA,EAAA,MAAA;EAAR,SAAA,IAAA,CAAA,EAtEa,aAsEb,CAAA,MAAA,CAAA;;;;;;;;;;AAQsC,UAnE1B,kBAAA,CAmE0B;EAAgB,SAAA,EAAA,EAAA,MAAA;EACF,SAAA,WAAA,EAAA,MAAA;EAAd,SAAA,YAAA,EAAA,MAAA;EAAR,SAAA,SAAA,CAAA,EAAA,MAAA;EAEV,SAAA,IAAA,CAAA,EAjEP,aAiEO,CAAA,MAAA,CAAA;;;;;;AAezB;;AAIsC,UA3ErB,kBAAA,CA2EqB;EAAd,SAAA,SAAA,EAAA,MAAA;EAAR,SAAA,UAAA,EAAA,MAAA;EAMJ,SAAA,QAAA,EAAA,MAAA;EACP,SAAA,UAAA,EAAA,MAAA;EAEqB,SAAA,MAAA,EAAA,SAAA,GAAA,WAAA,GAAA,WAAA,GAAA,QAAA;;;;;;;;;;;;;;;UA/DT,iBAAA;;;;;;;;;;sBAUK,SAAS;;;;;;;;UASd,YAAA;0BACS,kBAAkB;iCACX,QAAQ;sBAE9B,KAAK,sCACX,QAAQ,cAAc;0CACe,QAAQ,mBAAmB;qDAChB;uBAE9B,qBAAqB;mDACO;iCAClB,QAAQ;2CAEE,gBAAgB;mCACxB,QAAQ,cAAc;yBAEhC,qBAAqB;uCACP,QAAQ,cAAc;;;;;;;;;;;;;UAc5C,eAAA,SAAwB;;gCAET;;gBAEhB,QAAQ,cAAc;;2FAM1B,+BACP;;0BAEqB,oBAAoB;;;;MAKzC,QAAQ,cAAc;;4CAEiB;;;;;;;oCAOR;;;;;;;;;;MAU9B"}

package/dist/contracts/token-counter.d.ts

@@ -0,0 +1,28 @@
+import { Message } from "../types/message.js";
+
+//#region src/contracts/token-counter.d.ts
+
+/**
+ * Pluggable token counter. Implementations live in `@graphorin/provider`
+ * (default `JsTiktokenCounter` for OpenAI/compatible, plus per-vendor
+ * native counters) and are interchangeable behind this interface.
+ *
+ * Counters carry a `version` field so that consumers (e.g. the
+ * `session_messages.tokenizer_version` cache column) can invalidate stale
+ * cached counts when the underlying tokenizer is upgraded.
+ *
+ * @stable
+ */
+interface TokenCounter {
+  /** Human-readable identifier (`'js-tiktoken@cl100k_base'`, …). */
+  readonly id: string;
+  /** Tokenizer version string used for cache invalidation. */
+  readonly version: string;
+  /** Count tokens in a list of `Message`s (system/user/assistant/tool). */
+  count(messages: ReadonlyArray<Message>): Promise<number>;
+  /** Count tokens in a raw text string. */
+  countText(text: string): Promise<number>;
+}
+//#endregion
+export { TokenCounter };
+//# sourceMappingURL=token-counter.d.ts.map

package/dist/contracts/token-counter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-counter.d.ts","names":[],"sources":["../../src/contracts/token-counter.ts"],"sourcesContent":[],"mappings":";;;;;;AAaA;;;;;;;;;UAAiB,YAAA;;;;;;kBAMC,cAAc,WAAW;;2BAEhB"}