@nanobpm/agentic 0.1.0 → 0.4.0

package/dist/session/events.js

@@ -0,0 +1,192 @@
+/**
+ * The canonical `SessionEvent` model — ADR 0062, slice 1 (the shared contract).
+ *
+ * This is **Nano's own** agent-session event model: the single schema every
+ * harness dialect (ACP, stream-json, a native normalizer, …) normalizes *into*.
+ * We never adopt an external harness schema as ours — those are ingestion
+ * details owned by the later slices; this union is the stable interface they all
+ * target.
+ *
+ * ## The causal chain
+ *
+ * A session is an append-only log of events. Two orthogonal orderings make the
+ * log both replayable and mergeable:
+ *
+ *  - a **monotonic, gap-free `offset`** assigned by the authoritative log on
+ *    append (see {@link AppendedSessionEvent}); it is the resume coordinate —
+ *    `restore` hands back everything up to a checkpoint offset.
+ *  - a **causal `parentId`** the producer stamps: the id of the event this one
+ *    logically follows (`null` for the first event of a session). Offset gives a
+ *    total order for replay; `parentId` records the *causal* edge, which survives
+ *    a compaction that rewrites offsets.
+ *
+ * The producer owns identity (`id`) and causality (`parentId`); the log owns
+ * ordering (`offset`) and fencing (`incarnation`). Keeping those responsibilities
+ * split is what lets a resumed incarnation continue the same causal chain at a
+ * fresh offset without the producer knowing the log's internal cursor.
+ */
+/** The set of valid event types, for a runtime membership check at the DB boundary. */
+export const SESSION_EVENT_TYPES = [
+    "system",
+    "user",
+    "assistant",
+    "reasoning",
+    "tool-call",
+    "tool-result",
+    "compaction",
+    "usage",
+    "turn-start",
+    "turn-end",
+];
+/** Raised when a value read back from storage is not a well-formed session event. */
+export class SessionEventShapeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SessionEventShapeError";
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function reqString(obj, field) {
+    const v = obj[field];
+    if (typeof v !== "string") {
+        throw new SessionEventShapeError(`session event field "${field}" must be a string, got ${typeof v}`);
+    }
+    return v;
+}
+function optString(obj, field) {
+    const v = obj[field];
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== "string") {
+        throw new SessionEventShapeError(`session event field "${field}" must be a string when present, got ${typeof v}`);
+    }
+    return v;
+}
+function reqNonNegInt(obj, field) {
+    const v = obj[field];
+    if (typeof v !== "number" || !Number.isSafeInteger(v) || v < 0) {
+        throw new SessionEventShapeError(`session event field "${field}" must be a non-negative safe integer, got ${String(v)}`);
+    }
+    return v;
+}
+function reqBool(obj, field) {
+    const v = obj[field];
+    if (typeof v !== "boolean") {
+        throw new SessionEventShapeError(`session event field "${field}" must be a boolean, got ${typeof v}`);
+    }
+    return v;
+}
+function parentId(obj) {
+    const v = obj.parentId;
+    if (v === null)
+        return null;
+    if (typeof v === "string")
+        return v;
+    throw new SessionEventShapeError(`session event "parentId" must be a string or null, got ${typeof v}`);
+}
+/**
+ * Coerce a required opaque payload (a tool-call `args` / tool-result `result`) to
+ * a JSON-serialisable value. These fields are documented as opaque *JSON-
+ * serialisable* values, but a dialect can legitimately omit them (e.g. a tool
+ * call with no arguments surfaces as `obj.arguments ?? obj.args === undefined`).
+ * `undefined` is not JSON-serialisable — `JSON.stringify` drops the key — so an
+ * un-normalised `undefined` would persist an event that no longer round-trips to
+ * the same shape on replay. We normalise the absence to the canonical JSON "no
+ * value" (`null`) here, at the single boundary every dialect flows through, so
+ * they all get the same replay-stable guarantee (derivation over duplication).
+ */
+function opaquePayload(value) {
+    return value === undefined ? null : value;
+}
+/**
+ * Parse and validate an untyped value (e.g. `JSON.parse` of a stored row) into a
+ * {@link SessionEvent}, reconstructing the exact union member for its `type`.
+ * Throws {@link SessionEventShapeError} on any malformed field. This is the
+ * single trusted boundary between untyped storage and the typed union — it never
+ * uses an `as`-cast to fabricate a shape (see AGENTS.md), it *builds* one field
+ * by field, so a corrupt row fails loudly instead of masquerading as valid.
+ */
+export function parseSessionEvent(value) {
+    if (!isRecord(value)) {
+        throw new SessionEventShapeError(`session event must be an object, got ${typeof value}`);
+    }
+    const id = reqString(value, "id");
+    const parent = parentId(value);
+    const type = value.type;
+    switch (type) {
+        case "system":
+            return { type, id, parentId: parent, text: reqString(value, "text") };
+        case "user":
+            return { type, id, parentId: parent, text: reqString(value, "text") };
+        case "assistant":
+            return { type, id, parentId: parent, text: reqString(value, "text") };
+        case "reasoning": {
+            const event = { type, id, parentId: parent };
+            const text = optString(value, "text");
+            const cont = optString(value, "providerContinuation");
+            return {
+                ...event,
+                ...(text !== undefined ? { text } : {}),
+                ...(cont !== undefined ? { providerContinuation: cont } : {}),
+            };
+        }
+        case "tool-call":
+            return {
+                type,
+                id,
+                parentId: parent,
+                callId: reqString(value, "callId"),
+                name: reqString(value, "name"),
+                args: opaquePayload(value.args),
+            };
+        case "tool-result":
+            return {
+                type,
+                id,
+                parentId: parent,
+                callId: reqString(value, "callId"),
+                ok: reqBool(value, "ok"),
+                result: opaquePayload(value.result),
+            };
+        case "compaction": {
+            const reason = value.reason;
+            if (reason !== "compaction" && reason !== "truncation") {
+                throw new SessionEventShapeError(`compaction "reason" must be "compaction" or "truncation", got ${String(reason)}`);
+            }
+            const summary = optString(value, "summary");
+            const replacesFrom = reqNonNegInt(value, "replacesFrom");
+            const replacesTo = reqNonNegInt(value, "replacesTo");
+            if (replacesTo < replacesFrom) {
+                throw new SessionEventShapeError(`compaction "replacesTo" (${replacesTo}) must be >= "replacesFrom" (${replacesFrom})`);
+            }
+            return {
+                type,
+                id,
+                parentId: parent,
+                reason,
+                replacesFrom,
+                replacesTo,
+                ...(summary !== undefined ? { summary } : {}),
+            };
+        }
+        case "usage": {
+            const model = optString(value, "model");
+            return {
+                type,
+                id,
+                parentId: parent,
+                inputTokens: reqNonNegInt(value, "inputTokens"),
+                outputTokens: reqNonNegInt(value, "outputTokens"),
+                ...(model !== undefined ? { model } : {}),
+            };
+        }
+        case "turn-start":
+            return { type, id, parentId: parent, turn: reqNonNegInt(value, "turn") };
+        case "turn-end":
+            return { type, id, parentId: parent, turn: reqNonNegInt(value, "turn") };
+        default:
+            throw new SessionEventShapeError(`unknown session event type: ${JSON.stringify(type)}`);
+    }
+}

package/dist/session/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `@nanobpm/agentic/session` — the canonical agent-session contract (ADR 0062,
+ * slice 1). The foundation the two ingestion backends (ACP, normalisers) and the
+ * nano-workforce world-restore all code against in parallel.
+ *
+ * Exports, in the order a consumer meets them:
+ *  - the canonical {@link SessionEvent} union every harness dialect normalises
+ *    into, plus {@link parseSessionEvent} (the untyped-storage boundary);
+ *  - the three-method {@link SessionAdapter} interface (emit/checkpoint/restore)
+ *    with its {@link ActivationKey}, {@link SessionCheckpoint} and
+ *    {@link SessionSeed} types;
+ *  - the {@link SessionLog} port and its two backends — the in-memory reference
+ *    ({@link InMemorySessionLog}, the stub) and the durable, authoritative
+ *    {@link SqliteSessionLog} that promotes the ADR 0056 §12 relay ring + fence;
+ *  - {@link SessionBackend} (the one adapter implementation) and the
+ *    {@link openInMemorySession} / {@link openSqliteSession} factories.
+ *
+ * The new DB schema ships as the forward-only migration
+ * `db/migrations/005_agentic_session.sql`, mirrored by {@link SESSION_SCHEMA_SQL}
+ * and kept in lockstep by a drift-guard test. Nothing here rides the Camunda-8
+ * engine — the log is app-tier (ADR 0056 boundary preserved).
+ */
+export type { AppendedSessionEvent, AssistantMessageEvent, CompactionEvent, ReasoningEvent, SessionEvent, SessionEventEnvelope, SessionEventType, SystemMessageEvent, ToolCallEvent, ToolResultEvent, TurnEndEvent, TurnStartEvent, UsageEvent, UserMessageEvent, } from "./events.ts";
+export { parseSessionEvent, SESSION_EVENT_TYPES, SessionEventShapeError } from "./events.ts";
+export type { ActivationKey, EffectEntry, EffectLedger, SessionAdapter, SessionCheckpoint, SessionSeed, } from "./adapter.ts";
+export { activationKeyString, StaleIncarnationError } from "./adapter.ts";
+export type { Clock, SessionLog, SqliteDb } from "./log.ts";
+export { InMemorySessionLog, SessionLogCorruptionError, SqliteSessionLog, systemClock, } from "./log.ts";
+export type { SessionBackendOptions } from "./backend.ts";
+export { openInMemorySession, openSqliteSession, SessionBackend } from "./backend.ts";
+export { SESSION_CHECKPOINT_TABLE, SESSION_EVENT_TABLE, SESSION_LOG_TABLE, SESSION_SCHEMA_SQL, } from "./schema.ts";

package/dist/session/index.js

@@ -0,0 +1,5 @@
+export { parseSessionEvent, SESSION_EVENT_TYPES, SessionEventShapeError } from "./events.js";
+export { activationKeyString, StaleIncarnationError } from "./adapter.js";
+export { InMemorySessionLog, SessionLogCorruptionError, SqliteSessionLog, systemClock, } from "./log.js";
+export { openInMemorySession, openSqliteSession, SessionBackend } from "./backend.js";
+export { SESSION_CHECKPOINT_TABLE, SESSION_EVENT_TABLE, SESSION_LOG_TABLE, SESSION_SCHEMA_SQL, } from "./schema.js";

package/dist/session/log.d.ts

@@ -0,0 +1,107 @@
+import { type ActivationKey, type SessionCheckpoint } from "./adapter.ts";
+import { type AppendedSessionEvent, type SessionEvent } from "./events.ts";
+/**
+ * The authoritative-log port the {@link SessionBackend} adapter writes through.
+ * Two backends implement it: {@link InMemorySessionLog} (the reference/stub) and
+ * {@link SqliteSessionLog} (durable, over the app DataLayer). All writes are
+ * fenced by `incarnation`; a stale writer throws {@link StaleIncarnationError}.
+ */
+export interface SessionLog {
+    /**
+     * Take (or renew) the lease for `key` at `incarnation`, advancing the fence
+     * high-water mark. Throws {@link StaleIncarnationError} if a newer incarnation
+     * already owns the activation. Called once when an adapter is constructed so a
+     * re-lease fences prior incarnations immediately, before any write.
+     */
+    lease(key: ActivationKey, incarnation: number): void;
+    /** The current (highest leased) incarnation for `key`, or `undefined`. */
+    currentIncarnation(key: ActivationKey): number | undefined;
+    /** The offset the next appended event will occupy (also the event count). */
+    nextOffset(key: ActivationKey): number;
+    /**
+     * Append `event` at `offset` under `incarnation`, returning it stamped as an
+     * {@link AppendedSessionEvent}. Fenced. `offset` must be `<= nextOffset`: at
+     * `nextOffset` it extends the log; below it (a resume writing back into the log
+     * after `restore`) it first drops the now-superseded uncommitted tail
+     * `[offset, nextOffset)` — **and every checkpoint pinned above `offset`**, which
+     * would otherwise dangle past the rewritten head and mis-seed a later `restore`
+     * (a gap `RangeError` on the next `emit`) — and then writes: an idempotent
+     * re-key that keeps the authoritative log gap-free. An `offset > nextOffset` is
+     * a gap and throws.
+     */
+    append(key: ActivationKey, incarnation: number, offset: number, event: SessionEvent): AppendedSessionEvent;
+    /** Persist a checkpoint (fenced by `incarnation`). Returns it unchanged. */
+    putCheckpoint(key: ActivationKey, incarnation: number, checkpoint: SessionCheckpoint): SessionCheckpoint;
+    /** The checkpoint with the highest offset (newest), or `undefined`. */
+    latestCheckpoint(key: ActivationKey): SessionCheckpoint | undefined;
+    /** A specific checkpoint by id, or `undefined`. */
+    getCheckpoint(key: ActivationKey, id: string): SessionCheckpoint | undefined;
+    /** The events with `from <= offset < to`, in offset order. `to` defaults to the head. */
+    replay(key: ActivationKey, from: number, to?: number): AppendedSessionEvent[];
+}
+/**
+ * The in-memory reference backend (the stub slices 2–5 code against and the tests
+ * exercise). Reuses the relay {@link IncarnationFence} verbatim and keeps each
+ * activation's full event array — the authoritative, non-evicting analogue of the
+ * relay ring's resume window.
+ */
+export declare class InMemorySessionLog implements SessionLog {
+    #private;
+    lease(key: ActivationKey, incarnation: number): void;
+    currentIncarnation(key: ActivationKey): number | undefined;
+    nextOffset(key: ActivationKey): number;
+    append(key: ActivationKey, incarnation: number, offset: number, event: SessionEvent): AppendedSessionEvent;
+    putCheckpoint(key: ActivationKey, incarnation: number, checkpoint: SessionCheckpoint): SessionCheckpoint;
+    latestCheckpoint(key: ActivationKey): SessionCheckpoint | undefined;
+    getCheckpoint(key: ActivationKey, id: string): SessionCheckpoint | undefined;
+    replay(key: ActivationKey, from: number, to?: number): AppendedSessionEvent[];
+}
+/**
+ * The minimal synchronous SQLite handle the durable log needs — structurally the
+ * same surface the Urban runtime's DataLayer exposes (`host.openSqlite`), and
+ * identical to the presence/transcript stores' `SqliteDb`. Kept local so the log
+ * depends on a shape, not on the runtime package.
+ */
+export interface SqliteDb {
+    exec(sql: string): void;
+    run(sql: string, params?: unknown[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    all<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+}
+/** A monotonic wall clock, injectable for deterministic tests. */
+export interface Clock {
+    now(): number;
+}
+/** The default clock: `Date.now()`. */
+export declare const systemClock: Clock;
+/**
+ * The durable authoritative log over the app DataLayer/SQLite. The fence
+ * high-water lives in the activation row's `incarnation` column, so fencing
+ * survives a process restart — the durable counterpart of the in-memory
+ * {@link IncarnationFence}.
+ */
+export declare class SqliteSessionLog implements SessionLog {
+    #private;
+    constructor(db: SqliteDb, options?: {
+        clock?: Clock;
+    });
+    /** Apply the canonical DDL (idempotent). Identical to the boot migration (drift-guarded). */
+    ensureSchema(): void;
+    lease(key: ActivationKey, incarnation: number): void;
+    currentIncarnation(key: ActivationKey): number | undefined;
+    nextOffset(key: ActivationKey): number;
+    append(key: ActivationKey, incarnation: number, offset: number, event: SessionEvent): AppendedSessionEvent;
+    putCheckpoint(key: ActivationKey, incarnation: number, checkpoint: SessionCheckpoint): SessionCheckpoint;
+    latestCheckpoint(key: ActivationKey): SessionCheckpoint | undefined;
+    getCheckpoint(key: ActivationKey, id: string): SessionCheckpoint | undefined;
+    replay(key: ActivationKey, from: number, to?: number): AppendedSessionEvent[];
+}
+/**
+ * Raised when a row read back from the durable session log holds a value outside
+ * its domain (e.g. a corrupt effect-ledger JSON). Fail fast rather than coercing.
+ */
+export declare class SessionLogCorruptionError extends Error {
+    constructor(message: string);
+}