@nanobpm/agentic 0.1.0 → 0.4.0

package/dist/session/log.js

@@ -0,0 +1,351 @@
+/**
+ * The authoritative session-log store — ADR 0062, slice 1.
+ *
+ * This **promotes** the advisory relay substrate (ADR 0056 §12: the bounded
+ * replay ring's resume-from-offset, plus generation/incarnation fencing) into an
+ * *authoritative* per-activation log. Two things change on promotion:
+ *
+ *  - **Unbounded, durable retention.** The relay ring is a bounded in-memory
+ *    resume window that evicts; the authoritative log retains every event of an
+ *    activation (lifecycle-bounded like the S6 transcript, swept only when the
+ *    activation is retired), so `restore` can always replay from offset 0.
+ *  - **Durable fencing.** The relay {@link IncarnationFence} (which this module
+ *    reuses verbatim for the in-memory backend) lives in memory; the SQLite
+ *    backend persists the same high-water mark in the activation row's
+ *    `incarnation` column, so a stale writer is fenced even across a restart.
+ *
+ * Transport is never re-implemented — this is a storage layer over the app
+ * DataLayer (or memory), exactly as the transcript store is. Nothing here rides
+ * the Camunda-8 engine (ADR 0056 boundary preserved).
+ */
+import { IncarnationFence } from "../relay/incarnation.js";
+import { activationKeyString, StaleIncarnationError, } from "./adapter.js";
+import { parseSessionEvent } from "./events.js";
+import { SESSION_CHECKPOINT_TABLE, SESSION_EVENT_TABLE, SESSION_LOG_TABLE, SESSION_SCHEMA_SQL, } from "./schema.js";
+function isNonNegInt(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function assertOffset(offset) {
+    if (!isNonNegInt(offset)) {
+        throw new RangeError(`session log offset must be a non-negative safe integer, got ${offset}`);
+    }
+}
+/**
+ * Validate a `replay(from, to)` window: `from` is a normal offset, and when a
+ * bounded `to` is given it must itself be a valid offset that is not below
+ * `from` — so an out-of-range or inverted bound fails fast instead of silently
+ * yielding a surprising `Array.slice`/SQL range.
+ */
+function assertReplayBounds(from, to) {
+    assertOffset(from);
+    if (to === undefined)
+        return;
+    if (!isNonNegInt(to)) {
+        throw new RangeError(`session log replay 'to' must be a non-negative safe integer, got ${to}`);
+    }
+    if (to < from) {
+        throw new RangeError(`session log replay 'to' (${to}) must be >= 'from' (${from})`);
+    }
+}
+/**
+ * A checkpoint's own {@link SessionCheckpoint.incarnation} must equal the fence
+ * token it is written under — otherwise the row would be fenced with one
+ * incarnation but stamped with another, producing inconsistent durable data.
+ */
+function assertCheckpointIncarnation(incarnation, checkpoint) {
+    if (checkpoint.incarnation !== incarnation) {
+        throw new RangeError(`checkpoint ${checkpoint.id} incarnation (${checkpoint.incarnation}) must equal the write lease incarnation (${incarnation})`);
+    }
+}
+/**
+ * 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 class InMemorySessionLog {
+    #fence = new IncarnationFence();
+    #events = new Map();
+    #checkpoints = new Map();
+    #eventsFor(key) {
+        const s = activationKeyString(key);
+        let arr = this.#events.get(s);
+        if (arr === undefined) {
+            arr = [];
+            this.#events.set(s, arr);
+        }
+        return arr;
+    }
+    #checkpointsFor(key) {
+        const s = activationKeyString(key);
+        let arr = this.#checkpoints.get(s);
+        if (arr === undefined) {
+            arr = [];
+            this.#checkpoints.set(s, arr);
+        }
+        return arr;
+    }
+    #admit(key, incarnation) {
+        const s = activationKeyString(key);
+        if (!this.#fence.admit(s, incarnation)) {
+            throw new StaleIncarnationError(key, incarnation, this.#fence.current(s) ?? incarnation);
+        }
+    }
+    lease(key, incarnation) {
+        this.#admit(key, incarnation);
+    }
+    currentIncarnation(key) {
+        return this.#fence.current(activationKeyString(key));
+    }
+    nextOffset(key) {
+        return this.#eventsFor(key).length;
+    }
+    append(key, incarnation, offset, event) {
+        assertOffset(offset);
+        this.#admit(key, incarnation);
+        const arr = this.#eventsFor(key);
+        if (offset > arr.length) {
+            throw new RangeError(`session log gap: append at offset ${offset} but next offset is ${arr.length}`);
+        }
+        if (offset < arr.length) {
+            // Resuming: drop the now-superseded uncommitted tail before re-keying, and
+            // prune any checkpoint pinned above the resume boundary — it now points
+            // past the rewritten head and would mis-seed a later restore.
+            arr.length = offset;
+            this.#pruneCheckpointsAbove(key, offset);
+        }
+        const appended = { ...event, offset, incarnation };
+        arr.push(appended);
+        return appended;
+    }
+    /** Drop checkpoints whose offset sits above `offset` (past a rewritten head). */
+    #pruneCheckpointsAbove(key, offset) {
+        const arr = this.#checkpointsFor(key);
+        for (let i = arr.length - 1; i >= 0; i--) {
+            if (arr[i].offset > offset)
+                arr.splice(i, 1);
+        }
+    }
+    putCheckpoint(key, incarnation, checkpoint) {
+        this.#admit(key, incarnation);
+        assertCheckpointIncarnation(incarnation, checkpoint);
+        const arr = this.#checkpointsFor(key);
+        // First-wins on checkpoint.id — mirrors the durable backend's
+        // ON CONFLICT(checkpoint_id) DO NOTHING so a retry never duplicates.
+        if (arr.some((cp) => cp.id === checkpoint.id))
+            return checkpoint;
+        arr.push(checkpoint);
+        return checkpoint;
+    }
+    latestCheckpoint(key) {
+        let best;
+        for (const cp of this.#checkpointsFor(key)) {
+            // Highest offset wins; a later insert at the same offset supersedes.
+            if (best === undefined || cp.offset >= best.offset)
+                best = cp;
+        }
+        return best;
+    }
+    getCheckpoint(key, id) {
+        return this.#checkpointsFor(key).find((cp) => cp.id === id);
+    }
+    replay(key, from, to) {
+        assertReplayBounds(from, to);
+        const arr = this.#eventsFor(key);
+        const end = to === undefined ? arr.length : to;
+        return arr.slice(from, end);
+    }
+}
+/** The default clock: `Date.now()`. */
+export const systemClock = { now: () => Date.now() };
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isEffectLedger(value) {
+    if (!Array.isArray(value))
+        return false;
+    return value.every((entry) => isRecord(entry) && typeof entry.id === "string" && typeof entry.kind === "string");
+}
+/**
+ * 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 class SqliteSessionLog {
+    #db;
+    #clock;
+    constructor(db, options = {}) {
+        this.#db = db;
+        this.#clock = options.clock ?? systemClock;
+    }
+    /** Apply the canonical DDL (idempotent). Identical to the boot migration (drift-guarded). */
+    ensureSchema() {
+        this.#db.exec(SESSION_SCHEMA_SQL);
+    }
+    #logRow(key) {
+        return this.#db.all(`SELECT incarnation, next_offset FROM ${SESSION_LOG_TABLE} WHERE process_instance_key = ? AND element_id = ?`, [key.processInstanceKey, key.elementId])[0];
+    }
+    #admit(key, incarnation) {
+        if (!isNonNegInt(incarnation)) {
+            throw new RangeError(`incarnation must be a non-negative safe integer, got ${incarnation}`);
+        }
+        // Insert the activation row if it is missing, or advance its fence high-water when
+        // this lease is newer — as one atomic UPSERT. A plain ON CONFLICT DO NOTHING would
+        // let a concurrent first-lease race slip through: if another writer created the row
+        // between a pre-read and this INSERT, DO NOTHING would neither advance the fence nor
+        // reject a stale lease. Re-read and assert afterwards (insert-then-get, mirroring the
+        // transcript store) so a lease below the stored high-water is always fenced out.
+        this.#db.run(`INSERT INTO ${SESSION_LOG_TABLE} (process_instance_key, element_id, incarnation, created_at, next_offset)
+       VALUES (?, ?, ?, ?, 0)
+       ON CONFLICT(process_instance_key, element_id)
+         DO UPDATE SET incarnation = excluded.incarnation
+         WHERE excluded.incarnation > ${SESSION_LOG_TABLE}.incarnation`, [key.processInstanceKey, key.elementId, incarnation, new Date(this.#clock.now()).toISOString()]);
+        const row = this.#logRow(key);
+        if (row === undefined) {
+            throw new Error(`session log row vanished immediately after admit: ${activationKeyString(key)}`);
+        }
+        if (incarnation < row.incarnation) {
+            throw new StaleIncarnationError(key, incarnation, row.incarnation);
+        }
+    }
+    lease(key, incarnation) {
+        this.#admit(key, incarnation);
+    }
+    currentIncarnation(key) {
+        return this.#logRow(key)?.incarnation;
+    }
+    nextOffset(key) {
+        return this.#logRow(key)?.next_offset ?? 0;
+    }
+    append(key, incarnation, offset, event) {
+        assertOffset(offset);
+        this.#admit(key, incarnation);
+        const next = this.nextOffset(key);
+        if (offset > next) {
+            throw new RangeError(`session log gap: append at offset ${offset} but next offset is ${next}`);
+        }
+        const appended = { ...event, offset, incarnation };
+        return this.#atomic(() => {
+            if (offset < next) {
+                // Resuming: drop the now-superseded uncommitted tail before re-keying.
+                this.#db.run(`DELETE FROM ${SESSION_EVENT_TABLE} WHERE process_instance_key = ? AND element_id = ? AND event_offset >= ?`, [key.processInstanceKey, key.elementId, offset]);
+                // Prune checkpoints pinned above the resume boundary: they now point
+                // past the rewritten head and would mis-seed a later restore (a gap
+                // RangeError on the next emit).
+                this.#db.run(`DELETE FROM ${SESSION_CHECKPOINT_TABLE} WHERE process_instance_key = ? AND element_id = ? AND checkpoint_offset > ?`, [key.processInstanceKey, key.elementId, offset]);
+            }
+            this.#db.run(`INSERT INTO ${SESSION_EVENT_TABLE}
+           (process_instance_key, element_id, event_offset, incarnation, event_id, parent_id, event_type, payload, appended_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+                key.processInstanceKey,
+                key.elementId,
+                offset,
+                incarnation,
+                event.id,
+                event.parentId,
+                event.type,
+                JSON.stringify(appended),
+                new Date(this.#clock.now()).toISOString(),
+            ]);
+            this.#advanceWindow(key, offset);
+            return appended;
+        });
+    }
+    putCheckpoint(key, incarnation, checkpoint) {
+        this.#admit(key, incarnation);
+        assertCheckpointIncarnation(incarnation, checkpoint);
+        this.#db.run(`INSERT INTO ${SESSION_CHECKPOINT_TABLE}
+         (process_instance_key, element_id, checkpoint_id, checkpoint_offset, incarnation, commit_sha, effect_ledger, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(process_instance_key, element_id, checkpoint_id) DO NOTHING`, [
+            key.processInstanceKey,
+            key.elementId,
+            checkpoint.id,
+            checkpoint.offset,
+            incarnation,
+            checkpoint.commitSha,
+            JSON.stringify(checkpoint.effectLedger),
+            checkpoint.at,
+        ]);
+        return checkpoint;
+    }
+    latestCheckpoint(key) {
+        const row = this.#db.all(`SELECT checkpoint_id, checkpoint_offset, incarnation, commit_sha, effect_ledger, created_at
+       FROM ${SESSION_CHECKPOINT_TABLE}
+       WHERE process_instance_key = ? AND element_id = ?
+       ORDER BY checkpoint_offset DESC, rowid DESC LIMIT 1`, [key.processInstanceKey, key.elementId])[0];
+        return row === undefined ? undefined : this.#toCheckpoint(row);
+    }
+    getCheckpoint(key, id) {
+        const row = this.#db.all(`SELECT checkpoint_id, checkpoint_offset, incarnation, commit_sha, effect_ledger, created_at
+       FROM ${SESSION_CHECKPOINT_TABLE}
+       WHERE process_instance_key = ? AND element_id = ? AND checkpoint_id = ?`, [key.processInstanceKey, key.elementId, id])[0];
+        return row === undefined ? undefined : this.#toCheckpoint(row);
+    }
+    #toCheckpoint(row) {
+        const ledgerRaw = JSON.parse(row.effect_ledger);
+        if (!isEffectLedger(ledgerRaw)) {
+            throw new SessionLogCorruptionError(`checkpoint ${row.checkpoint_id} effect_ledger is not a valid EffectLedger`);
+        }
+        return {
+            id: row.checkpoint_id,
+            offset: row.checkpoint_offset,
+            commitSha: row.commit_sha,
+            effectLedger: ledgerRaw,
+            incarnation: row.incarnation,
+            at: row.created_at,
+        };
+    }
+    replay(key, from, to) {
+        assertReplayBounds(from, to);
+        const upper = to === undefined ? Number.MAX_SAFE_INTEGER : to;
+        return this.#db
+            .all(`SELECT event_offset, incarnation, payload FROM ${SESSION_EVENT_TABLE}
+         WHERE process_instance_key = ? AND element_id = ? AND event_offset >= ? AND event_offset < ?
+         ORDER BY event_offset`, [key.processInstanceKey, key.elementId, from, upper])
+            .map((row) => {
+            const parsed = JSON.parse(row.payload);
+            const event = parseSessionEvent(parsed);
+            return { ...event, offset: row.event_offset, incarnation: row.incarnation };
+        });
+    }
+    /**
+     * Advance an activation's retained offset window (`first_offset`/`next_offset`,
+     * keyed by ActivationKey) to include the offset just appended. `append` always
+     * truncates the tail (`event_offset >= offset`) before inserting at `offset`, so
+     * the freshly stored offset is necessarily the new maximum (`next_offset =
+     * offset + 1`) and the minimum can only move down. Updating incrementally from
+     * the appended offset therefore keeps the window exact in O(1) — a full MIN/MAX
+     * scan of the event table on every append would be O(n) and make appends O(n²)
+     * as the log grows.
+     */
+    #advanceWindow(key, offset) {
+        this.#db.run(`UPDATE ${SESSION_LOG_TABLE}
+         SET first_offset = MIN(COALESCE(first_offset, ?), ?), next_offset = ?
+       WHERE process_instance_key = ? AND element_id = ?`, [offset, offset, offset + 1, key.processInstanceKey, key.elementId]);
+    }
+    #atomic(body) {
+        this.#db.exec("SAVEPOINT nano_session_atomic");
+        try {
+            const result = body();
+            this.#db.exec("RELEASE SAVEPOINT nano_session_atomic");
+            return result;
+        }
+        catch (err) {
+            this.#db.exec("ROLLBACK TO SAVEPOINT nano_session_atomic");
+            this.#db.exec("RELEASE SAVEPOINT nano_session_atomic");
+            throw err;
+        }
+    }
+}
+/**
+ * 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 class SessionLogCorruptionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SessionLogCorruptionError";
+    }
+}

package/dist/session/normalizer/claude.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Claude Code normalizer — ADR 0062 slice 3, reference dialect B.
+ *
+ * Driven with `claude -p --output-format stream-json` (paired with
+ * `--input-format stream-json` to feed it), Claude Code streams one JSON object
+ * per line. A turn arrives as an `assistant` frame whose `message.content` is an
+ * array of typed parts — `text`, `thinking` (with an encrypted `signature`),
+ * `tool_use` — and tool outputs come back as a `user` frame carrying
+ * `tool_result` parts. Restore is the native `--resume <id>` (`-c` continues the
+ * latest, `--from-pr` seeds from a PR — both resume-by-latest, not by-id, so the
+ * id-restore shim is `--resume`). Streaming + resume-by-id → `durable-resume`.
+ *
+ * ## Resume-critical fidelity: `thinking.signature`
+ *
+ * Claude's `thinking` parts carry a `signature`: the provider's opaque, encrypted
+ * reasoning-continuation token that must be replayed verbatim to continue
+ * extended thinking across a resume (ADR 0062 §5). We map it to the canonical
+ * `ReasoningEvent.providerContinuation`, so the native transcript remains the
+ * authoritative restore path for Claude just as it does for Copilot.
+ */
+import { type HarnessNormalizer } from "./types.ts";
+/** The Claude Code fallback normalizer. Streaming + resume-by-id → durable. */
+export declare const claudeNormalizer: HarnessNormalizer;

package/dist/session/normalizer/claude.js

@@ -0,0 +1,138 @@
+/**
+ * Claude Code normalizer — ADR 0062 slice 3, reference dialect B.
+ *
+ * Driven with `claude -p --output-format stream-json` (paired with
+ * `--input-format stream-json` to feed it), Claude Code streams one JSON object
+ * per line. A turn arrives as an `assistant` frame whose `message.content` is an
+ * array of typed parts — `text`, `thinking` (with an encrypted `signature`),
+ * `tool_use` — and tool outputs come back as a `user` frame carrying
+ * `tool_result` parts. Restore is the native `--resume <id>` (`-c` continues the
+ * latest, `--from-pr` seeds from a PR — both resume-by-latest, not by-id, so the
+ * id-restore shim is `--resume`). Streaming + resume-by-id → `durable-resume`.
+ *
+ * ## Resume-critical fidelity: `thinking.signature`
+ *
+ * Claude's `thinking` parts carry a `signature`: the provider's opaque, encrypted
+ * reasoning-continuation token that must be replayed verbatim to continue
+ * extended thinking across a resume (ADR 0062 §5). We map it to the canonical
+ * `ReasoningEvent.providerContinuation`, so the native transcript remains the
+ * authoritative restore path for Claude just as it does for Copilot.
+ */
+import { NormalizerDialectError } from "./types.js";
+import { asArray, asRecord, isRecord, optNumber, optString, reqString } from "./record.js";
+const HARNESS = "claude-code";
+function messageContent(obj) {
+    const message = obj.message;
+    if (!isRecord(message)) {
+        throw new NormalizerDialectError(HARNESS, `${String(obj.type)} frame must carry a "message" object`);
+    }
+    const content = message.content;
+    // Claude also permits a bare-string message content for a plain text turn.
+    if (typeof content === "string")
+        return [{ type: "text", text: content }];
+    return asArray(HARNESS, content, "message.content");
+}
+function usageDrafts(usage, model) {
+    if (!isRecord(usage))
+        return [];
+    return [
+        {
+            type: "usage",
+            inputTokens: optNumber(HARNESS, usage, "input_tokens") ?? 0,
+            outputTokens: optNumber(HARNESS, usage, "output_tokens") ?? 0,
+            ...(model !== undefined ? { model } : {}),
+        },
+    ];
+}
+function toDrafts(record) {
+    const obj = asRecord(HARNESS, record);
+    switch (obj.type) {
+        case "system":
+            // The `init` system frame is session metadata (tools, model, cwd), not a
+            // conversational system turn — it carries no canonical text.
+            return [];
+        case "assistant": {
+            const message = isRecord(obj.message) ? obj.message : {};
+            const model = optString(HARNESS, message, "model");
+            const drafts = [];
+            for (const part of messageContent(obj)) {
+                if (!isRecord(part))
+                    continue;
+                switch (part.type) {
+                    case "text": {
+                        const text = optString(HARNESS, part, "text");
+                        if (text !== undefined && text.length > 0)
+                            drafts.push({ type: "assistant", text });
+                        break;
+                    }
+                    case "thinking": {
+                        const text = optString(HARNESS, part, "thinking");
+                        const signature = optString(HARNESS, part, "signature");
+                        drafts.push({
+                            type: "reasoning",
+                            ...(text !== undefined ? { text } : {}),
+                            ...(signature !== undefined ? { providerContinuation: signature } : {}),
+                        });
+                        break;
+                    }
+                    case "tool_use": {
+                        const callId = reqString(HARNESS, part, "id");
+                        drafts.push({
+                            type: "tool-call",
+                            id: `call:${callId}`,
+                            callId,
+                            name: reqString(HARNESS, part, "name"),
+                            args: part.input,
+                        });
+                        break;
+                    }
+                    default:
+                        break;
+                }
+            }
+            // A turn's usage rides on its assistant message.
+            drafts.push(...usageDrafts(message.usage, model));
+            return drafts;
+        }
+        case "user": {
+            const drafts = [];
+            for (const part of messageContent(obj)) {
+                if (!isRecord(part))
+                    continue;
+                if (part.type === "tool_result") {
+                    const callId = reqString(HARNESS, part, "tool_use_id");
+                    drafts.push({
+                        type: "tool-result",
+                        id: `result:${callId}`,
+                        callId,
+                        ok: part.is_error !== true,
+                        result: part.content,
+                    });
+                }
+                else if (part.type === "text") {
+                    const text = optString(HARNESS, part, "text");
+                    if (text !== undefined && text.length > 0)
+                        drafts.push({ type: "user", text });
+                }
+            }
+            return drafts;
+        }
+        case "result":
+            // Terminal accounting frame: fold its top-level usage in whenever present.
+            // Like every other frame's usage (and every other normalizer), this maps to
+            // its own canonical `usage` event — assistant frames emit their own
+            // per-message usage and the linker never dedupes; consumers aggregate.
+            return usageDrafts(obj.usage, optString(HARNESS, obj, "model"));
+        default:
+            return [];
+    }
+}
+/** The Claude Code fallback normalizer. Streaming + resume-by-id → durable. */
+export const claudeNormalizer = {
+    harness: HARNESS,
+    capabilities: { streaming: true, resumeById: true },
+    toDrafts,
+    resume(sessionId) {
+        return { transport: "cli", sessionId, args: ["--resume", sessionId] };
+    },
+};

package/dist/session/normalizer/copilot.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `@github/copilot` normalizer — ADR 0062 slice 3, reference dialect A.
+ *
+ * Copilot runs in-process through `copilot-sdk`: the mind source is its own
+ * `SessionEvent` stream (`session.on(...)`, or the `events.jsonl` transcript it
+ * writes), and restore is the SDK's `resumeSession(id)` (the `sessionFsProvider`
+ * seam is the same call under a different persistence root, so the resume shim is
+ * identical). Copilot both streams and resumes-by-id → it advertises
+ * `durable-resume`.
+ *
+ * ## Resume-critical fidelity: `reasoningOpaque`
+ *
+ * ADR 0062 §5 lets a native adapter *prefer the native transcript for restore*
+ * when it carries more than the ACP models. Copilot's reasoning events carry a
+ * `reasoningOpaque` blob — the provider reasoning-continuation handle that must
+ * be replayed verbatim to continue the model's reasoning across a resume. The
+ * canonical `ReasoningEvent` has a home for exactly this (`providerContinuation`),
+ * so we map it straight through, untouched. Dropping it (as a lossy ACP
+ * projection might) would silently break reasoning continuation on resume — so
+ * this dialect is the authoritative ingestion path for Copilot.
+ */
+import type { HarnessNormalizer } from "./types.ts";
+/**
+ * The `@github/copilot` fallback normalizer. `streaming`/`resumeById` are both
+ * true, so {@link capabilityProbe} derives `durable-resume: true`.
+ */
+export declare const copilotNormalizer: HarnessNormalizer;

package/dist/session/normalizer/copilot.js

@@ -0,0 +1,105 @@
+import { asRecord, contentText, optNumber, optString, reqString } from "./record.js";
+const HARNESS = "@github/copilot";
+/**
+ * Map one `copilot-sdk` `SessionEvent` to canonical drafts. Copilot's event
+ * `type`s are close to ours but not identical (`assistant_message` vs
+ * `assistant`, `reasoningOpaque` vs `providerContinuation`, `turn_started` vs
+ * `turn-start`); this is exactly the per-dialect translation the slice exists to
+ * own.
+ */
+function toDrafts(record) {
+    const obj = asRecord(HARNESS, record);
+    switch (obj.type) {
+        case "system":
+        case "system_message":
+            return [{ type: "system", text: reqString(HARNESS, obj, "text") }];
+        case "user":
+        case "user_message":
+            return [{ type: "user", text: reqString(HARNESS, obj, "text") }];
+        case "assistant":
+        case "assistant_message": {
+            const text = contentText(obj.text ?? obj.content);
+            return text === undefined ? [] : [{ type: "assistant", text }];
+        }
+        case "reasoning": {
+            const text = optString(HARNESS, obj, "text");
+            // Copilot names the continuation blob `reasoningOpaque`; accept the
+            // canonical spelling too so a pre-normalized feed round-trips.
+            const providerContinuation = optString(HARNESS, obj, "reasoningOpaque") ?? optString(HARNESS, obj, "providerContinuation");
+            return [
+                {
+                    type: "reasoning",
+                    ...(text !== undefined ? { text } : {}),
+                    ...(providerContinuation !== undefined ? { providerContinuation } : {}),
+                },
+            ];
+        }
+        case "tool_call": {
+            const callId = reqString(HARNESS, obj, "id");
+            return [
+                {
+                    type: "tool-call",
+                    id: `call:${callId}`,
+                    callId,
+                    name: reqString(HARNESS, obj, "name"),
+                    args: obj.arguments ?? obj.args,
+                },
+            ];
+        }
+        case "tool_result": {
+            const callId = reqString(HARNESS, obj, "id");
+            // Copilot marks failure with an `isError` flag; the payload lives in
+            // `output` either way.
+            const ok = obj.isError === true ? false : obj.error == null;
+            return [
+                {
+                    type: "tool-result",
+                    id: `result:${callId}`,
+                    callId,
+                    ok,
+                    result: obj.output ?? obj.result ?? obj.error,
+                },
+            ];
+        }
+        case "turn_started":
+            return [{ type: "turn-start", turn: turnIndex(obj) }];
+        case "turn_completed":
+        case "turn_ended":
+            return [{ type: "turn-end", turn: turnIndex(obj) }];
+        case "usage": {
+            const model = optString(HARNESS, obj, "model");
+            return [
+                {
+                    type: "usage",
+                    inputTokens: usageCount(obj, "inputTokens", "input_tokens"),
+                    outputTokens: usageCount(obj, "outputTokens", "output_tokens"),
+                    ...(model !== undefined ? { model } : {}),
+                },
+            ];
+        }
+        default:
+            // Transport frames Copilot emits that carry no session-log meaning
+            // (heartbeats, session-ready acks) normalize to nothing.
+            return [];
+    }
+}
+function turnIndex(obj) {
+    return optNumber(HARNESS, obj, "turn") ?? 0;
+}
+function usageCount(obj, camel, snake) {
+    return optNumber(HARNESS, obj, camel) ?? optNumber(HARNESS, obj, snake) ?? 0;
+}
+/**
+ * The `@github/copilot` fallback normalizer. `streaming`/`resumeById` are both
+ * true, so {@link capabilityProbe} derives `durable-resume: true`.
+ */
+export const copilotNormalizer = {
+    harness: HARNESS,
+    capabilities: { streaming: true, resumeById: true },
+    toDrafts,
+    resume(sessionId) {
+        // In-process SDK restore: `resumeSession(id)` (the sessionFsProvider seam is
+        // the same call under a different persistence root).
+        return { transport: "sdk", sessionId, call: "resumeSession", args: [sessionId] };
+    },
+};

package/dist/session/normalizer/deepseek.d.ts

@@ -0,0 +1,11 @@
+/**
+ * DeepSeek Harness normalizer — ADR 0062 slice 3.
+ *
+ * The DeepSeek Harness exposes a live `SessionEvent` feed rather than a spawned
+ * `stream-json` transport: its frames are already event-shaped (`kind`-tagged),
+ * so the dialect is a thin renaming onto the canonical union. Restore is the
+ * harness's in-process `seed`/`restore` pair, so the resume shim is the SDK
+ * `restore(id)` call. Streaming + resume-by-id → `durable-resume`.
+ */
+import type { HarnessNormalizer } from "./types.ts";
+export declare const deepseekNormalizer: HarnessNormalizer;