specrails-core 6.4.0 → 6.5.0

package/dist/agent-runtime/session/journal/sqlite-journal.js

@@ -0,0 +1,279 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { sessionsRoot } from '../../../shared/specrails-home.js';
+import { PersistenceError, privateSqlitePath } from '../../engine/storage/private-path.js';
+import { SessionError } from '../domain/errors.js';
+import { emptySnapshot, foldEvents } from '../domain/snapshot.js';
+import { JOURNAL_MIGRATIONS, JOURNAL_SCHEMA_VERSION } from './schema.js';
+export const JOURNAL_LEASE_MS = 60_000;
+export const JOURNAL_HEARTBEAT_MS = 15_000;
+export const JOURNAL_FILENAME = 'sessions.sqlite';
+/**
+ * Durable per-scope session journal (`~/.specrails/sessions/<scope>/sessions.sqlite`).
+ * One host owns it through an epoch-fenced lease that is asserted inside every
+ * write transaction. Events and the folded snapshot commit together; provider
+ * I/O never runs inside a transaction.
+ */
+export class SqliteSessionJournal {
+    filename;
+    db;
+    lease;
+    now;
+    leaseMs;
+    cache = new Map();
+    heartbeatTimer = null;
+    closed = false;
+    constructor(filename, db, lease, now, leaseMs) {
+        this.filename = filename;
+        this.db = db;
+        this.lease = lease;
+        this.now = now;
+        this.leaseMs = leaseMs;
+    }
+    static async open(options) {
+        const filename = options.filename ?? path.join(sessionsRoot(options.scope, options.home), JOURNAL_FILENAME);
+        let target;
+        try {
+            target = await privateSqlitePath(filename, { create: !existsSync(filename) });
+        }
+        catch (error) {
+            if (error instanceof PersistenceError)
+                throw new SessionError('internal', `Session journal storage is unsafe or unavailable: ${error.message}`);
+            throw error;
+        }
+        const db = new DatabaseSync(target);
+        const now = options.now ?? Date.now;
+        const leaseMs = options.leaseMs ?? JOURNAL_LEASE_MS;
+        try {
+            db.exec('PRAGMA foreign_keys=ON; PRAGMA busy_timeout=5000; PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL;');
+            migrate(db);
+            const lease = acquireLease(db, options.owner, now, leaseMs);
+            const journal = new SqliteSessionJournal(target, db, lease, now, leaseMs);
+            if (options.heartbeat !== false)
+                journal.startHeartbeat(options.onLeaseLost);
+            return journal;
+        }
+        catch (error) {
+            db.close();
+            throw error;
+        }
+    }
+    // ── SessionJournal ────────────────────────────────────────────────────────
+    createSession(record) {
+        this.write(() => {
+            if (this.db.prepare('SELECT 1 FROM sessions WHERE session_id=?').get(record.sessionId)) {
+                throw new SessionError('invalid_params', `Session ${record.sessionId} already exists`, { path: 'sessionId' });
+            }
+            const snapshot = emptySnapshot(record.sessionId);
+            this.db.prepare('INSERT INTO sessions(session_id,driver,cwd,metadata_json,status,last_seq,snapshot_json,created_at,updated_at) VALUES (?,?,?,?,?,?,?,?,?)')
+                .run(record.sessionId, record.driver, record.cwd, JSON.stringify(record.metadata ?? {}), 'open', 0, JSON.stringify(snapshot), record.createdAt, record.createdAt);
+            this.cache.set(record.sessionId, snapshot);
+        });
+    }
+    getSession(sessionId) {
+        const row = this.db.prepare('SELECT session_id,driver,cwd,metadata_json,created_at FROM sessions WHERE session_id=?').get(sessionId);
+        return row ? toRecord(row) : null;
+    }
+    append(sessionId, events, options) {
+        if (events.length === 0)
+            return [];
+        return this.write(() => {
+            const current = this.loadSnapshot(sessionId);
+            if (!current)
+                throw new SessionError('session_not_found', `Unknown session ${sessionId}`);
+            const envelopes = events.map((event, index) => ({ sessionId, seq: current.lastSeq + index + 1, event }));
+            const next = foldEvents(current, envelopes);
+            const insert = this.db.prepare('INSERT INTO events(session_id,seq,type,at,payload_json) VALUES (?,?,?,?,?)');
+            for (const envelope of envelopes)
+                insert.run(sessionId, envelope.seq, envelope.event.type, envelope.event.at, JSON.stringify(envelope.event));
+            this.db.prepare('UPDATE sessions SET last_seq=?, status=?, snapshot_json=?, updated_at=? WHERE session_id=?')
+                .run(next.lastSeq, next.status, JSON.stringify(next), envelopes.at(-1).event.at, sessionId);
+            if (options?.baseline) {
+                this.db.prepare('INSERT INTO usage_baselines(provider_ref,baseline_json,updated_at) VALUES (?,?,?) ON CONFLICT(provider_ref) DO UPDATE SET baseline_json=excluded.baseline_json, updated_at=excluded.updated_at')
+                    .run(options.baseline.providerRef, JSON.stringify(options.baseline.value), envelopes.at(-1).event.at);
+            }
+            this.cache.set(sessionId, next);
+            return envelopes;
+        }, () => this.cache.delete(sessionId));
+    }
+    read(sessionId, afterSeq, limit) {
+        const rows = this.db.prepare('SELECT seq,payload_json FROM events WHERE session_id=? AND seq>? ORDER BY seq LIMIT ?').all(sessionId, afterSeq, limit + 1);
+        const events = rows.slice(0, limit).map((row) => ({ sessionId, seq: Number(row.seq), event: JSON.parse(String(row.payload_json)) }));
+        return { events, hasMore: rows.length > limit };
+    }
+    snapshot(sessionId) {
+        const snapshot = this.loadSnapshot(sessionId);
+        return snapshot ? structuredClone(snapshot) : null;
+    }
+    list(filter) {
+        const sql = 'SELECT session_id,driver,cwd,metadata_json,created_at,status,last_seq,snapshot_json FROM sessions';
+        const rows = filter === 'all' ? this.db.prepare(`${sql} ORDER BY created_at`).all() : this.db.prepare(`${sql} WHERE status=? ORDER BY created_at`).all(filter);
+        return rows.map((row) => {
+            const snapshot = JSON.parse(String(row.snapshot_json));
+            return {
+                sessionId: String(row.session_id),
+                driver: String(row.driver),
+                model: snapshot.model,
+                status: row.status === 'closed' ? 'closed' : 'open',
+                phase: snapshot.phase,
+                lastSeq: Number(row.last_seq),
+                createdAt: String(row.created_at),
+                metadata: JSON.parse(String(row.metadata_json)),
+            };
+        });
+    }
+    baseline(providerRef) {
+        const row = this.db.prepare('SELECT baseline_json FROM usage_baselines WHERE provider_ref=?').get(providerRef);
+        return row ? JSON.parse(String(row.baseline_json)) : null;
+    }
+    // ── Retention, lease and lifecycle ────────────────────────────────────────
+    /** Remove closed sessions last updated before `olderThan` (epoch ms). Open sessions are never removed. */
+    sweepClosed(olderThan) {
+        return this.write(() => {
+            const cutoff = new Date(olderThan).toISOString();
+            const ids = this.db.prepare("SELECT session_id FROM sessions WHERE status='closed' AND updated_at<?").all(cutoff).map((row) => String(row.session_id));
+            const remove = this.db.prepare('DELETE FROM sessions WHERE session_id=?');
+            for (const id of ids) {
+                remove.run(id);
+                this.cache.delete(id);
+            }
+            return ids.length;
+        });
+    }
+    /** Extend the lease; throws `journal_locked` when it was lost. */
+    renew() {
+        this.write(() => {
+            this.db.prepare('UPDATE host_lease SET heartbeat_at=?, expires_at=? WHERE singleton=1 AND owner=? AND epoch=?')
+                .run(new Date(this.now()).toISOString(), this.now() + this.leaseMs, this.lease.owner, this.lease.epoch);
+        });
+    }
+    /** Release the lease (clean shutdown) and close the database. Idempotent. */
+    close() {
+        if (this.closed)
+            return;
+        this.stopHeartbeat();
+        try {
+            this.transaction(() => {
+                this.db.prepare('DELETE FROM host_lease WHERE singleton=1 AND owner=? AND epoch=?').run(this.lease.owner, this.lease.epoch);
+            });
+        }
+        finally {
+            this.closed = true;
+            this.db.close();
+        }
+    }
+    checkIntegrity() {
+        const result = this.db.prepare('PRAGMA integrity_check').get();
+        if (result?.integrity_check !== 'ok')
+            throw new SessionError('internal', `Journal integrity check failed: ${String(result?.integrity_check)}`);
+    }
+    startHeartbeat(onLost) {
+        this.heartbeatTimer = setInterval(() => {
+            try {
+                this.renew();
+            }
+            catch (error) {
+                this.stopHeartbeat();
+                onLost?.(error instanceof SessionError ? error : new SessionError('journal_locked', String(error)));
+            }
+        }, JOURNAL_HEARTBEAT_MS);
+        this.heartbeatTimer.unref();
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer)
+            clearInterval(this.heartbeatTimer);
+        this.heartbeatTimer = null;
+    }
+    // ── internals ─────────────────────────────────────────────────────────────
+    loadSnapshot(sessionId) {
+        const cached = this.cache.get(sessionId);
+        if (cached)
+            return cached;
+        const row = this.db.prepare('SELECT snapshot_json FROM sessions WHERE session_id=?').get(sessionId);
+        if (!row)
+            return null;
+        const snapshot = JSON.parse(String(row.snapshot_json));
+        this.cache.set(sessionId, snapshot);
+        return snapshot;
+    }
+    /** A fenced write: the lease is asserted inside the same transaction. */
+    write(fn, onRollback) {
+        if (this.closed)
+            throw new SessionError('internal', 'Session journal is closed');
+        return this.transaction(() => {
+            this.assertLease();
+            return fn();
+        }, onRollback);
+    }
+    transaction(fn, onRollback) {
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const result = fn();
+            this.db.exec('COMMIT');
+            return result;
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            onRollback?.();
+            throw error;
+        }
+    }
+    assertLease() {
+        const row = this.db.prepare('SELECT owner,epoch,expires_at FROM host_lease WHERE singleton=1').get();
+        if (!row || String(row.owner) !== this.lease.owner || Number(row.epoch) !== this.lease.epoch || Number(row.expires_at) <= this.now()) {
+            throw new SessionError('journal_locked', 'The session journal lease was lost; another host owns this scope');
+        }
+    }
+}
+function migrate(db) {
+    const version = Number(db.prepare('PRAGMA user_version').get()?.user_version ?? 0);
+    if (version > JOURNAL_SCHEMA_VERSION) {
+        throw new SessionError('store_incompatible', `Session journal schema ${version} is newer than supported ${JOURNAL_SCHEMA_VERSION}`);
+    }
+    for (let index = version; index < JOURNAL_SCHEMA_VERSION; index++) {
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            db.exec(JOURNAL_MIGRATIONS[index]);
+            db.exec(`PRAGMA user_version=${index + 1}`);
+            db.exec('COMMIT');
+        }
+        catch (error) {
+            db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+}
+function acquireLease(db, owner, now, leaseMs) {
+    if (!owner)
+        throw new SessionError('invalid_params', 'A journal owner is required');
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        const at = now();
+        const prior = db.prepare('SELECT owner,expires_at FROM host_lease WHERE singleton=1').get();
+        if (prior && Number(prior.expires_at) > at) {
+            throw new SessionError('journal_locked', `Another session host (${String(prior.owner)}) owns this scope`);
+        }
+        const epoch = Number(db.prepare('SELECT epoch FROM lease_epoch WHERE singleton=1').get().epoch) + 1;
+        const previousEver = epoch > 1;
+        db.prepare('UPDATE lease_epoch SET epoch=? WHERE singleton=1').run(epoch);
+        const iso = new Date(at).toISOString();
+        db.prepare('INSERT INTO host_lease(singleton,owner,epoch,acquired_at,heartbeat_at,expires_at) VALUES (1,?,?,?,?,?) ON CONFLICT(singleton) DO UPDATE SET owner=excluded.owner, epoch=excluded.epoch, acquired_at=excluded.acquired_at, heartbeat_at=excluded.heartbeat_at, expires_at=excluded.expires_at')
+            .run(owner, epoch, iso, iso, at + leaseMs);
+        db.exec('COMMIT');
+        return { owner, epoch, expiresAt: at + leaseMs, previous: prior ? 'lost' : previousEver ? 'released' : 'none' };
+    }
+    catch (error) {
+        db.exec('ROLLBACK');
+        throw error;
+    }
+}
+function toRecord(row) {
+    return {
+        sessionId: String(row.session_id),
+        driver: String(row.driver),
+        cwd: String(row.cwd),
+        createdAt: String(row.created_at),
+        metadata: JSON.parse(String(row.metadata_json)),
+    };
+}

package/dist/agent-runtime/session/ports.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Ports owned by the session application layer. Each interface is as narrow as
+ * its use case: drivers move provider work, the journal persists committed
+ * events, the clock and ids make timing and identity deterministic in tests.
+ * Implementations live in drivers/, journal/ and testing/; the composition root
+ * (index.ts) wires them.
+ */
+import type { SessionEvent, SessionEventEnvelope, ToolActivity } from './domain/events.js';
+import type { SessionSnapshot } from './domain/snapshot.js';
+import type { Attachment, DriverDescriptor, OutputChannel, SessionPolicy, SubagentKind, SubagentPhase } from './domain/types.js';
+import type { ReportedUsage, UsageBaseline } from './domain/usage.js';
+export interface DriverOpenSpec {
+    sessionId: string;
+    /** Increments every time the session gets a new provider process. */
+    generation: number;
+    cwd: string;
+    model: string;
+    effort: string | null;
+    systemPrompt: string | null;
+    policy: SessionPolicy;
+    /** Provider session to resume (Claude session id, Codex thread id), if any. */
+    providerSessionRef: string | null;
+}
+export interface DriverInput {
+    inputId: string;
+    text: string;
+    attachments?: Attachment[];
+    delivery: 'queue' | 'steer';
+    /** Set by the application for policy-driven turns (e.g. collecting settled sub-agents). */
+    origin?: 'user' | 'system';
+}
+export type CloseReason = 'idle' | 'stalled' | 'limit' | 'user_stop' | 'host_request' | 'config_change' | 'evicted' | 'shutdown' | 'session_closed';
+/**
+ * Normalized, uncommitted facts a driver observed. Drivers never assign turn or
+ * session sequence numbers; the application turns these into journaled events.
+ */
+export type DriverEvent = {
+    kind: 'process.started';
+    pid?: number;
+    version?: string;
+} | {
+    kind: 'process.exited';
+    exitCode: number | null;
+    signal: string | null;
+} | {
+    kind: 'provider.ref';
+    providerSessionRef: string;
+} | {
+    kind: 'input.receipt';
+    inputId: string;
+    state: 'queued' | 'started' | 'completed' | 'rejected';
+    reason?: string;
+}
+/** `continuation` = the provider started a turn on its own (e.g. after a background sub-agent finished). */
+ | {
+    kind: 'turn.started';
+    trigger: 'input' | 'continuation';
+    inputIds: string[];
+} | {
+    kind: 'turn.output';
+    channel: OutputChannel;
+    delta: string;
+} | ({
+    kind: 'turn.tool';
+} & ToolActivity) | {
+    kind: 'turn.completed';
+    status: 'completed' | 'failed' | 'stopped';
+    text: string;
+    error?: string;
+    usage: ReportedUsage;
+} | {
+    kind: 'subagent.started';
+    subagentId: string;
+    parentId: string | null;
+    agentKind: SubagentKind;
+    agentType?: string;
+    description: string;
+    prompt?: string;
+} | {
+    kind: 'subagent.phase';
+    subagentId: string;
+    phase: SubagentPhase;
+    reason?: string;
+} | {
+    kind: 'subagent.output';
+    subagentId: string;
+    channel: 'text' | 'tool';
+    delta?: string;
+    tool?: ToolActivity;
+}
+/** Cumulative per-sub-agent usage as reported (the application derives deltas when needed). */
+ | {
+    kind: 'subagent.usage';
+    subagentId: string;
+    usage: ReportedUsage;
+    toolUses?: number;
+    durationMs?: number;
+} | {
+    kind: 'subagent.result';
+    subagentId: string;
+    summary: string;
+}
+/** The provider's authoritative list of live sub-agent ids, when it reports one. */
+ | {
+    kind: 'roster';
+    liveSubagentIds: string[];
+} | {
+    kind: 'diagnostic';
+    level: 'info' | 'warning';
+    code: string;
+    message: string;
+};
+export type DriverEventSink = (event: DriverEvent) => void;
+export interface DriverSession {
+    /** Write input to the provider. Receipts arrive as `input.receipt` events. */
+    send(input: DriverInput): Promise<void>;
+    /** Stop the running turn only. The driver reports `turn.completed` with status `stopped`. */
+    interrupt(): Promise<void>;
+    /**
+     * Stop the given sub-agents (all when omitted). Resolves with the ids the
+     * driver could stop selectively; `'process'` means it had to end the process.
+     */
+    stopSubagents(subagentIds?: string[]): Promise<string[] | 'process'>;
+    /** Idempotent. Resolves after the process tree is gone; no events after that. */
+    close(reason: CloseReason): Promise<void>;
+}
+export interface DriverFactory {
+    readonly descriptor: DriverDescriptor;
+    open(spec: DriverOpenSpec, sink: DriverEventSink): Promise<DriverSession>;
+}
+export interface DriverCatalog {
+    get(driverId: string): DriverFactory | undefined;
+    descriptors(): DriverDescriptor[];
+}
+export interface SessionRecord {
+    sessionId: string;
+    driver: string;
+    cwd: string;
+    createdAt: string;
+    metadata: Record<string, unknown>;
+}
+export interface SessionSummary {
+    sessionId: string;
+    driver: string;
+    model: string;
+    status: 'open' | 'closed';
+    phase: SessionSnapshot['phase'];
+    lastSeq: number;
+    createdAt: string;
+    metadata: Record<string, unknown>;
+}
+export interface AppendOptions {
+    /** Persist the provider's cumulative totals in the same transaction as the events. */
+    baseline?: {
+        providerRef: string;
+        value: UsageBaseline;
+    };
+}
+/**
+ * Durable, append-only event store for one scope. All methods are synchronous
+ * (node:sqlite) and every append is one transaction that assigns gap-free
+ * sequence numbers. It validates nothing about meaning: the application folds
+ * events before appending them.
+ */
+export interface SessionJournal {
+    createSession(record: SessionRecord): void;
+    getSession(sessionId: string): SessionRecord | null;
+    /** Events arrive stamped (`at`) and already validated by the application's fold. */
+    append(sessionId: string, events: SessionEvent[], options?: AppendOptions): SessionEventEnvelope[];
+    read(sessionId: string, afterSeq: number, limit: number): {
+        events: SessionEventEnvelope[];
+        hasMore: boolean;
+    };
+    /** Latest snapshot (folded and cached by the implementation). */
+    snapshot(sessionId: string): SessionSnapshot | null;
+    list(filter: 'open' | 'closed' | 'all'): SessionSummary[];
+    baseline(providerRef: string): UsageBaseline | null;
+}
+export interface TimerHandle {
+    cancel(): void;
+}
+export interface Clock {
+    now(): number;
+    /** ISO-8601 time for event stamps. */
+    iso(): string;
+    after(ms: number, callback: () => void): TimerHandle;
+}
+export interface Ids {
+    session(): string;
+    turn(): string;
+    input(): string;
+}

package/dist/agent-runtime/session/ports.js

@@ -0,0 +1 @@
+export {};

package/dist/agent-runtime/session/testing/driver-conformance.d.ts

@@ -0,0 +1,21 @@
+import type { DriverFactory } from '../ports.js';
+/**
+ * Shared behavioural contract for every session driver (Liskov substitution:
+ * the application must not care which provider it talks to). Framework-free:
+ * each check throws on failure, so any test runner can execute it.
+ */
+export interface ConformanceHarness {
+    /** A fresh factory whose provider answers one simple prompt with text and ends the turn. */
+    factory(): DriverFactory;
+    /** Let the provider progress until it waits for input (e.g. a replay's idle point). */
+    settle(factory: DriverFactory): Promise<void>;
+    /** Model to open sessions with. */
+    model: string;
+    /** Sub-agent policy the scripted turn was recorded with. */
+    subagents: 'enabled' | 'disabled';
+}
+export interface ConformanceCheck {
+    name: string;
+    run(harness: ConformanceHarness): Promise<void>;
+}
+export declare const DRIVER_CONFORMANCE: readonly ConformanceCheck[];

package/dist/agent-runtime/session/testing/driver-conformance.js

@@ -0,0 +1,97 @@
+import { SessionService } from '../application/session-service.js';
+import { validateDescriptor } from '../domain/descriptor.js';
+import { resolvePolicy } from '../domain/policy.js';
+import { FakeClock, SequentialIds } from './fake-clock.js';
+import { MemoryJournal } from './memory-journal.js';
+import { catalogOf } from './scripted-driver.js';
+function assert(condition, message) {
+    if (!condition)
+        throw new Error(`Driver conformance: ${message}`);
+}
+async function oneTurn(harness) {
+    const factory = harness.factory();
+    const journal = new MemoryJournal();
+    const service = new SessionService({ journal, drivers: catalogOf(factory), clock: new FakeClock(), ids: new SequentialIds() });
+    const { sessionId } = await service.open({ driver: factory.descriptor.id, model: harness.model, cwd: process.cwd(), policy: { subagents: harness.subagents } });
+    await service.send(sessionId, { inputId: 'conformance-1', text: 'Reply briefly.', delivery: 'queue' });
+    await harness.settle(factory);
+    const events = () => journal.events(sessionId).map((envelope) => envelope.event);
+    return { factory, journal, service, sessionId, events };
+}
+export const DRIVER_CONFORMANCE = Object.freeze([
+    {
+        name: 'declares a valid, coherent descriptor',
+        async run(harness) {
+            validateDescriptor(harness.factory().descriptor);
+        },
+    },
+    {
+        name: 'refuses policies it cannot enforce instead of ignoring them',
+        async run(harness) {
+            const descriptor = harness.factory().descriptor;
+            const caps = descriptor.capabilities;
+            const refuses = (input) => {
+                try {
+                    resolvePolicy(input, descriptor);
+                    return false;
+                }
+                catch (error) {
+                    return error.code === 'policy_unenforceable';
+                }
+            };
+            if (caps.subagents === 'supported')
+                assert(refuses({ subagents: 'disabled' }) === !caps.subagentDisable, 'sub-agent disabling must match subagentDisable');
+            assert(refuses({ subagents: 'disabled', tools: { mode: 'read-only' } }) === !caps.toolFiltering, 'tool filtering must match toolFiltering');
+        },
+    },
+    {
+        name: 'runs one user turn with ordered receipts and a terminal outcome',
+        async run(harness) {
+            const { events, service, sessionId } = await oneTurn(harness);
+            const list = events();
+            const types = list.map((event) => event.type);
+            const index = (predicate) => list.findIndex(predicate);
+            const accepted = index((event) => event.type === 'input.accepted');
+            const started = index((event) => event.type === 'input.state' && event.state === 'started');
+            const turnStarted = index((event) => event.type === 'turn.started');
+            const turnDone = index((event) => event.type === 'turn.completed');
+            assert(types.includes('session.process'), 'the provider process start is recorded');
+            assert(accepted >= 0 && started > accepted, 'the input is accepted, then started');
+            assert(turnStarted >= 0 && turnDone > turnStarted, 'the turn starts and completes');
+            const turn = list[turnStarted];
+            assert(turn.origin === 'user' && turn.inputIds.includes('conformance-1'), 'the turn is a user turn bound to its input');
+            const done = list[turnDone];
+            assert(done.status === 'completed' && done.text.trim().length > 0, 'the turn completes with text');
+            const snapshot = service.snapshot(sessionId);
+            assert(snapshot.inputs['conformance-1']?.state === 'completed', 'the input completes with its turn');
+            assert(snapshot.openTurn === null && snapshot.phase === 'idle', 'the session is idle after a turn without sub-agents');
+        },
+    },
+    {
+        name: 'reports usage according to its declared semantics',
+        async run(harness) {
+            const { events, factory } = await oneTurn(harness);
+            const done = events().find((event) => event.type === 'turn.completed');
+            assert(done, 'a turn completed');
+            const usage = factory.descriptor.capabilities.usage;
+            if (usage.costUsd === 'none')
+                assert(done.usage.costUsd === null || done.usage.costEstimated, 'a driver without billed cost never reports billed USD');
+            if (usage.tokens === 'none')
+                assert(done.usage.inputTokens === null && done.usage.outputTokens === null, 'a driver without tokens reports none');
+            for (const value of [done.usage.inputTokens, done.usage.outputTokens, done.usage.costUsd])
+                assert(value === null || (Number.isFinite(value) && value >= 0), 'usage values are null or non-negative');
+        },
+    },
+    {
+        name: 'closes idempotently and emits nothing afterwards',
+        async run(harness) {
+            const { service, sessionId, journal, factory } = await oneTurn(harness);
+            await service.close(sessionId, 'conformance');
+            await service.close(sessionId, 'conformance');
+            const count = journal.events(sessionId).length;
+            await harness.settle(factory);
+            assert(journal.events(sessionId).length === count, 'no events after close');
+            assert(service.snapshot(sessionId).status === 'closed', 'the session is closed');
+        },
+    },
+]);

package/dist/agent-runtime/session/testing/fake-clock.d.ts

@@ -0,0 +1,20 @@
+import type { Clock, Ids, TimerHandle } from '../ports.js';
+/** Deterministic clock: time only moves through `advance`. */
+export declare class FakeClock implements Clock {
+    private current;
+    private seq;
+    private readonly timers;
+    constructor(start?: number);
+    now(): number;
+    iso(): string;
+    after(ms: number, callback: () => void): TimerHandle;
+    /** Move time forward, firing due timers in order (timers armed by callbacks included). */
+    advance(ms: number): void;
+    pendingTimers(): number;
+}
+export declare class SequentialIds implements Ids {
+    private counters;
+    session(): string;
+    turn(): string;
+    input(): string;
+}

package/dist/agent-runtime/session/testing/fake-clock.js

@@ -0,0 +1,34 @@
+/** Deterministic clock: time only moves through `advance`. */
+export class FakeClock {
+    current;
+    seq = 0;
+    timers = new Map();
+    constructor(start = Date.UTC(2026, 9, 7, 10, 0, 0)) { this.current = start; }
+    now() { return this.current; }
+    iso() { return new Date(this.current).toISOString(); }
+    after(ms, callback) {
+        const id = ++this.seq;
+        this.timers.set(id, { at: this.current + Math.max(0, ms), callback });
+        return { cancel: () => { this.timers.delete(id); } };
+    }
+    /** Move time forward, firing due timers in order (timers armed by callbacks included). */
+    advance(ms) {
+        const target = this.current + ms;
+        for (;;) {
+            const due = [...this.timers.entries()].filter(([, timer]) => timer.at <= target).sort((a, b) => a[1].at - b[1].at || a[0] - b[0])[0];
+            if (!due)
+                break;
+            this.timers.delete(due[0]);
+            this.current = Math.max(this.current, due[1].at);
+            due[1].callback();
+        }
+        this.current = target;
+    }
+    pendingTimers() { return this.timers.size; }
+}
+export class SequentialIds {
+    counters = { session: 0, turn: 0, input: 0 };
+    session() { return `session-${++this.counters.session}`; }
+    turn() { return `turn-${++this.counters.turn}`; }
+    input() { return `input-${++this.counters.input}`; }
+}