specrails-core 6.4.0 → 6.5.0

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

@@ -0,0 +1,176 @@
+import type { SessionEventEnvelope, ToolActivity } from '../domain/events.js';
+import { type SessionSnapshot } from '../domain/snapshot.js';
+import { type SessionPolicy, type SubagentPhase, type Usage } from '../domain/types.js';
+import { type RateCard } from '../domain/usage.js';
+import type { Clock, CloseReason, DriverFactory, DriverInput, Ids, SessionJournal } from '../ports.js';
+import { type OutputLimits } from './output-buffer.js';
+export interface ActiveSessionDeps {
+    journal: SessionJournal;
+    factory: DriverFactory;
+    clock: Clock;
+    ids: Ids;
+    rateCard: (driver: string, model: string) => RateCard | null;
+    publish: (envelopes: SessionEventEnvelope[]) => void;
+    /** Called whenever the session's process liveness or recency changes (LRU bookkeeping). */
+    touched: (session: ActiveSession) => void;
+    outputLimits?: OutputLimits;
+    /** How long `interrupt` waits for the provider before ending the process. */
+    interruptGraceMs?: number;
+    /** Delay before buffered deltas are flushed. */
+    flushMs?: number;
+}
+export interface SessionConfig {
+    cwd: string;
+    model: string;
+    effort: string | null;
+    systemPrompt: string | null;
+    policy: SessionPolicy;
+}
+/** How work that was running ends when the process goes away. */
+interface Teardown {
+    turnStatus: 'stopped' | 'interrupted' | 'failed';
+    subagentPhase: SubagentPhase;
+    reason: string;
+    error?: string;
+}
+/**
+ * Coordinates one session: turns driver facts into journaled events, owns the
+ * provider process lifecycle, phases, settlement, limits and teardown.
+ * All mutation goes through `commit`, which folds before appending, so the
+ * journal never holds an event the domain would reject.
+ */
+export declare class ActiveSession {
+    readonly sessionId: string;
+    private config;
+    private readonly deps;
+    state: SessionSnapshot;
+    private driver;
+    private opening;
+    private generation;
+    /** Generation whose events are accepted (the live or opening process); null when none. */
+    private liveGeneration;
+    private closing;
+    private baseline;
+    private readonly timers;
+    private readonly output;
+    private readonly descriptor;
+    /** Inputs held back for drivers without a native input queue. */
+    private readonly heldInputs;
+    /** Inputs the application wrote on its own (policy-driven turns). */
+    private readonly systemInputIds;
+    private pendingDeferred;
+    private roster;
+    private handoffs;
+    private finishedSinceLastTurn;
+    /** Finished delegated sub-agents whose results the agent has not received yet. */
+    private readonly delegatedResults;
+    private lastUserTurnAt;
+    lastUsedAt: number;
+    constructor(sessionId: string, snapshot: SessionSnapshot, config: SessionConfig, deps: ActiveSessionDeps);
+    get processAlive(): boolean;
+    get isBusy(): boolean;
+    get policy(): SessionPolicy;
+    send(input: {
+        inputId: string;
+        text: string;
+        attachments?: DriverInput['attachments'];
+        delivery: 'queue' | 'steer';
+    }): Promise<{
+        inputId: string;
+        state: string;
+    }>;
+    interrupt(): Promise<string | null>;
+    stopSubagents(ids?: string[]): Promise<string[]>;
+    /**
+     * Policy says no sub-agents, yet the provider started one (a provider switch
+     * can be ignored by a model or CLI version). Stop it and say so: the policy
+     * holds whatever the provider's own switch does.
+     */
+    private blockSubagent;
+    /** Apply now when nothing is running; otherwise defer to the next idle point. */
+    update(changes: {
+        model?: string;
+        effort?: string;
+        systemPrompt?: string;
+        policy?: SessionPolicy;
+    }): Promise<'applied' | 'deferred'>;
+    close(reason: string): Promise<void>;
+    /**
+     * Record work a previous host left running as interrupted. Nothing is
+     * restarted: the next user input carries the interruption notice instead.
+     */
+    recoverAfterHostLoss(reason: 'restart' | 'host_lost'): void;
+    /** Retire the provider process; running work ends as described by `teardown`. */
+    retire(reason: CloseReason, teardown: Teardown): Promise<void>;
+    private deliver;
+    private ensureDriver;
+    private onDriverEvent;
+    private handleDriverEvent;
+    private startTurn;
+    private completeTurn;
+    /**
+     * Inputs whose receipts never reported completion are completed with their
+     * turn: the ones that opened it and the ones steered into it.
+     */
+    private completeTurnInputs;
+    private settlePhaseAfterTurn;
+    private afterSubagentChange;
+    private onSettled;
+    /** Live = running in our tree and, when the provider reports a roster, still on it. */
+    private liveCount;
+    private maybeResumeAgent;
+    /** Give the agent the results of delegated sub-agents it has not seen. */
+    private maybeDeliverDelegatedResults;
+    /** Running sub-agents Core launched for this session. */
+    delegatedLive(): string[];
+    delegatedStarted(child: {
+        subagentId: string;
+        description: string;
+        agentType: string;
+        prompt: string;
+        driver: string;
+        model: string;
+    }): void;
+    delegatedOutput(subagentId: string, event: {
+        channel: 'text';
+        delta: string;
+    } | {
+        channel: 'tool';
+        tool: ToolActivity;
+    }): void;
+    /**
+     * A delegated child ended. Its usage is its own provider's spend (billed
+     * separately); unless a host already collected the result, the agent gets it
+     * when the session next settles.
+     */
+    delegatedFinished(subagentId: string, outcome: {
+        status: 'completed' | 'failed' | 'stopped' | 'interrupted';
+        text: string;
+        usage: Usage | null;
+        reason?: string;
+        collected: boolean;
+    }): void;
+    /** A host received these results through a wait; never inject them again. */
+    collectDelegated(subagentIds: readonly string[]): void;
+    private enterIdle;
+    private enterBackground;
+    private idleTeardown;
+    private armTurnInactivity;
+    private markActivity;
+    private applyChanges;
+    private releaseHeldInput;
+    /** End whatever was running; used by retire and unexpected exits. */
+    private endRunningWork;
+    private turnUsage;
+    private subagentUsage;
+    private commitBuffered;
+    /**
+     * Validate (fold) then append atomically, then publish. Buffered deltas are
+     * flushed first so ordering is preserved.
+     */
+    private commit;
+    private requireTurn;
+    private assertOpen;
+    private touch;
+}
+export {};