specrails-core 6.4.0 → 6.6.0

package/dist/agent-runtime/session/host/protocol.d.ts

@@ -0,0 +1,18 @@
+import { type ValidateFunction } from 'ajv/dist/2020.js';
+/** Protocol versions this host speaks (docs/agent-sessions/protocol.md). */
+export declare const SESSION_PROTOCOL_VERSIONS: readonly number[];
+/** Longest accepted request line. */
+export declare const MAX_FRAME_BYTES: number;
+type Schema = Record<string, unknown>;
+/** Closed parameter schemas, one per method. */
+export declare const METHOD_SCHEMAS: Readonly<Record<string, Schema>>;
+export type MethodName = keyof typeof METHOD_SCHEMAS;
+/** Compiled validators (lazy, shared). */
+export declare function validatorFor(method: string): ValidateFunction | undefined;
+/** JSON-RPC error codes: standard ones plus one application range for SessionError codes. */
+export declare const RPC_PARSE_ERROR = -32700;
+export declare const RPC_INVALID_REQUEST = -32600;
+export declare const RPC_METHOD_NOT_FOUND = -32601;
+export declare const RPC_INVALID_PARAMS = -32602;
+export declare const RPC_APPLICATION_ERROR = -32000;
+export {};

package/dist/agent-runtime/session/host/protocol.js

@@ -0,0 +1,88 @@
+import { Ajv2020 } from 'ajv/dist/2020.js';
+/** Protocol versions this host speaks (docs/agent-sessions/protocol.md). */
+export const SESSION_PROTOCOL_VERSIONS = Object.freeze([1]);
+/** Longest accepted request line. */
+export const MAX_FRAME_BYTES = 2 * 1024 * 1024;
+const id = { type: 'string', minLength: 1, maxLength: 200 };
+const text = { type: 'string', maxLength: 1024 * 1024 };
+const attachment = { type: 'object', additionalProperties: false, required: ['kind', 'path'], properties: { kind: { enum: ['image', 'file'] }, path: { type: 'string', minLength: 1, maxLength: 4096 }, mimeType: { type: 'string', maxLength: 200 } } };
+const mcpServer = {
+    type: 'object', additionalProperties: false, required: ['name'],
+    properties: {
+        name: { type: 'string', pattern: '^[A-Za-z0-9_.-]{1,64}$' },
+        command: { type: 'string', maxLength: 4096 },
+        args: { type: 'array', maxItems: 64, items: { type: 'string', maxLength: 4096 } },
+        env: { type: 'object', additionalProperties: { type: 'string', maxLength: 16384 } },
+        url: { type: 'string', maxLength: 4096 },
+        headers: { type: 'object', additionalProperties: { type: 'string', maxLength: 16384 } },
+        autoApprove: { type: 'boolean' },
+    },
+};
+const limits = {
+    type: 'object', additionalProperties: false,
+    properties: Object.fromEntries(['idleMs', 'stallMs', 'backgroundMaxMs', 'turnInactivityMs', 'maxSettleHandoffs', 'settleDebounceMs'].map((key) => [key, { type: 'integer', minimum: 0 }])),
+};
+const policy = {
+    type: 'object', additionalProperties: false, required: ['subagents'],
+    properties: {
+        subagents: { enum: ['enabled', 'disabled'] },
+        onSubagentsSettled: { enum: ['provider-native', 'resume-agent', 'notify-only'] },
+        tools: { type: 'object', additionalProperties: false, required: ['mode'], properties: { mode: { enum: ['default', 'read-only', 'none'] }, allow: { type: 'array', maxItems: 200, items: { type: 'string', maxLength: 200 } }, deny: { type: 'array', maxItems: 200, items: { type: 'string', maxLength: 200 } } } },
+        permissions: { enum: ['bypass', 'workspace-write', 'read-only'] },
+        mcp: { type: 'object', additionalProperties: false, properties: { servers: { type: 'array', maxItems: 32, items: mcpServer }, inheritUserScope: { type: 'boolean' } } },
+        limits,
+        subagentRuntime: {
+            oneOf: [
+                { type: 'object', additionalProperties: false, required: ['mode'], properties: { mode: { const: 'native' }, model: { type: 'string', minLength: 1, maxLength: 200 }, effort: { type: 'string', minLength: 1, maxLength: 50 } } },
+                { type: 'object', additionalProperties: false, required: ['mode', 'driver', 'model'], properties: { mode: { const: 'delegated' }, driver: { type: 'string', pattern: '^[a-z0-9][a-z0-9-]{0,63}$' }, model: { type: 'string', minLength: 1, maxLength: 200 }, effort: { type: 'string', minLength: 1, maxLength: 50 }, maxConcurrent: { type: 'integer', minimum: 1, maximum: 16 } } },
+            ],
+        },
+    },
+};
+/** Closed parameter schemas, one per method. */
+export const METHOD_SCHEMAS = Object.freeze({
+    'initialize': { type: 'object', additionalProperties: false, required: ['protocolVersions', 'host'], properties: { protocolVersions: { type: 'array', minItems: 1, maxItems: 16, items: { type: 'integer', minimum: 1 } }, host: { type: 'object', additionalProperties: false, required: ['name', 'version'], properties: { name: { type: 'string', maxLength: 200 }, version: { type: 'string', maxLength: 200 } } }, scope: { type: 'string', maxLength: 128 } } },
+    'session.open': {
+        type: 'object', additionalProperties: false,
+        properties: {
+            sessionId: id,
+            resume: { type: 'object', additionalProperties: false, required: ['sessionId'], properties: { sessionId: id } },
+            driver: { type: 'string', pattern: '^[a-z0-9][a-z0-9._-]{0,63}$' },
+            model: { type: 'string', minLength: 1, maxLength: 200 },
+            effort: { type: 'string', maxLength: 50 },
+            cwd: { type: 'string', minLength: 1, maxLength: 4096 },
+            systemPrompt: text,
+            policy,
+            providerSessionRef: id,
+            metadata: { type: 'object' },
+        },
+        oneOf: [{ required: ['resume'] }, { required: ['driver', 'model', 'cwd', 'policy'] }],
+    },
+    'session.send': { type: 'object', additionalProperties: false, required: ['sessionId', 'input'], properties: { sessionId: id, input: { type: 'object', additionalProperties: false, required: ['inputId', 'text', 'delivery'], properties: { inputId: id, text, attachments: { type: 'array', maxItems: 32, items: attachment }, delivery: { enum: ['queue', 'steer'] } } } } },
+    'session.interrupt': { type: 'object', additionalProperties: false, required: ['sessionId'], properties: { sessionId: id } },
+    'session.stopSubagents': { type: 'object', additionalProperties: false, required: ['sessionId'], properties: { sessionId: id, subagentIds: { type: 'array', maxItems: 500, items: id } } },
+    'session.delegate': { type: 'object', additionalProperties: false, required: ['sessionId', 'description', 'prompt'], properties: { sessionId: id, description: { type: 'string', minLength: 1, maxLength: 200 }, prompt: { type: 'string', minLength: 1, maxLength: 64 * 1024 }, agentType: { type: 'string', minLength: 1, maxLength: 100 }, contextTurns: { type: 'integer', minimum: 0, maximum: 10 } } },
+    'session.waitSubagents': { type: 'object', additionalProperties: false, required: ['sessionId', 'timeoutMs'], properties: { sessionId: id, subagentIds: { type: 'array', maxItems: 500, items: id }, timeoutMs: { type: 'integer', minimum: 0, maximum: 30 * 60_000 } } },
+    'session.update': { type: 'object', additionalProperties: false, required: ['sessionId'], minProperties: 2, properties: { sessionId: id, model: { type: 'string', minLength: 1, maxLength: 200 }, effort: { type: 'string', maxLength: 50 }, systemPrompt: text, policy } },
+    'session.close': { type: 'object', additionalProperties: false, required: ['sessionId', 'reason'], properties: { sessionId: id, reason: { type: 'string', minLength: 1, maxLength: 200 } } },
+    'session.snapshot': { type: 'object', additionalProperties: false, required: ['sessionId'], properties: { sessionId: id } },
+    'session.events': { type: 'object', additionalProperties: false, required: ['sessionId', 'afterSeq'], properties: { sessionId: id, afterSeq: { type: 'integer', minimum: 0 }, limit: { type: 'integer', minimum: 1, maximum: 5000 } } },
+    'session.list': { type: 'object', additionalProperties: false, properties: { state: { enum: ['open', 'closed', 'all'] } } },
+    'host.ping': { type: 'object', additionalProperties: false },
+    'host.shutdown': { type: 'object', additionalProperties: false, properties: { graceMs: { type: 'integer', minimum: 0, maximum: 120000 } } },
+});
+let validators = null;
+/** Compiled validators (lazy, shared). */
+export function validatorFor(method) {
+    if (!validators) {
+        const ajv = new Ajv2020({ allErrors: false, strict: false, validateFormats: false, ownProperties: true });
+        validators = new Map(Object.entries(METHOD_SCHEMAS).map(([name, schema]) => [name, ajv.compile(schema)]));
+    }
+    return validators.get(method);
+}
+/** JSON-RPC error codes: standard ones plus one application range for SessionError codes. */
+export const RPC_PARSE_ERROR = -32700;
+export const RPC_INVALID_REQUEST = -32600;
+export const RPC_METHOD_NOT_FOUND = -32601;
+export const RPC_INVALID_PARAMS = -32602;
+export const RPC_APPLICATION_ERROR = -32000;

package/dist/agent-runtime/session/host/server.d.ts

@@ -0,0 +1,57 @@
+import type { SessionService } from '../application/session-service.js';
+type Json = Record<string, unknown>;
+/** What the composition root hands the host. */
+export interface HostRuntime {
+    service: SessionService;
+    scope: string;
+    identity: Json;
+    /** Retire providers, record interruptions and release the journal. */
+    close(): Promise<void>;
+}
+export interface HostIo {
+    input: NodeJS.ReadableStream;
+    output: NodeJS.WritableStream;
+}
+export interface SessionHostOptions {
+    /** Queued notifications before the busiest session is marked lagged. */
+    notificationQueueLimit?: number;
+    /** Default grace for provider shutdown. */
+    shutdownGraceMs?: number;
+}
+/**
+ * JSON-RPC 2.0 server over NDJSON stdio (session protocol v1).
+ * One handler per method (closed table); each validates its params with a
+ * closed schema and calls exactly one application use case.
+ */
+export declare class SessionHost {
+    private readonly runtime;
+    private readonly io;
+    private readonly options;
+    private initialized;
+    private stopping;
+    private readonly lastSent;
+    private readonly notifications;
+    private readonly responses;
+    private writing;
+    private readonly handlers;
+    private unsubscribe;
+    private finished;
+    readonly done: Promise<void>;
+    constructor(runtime: HostRuntime, io: HostIo, options?: SessionHostOptions);
+    /** Serve until input ends or `host.shutdown`; resolves after a clean stop. */
+    start(): Promise<void>;
+    /** Another host took the journal: tell the client and stop without further writes. */
+    leaseLost(): void;
+    stop(): Promise<void>;
+    private handleLine;
+    private initialize;
+    private publish;
+    /** Keep the live feed bounded: drop the busiest session's queued events after a lag notice. */
+    private shed;
+    private respondError;
+    private queueResponse;
+    /** Responses first (never dropped), then notifications; honours stream backpressure. */
+    private drain;
+    private flush;
+}
+export {};

package/dist/agent-runtime/session/host/server.js

@@ -0,0 +1,229 @@
+import { StringDecoder } from 'node:string_decoder';
+import { SessionError, isSessionError } from '../domain/errors.js';
+import { MAX_FRAME_BYTES, RPC_APPLICATION_ERROR, RPC_INVALID_PARAMS, RPC_INVALID_REQUEST, RPC_METHOD_NOT_FOUND, RPC_PARSE_ERROR, SESSION_PROTOCOL_VERSIONS, validatorFor, } from './protocol.js';
+/**
+ * JSON-RPC 2.0 server over NDJSON stdio (session protocol v1).
+ * One handler per method (closed table); each validates its params with a
+ * closed schema and calls exactly one application use case.
+ */
+export class SessionHost {
+    runtime;
+    io;
+    options;
+    initialized = false;
+    stopping = null;
+    lastSent = new Map();
+    notifications = [];
+    responses = [];
+    writing = false;
+    handlers;
+    unsubscribe = null;
+    finished;
+    done = new Promise((resolve) => { this.finished = resolve; });
+    constructor(runtime, io, options = {}) {
+        this.runtime = runtime;
+        this.io = io;
+        this.options = options;
+        const service = runtime.service;
+        this.handlers = Object.freeze({
+            'initialize': async (params) => this.initialize(params),
+            'session.open': async (params) => service.open(params),
+            'session.send': async (params) => service.send(String(params.sessionId), params.input),
+            'session.interrupt': async (params) => service.interrupt(String(params.sessionId)),
+            'session.delegate': async (params) => service.delegate(String(params.sessionId), {
+                description: String(params.description),
+                prompt: String(params.prompt),
+                ...(typeof params.agentType === 'string' ? { agentType: params.agentType } : {}),
+                ...(typeof params.contextTurns === 'number' ? { contextTurns: params.contextTurns } : {}),
+            }),
+            'session.waitSubagents': async (params) => service.waitSubagents(String(params.sessionId), Array.isArray(params.subagentIds) ? params.subagentIds.map(String) : undefined, Number(params.timeoutMs)),
+            'session.stopSubagents': async (params) => service.stopSubagents(String(params.sessionId), params.subagentIds),
+            'session.update': async (params) => { const { sessionId, ...changes } = params; return service.update(String(sessionId), changes); },
+            'session.close': async (params) => { await service.close(String(params.sessionId), String(params.reason)); return {}; },
+            'session.snapshot': async (params) => service.snapshot(String(params.sessionId)),
+            'session.events': async (params) => service.events(String(params.sessionId), Number(params.afterSeq), params.limit === undefined ? undefined : Number(params.limit)),
+            'session.list': async (params) => ({ sessions: service.list(params.state ?? 'open') }),
+            'host.ping': async () => ({ ...service.stats(), uptimeMs: Math.round(process.uptime() * 1000) }),
+            'host.shutdown': async () => { setImmediate(() => void this.stop()); return {}; },
+        });
+    }
+    /** Serve until input ends or `host.shutdown`; resolves after a clean stop. */
+    start() {
+        this.unsubscribe = this.runtime.service.subscribe((envelopes) => this.publish(envelopes));
+        const decoder = new StringDecoder('utf8');
+        let pending = '';
+        this.io.input.on('data', (chunk) => {
+            pending += typeof chunk === 'string' ? chunk : decoder.write(chunk);
+            for (;;) {
+                const newline = pending.indexOf('\n');
+                if (newline < 0)
+                    break;
+                const line = pending.slice(0, newline).replace(/\r$/, '');
+                pending = pending.slice(newline + 1);
+                if (line.trim())
+                    void this.handleLine(line);
+            }
+            if (Buffer.byteLength(pending) > MAX_FRAME_BYTES) {
+                pending = '';
+                this.respondError(null, RPC_INVALID_REQUEST, `Request exceeds ${MAX_FRAME_BYTES} bytes`, { code: 'payload_too_large', retryable: false });
+            }
+        });
+        this.io.input.on('end', () => void this.stop());
+        return this.done;
+    }
+    /** Another host took the journal: tell the client and stop without further writes. */
+    leaseLost() {
+        this.queueResponse(JSON.stringify({ jsonrpc: '2.0', method: 'host.leaseLost', params: {} }));
+        void this.stop();
+    }
+    stop() {
+        this.stopping ??= (async () => {
+            this.unsubscribe?.();
+            try {
+                await this.runtime.close();
+            }
+            catch (error) {
+                process.stderr.write(`session host: shutdown failed: ${error.message}\n`);
+            }
+            await this.flush();
+            this.finished();
+        })();
+        return this.stopping;
+    }
+    // ── requests ──────────────────────────────────────────────────────────────
+    async handleLine(line) {
+        if (Buffer.byteLength(line) > MAX_FRAME_BYTES) {
+            this.respondError(null, RPC_INVALID_REQUEST, `Request exceeds ${MAX_FRAME_BYTES} bytes`, { code: 'payload_too_large', retryable: false });
+            return;
+        }
+        let request;
+        try {
+            request = JSON.parse(line);
+        }
+        catch {
+            this.respondError(null, RPC_PARSE_ERROR, 'Invalid JSON', { code: 'invalid_params', retryable: false });
+            return;
+        }
+        const id = typeof request.id === 'string' || typeof request.id === 'number' ? request.id : null;
+        const method = request.method;
+        if (typeof method !== 'string') {
+            this.respondError(id, RPC_INVALID_REQUEST, 'Missing method', { code: 'invalid_params', retryable: false });
+            return;
+        }
+        if (id === null)
+            return; // notifications from the client carry no work in protocol v1
+        const handler = Object.hasOwn(this.handlers, method) ? this.handlers[method] : undefined;
+        if (!handler) {
+            this.respondError(id, RPC_METHOD_NOT_FOUND, `Unknown method ${method}`, { code: 'invalid_params', retryable: false });
+            return;
+        }
+        if (this.stopping && method !== 'host.ping') {
+            this.respondError(id, RPC_APPLICATION_ERROR, 'The session host is shutting down', { code: 'busy', retryable: true });
+            return;
+        }
+        if (!this.initialized && method !== 'initialize' && method !== 'host.ping') {
+            this.respondError(id, RPC_APPLICATION_ERROR, 'Call initialize first', { code: 'not_initialized', retryable: false });
+            return;
+        }
+        const params = (request.params ?? {});
+        const validate = validatorFor(method);
+        if (validate && !validate(params)) {
+            const first = validate.errors?.[0];
+            this.respondError(id, RPC_INVALID_PARAMS, `Invalid params${first ? ` at ${first.instancePath || '/'}: ${first.message ?? ''}` : ''}`, { code: 'invalid_params', retryable: false, detail: { path: first?.instancePath ?? '' } });
+            return;
+        }
+        try {
+            const result = await handler(params);
+            this.queueResponse(JSON.stringify({ jsonrpc: '2.0', id, result: result ?? {} }));
+        }
+        catch (error) {
+            if (isSessionError(error)) {
+                this.respondError(id, error.code === 'invalid_params' ? RPC_INVALID_PARAMS : RPC_APPLICATION_ERROR, error.message, { code: error.code, retryable: error.retryable, ...(error.detail ? { detail: error.detail } : {}) });
+            }
+            else {
+                process.stderr.write(`session host: ${method} failed: ${error.stack ?? String(error)}\n`);
+                this.respondError(id, RPC_APPLICATION_ERROR, error.message || 'Internal error', { code: 'internal', retryable: true });
+            }
+        }
+    }
+    initialize(params) {
+        const requested = params.protocolVersions.filter((version) => SESSION_PROTOCOL_VERSIONS.includes(version));
+        if (requested.length === 0) {
+            throw new SessionError('protocol_mismatch', `No common session protocol version; this host supports ${SESSION_PROTOCOL_VERSIONS.join(', ')}`, { supported: [...SESSION_PROTOCOL_VERSIONS] });
+        }
+        if (params.scope !== undefined && params.scope !== this.runtime.scope) {
+            throw new SessionError('invalid_params', `This host serves scope "${this.runtime.scope}", not "${String(params.scope)}"`, { path: '/scope' });
+        }
+        this.initialized = true;
+        return {
+            protocolVersion: Math.max(...requested),
+            scope: this.runtime.scope,
+            runtime: this.runtime.identity,
+            // `delegation`: session.delegate / session.waitSubagents and subagentRuntime.mode 'delegated'.
+            capabilities: { sessions: 1, delegation: 1 },
+            drivers: this.runtime.service.drivers(),
+        };
+    }
+    // ── output ────────────────────────────────────────────────────────────────
+    publish(envelopes) {
+        if (!this.initialized)
+            return;
+        for (const envelope of envelopes) {
+            this.notifications.push({
+                sessionId: envelope.sessionId,
+                seq: envelope.seq,
+                line: JSON.stringify({ jsonrpc: '2.0', method: 'session.event', params: { sessionId: envelope.sessionId, seq: envelope.seq, event: envelope.event } }),
+            });
+        }
+        this.shed();
+        void this.drain();
+    }
+    /** Keep the live feed bounded: drop the busiest session's queued events after a lag notice. */
+    shed() {
+        const limit = this.options.notificationQueueLimit ?? 5_000;
+        while (this.notifications.length > limit) {
+            const counts = new Map();
+            for (const item of this.notifications)
+                counts.set(item.sessionId, (counts.get(item.sessionId) ?? 0) + 1);
+            const busiest = [...counts.entries()].sort((a, b) => b[1] - a[1])[0][0];
+            const kept = this.notifications.filter((item) => item.sessionId !== busiest);
+            this.notifications.length = 0;
+            this.notifications.push(...kept);
+            this.queueResponse(JSON.stringify({ jsonrpc: '2.0', method: 'session.lagged', params: { sessionId: busiest, deliveredSeq: this.lastSent.get(busiest) ?? 0 } }));
+        }
+    }
+    respondError(id, code, message, data) {
+        this.queueResponse(JSON.stringify({ jsonrpc: '2.0', id, error: { code, message, data } }));
+    }
+    queueResponse(line) {
+        this.responses.push(line);
+        void this.drain();
+    }
+    /** Responses first (never dropped), then notifications; honours stream backpressure. */
+    async drain() {
+        if (this.writing)
+            return;
+        this.writing = true;
+        try {
+            for (;;) {
+                const response = this.responses.shift();
+                const notification = response === undefined ? this.notifications.shift() : undefined;
+                const line = response ?? notification?.line;
+                if (line === undefined)
+                    break;
+                if (notification)
+                    this.lastSent.set(notification.sessionId, notification.seq);
+                if (!this.io.output.write(`${line}\n`))
+                    await new Promise((resolve) => this.io.output.once('drain', () => resolve()));
+            }
+        }
+        finally {
+            this.writing = false;
+        }
+    }
+    async flush() {
+        await this.drain();
+        while (this.responses.length > 0 || this.notifications.length > 0)
+            await this.drain();
+    }
+}

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

@@ -0,0 +1,45 @@
+import { GLOBAL_SESSION_SCOPE } from '../../shared/specrails-home.js';
+import { SessionService } from './application/session-service.js';
+import type { RateCard } from './domain/usage.js';
+import { type DriverRegistryOptions } from './drivers/registry.js';
+import { SqliteSessionJournal } from './journal/sqlite-journal.js';
+import type { Clock, DriverCatalog, Ids } from './ports.js';
+export { SessionError, isSessionError, type SessionErrorCode } from './domain/errors.js';
+export { SESSION_EVENT_TYPES, type SessionEvent, type SessionEventBody, type SessionEventEnvelope, type SessionEventType, type ToolActivity } from './domain/events.js';
+export type { SessionSnapshot, SubagentNode, TurnRecord, InputRecord, OpenTurn } from './domain/snapshot.js';
+export type { DriverCapabilities, DriverDescriptor, SessionLimits, SessionPolicy, Usage, McpServerSpec, Attachment } from './domain/types.js';
+export type { SessionPolicyInput } from './domain/policy.js';
+export { DEFAULT_LIMITS } from './domain/policy.js';
+export { SessionService, type OpenParams, type SendParams } from './application/session-service.js';
+export { createDriverRegistry, DriverRegistry, type DriverRegistryOptions } from './drivers/registry.js';
+export type { DriverCatalog, DriverFactory, DriverSession, DriverEvent, SessionJournal } from './ports.js';
+export { GLOBAL_SESSION_SCOPE };
+export declare const systemClock: Clock;
+export declare const randomIds: Ids;
+export interface SessionRuntimeOptions {
+    /** Project key (slug) or `global`. */
+    scope?: string;
+    /** Base home for `~/.specrails` (defaults honour SPECRAILS_REGISTRY_HOME). */
+    home?: string;
+    /** Lease owner label; defaults to `host-<pid>`. */
+    owner?: string;
+    drivers?: DriverCatalog | DriverRegistryOptions;
+    clock?: Clock;
+    ids?: Ids;
+    rateCard?: (driver: string, model: string) => RateCard | null;
+    maxResident?: number;
+    /** Called when another host takes over the journal; the runtime has stopped writing. */
+    onLeaseLost?: () => void;
+    /** Explicit journal file (tests). */
+    journalFile?: string;
+}
+export interface SessionRuntime {
+    scope: string;
+    service: SessionService;
+    journal: SqliteSessionJournal;
+    /** Sessions whose running work was recorded as interrupted at startup. */
+    recovered: string[];
+    /** Retire providers, record interruptions, release the lease. Idempotent. */
+    close(): Promise<void>;
+}
+export declare function createSessionRuntime(options?: SessionRuntimeOptions): Promise<SessionRuntime>;

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

@@ -0,0 +1,74 @@
+/**
+ * Agent session runtime — public API and composition root.
+ *
+ * `createSessionRuntime` is the only place where the journal, drivers and the
+ * application are wired together. Hosts talk to a running runtime over the
+ * session protocol (`specrails-core runtime host --stdio`); embedding it
+ * in-process is supported for tests and tools.
+ */
+import { randomUUID } from 'node:crypto';
+import { GLOBAL_SESSION_SCOPE } from '../../shared/specrails-home.js';
+import { SessionService } from './application/session-service.js';
+import { createDriverRegistry } from './drivers/registry.js';
+import { SqliteSessionJournal } from './journal/sqlite-journal.js';
+export { SessionError, isSessionError } from './domain/errors.js';
+export { SESSION_EVENT_TYPES } from './domain/events.js';
+export { DEFAULT_LIMITS } from './domain/policy.js';
+export { SessionService } from './application/session-service.js';
+export { createDriverRegistry, DriverRegistry } from './drivers/registry.js';
+export { GLOBAL_SESSION_SCOPE };
+export const systemClock = {
+    now: () => Date.now(),
+    iso: () => new Date().toISOString(),
+    after(ms, callback) {
+        const timer = setTimeout(callback, Math.max(0, ms));
+        timer.unref?.();
+        return { cancel: () => clearTimeout(timer) };
+    },
+};
+export const randomIds = {
+    session: () => `ses_${randomUUID()}`,
+    turn: () => `turn_${randomUUID()}`,
+    input: () => `in_${randomUUID()}`,
+};
+function isCatalog(value) {
+    return !!value && typeof value.get === 'function' && typeof value.descriptors === 'function';
+}
+export async function createSessionRuntime(options = {}) {
+    const scope = options.scope ?? GLOBAL_SESSION_SCOPE;
+    let leaseLost = false;
+    const journal = await SqliteSessionJournal.open({
+        scope,
+        owner: options.owner ?? `host-${process.pid}`,
+        ...(options.home ? { home: options.home } : {}),
+        ...(options.journalFile ? { filename: options.journalFile } : {}),
+        onLeaseLost: () => { leaseLost = true; options.onLeaseLost?.(); },
+    });
+    const drivers = isCatalog(options.drivers) ? options.drivers : createDriverRegistry(options.drivers ?? {});
+    const serviceOptions = {
+        journal,
+        drivers,
+        clock: options.clock ?? systemClock,
+        ids: options.ids ?? randomIds,
+        ...(options.rateCard ? { rateCard: options.rateCard } : {}),
+        ...(options.maxResident !== undefined ? { maxResident: options.maxResident } : {}),
+    };
+    const service = new SessionService(serviceOptions);
+    // A predecessor that died without releasing the lease lost its host; otherwise it restarted.
+    const recovered = service.recover(journal.lease.previous === 'lost' ? 'host_lost' : 'restart');
+    let closing = null;
+    return {
+        scope,
+        service,
+        journal,
+        recovered,
+        close() {
+            closing ??= (async () => {
+                if (!leaseLost)
+                    await service.shutdown();
+                journal.close();
+            })();
+            return closing;
+        },
+    };
+}

package/dist/agent-runtime/session/journal/schema.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Ordered, forward-only migrations for the long-lived per-scope journal.
+ * `PRAGMA user_version` equals the number of applied migrations. Never edit or
+ * reorder a shipped entry; append a new one. Unknown future versions are refused.
+ */
+export declare const JOURNAL_MIGRATIONS: readonly string[];
+export declare const JOURNAL_SCHEMA_VERSION: number;

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

@@ -0,0 +1,44 @@
+/**
+ * Ordered, forward-only migrations for the long-lived per-scope journal.
+ * `PRAGMA user_version` equals the number of applied migrations. Never edit or
+ * reorder a shipped entry; append a new one. Unknown future versions are refused.
+ */
+export const JOURNAL_MIGRATIONS = Object.freeze([
+    // 1 — sessions, events, usage baselines, host lease
+    `
+  CREATE TABLE sessions (
+    session_id TEXT PRIMARY KEY,
+    driver TEXT NOT NULL,
+    cwd TEXT NOT NULL,
+    metadata_json TEXT NOT NULL,
+    status TEXT NOT NULL CHECK(status IN ('open','closed')),
+    last_seq INTEGER NOT NULL DEFAULT 0,
+    snapshot_json TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL);
+  CREATE TABLE events (
+    session_id TEXT NOT NULL REFERENCES sessions(session_id) ON DELETE CASCADE,
+    seq INTEGER NOT NULL,
+    type TEXT NOT NULL,
+    at TEXT NOT NULL,
+    payload_json TEXT NOT NULL,
+    PRIMARY KEY(session_id, seq)) WITHOUT ROWID;
+  CREATE TABLE usage_baselines (
+    provider_ref TEXT PRIMARY KEY,
+    baseline_json TEXT NOT NULL,
+    updated_at TEXT NOT NULL);
+  CREATE TABLE host_lease (
+    singleton INTEGER PRIMARY KEY CHECK(singleton = 1),
+    owner TEXT NOT NULL,
+    epoch INTEGER NOT NULL,
+    acquired_at TEXT NOT NULL,
+    heartbeat_at TEXT NOT NULL,
+    expires_at INTEGER NOT NULL);
+  CREATE TABLE lease_epoch (
+    singleton INTEGER PRIMARY KEY CHECK(singleton = 1),
+    epoch INTEGER NOT NULL);
+  INSERT INTO lease_epoch(singleton, epoch) VALUES (1, 0);
+  CREATE INDEX sessions_status ON sessions(status, updated_at);
+  `,
+]);
+export const JOURNAL_SCHEMA_VERSION = JOURNAL_MIGRATIONS.length;

package/dist/agent-runtime/session/journal/sqlite-journal.d.ts

@@ -0,0 +1,70 @@
+import { SessionError } from '../domain/errors.js';
+import type { SessionEvent, SessionEventEnvelope } from '../domain/events.js';
+import { type SessionSnapshot } from '../domain/snapshot.js';
+import type { UsageBaseline } from '../domain/usage.js';
+import type { AppendOptions, SessionJournal, SessionRecord, SessionSummary } from '../ports.js';
+export declare const JOURNAL_LEASE_MS = 60000;
+export declare const JOURNAL_HEARTBEAT_MS = 15000;
+export declare const JOURNAL_FILENAME = "sessions.sqlite";
+export interface JournalLease {
+    owner: string;
+    epoch: number;
+    expiresAt: number;
+    /** How the previous owner left: released cleanly, lost (expired), or first ever owner. */
+    previous: 'none' | 'released' | 'lost';
+}
+export interface OpenJournalOptions {
+    scope: string;
+    owner: string;
+    home?: string;
+    /** Explicit database file (tests); defaults to `<sessionsRoot(scope)>/sessions.sqlite`. */
+    filename?: string;
+    now?: () => number;
+    leaseMs?: number;
+    /** Called when the heartbeat cannot renew the lease; the host must stop writing. */
+    onLeaseLost?: (error: SessionError) => void;
+    /** Disable the heartbeat timer (tests drive `renew` explicitly). */
+    heartbeat?: boolean;
+}
+/**
+ * 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 declare class SqliteSessionJournal implements SessionJournal {
+    readonly filename: string;
+    private readonly db;
+    readonly lease: JournalLease;
+    private readonly now;
+    private readonly leaseMs;
+    private readonly cache;
+    private heartbeatTimer;
+    private closed;
+    private constructor();
+    static open(options: OpenJournalOptions): Promise<SqliteSessionJournal>;
+    createSession(record: SessionRecord): void;
+    getSession(sessionId: string): SessionRecord | null;
+    append(sessionId: string, events: SessionEvent[], options?: AppendOptions): SessionEventEnvelope[];
+    read(sessionId: string, afterSeq: number, limit: number): {
+        events: SessionEventEnvelope[];
+        hasMore: boolean;
+    };
+    snapshot(sessionId: string): SessionSnapshot | null;
+    list(filter: 'open' | 'closed' | 'all'): SessionSummary[];
+    baseline(providerRef: string): UsageBaseline | null;
+    /** Remove closed sessions last updated before `olderThan` (epoch ms). Open sessions are never removed. */
+    sweepClosed(olderThan: number): number;
+    /** Extend the lease; throws `journal_locked` when it was lost. */
+    renew(): void;
+    /** Release the lease (clean shutdown) and close the database. Idempotent. */
+    close(): void;
+    checkIntegrity(): void;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private loadSnapshot;
+    /** A fenced write: the lease is asserted inside the same transaction. */
+    private write;
+    private transaction;
+    private assertLease;
+}