specrails-core 6.4.0 → 6.6.0

package/dist/agent-runtime/session/application/session-service.js

@@ -0,0 +1,256 @@
+import { SessionError } from '../domain/errors.js';
+import { resolvePolicy } from '../domain/policy.js';
+import { liveSubagents } from '../domain/snapshot.js';
+import { ActiveSession } from './active-session.js';
+import { DelegationCoordinator } from './delegation.js';
+export const DEFAULT_MAX_RESIDENT = 6;
+/**
+ * Application facade for one scope: the use cases behind every protocol method.
+ * Operations on one session are serialized; different sessions run concurrently.
+ */
+export class SessionService {
+    options;
+    active = new Map();
+    locks = new Map();
+    listeners = new Set();
+    shuttingDown = false;
+    delegation;
+    constructor(options) {
+        this.options = options;
+        this.delegation = new DelegationCoordinator({
+            journal: options.journal,
+            ids: options.ids,
+            parent: (sessionId) => this.session(sessionId),
+            open: (params) => this.open(params),
+            send: (sessionId, input) => this.send(sessionId, input),
+            interrupt: (sessionId) => this.interrupt(sessionId),
+            close: (sessionId, reason) => this.close(sessionId, reason),
+            snapshot: (sessionId) => this.snapshot(sessionId),
+        });
+    }
+    drivers() {
+        return this.options.drivers.descriptors();
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    /**
+     * Mark work a previous host left running as interrupted. Called once at
+     * startup before serving requests; never starts a provider process.
+     */
+    recover(reason = 'restart') {
+        const recovered = [];
+        for (const summary of this.options.journal.list('open')) {
+            const snapshot = this.options.journal.snapshot(summary.sessionId);
+            if (!snapshot || !needsRecovery(snapshot))
+                continue;
+            const factory = this.options.drivers.get(snapshot.driver);
+            if (!factory)
+                continue;
+            new ActiveSession(summary.sessionId, snapshot, this.configFrom(snapshot), this.deps(factory)).recoverAfterHostLoss(reason);
+            recovered.push(summary.sessionId);
+        }
+        // A delegated child cannot outlive the host that ran it: close the orphans.
+        for (const summary of this.options.journal.list('open')) {
+            if (this.options.journal.getSession(summary.sessionId)?.metadata?.delegated !== true)
+                continue;
+            const envelopes = this.options.journal.append(summary.sessionId, [{ type: 'session.closed', reason: 'delegation_interrupted', at: this.options.clock.iso() }]);
+            this.publish(envelopes);
+        }
+        return recovered;
+    }
+    async open(params) {
+        this.assertRunning();
+        if (params.resume)
+            return this.resume(params.resume.sessionId);
+        const factory = this.options.drivers.get(params.driver);
+        if (!factory)
+            throw new SessionError('driver_unavailable', `Driver "${params.driver}" is not registered`, { driver: params.driver });
+        const policy = resolvePolicy(params.policy, factory.descriptor);
+        const sessionId = params.sessionId ?? this.options.ids.session();
+        if (this.options.journal.getSession(sessionId))
+            throw new SessionError('invalid_params', `Session ${sessionId} already exists; use resume`, { path: 'sessionId' });
+        this.options.journal.createSession({ sessionId, driver: params.driver, cwd: params.cwd, createdAt: this.options.clock.iso(), metadata: { ...(params.metadata ?? {}) } });
+        const envelopes = this.options.journal.append(sessionId, [{
+                type: 'session.opened',
+                driver: params.driver,
+                model: params.model,
+                ...(params.effort ? { effort: params.effort } : {}),
+                ...(params.systemPrompt ? { systemPrompt: params.systemPrompt } : {}),
+                policy,
+                resumed: params.providerSessionRef !== undefined,
+                providerSessionRef: params.providerSessionRef ?? null,
+                at: this.options.clock.iso(),
+            }]);
+        this.publish(envelopes);
+        const session = this.activate(sessionId);
+        return { sessionId, snapshot: session.state };
+    }
+    async send(sessionId, input) {
+        return this.exclusive(sessionId, () => this.session(sessionId).send(input));
+    }
+    async interrupt(sessionId) {
+        return this.exclusive(sessionId, async () => ({ turnId: await this.session(sessionId).interrupt() }));
+    }
+    async stopSubagents(sessionId, subagentIds) {
+        return this.exclusive(sessionId, async () => {
+            const session = this.session(sessionId);
+            const native = subagentIds?.filter((id) => !this.delegation.isDelegated(id));
+            const delegated = await this.delegation.stop(sessionId, subagentIds);
+            const stopped = native?.length === 0 ? [] : await session.stopSubagents(native);
+            return { stopped: [...delegated, ...stopped] };
+        });
+    }
+    /** Launch a sub-agent as a child session (delegated runtime). */
+    async delegate(sessionId, params) {
+        return this.exclusive(sessionId, () => this.delegation.delegate(sessionId, params));
+    }
+    /** Wait for delegated sub-agents; never holds the session lock while waiting. */
+    async waitSubagents(sessionId, subagentIds, timeoutMs) {
+        this.session(sessionId);
+        return this.delegation.wait(sessionId, subagentIds, timeoutMs);
+    }
+    async update(sessionId, changes) {
+        return this.exclusive(sessionId, async () => {
+            const session = this.session(sessionId);
+            const factory = this.requireFactory(session.state.driver);
+            const { policy, ...rest } = changes;
+            const resolved = policy ? { ...rest, policy: resolvePolicy(policy, factory.descriptor) } : rest;
+            return { outcome: await session.update(resolved) };
+        });
+    }
+    async close(sessionId, reason) {
+        await this.exclusive(sessionId, async () => {
+            const snapshot = this.options.journal.snapshot(sessionId);
+            if (!snapshot)
+                throw new SessionError('session_not_found', `Unknown session ${sessionId}`);
+            if (snapshot.status === 'closed')
+                return;
+            await this.delegation.closeParent(sessionId);
+            await this.session(sessionId).close(reason);
+            this.active.delete(sessionId);
+        });
+    }
+    snapshot(sessionId) {
+        const active = this.active.get(sessionId);
+        if (active)
+            return active.state;
+        const snapshot = this.options.journal.snapshot(sessionId);
+        if (!snapshot)
+            throw new SessionError('session_not_found', `Unknown session ${sessionId}`);
+        return snapshot;
+    }
+    events(sessionId, afterSeq, limit = 500) {
+        if (!this.options.journal.getSession(sessionId))
+            throw new SessionError('session_not_found', `Unknown session ${sessionId}`);
+        const page = this.options.journal.read(sessionId, afterSeq, Math.min(Math.max(limit, 1), 5_000));
+        return { events: page.events, nextSeq: page.events.at(-1)?.seq ?? afterSeq, hasMore: page.hasMore };
+    }
+    list(state = 'open') {
+        return this.options.journal.list(state);
+    }
+    stats() {
+        return { sessions: this.active.size, residentProcesses: [...this.active.values()].filter((session) => session.processAlive).length };
+    }
+    /** Retire every provider process; running work is recorded as interrupted. */
+    async shutdown() {
+        this.shuttingDown = true;
+        await Promise.allSettled([...this.active.values()].map((session) => session.retire('shutdown', { turnStatus: 'interrupted', subagentPhase: 'interrupted', reason: 'shutdown' })));
+    }
+    // ── internals ─────────────────────────────────────────────────────────────
+    async resume(sessionId) {
+        const snapshot = this.options.journal.snapshot(sessionId);
+        if (!snapshot)
+            throw new SessionError('session_not_found', `Unknown session ${sessionId}`);
+        if (snapshot.status === 'closed')
+            throw new SessionError('session_closed', `Session ${sessionId} is closed`);
+        const session = this.activate(sessionId);
+        return { sessionId, snapshot: session.state };
+    }
+    activate(sessionId) {
+        const existing = this.active.get(sessionId);
+        if (existing)
+            return existing;
+        const snapshot = this.options.journal.snapshot(sessionId);
+        if (!snapshot)
+            throw new SessionError('session_not_found', `Unknown session ${sessionId}`);
+        const session = new ActiveSession(sessionId, snapshot, this.configFrom(snapshot), this.deps(this.requireFactory(snapshot.driver)));
+        this.active.set(sessionId, session);
+        return session;
+    }
+    session(sessionId) {
+        this.assertRunning();
+        const snapshot = this.active.get(sessionId)?.state ?? this.options.journal.snapshot(sessionId);
+        if (!snapshot)
+            throw new SessionError('session_not_found', `Unknown session ${sessionId}`);
+        if (snapshot.status === 'closed')
+            throw new SessionError('session_closed', `Session ${sessionId} is closed`);
+        return this.activate(sessionId);
+    }
+    configFrom(snapshot) {
+        const record = this.options.journal.getSession(snapshot.sessionId);
+        if (!snapshot.policy || !record)
+            throw new SessionError('internal', `Session ${snapshot.sessionId} has no opening record`);
+        return { cwd: record.cwd, model: snapshot.model, effort: snapshot.effort, systemPrompt: snapshot.systemPrompt, policy: snapshot.policy };
+    }
+    deps(factory) {
+        return {
+            journal: this.options.journal,
+            factory,
+            clock: this.options.clock,
+            ids: this.options.ids,
+            rateCard: this.options.rateCard ?? (() => null),
+            publish: (envelopes) => this.publish(envelopes),
+            touched: () => this.enforceResidentCap(),
+            ...(this.options.outputLimits ? { outputLimits: this.options.outputLimits } : {}),
+            ...(this.options.interruptGraceMs !== undefined ? { interruptGraceMs: this.options.interruptGraceMs } : {}),
+        };
+    }
+    requireFactory(driverId) {
+        const factory = this.options.drivers.get(driverId);
+        if (!factory)
+            throw new SessionError('driver_unavailable', `Driver "${driverId}" is not registered`, { driver: driverId });
+        return factory;
+    }
+    /** Keep-alive cap: retire least-recently-used idle processes; never busy ones. */
+    enforceResidentCap() {
+        const cap = this.options.maxResident ?? DEFAULT_MAX_RESIDENT;
+        const alive = [...this.active.values()].filter((session) => session.processAlive);
+        if (alive.length <= cap)
+            return;
+        const evictable = alive.filter((session) => !session.isBusy).sort((a, b) => a.lastUsedAt - b.lastUsedAt);
+        for (const session of evictable.slice(0, alive.length - cap)) {
+            void this.exclusive(session.sessionId, () => session.retire('evicted', { turnStatus: 'interrupted', subagentPhase: 'interrupted', reason: 'evicted' }));
+        }
+    }
+    publish(envelopes) {
+        if (envelopes.length === 0)
+            return;
+        for (const listener of this.listeners)
+            listener(envelopes);
+        // Mirror delegated children into their parents (after hosts saw the child events).
+        this.delegation.observe(envelopes);
+    }
+    /** Serialize operations per session. */
+    exclusive(sessionId, fn) {
+        const previous = this.locks.get(sessionId) ?? Promise.resolve();
+        const next = previous.then(fn, fn);
+        const settled = next.catch(() => undefined);
+        this.locks.set(sessionId, settled);
+        void settled.then(() => { if (this.locks.get(sessionId) === settled)
+            this.locks.delete(sessionId); });
+        return next;
+    }
+    assertRunning() {
+        if (this.shuttingDown)
+            throw new SessionError('busy', 'The session host is shutting down');
+    }
+}
+function needsRecovery(snapshot) {
+    return snapshot.openTurn !== null
+        || snapshot.process.alive
+        || snapshot.phase !== 'idle'
+        || liveSubagents(snapshot).length > 0
+        || Object.values(snapshot.inputs).some((input) => input.state === 'accepted' || input.state === 'queued' || input.state === 'started');
+}

package/dist/agent-runtime/session/application/timers.d.ts

@@ -0,0 +1,15 @@
+import type { Clock } from '../ports.js';
+/** The timers one session can hold; each kind has at most one armed timer. */
+export type TimerKind = 'idle' | 'stall' | 'backgroundMax' | 'turnInactivity' | 'settle' | 'interruptGrace' | 'flush';
+/** Named, cancellable timers for one session. Re-arming a kind replaces it. */
+export declare class SessionTimers {
+    private readonly clock;
+    private readonly armed;
+    constructor(clock: Clock);
+    arm(kind: TimerKind, ms: number, callback: () => void): void;
+    /** Arm only when not already armed (deadlines that must not slide). */
+    ensure(kind: TimerKind, ms: number, callback: () => void): void;
+    isArmed(kind: TimerKind): boolean;
+    cancel(...kinds: TimerKind[]): void;
+    cancelAll(): void;
+}

package/dist/agent-runtime/session/application/timers.js

@@ -0,0 +1,35 @@
+/** Named, cancellable timers for one session. Re-arming a kind replaces it. */
+export class SessionTimers {
+    clock;
+    armed = new Map();
+    constructor(clock) {
+        this.clock = clock;
+    }
+    arm(kind, ms, callback) {
+        this.cancel(kind);
+        const handle = this.clock.after(ms, () => {
+            if (this.armed.get(kind) !== handle)
+                return;
+            this.armed.delete(kind);
+            callback();
+        });
+        this.armed.set(kind, handle);
+    }
+    /** Arm only when not already armed (deadlines that must not slide). */
+    ensure(kind, ms, callback) {
+        if (!this.armed.has(kind))
+            this.arm(kind, ms, callback);
+    }
+    isArmed(kind) {
+        return this.armed.has(kind);
+    }
+    cancel(...kinds) {
+        for (const kind of kinds) {
+            this.armed.get(kind)?.cancel();
+            this.armed.delete(kind);
+        }
+    }
+    cancelAll() {
+        this.cancel(...this.armed.keys());
+    }
+}

package/dist/agent-runtime/session/domain/descriptor.d.ts

@@ -0,0 +1,6 @@
+import type { DriverDescriptor } from './types.js';
+/**
+ * Validate a driver descriptor, including capability coherence: a driver
+ * cannot claim behaviour that depends on a capability it does not have.
+ */
+export declare function validateDescriptor(descriptor: DriverDescriptor): void;

package/dist/agent-runtime/session/domain/descriptor.js

@@ -0,0 +1,32 @@
+import { SessionError } from './errors.js';
+const DRIVER_ID = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const COST = new Set(['session-cumulative', 'per-turn', 'none']);
+const TOKENS = new Set(['per-turn', 'cumulative', 'none']);
+/**
+ * Validate a driver descriptor, including capability coherence: a driver
+ * cannot claim behaviour that depends on a capability it does not have.
+ */
+export function validateDescriptor(descriptor) {
+    const fail = (message) => { throw new SessionError('internal', `Invalid driver descriptor "${descriptor?.id}": ${message}`); };
+    if (!descriptor || typeof descriptor.id !== 'string' || !DRIVER_ID.test(descriptor.id))
+        fail('id must match [a-z0-9][a-z0-9._-]{0,63}');
+    if (typeof descriptor.displayName !== 'string' || !descriptor.displayName.trim())
+        fail('displayName is required');
+    const caps = descriptor.capabilities;
+    if (!caps)
+        fail('capabilities are required');
+    for (const key of ['resident', 'nativeInputQueue', 'subagentDisable', 'autonomousContinuation', 'steer', 'toolFiltering']) {
+        if (typeof caps[key] !== 'boolean')
+            fail(`capabilities.${key} must be a boolean`);
+    }
+    if (caps.subagents !== 'supported' && caps.subagents !== 'unsupported')
+        fail('capabilities.subagents must be supported|unsupported');
+    if (caps.subagents === 'unsupported' && (caps.subagentDisable || caps.autonomousContinuation))
+        fail('sub-agent capabilities require subagents=supported');
+    if (!caps.resident && caps.nativeInputQueue)
+        fail('a native input queue requires a resident process');
+    if (!caps.resident && caps.autonomousContinuation)
+        fail('autonomous continuation requires a resident process');
+    if (!COST.has(caps.usage?.costUsd) || !TOKENS.has(caps.usage?.tokens))
+        fail('capabilities.usage is invalid');
+}

package/dist/agent-runtime/session/domain/errors.d.ts

@@ -0,0 +1,9 @@
+/** Stable error codes shared by the domain, application and protocol layers. */
+export type SessionErrorCode = 'protocol_mismatch' | 'not_initialized' | 'invalid_params' | 'payload_too_large' | 'session_not_found' | 'session_closed' | 'driver_unavailable' | 'policy_unenforceable' | 'input_conflict' | 'illegal_transition' | 'journal_locked' | 'store_incompatible' | 'busy' | 'limit_reached' | 'internal';
+export declare class SessionError extends Error {
+    readonly code: SessionErrorCode;
+    readonly detail?: Record<string, unknown> | undefined;
+    readonly retryable: boolean;
+    constructor(code: SessionErrorCode, message: string, detail?: Record<string, unknown> | undefined);
+}
+export declare function isSessionError(error: unknown): error is SessionError;

package/dist/agent-runtime/session/domain/errors.js

@@ -0,0 +1,16 @@
+const RETRYABLE = new Set(['journal_locked', 'busy', 'internal']);
+export class SessionError extends Error {
+    code;
+    detail;
+    retryable;
+    constructor(code, message, detail) {
+        super(message);
+        this.code = code;
+        this.detail = detail;
+        this.name = 'SessionError';
+        this.retryable = RETRYABLE.has(code);
+    }
+}
+export function isSessionError(error) {
+    return error instanceof SessionError;
+}

package/dist/agent-runtime/session/domain/events.d.ts

@@ -0,0 +1,147 @@
+import type { Attachment, InputDelivery, OutputChannel, SessionPhase, SessionPolicy, SubagentKind, SubagentPhase, TurnOrigin, Usage } from './types.js';
+/**
+ * The journaled, provider-neutral event vocabulary (session protocol v1).
+ * Events are the source of truth: snapshots and projections are folds over them.
+ * Adding a type is non-breaking; changing a payload's meaning needs a new
+ * protocol version (docs/agent-sessions/protocol.md).
+ */
+export interface ToolActivity {
+    toolUseId: string;
+    name: string;
+    phase: 'started' | 'completed';
+    input?: unknown;
+    output?: string;
+    isError?: boolean;
+}
+export type SessionEventBody = {
+    type: 'session.opened';
+    driver: string;
+    model: string;
+    effort?: string;
+    systemPrompt?: string;
+    policy: SessionPolicy;
+    resumed: boolean;
+    providerSessionRef: string | null;
+} | {
+    type: 'session.phase';
+    phase: SessionPhase;
+} | {
+    type: 'session.process';
+    state: 'started' | 'retired' | 'exited';
+    generation: number;
+    reason?: string;
+    exitCode?: number | null;
+} | {
+    type: 'session.provider-ref';
+    providerSessionRef: string;
+} | {
+    type: 'session.updated';
+    changes: Record<string, unknown>;
+    outcome: 'applied' | 'deferred';
+} | {
+    type: 'session.closed';
+    reason: string;
+} | {
+    type: 'input.accepted';
+    inputId: string;
+    delivery: InputDelivery;
+    text: string;
+    attachments?: Attachment[];
+} | {
+    type: 'input.state';
+    inputId: string;
+    state: 'queued' | 'started' | 'completed' | 'rejected' | 'interrupted';
+    turnId?: string;
+    reason?: string;
+} | {
+    type: 'turn.started';
+    turnId: string;
+    origin: TurnOrigin;
+    inputIds: string[];
+    trigger?: {
+        subagentIds: string[];
+    };
+} | {
+    type: 'turn.output';
+    turnId: string;
+    channel: OutputChannel;
+    delta: string;
+} | ({
+    type: 'turn.tool';
+    turnId: string;
+} & ToolActivity) | {
+    type: 'turn.completed';
+    turnId: string;
+    status: 'completed' | 'failed' | 'stopped' | 'interrupted';
+    text: string;
+    error?: string;
+    usage: Usage;
+} | {
+    type: 'subagent.started';
+    subagentId: string;
+    parentId: string | null;
+    kind: SubagentKind;
+    agentType?: string;
+    description: string;
+    prompt?: string;
+    delegated?: {
+        driver: string;
+        model: string;
+    };
+} | {
+    type: 'subagent.phase';
+    subagentId: string;
+    phase: SubagentPhase;
+    reason?: string;
+} | {
+    type: 'subagent.output';
+    subagentId: string;
+    channel: 'text' | 'tool';
+    delta?: string;
+    tool?: ToolActivity;
+} | {
+    type: 'subagent.usage';
+    subagentId: string;
+    usage: Usage;
+    toolUses?: number;
+    durationMs?: number;
+    billing?: 'included' | 'separate';
+} | {
+    type: 'subagent.result';
+    subagentId: string;
+    summary: string;
+} | {
+    type: 'subagents.settled';
+    settled: boolean;
+    live: number;
+} | {
+    type: 'output.truncated';
+    scope: {
+        turnId: string;
+    } | {
+        subagentId: string;
+    };
+    droppedEvents: number;
+    droppedBytes: number;
+} | {
+    type: 'notice.interruption';
+    subagentIds: string[];
+    inputIds: string[];
+} | {
+    type: 'provider.diagnostic';
+    level: 'info' | 'warning';
+    code: string;
+    message: string;
+};
+export type SessionEventType = SessionEventBody['type'];
+/** A committed event: body plus journal coordinates. */
+export type SessionEvent = SessionEventBody & {
+    at: string;
+};
+export interface SessionEventEnvelope {
+    sessionId: string;
+    seq: number;
+    event: SessionEvent;
+}
+/** Closed list of event types (mirrored into integration-contract.json). */
+export declare const SESSION_EVENT_TYPES: readonly ["session.opened", "session.phase", "session.process", "session.provider-ref", "session.updated", "session.closed", "input.accepted", "input.state", "turn.started", "turn.output", "turn.tool", "turn.completed", "subagent.started", "subagent.phase", "subagent.output", "subagent.usage", "subagent.result", "subagents.settled", "output.truncated", "notice.interruption", "provider.diagnostic"];

package/dist/agent-runtime/session/domain/events.js

@@ -0,0 +1,24 @@
+/** Closed list of event types (mirrored into integration-contract.json). */
+export const SESSION_EVENT_TYPES = Object.freeze([
+    'session.opened',
+    'session.phase',
+    'session.process',
+    'session.provider-ref',
+    'session.updated',
+    'session.closed',
+    'input.accepted',
+    'input.state',
+    'turn.started',
+    'turn.output',
+    'turn.tool',
+    'turn.completed',
+    'subagent.started',
+    'subagent.phase',
+    'subagent.output',
+    'subagent.usage',
+    'subagent.result',
+    'subagents.settled',
+    'output.truncated',
+    'notice.interruption',
+    'provider.diagnostic',
+]);

package/dist/agent-runtime/session/domain/fingerprint.d.ts

@@ -0,0 +1,2 @@
+/** 64-bit FNV-1a over UTF-16 code units, hex. Identity check only, not security. */
+export declare function fingerprint(text: string): string;

package/dist/agent-runtime/session/domain/fingerprint.js

@@ -0,0 +1,10 @@
+/** 64-bit FNV-1a over UTF-16 code units, hex. Identity check only, not security. */
+export function fingerprint(text) {
+    let hash = 0xcbf29ce484222325n;
+    const prime = 0x100000001b3n;
+    for (let index = 0; index < text.length; index++) {
+        hash ^= BigInt(text.charCodeAt(index));
+        hash = (hash * prime) & 0xffffffffffffffffn;
+    }
+    return hash.toString(16).padStart(16, '0');
+}

package/dist/agent-runtime/session/domain/interruption.d.ts

@@ -0,0 +1,13 @@
+import type { SessionSnapshot } from './snapshot.js';
+export interface InterruptionNotice {
+    text: string;
+    subagentIds: string[];
+    inputIds: string[];
+}
+/**
+ * Build the one-time notice prefixed to the next user input after work was
+ * interrupted. It names what happened and tells the agent not to relaunch it on
+ * its own — providers otherwise "resume" orphaned work silently (spike finding).
+ * Returns null when there is nothing to report.
+ */
+export declare function buildInterruptionNotice(state: SessionSnapshot): InterruptionNotice | null;

package/dist/agent-runtime/session/domain/interruption.js

@@ -0,0 +1,39 @@
+const REASONS = Object.freeze({
+    user_stop: 'stopped by the user',
+    host_request: 'stopped by the host',
+    restart: 'interrupted by an application restart',
+    shutdown: 'interrupted when the application closed',
+    host_lost: 'interrupted when the session host was lost',
+    crashed: 'interrupted when the provider process exited unexpectedly',
+    stalled: 'interrupted after no progress',
+    limit: 'stopped after reaching its time limit',
+    project_removed: 'interrupted because its project was removed',
+});
+function describeReason(phase, reason) {
+    return (reason && REASONS[reason]) ?? (phase === 'interrupted' ? 'interrupted' : 'stopped');
+}
+/**
+ * Build the one-time notice prefixed to the next user input after work was
+ * interrupted. It names what happened and tells the agent not to relaunch it on
+ * its own — providers otherwise "resume" orphaned work silently (spike finding).
+ * Returns null when there is nothing to report.
+ */
+export function buildInterruptionNotice(state) {
+    const { subagentIds, inputIds } = state.pendingInterruptions;
+    if (subagentIds.length === 0 && inputIds.length === 0)
+        return null;
+    const lines = ['[Specrails session notice]'];
+    if (subagentIds.length > 0) {
+        lines.push('These sub-agents did not finish:');
+        for (const id of subagentIds) {
+            const node = state.subagents[id];
+            if (node)
+                lines.push(`- "${node.description}" (${node.agentType ?? node.kind}) — ${describeReason(node.phase, node.reason)}.`);
+        }
+        lines.push('Do not relaunch or resume them unless the user explicitly asks. If their results matter for the next step, say so and ask.');
+    }
+    if (inputIds.length > 0) {
+        lines.push(`${inputIds.length === 1 ? 'One earlier user message' : `${inputIds.length} earlier user messages`} may not have reached you before the interruption; the user can resend if needed.`);
+    }
+    return { text: lines.join('\n'), subagentIds: [...subagentIds], inputIds: [...inputIds] };
+}

package/dist/agent-runtime/session/domain/policy.d.ts

@@ -0,0 +1,42 @@
+import type { DriverDescriptor, McpServerSpec, SessionLimits, SessionPolicy, SubagentRuntime } from './types.js';
+/** Defaults chosen from the provider spike and Desktop's previous mission limits. */
+export declare const DEFAULT_LIMITS: SessionLimits;
+/** What a host may send in `session.open` / `session.update`. Only `subagents` is mandatory. */
+export interface SessionPolicyInput {
+    subagents: SessionPolicy['subagents'];
+    onSubagentsSettled?: SessionPolicy['onSubagentsSettled'];
+    tools?: SessionPolicy['tools'];
+    permissions?: SessionPolicy['permissions'];
+    mcp?: {
+        servers?: McpServerSpec[];
+        inheritUserScope?: boolean;
+    };
+    limits?: Partial<SessionLimits>;
+    subagentRuntime?: {
+        mode: 'native';
+        model?: string;
+        effort?: string;
+    } | {
+        mode: 'delegated';
+        driver: string;
+        model: string;
+        effort?: string;
+        maxConcurrent?: number;
+    };
+}
+export declare const DEFAULT_MAX_DELEGATED = 4;
+/**
+ * Resolve a host policy against a driver's declared capabilities. The result is
+ * fully specified; anything the driver cannot enforce is refused, never ignored.
+ */
+export declare function resolvePolicy(input: SessionPolicyInput, driver: DriverDescriptor): SessionPolicy;
+/** True when the provider's own sub-agents may run (enabled and not delegated to Core). */
+export declare function nativeSubagentsAllowed(policy: SessionPolicy): boolean;
+/** True when Core launches this session's sub-agents itself. */
+export declare function delegatedSubagents(policy: SessionPolicy): policy is SessionPolicy & {
+    subagentRuntime: Extract<SubagentRuntime, {
+        mode: 'delegated';
+    }>;
+};
+/** True when the effective native sub-agent behaviour of the session is "enabled". */
+export declare function subagentsActive(policy: SessionPolicy, driver: DriverDescriptor): boolean;