specrails-core 6.4.0 → 6.5.0

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

@@ -0,0 +1,104 @@
+import { SessionError } from './errors.js';
+/** Defaults chosen from the provider spike and Desktop's previous mission limits. */
+export const DEFAULT_LIMITS = Object.freeze({
+    idleMs: 10 * 60_000,
+    stallMs: 15 * 60_000,
+    backgroundMaxMs: 2 * 60 * 60_000,
+    turnInactivityMs: 5 * 60_000,
+    maxSettleHandoffs: 3,
+    settleDebounceMs: 1_500,
+});
+const LIMIT_BOUNDS = Object.freeze({
+    idleMs: [1_000, 24 * 60 * 60_000],
+    stallMs: [1_000, 24 * 60 * 60_000],
+    backgroundMaxMs: [1_000, 7 * 24 * 60 * 60_000],
+    turnInactivityMs: [1_000, 24 * 60 * 60_000],
+    maxSettleHandoffs: [0, 20],
+    settleDebounceMs: [0, 60_000],
+});
+export const DEFAULT_MAX_DELEGATED = 4;
+const MAX_DELEGATED_BOUNDS = [1, 16];
+/** Validate the sub-agent runtime against what the parent driver can enforce. */
+function resolveRuntime(input, driver) {
+    const runtime = input.subagentRuntime ?? { mode: 'native' };
+    const caps = driver.capabilities;
+    if (runtime.mode === 'native') {
+        if (runtime.model && !caps.subagentModel)
+            throw unenforceable(`Driver "${driver.id}" cannot choose a model for its own sub-agents`, { field: 'subagentRuntime.model', driver: driver.id });
+        if (runtime.effort && !caps.subagentEffort)
+            throw unenforceable(`Driver "${driver.id}" cannot choose an effort for its own sub-agents`, { field: 'subagentRuntime.effort', driver: driver.id });
+        return { mode: 'native', ...(runtime.model ? { model: runtime.model } : {}), ...(runtime.effort ? { effort: runtime.effort } : {}) };
+    }
+    // Delegated: the parent's own tool must be switchable off, or the setting would not hold.
+    if (caps.subagents === 'supported' && !caps.subagentDisable) {
+        throw unenforceable(`Driver "${driver.id}" cannot disable its own sub-agents, so Core cannot launch them instead`, { field: 'subagentRuntime.mode', driver: driver.id });
+    }
+    const maxConcurrent = runtime.maxConcurrent ?? DEFAULT_MAX_DELEGATED;
+    if (!Number.isInteger(maxConcurrent) || maxConcurrent < MAX_DELEGATED_BOUNDS[0] || maxConcurrent > MAX_DELEGATED_BOUNDS[1]) {
+        throw new SessionError('invalid_params', `policy.subagentRuntime.maxConcurrent must be an integer in [${MAX_DELEGATED_BOUNDS[0]}, ${MAX_DELEGATED_BOUNDS[1]}]`, { path: 'policy.subagentRuntime.maxConcurrent' });
+    }
+    if (!runtime.model)
+        throw new SessionError('invalid_params', 'Delegated sub-agents need a model', { path: 'policy.subagentRuntime.model' });
+    return { mode: 'delegated', driver: runtime.driver, model: runtime.model, ...(runtime.effort ? { effort: runtime.effort } : {}), maxConcurrent };
+}
+function unenforceable(message, detail) {
+    return new SessionError('policy_unenforceable', message, detail);
+}
+function resolveLimits(input) {
+    const limits = { ...DEFAULT_LIMITS };
+    for (const [key, value] of Object.entries(input ?? {})) {
+        if (value === undefined)
+            continue;
+        const bounds = LIMIT_BOUNDS[key];
+        if (!bounds)
+            throw new SessionError('invalid_params', `Unknown limit "${key}"`, { path: `policy.limits.${key}` });
+        if (!Number.isInteger(value) || value < bounds[0] || value > bounds[1]) {
+            throw new SessionError('invalid_params', `policy.limits.${key} must be an integer in [${bounds[0]}, ${bounds[1]}]`, { path: `policy.limits.${key}` });
+        }
+        limits[key] = value;
+    }
+    return limits;
+}
+/**
+ * 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 function resolvePolicy(input, driver) {
+    const caps = driver.capabilities;
+    const supportsSubagents = caps.subagents === 'supported';
+    if (input.subagents === 'disabled' && supportsSubagents && !caps.subagentDisable) {
+        throw unenforceable(`Driver "${driver.id}" cannot disable sub-agents`, { field: 'subagents', driver: driver.id });
+    }
+    const onSubagentsSettled = input.onSubagentsSettled ?? (caps.autonomousContinuation ? 'provider-native' : 'resume-agent');
+    if (onSubagentsSettled === 'provider-native' && supportsSubagents && input.subagents === 'enabled' && !caps.autonomousContinuation) {
+        throw unenforceable(`Driver "${driver.id}" does not continue on its own after sub-agents finish`, { field: 'onSubagentsSettled', driver: driver.id });
+    }
+    const tools = input.tools ?? { mode: 'default' };
+    if (!caps.toolFiltering && (tools.mode !== 'default' || tools.allow?.length || tools.deny?.length)) {
+        throw unenforceable(`Driver "${driver.id}" cannot restrict its tool set`, { field: 'tools', driver: driver.id });
+    }
+    if (tools.mode === 'none' && caps.resident && caps.subagents === 'supported' && input.subagents === 'enabled') {
+        throw unenforceable('A session without tools cannot launch sub-agents; disable sub-agents or allow tools', { field: 'tools.mode' });
+    }
+    return {
+        subagents: input.subagents,
+        subagentRuntime: resolveRuntime(input, driver),
+        onSubagentsSettled,
+        tools: { mode: tools.mode, ...(tools.allow ? { allow: [...tools.allow] } : {}), ...(tools.deny ? { deny: [...tools.deny] } : {}) },
+        permissions: input.permissions ?? 'workspace-write',
+        mcp: { servers: [...(input.mcp?.servers ?? [])], inheritUserScope: input.mcp?.inheritUserScope ?? false },
+        limits: resolveLimits(input.limits),
+    };
+}
+/** True when the provider's own sub-agents may run (enabled and not delegated to Core). */
+export function nativeSubagentsAllowed(policy) {
+    return policy.subagents === 'enabled' && policy.subagentRuntime.mode === 'native';
+}
+/** True when Core launches this session's sub-agents itself. */
+export function delegatedSubagents(policy) {
+    return policy.subagents === 'enabled' && policy.subagentRuntime.mode === 'delegated';
+}
+/** True when the effective native sub-agent behaviour of the session is "enabled". */
+export function subagentsActive(policy, driver) {
+    return nativeSubagentsAllowed(policy) && driver.capabilities.subagents === 'supported';
+}

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

@@ -0,0 +1,100 @@
+import type { SessionEvent, SessionEventEnvelope } from './events.js';
+import type { InputDelivery, InputState, SessionPhase, SessionPolicy, SessionStatus, SubagentKind, SubagentPhase, TurnOrigin, TurnStatus, Usage } from './types.js';
+export interface InputRecord {
+    inputId: string;
+    delivery: InputDelivery;
+    state: InputState;
+    turnId: string | null;
+    textLength: number;
+    /** Detects a retried inputId carrying different content. */
+    fingerprint: string;
+}
+export interface OpenTurn {
+    turnId: string;
+    origin: TurnOrigin;
+    inputIds: string[];
+    startedAt: string;
+    text: string;
+}
+export interface TurnRecord {
+    turnId: string;
+    origin: TurnOrigin;
+    status: TurnStatus;
+    startedAt: string;
+    endedAt: string | null;
+    usage: Usage | null;
+}
+export interface SubagentNode {
+    subagentId: string;
+    parentId: string | null;
+    kind: SubagentKind;
+    agentType: string | null;
+    description: string;
+    phase: SubagentPhase;
+    reason: string | null;
+    /** Times the provider restarted it after an idle phase. */
+    restarts: number;
+    startedAt: string;
+    endedAt: string | null;
+    usage: Usage | null;
+    toolUses: number | null;
+    durationMs: number | null;
+    resultSummary: string | null;
+    /** Set when Core launched it as a child session (delegated runtime); its spend is billed separately. */
+    delegated: {
+        driver: string;
+        model: string;
+    } | null;
+}
+/** Bounded history kept in the snapshot; the journal keeps every event. */
+export declare const SNAPSHOT_TURN_HISTORY = 100;
+export declare const SNAPSHOT_TERMINAL_INPUTS = 500;
+export interface SessionSnapshot {
+    sessionId: string;
+    lastSeq: number;
+    status: SessionStatus;
+    driver: string;
+    model: string;
+    effort: string | null;
+    systemPrompt: string | null;
+    policy: SessionPolicy | null;
+    providerSessionRef: string | null;
+    phase: SessionPhase;
+    process: {
+        generation: number;
+        alive: boolean;
+    };
+    openTurn: OpenTurn | null;
+    /** Most recent turns (bounded); `turnCount` counts all of them. */
+    turns: TurnRecord[];
+    turnCount: number;
+    inputs: Record<string, InputRecord>;
+    subagents: Record<string, SubagentNode>;
+    settled: {
+        settled: boolean;
+        live: number;
+    };
+    /** Interrupted work the agent has not been told about yet. */
+    pendingInterruptions: {
+        subagentIds: string[];
+        inputIds: string[];
+    };
+    closedReason: string | null;
+}
+export declare function emptySnapshot(sessionId: string): SessionSnapshot;
+/**
+ * Apply one event. Pure: returns a new snapshot and throws `illegal_transition`
+ * for events that would break an invariant. The application validates every
+ * event with this function before committing it, so a journal only ever
+ * contains foldable events and replay equals the live state.
+ */
+export declare function applyEvent(state: SessionSnapshot, event: SessionEvent): SessionSnapshot;
+/** Fold committed envelopes; sequence numbers must be gap-free and increasing. */
+export declare function foldEvents(initial: SessionSnapshot, envelopes: readonly SessionEventEnvelope[]): SessionSnapshot;
+/** Sub-agents currently occupying the provider. */
+export declare function liveSubagents(state: SessionSnapshot): SubagentNode[];
+/**
+ * Journals written before `subagentRuntime` existed carry policies without it:
+ * those sessions ran native sub-agents, so replay reads them as such.
+ */
+export declare function normalizePolicy(policy: SessionPolicy): SessionPolicy;

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

@@ -0,0 +1,234 @@
+import { SessionError } from './errors.js';
+import { fingerprint } from './fingerprint.js';
+import { INPUT_TRANSITIONS, SESSION_PHASE_TRANSITIONS, SUBAGENT_TRANSITIONS, TURN_TRANSITIONS, assertTransition, isLiveSubagentPhase, } from './state-machines.js';
+/** Bounded history kept in the snapshot; the journal keeps every event. */
+export const SNAPSHOT_TURN_HISTORY = 100;
+export const SNAPSHOT_TERMINAL_INPUTS = 500;
+export function emptySnapshot(sessionId) {
+    return {
+        sessionId,
+        lastSeq: 0,
+        status: 'open',
+        driver: '',
+        model: '',
+        effort: null,
+        systemPrompt: null,
+        policy: null,
+        providerSessionRef: null,
+        phase: 'idle',
+        process: { generation: 0, alive: false },
+        openTurn: null,
+        turns: [],
+        turnCount: 0,
+        inputs: {},
+        subagents: {},
+        settled: { settled: true, live: 0 },
+        pendingInterruptions: { subagentIds: [], inputIds: [] },
+        closedReason: null,
+    };
+}
+/** Sub-agent end states that the agent must be told about before it continues. */
+const NOTIFIABLE = new Set(['interrupted', 'stopped', 'killed']);
+function addUnique(list, id) {
+    return list.includes(id) ? list : [...list, id];
+}
+function requireSubagent(state, subagentId) {
+    const node = state.subagents[subagentId];
+    if (!node)
+        throw new SessionError('illegal_transition', `Unknown sub-agent ${subagentId}`, { subagentId });
+    return node;
+}
+function requireOpenTurn(state, turnId) {
+    if (state.openTurn?.turnId !== turnId)
+        throw new SessionError('illegal_transition', `Turn ${turnId} is not running`, { turnId });
+    return state.openTurn;
+}
+/**
+ * Apply one event. Pure: returns a new snapshot and throws `illegal_transition`
+ * for events that would break an invariant. The application validates every
+ * event with this function before committing it, so a journal only ever
+ * contains foldable events and replay equals the live state.
+ */
+export function applyEvent(state, event) {
+    if (state.status === 'closed' && event.type !== 'provider.diagnostic') {
+        throw new SessionError('session_closed', `Session ${state.sessionId} is closed`);
+    }
+    switch (event.type) {
+        case 'session.opened':
+            return {
+                ...state,
+                driver: event.driver,
+                model: event.model,
+                effort: event.effort ?? null,
+                systemPrompt: event.systemPrompt ?? null,
+                policy: normalizePolicy(event.policy),
+                providerSessionRef: event.providerSessionRef ?? state.providerSessionRef,
+            };
+        case 'session.phase':
+            assertTransition('session phase', SESSION_PHASE_TRANSITIONS, state.phase, event.phase);
+            return { ...state, phase: event.phase };
+        case 'session.process':
+            return { ...state, process: { generation: event.generation, alive: event.state === 'started' } };
+        case 'session.provider-ref':
+            return { ...state, providerSessionRef: event.providerSessionRef };
+        case 'session.updated': {
+            if (event.outcome === 'deferred')
+                return state;
+            const changes = event.changes;
+            return {
+                ...state,
+                model: changes.model ?? state.model,
+                effort: changes.effort ?? state.effort,
+                systemPrompt: changes.systemPrompt ?? state.systemPrompt,
+                policy: changes.policy ? normalizePolicy(changes.policy) : state.policy,
+            };
+        }
+        case 'session.closed':
+            return { ...state, status: 'closed', closedReason: event.reason, process: { ...state.process, alive: false } };
+        case 'input.accepted':
+            if (state.inputs[event.inputId])
+                throw new SessionError('input_conflict', `Input ${event.inputId} already exists`, { inputId: event.inputId });
+            return {
+                ...state,
+                inputs: { ...state.inputs, [event.inputId]: { inputId: event.inputId, delivery: event.delivery, state: 'accepted', turnId: null, textLength: event.text.length, fingerprint: fingerprint(event.text) } },
+            };
+        case 'input.state': {
+            const input = state.inputs[event.inputId];
+            if (!input)
+                throw new SessionError('illegal_transition', `Unknown input ${event.inputId}`, { inputId: event.inputId });
+            assertTransition('input', INPUT_TRANSITIONS, input.state, event.state);
+            const pending = event.state === 'interrupted'
+                ? { ...state.pendingInterruptions, inputIds: addUnique(state.pendingInterruptions.inputIds, event.inputId) }
+                : state.pendingInterruptions;
+            return {
+                ...state,
+                inputs: pruneInputs({ ...state.inputs, [event.inputId]: { ...input, state: event.state, turnId: event.turnId ?? input.turnId } }),
+                pendingInterruptions: pending,
+            };
+        }
+        case 'turn.started':
+            if (state.openTurn)
+                throw new SessionError('illegal_transition', `Turn ${state.openTurn.turnId} is still running`, { turnId: event.turnId });
+            return {
+                ...state,
+                openTurn: { turnId: event.turnId, origin: event.origin, inputIds: [...event.inputIds], startedAt: event.at, text: '' },
+                turns: [...state.turns, { turnId: event.turnId, origin: event.origin, status: 'running', startedAt: event.at, endedAt: null, usage: null }].slice(-SNAPSHOT_TURN_HISTORY),
+                turnCount: state.turnCount + 1,
+            };
+        case 'turn.output': {
+            const turn = requireOpenTurn(state, event.turnId);
+            return event.channel === 'text' ? { ...state, openTurn: { ...turn, text: turn.text + event.delta } } : state;
+        }
+        case 'turn.tool':
+            requireOpenTurn(state, event.turnId);
+            return state;
+        case 'turn.completed': {
+            requireOpenTurn(state, event.turnId);
+            const turns = state.turns.map((turn) => {
+                if (turn.turnId !== event.turnId)
+                    return turn;
+                assertTransition('turn', TURN_TRANSITIONS, turn.status, event.status);
+                return { ...turn, status: event.status, endedAt: event.at, usage: event.usage };
+            });
+            return { ...state, openTurn: null, turns };
+        }
+        case 'subagent.started': {
+            const existing = state.subagents[event.subagentId];
+            if (existing) {
+                // Providers restart a sub-agent under the same id after an idle phase.
+                assertTransition('sub-agent', SUBAGENT_TRANSITIONS, existing.phase, 'running');
+                const restarted = existing.phase === 'idle';
+                return withSubagent(state, { ...existing, phase: 'running', reason: null, endedAt: null, restarts: existing.restarts + (restarted ? 1 : 0) });
+            }
+            if (event.parentId !== null && !state.subagents[event.parentId]) {
+                throw new SessionError('illegal_transition', `Unknown parent sub-agent ${event.parentId}`, { subagentId: event.subagentId });
+            }
+            return withSubagent(state, {
+                subagentId: event.subagentId,
+                parentId: event.parentId,
+                kind: event.kind,
+                agentType: event.agentType ?? null,
+                delegated: event.delegated ?? null,
+                description: event.description,
+                phase: 'running',
+                reason: null,
+                restarts: 0,
+                startedAt: event.at,
+                endedAt: null,
+                usage: null,
+                toolUses: null,
+                durationMs: null,
+                resultSummary: null,
+            });
+        }
+        case 'subagent.phase': {
+            const node = requireSubagent(state, event.subagentId);
+            assertTransition('sub-agent', SUBAGENT_TRANSITIONS, node.phase, event.phase);
+            const live = isLiveSubagentPhase(event.phase);
+            // A refinement (stopped → killed) keeps the original reason unless a new one is given.
+            const next = withSubagent(state, { ...node, phase: event.phase, reason: event.reason ?? (live ? null : node.reason), endedAt: live ? null : event.at });
+            return NOTIFIABLE.has(event.phase)
+                ? { ...next, pendingInterruptions: { ...next.pendingInterruptions, subagentIds: addUnique(next.pendingInterruptions.subagentIds, event.subagentId) } }
+                : next;
+        }
+        case 'subagent.output':
+            requireSubagent(state, event.subagentId);
+            return state;
+        case 'subagent.usage': {
+            const node = requireSubagent(state, event.subagentId);
+            return withSubagent(state, { ...node, usage: event.usage, toolUses: event.toolUses ?? node.toolUses, durationMs: event.durationMs ?? node.durationMs });
+        }
+        case 'subagent.result': {
+            const node = requireSubagent(state, event.subagentId);
+            return withSubagent(state, { ...node, resultSummary: event.summary });
+        }
+        case 'subagents.settled':
+            return { ...state, settled: { settled: event.settled, live: event.live } };
+        case 'notice.interruption':
+            return {
+                ...state,
+                pendingInterruptions: {
+                    subagentIds: state.pendingInterruptions.subagentIds.filter((id) => !event.subagentIds.includes(id)),
+                    inputIds: state.pendingInterruptions.inputIds.filter((id) => !event.inputIds.includes(id)),
+                },
+            };
+        case 'output.truncated':
+        case 'provider.diagnostic':
+            return state;
+    }
+}
+const TERMINAL_INPUT = new Set(['completed', 'rejected', 'interrupted']);
+/** Keep every live input and only the most recent terminal ones (insertion order). */
+function pruneInputs(inputs) {
+    const terminal = Object.values(inputs).filter((input) => TERMINAL_INPUT.has(input.state));
+    if (terminal.length <= SNAPSHOT_TERMINAL_INPUTS)
+        return inputs;
+    const drop = new Set(terminal.slice(0, terminal.length - SNAPSHOT_TERMINAL_INPUTS).map((input) => input.inputId));
+    return Object.fromEntries(Object.entries(inputs).filter(([id]) => !drop.has(id)));
+}
+function withSubagent(state, node) {
+    return { ...state, subagents: { ...state.subagents, [node.subagentId]: node } };
+}
+/** Fold committed envelopes; sequence numbers must be gap-free and increasing. */
+export function foldEvents(initial, envelopes) {
+    let state = initial;
+    for (const envelope of envelopes) {
+        if (envelope.sessionId !== state.sessionId)
+            throw new SessionError('internal', `Event for ${envelope.sessionId} folded into ${state.sessionId}`);
+        if (envelope.seq !== state.lastSeq + 1)
+            throw new SessionError('internal', `Sequence gap: expected ${state.lastSeq + 1}, got ${envelope.seq}`);
+        state = { ...applyEvent(state, envelope.event), lastSeq: envelope.seq };
+    }
+    return state;
+}
+/** Sub-agents currently occupying the provider. */
+export function liveSubagents(state) {
+    return Object.values(state.subagents).filter((node) => isLiveSubagentPhase(node.phase));
+}
+/**
+ * Journals written before `subagentRuntime` existed carry policies without it:
+ * those sessions ran native sub-agents, so replay reads them as such.
+ */
+export function normalizePolicy(policy) {
+    return policy.subagentRuntime ? policy : { ...policy, subagentRuntime: { mode: 'native' } };
+}

package/dist/agent-runtime/session/domain/state-machines.d.ts

@@ -0,0 +1,21 @@
+import type { InputState, SessionPhase, SubagentPhase, TurnStatus } from './types.js';
+/**
+ * Transition tables. A state absent from a table's keys is terminal.
+ * Re-applying the current state is always legal (providers repeat notifications).
+ */
+type Table<S extends string> = Readonly<Partial<Record<S, readonly S[]>>>;
+export declare const SESSION_PHASE_TRANSITIONS: Table<SessionPhase>;
+export declare const TURN_TRANSITIONS: Table<TurnStatus>;
+export declare const INPUT_TRANSITIONS: Table<InputState>;
+/**
+ * Sub-agents are re-entrant: providers report a sub-agent `idle` (its own turn
+ * ended) and later restart it (e.g. when a shell it backgrounded finishes).
+ * `stopped → killed` refines a stop into a forced kill.
+ */
+export declare const SUBAGENT_TRANSITIONS: Table<SubagentPhase>;
+export declare function canTransition<S extends string>(table: Table<S>, from: S, to: S): boolean;
+export declare function assertTransition<S extends string>(machine: string, table: Table<S>, from: S, to: S): void;
+export declare function isTerminal<S extends string>(table: Table<S>, state: S): boolean;
+/** Phases in which a sub-agent still occupies the provider. */
+export declare function isLiveSubagentPhase(phase: SubagentPhase): boolean;
+export {};

package/dist/agent-runtime/session/domain/state-machines.js

@@ -0,0 +1,41 @@
+import { SessionError } from './errors.js';
+export const SESSION_PHASE_TRANSITIONS = Object.freeze({
+    // idle → background: a provider restarts a finished sub-agent after the session went idle.
+    idle: ['turn', 'background'],
+    turn: ['idle', 'background'],
+    // A user or continuation turn can start while sub-agents run; work can settle while idle.
+    background: ['turn', 'idle'],
+});
+export const TURN_TRANSITIONS = Object.freeze({
+    running: ['completed', 'failed', 'stopped', 'interrupted'],
+});
+export const INPUT_TRANSITIONS = Object.freeze({
+    accepted: ['queued', 'started', 'rejected', 'interrupted'],
+    queued: ['started', 'rejected', 'interrupted'],
+    started: ['completed', 'interrupted'],
+});
+/**
+ * Sub-agents are re-entrant: providers report a sub-agent `idle` (its own turn
+ * ended) and later restart it (e.g. when a shell it backgrounded finishes).
+ * `stopped → killed` refines a stop into a forced kill.
+ */
+export const SUBAGENT_TRANSITIONS = Object.freeze({
+    running: ['idle', 'failed', 'stopped', 'killed', 'interrupted'],
+    idle: ['running', 'failed', 'stopped', 'killed', 'interrupted'],
+    stopped: ['killed'],
+});
+export function canTransition(table, from, to) {
+    return from === to || (table[from]?.includes(to) ?? false);
+}
+export function assertTransition(machine, table, from, to) {
+    if (!canTransition(table, from, to)) {
+        throw new SessionError('illegal_transition', `${machine}: ${from} → ${to} is not allowed`, { machine, from, to });
+    }
+}
+export function isTerminal(table, state) {
+    return table[state] === undefined;
+}
+/** Phases in which a sub-agent still occupies the provider. */
+export function isLiveSubagentPhase(phase) {
+    return phase === 'running';
+}

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

@@ -0,0 +1,130 @@
+/**
+ * Provider-neutral session vocabulary. Every type here is plain data so it can
+ * cross the protocol boundary, be journaled and be folded by pure reducers.
+ * Provider wire formats never appear in this module (see drivers/).
+ */
+export type SessionPhase = 'idle' | 'turn' | 'background';
+export type SessionStatus = 'open' | 'closed';
+export type TurnOrigin = 'user' | 'subagent' | 'system';
+export type TurnStatus = 'running' | 'completed' | 'failed' | 'stopped' | 'interrupted';
+export type InputDelivery = 'queue' | 'steer';
+export type InputState = 'accepted' | 'queued' | 'started' | 'completed' | 'rejected' | 'interrupted';
+export type SubagentKind = 'foreground' | 'background';
+export type SubagentPhase = 'running' | 'idle' | 'failed' | 'stopped' | 'killed' | 'interrupted';
+export type OutputChannel = 'text' | 'thinking';
+/** Usage for one turn or one sub-agent. `null` means "not reported", never zero. */
+export interface Usage {
+    inputTokens: number | null;
+    outputTokens: number | null;
+    cacheReadTokens: number | null;
+    cacheWriteTokens: number | null;
+    /** Provider total when it reports no breakdown (e.g. Claude sub-agent progress). */
+    totalTokens: number | null;
+    /** Per-turn delta in USD. Sub-agent usage is a breakdown and is never added on top. */
+    costUsd: number | null;
+    /** True when the cost was derived from a rate card instead of billed by the provider. */
+    costEstimated: boolean;
+    model: string | null;
+}
+export declare const EMPTY_USAGE: Usage;
+export interface McpServerSpec {
+    name: string;
+    /** stdio server */
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    /** http server */
+    url?: string;
+    headers?: Record<string, string>;
+    /**
+     * The host authorizes every call of this server itself (e.g. a capability-bound
+     * bridge), so the provider must not ask for per-call approval. Without it,
+     * providers that gate MCP tools refuse them under a non-interactive policy.
+     */
+    autoApprove?: boolean;
+}
+export interface SessionLimits {
+    /** Retire a resident process after this long in `idle`. */
+    idleMs: number;
+    /** In `background`, retire when no provider frame arrives for this long. */
+    stallMs: number;
+    /** In `background`, retire this long after the last user turn. */
+    backgroundMaxMs: number;
+    /** Fail a running turn when no provider frame (including sub-agent frames) arrives for this long. */
+    turnInactivityMs: number;
+    /** Maximum policy-driven `resume-agent` turns per settle cycle. */
+    maxSettleHandoffs: number;
+    /** Debounce before an empty sub-agent roster counts as settled. */
+    settleDebounceMs: number;
+}
+/**
+ * Who launches sub-agents. `native`: the provider's own tool, optionally with a
+ * model/effort override. `delegated`: Core launches each one as a child session
+ * on `driver` (the provider's own tool is then disabled).
+ */
+export type SubagentRuntime = {
+    mode: 'native';
+    model?: string;
+    effort?: string;
+} | {
+    mode: 'delegated';
+    driver: string;
+    model: string;
+    effort?: string;
+    maxConcurrent: number;
+};
+export interface SessionPolicy {
+    subagents: 'enabled' | 'disabled';
+    subagentRuntime: SubagentRuntime;
+    onSubagentsSettled: 'provider-native' | 'resume-agent' | 'notify-only';
+    tools: {
+        mode: 'default' | 'read-only' | 'none';
+        allow?: string[];
+        deny?: string[];
+    };
+    permissions: 'bypass' | 'workspace-write' | 'read-only';
+    mcp: {
+        servers: McpServerSpec[];
+        inheritUserScope: boolean;
+    };
+    limits: SessionLimits;
+}
+/** Usage semantics a driver declares; the domain computes deltas from them. */
+export interface UsageSemantics {
+    /** How the provider reports USD. */
+    costUsd: 'session-cumulative' | 'per-turn' | 'none';
+    /** How the provider reports tokens for a turn. */
+    tokens: 'per-turn' | 'cumulative' | 'none';
+}
+export interface DriverCapabilities {
+    /** Multi-turn on one long-lived provider process. */
+    resident: boolean;
+    /** The provider serializes turns itself and reports per-input receipts. */
+    nativeInputQueue: boolean;
+    subagents: 'unsupported' | 'supported';
+    /** `policy.subagents = 'disabled'` can be enforced natively. */
+    subagentDisable: boolean;
+    /** Native sub-agents can run on a model other than the parent's. */
+    subagentModel: boolean;
+    /** Native sub-agents can run at a reasoning effort other than the parent's. */
+    subagentEffort: boolean;
+    /** The provider starts a turn by itself when a background sub-agent finishes. */
+    autonomousContinuation: boolean;
+    /** Input can be delivered into a running turn. */
+    steer: boolean;
+    /** The tool set can be restricted (`policy.tools` other than the default). */
+    toolFiltering: boolean;
+    usage: UsageSemantics;
+}
+export interface DriverDescriptor {
+    id: string;
+    displayName: string;
+    capabilities: DriverCapabilities;
+    /** CLI versions the recorded fixtures cover, informative. */
+    testedVersions?: string[];
+}
+export interface Attachment {
+    kind: 'image' | 'file';
+    path: string;
+    mimeType?: string;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Provider-neutral session vocabulary. Every type here is plain data so it can
+ * cross the protocol boundary, be journaled and be folded by pure reducers.
+ * Provider wire formats never appear in this module (see drivers/).
+ */
+export const EMPTY_USAGE = Object.freeze({
+    inputTokens: null,
+    outputTokens: null,
+    cacheReadTokens: null,
+    cacheWriteTokens: null,
+    totalTokens: null,
+    costUsd: null,
+    costEstimated: false,
+    model: null,
+});