specrails-core 6.4.0 → 6.6.0

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

@@ -0,0 +1,73 @@
+import type { SessionEventEnvelope } from '../domain/events.js';
+import { type SessionPolicyInput } from '../domain/policy.js';
+import type { SessionSnapshot } from '../domain/snapshot.js';
+import type { Ids, SessionJournal } from '../ports.js';
+import type { ActiveSession } from './active-session.js';
+/** What the coordinator needs from the session service (no cycle with its internals). */
+export interface DelegationPort {
+    journal: SessionJournal;
+    ids: Ids;
+    /** The open parent session, activated if needed; throws when unknown or closed. */
+    parent(sessionId: string): ActiveSession;
+    open(params: {
+        sessionId: string;
+        driver: string;
+        model: string;
+        effort?: string;
+        cwd: string;
+        systemPrompt: string;
+        policy: SessionPolicyInput;
+        metadata: Record<string, unknown>;
+    }): Promise<unknown>;
+    send(sessionId: string, input: {
+        inputId: string;
+        text: string;
+        delivery: 'queue';
+    }): Promise<unknown>;
+    interrupt(sessionId: string): Promise<unknown>;
+    close(sessionId: string, reason: string): Promise<void>;
+    snapshot(sessionId: string): SessionSnapshot;
+}
+export interface DelegateParams {
+    description: string;
+    prompt: string;
+    agentType?: string;
+    /** Recent parent turns (user inputs and replies) to hand over as context. */
+    contextTurns?: number;
+}
+export interface DelegatedResult {
+    subagentId: string;
+    description: string;
+    status: 'completed' | 'failed' | 'stopped' | 'interrupted';
+    result: string;
+}
+/**
+ * Core-launched sub-agents (delegated runtime). Each one is a child session on
+ * the policy's driver, model and effort; the parent sees it as a sub-agent of
+ * its own tree. Results reach the parent through an explicit wait or, when
+ * nobody waits, a continuation turn (see ActiveSession.delegatedFinished).
+ */
+export declare class DelegationCoordinator {
+    private readonly port;
+    private readonly children;
+    constructor(port: DelegationPort);
+    delegate(parentId: string, params: DelegateParams): Promise<{
+        subagentId: string;
+    }>;
+    /** Resolve with finished results, or with what still runs when the timeout elapses. */
+    wait(parentId: string, subagentIds: readonly string[] | undefined, timeoutMs: number): Promise<{
+        results: DelegatedResult[];
+        running: string[];
+    }>;
+    /** Delegated ids among `ids` (all of the parent's when omitted), stopped. */
+    stop(parentId: string, ids?: readonly string[], reason?: string): Promise<string[]>;
+    /** The parent session is closing: its delegated work ends with it. */
+    closeParent(parentId: string): Promise<void>;
+    isDelegated(subagentId: string): boolean;
+    /** Mirror committed child events into the parent's tree. */
+    observe(envelopes: readonly SessionEventEnvelope[]): void;
+    private finish;
+    private parentIfOpen;
+    /** The task, optionally preceded by the parent's recent conversation. */
+    private composePrompt;
+}

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

@@ -0,0 +1,171 @@
+import { SessionError } from '../domain/errors.js';
+import { delegatedSubagents } from '../domain/policy.js';
+const SYSTEM_PROMPT = [
+    'You are a sub-agent: another agent working in this same workspace delegated a task to you.',
+    'Complete it on your own; nobody can answer questions.',
+    'Finish with a concise, self-contained result the delegating agent can act on: what you found or changed, where, and anything left open.',
+].join(' ');
+const MAX_CONTEXT_TURNS = 10;
+/**
+ * Core-launched sub-agents (delegated runtime). Each one is a child session on
+ * the policy's driver, model and effort; the parent sees it as a sub-agent of
+ * its own tree. Results reach the parent through an explicit wait or, when
+ * nobody waits, a continuation turn (see ActiveSession.delegatedFinished).
+ */
+export class DelegationCoordinator {
+    port;
+    children = new Map();
+    constructor(port) {
+        this.port = port;
+    }
+    async delegate(parentId, params) {
+        const parent = this.port.parent(parentId);
+        const policy = parent.policy;
+        if (!delegatedSubagents(policy)) {
+            throw new SessionError('invalid_params', 'This session does not delegate sub-agents; its provider launches them itself', { path: 'sessionId' });
+        }
+        const runtime = policy.subagentRuntime;
+        if (parent.delegatedLive().length >= runtime.maxConcurrent) {
+            throw new SessionError('limit_reached', `At most ${runtime.maxConcurrent} delegated sub-agents can run at once`, { limit: runtime.maxConcurrent });
+        }
+        const description = params.description.trim().slice(0, 200) || 'Sub-agent';
+        const childId = this.port.ids.session();
+        const cwd = this.port.journal.getSession(parentId)?.cwd;
+        if (!cwd)
+            throw new SessionError('internal', `Session ${parentId} has no working directory`);
+        const child = { childId, parentId, description, outcome: null, collected: false, waiters: new Set() };
+        this.children.set(childId, child);
+        parent.delegatedStarted({ subagentId: childId, description, agentType: params.agentType ?? `${runtime.driver}:${runtime.model}`, prompt: params.prompt, driver: runtime.driver, model: runtime.model });
+        try {
+            await this.port.open({
+                sessionId: childId,
+                driver: runtime.driver,
+                model: runtime.model,
+                ...(runtime.effort ? { effort: runtime.effort } : {}),
+                cwd,
+                systemPrompt: SYSTEM_PROMPT,
+                // Depth 1: a delegated sub-agent works alone, with the parent's permissions and MCP servers.
+                policy: { subagents: 'disabled', permissions: policy.permissions, mcp: { servers: policy.mcp.servers, inheritUserScope: policy.mcp.inheritUserScope } },
+                metadata: { parentSessionId: parentId, delegated: true, description },
+            });
+            await this.port.send(childId, { inputId: this.port.ids.input(), text: this.composePrompt(parentId, params), delivery: 'queue' });
+        }
+        catch (error) {
+            this.finish(child, { status: 'failed', text: '', usage: null, reason: error.message.slice(0, 300) });
+            throw error;
+        }
+        return { subagentId: childId };
+    }
+    /** Resolve with finished results, or with what still runs when the timeout elapses. */
+    async wait(parentId, subagentIds, timeoutMs) {
+        const targets = [...this.children.values()].filter((child) => child.parentId === parentId && (!subagentIds || subagentIds.includes(child.childId)));
+        const pending = targets.filter((child) => !child.outcome);
+        if (pending.length > 0) {
+            await new Promise((resolve) => {
+                const timer = setTimeout(done, Math.max(0, timeoutMs));
+                timer.unref?.();
+                function done() { clearTimeout(timer); for (const child of pending)
+                    child.waiters.delete(check); resolve(); }
+                function check() { if (pending.every((child) => child.outcome))
+                    done(); }
+                for (const child of pending)
+                    child.waiters.add(check);
+            });
+        }
+        const finished = targets.filter((child) => child.outcome);
+        for (const child of finished)
+            child.collected = true;
+        this.parentIfOpen(parentId)?.collectDelegated(finished.map((child) => child.childId));
+        return {
+            results: finished.map((child) => ({ subagentId: child.childId, description: child.description, status: child.outcome.status, result: child.outcome.text || `It ended without a result (${child.outcome.reason ?? child.outcome.status}).` })),
+            running: targets.filter((child) => !child.outcome).map((child) => child.childId),
+        };
+    }
+    /** Delegated ids among `ids` (all of the parent's when omitted), stopped. */
+    async stop(parentId, ids, reason = 'host_request') {
+        const targets = [...this.children.values()].filter((child) => child.parentId === parentId && !child.outcome && (!ids || ids.includes(child.childId)));
+        await Promise.all(targets.map(async (child) => {
+            this.finish(child, { status: 'stopped', text: '', usage: null, reason });
+            await this.port.interrupt(child.childId).catch(() => undefined);
+            await this.port.close(child.childId, 'delegation_stopped').catch(() => undefined);
+        }));
+        return targets.map((child) => child.childId);
+    }
+    /** The parent session is closing: its delegated work ends with it. */
+    async closeParent(parentId) {
+        await this.stop(parentId, undefined, 'host_request');
+        for (const [childId, child] of this.children)
+            if (child.parentId === parentId)
+                this.children.delete(childId);
+    }
+    isDelegated(subagentId) {
+        return this.children.has(subagentId);
+    }
+    /** Mirror committed child events into the parent's tree. */
+    observe(envelopes) {
+        for (const envelope of envelopes) {
+            const child = this.children.get(envelope.sessionId);
+            if (!child || child.outcome)
+                continue;
+            const event = envelope.event;
+            const parent = this.parentIfOpen(child.parentId);
+            switch (event.type) {
+                case 'turn.output':
+                    if (event.channel === 'text')
+                        parent?.delegatedOutput(child.childId, { channel: 'text', delta: event.delta });
+                    break;
+                case 'turn.tool': {
+                    const { type: _type, turnId: _turnId, at: _at, ...tool } = event;
+                    parent?.delegatedOutput(child.childId, { channel: 'tool', tool });
+                    break;
+                }
+                case 'turn.completed':
+                    this.finish(child, { status: event.status, text: event.text, usage: event.usage, ...(event.error ? { reason: event.error.slice(0, 300) } : {}) });
+                    // Its work is done: release the child's provider process and session.
+                    void this.port.close(child.childId, 'delegation_finished').catch(() => undefined);
+                    break;
+                case 'session.closed':
+                    this.finish(child, { status: 'interrupted', text: '', usage: null, reason: event.reason });
+                    break;
+            }
+        }
+    }
+    finish(child, outcome) {
+        if (child.outcome)
+            return;
+        child.outcome = outcome;
+        this.parentIfOpen(child.parentId)?.delegatedFinished(child.childId, { ...outcome, collected: child.collected });
+        for (const waiter of [...child.waiters])
+            waiter();
+    }
+    parentIfOpen(parentId) {
+        try {
+            return this.port.parent(parentId);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** The task, optionally preceded by the parent's recent conversation. */
+    composePrompt(parentId, params) {
+        const turns = Math.min(Math.max(params.contextTurns ?? 0, 0), MAX_CONTEXT_TURNS);
+        if (turns === 0)
+            return params.prompt;
+        const lines = [];
+        let after = Math.max(0, this.port.snapshot(parentId).lastSeq - 5_000);
+        for (;;) {
+            const page = this.port.journal.read(parentId, after, 1_000);
+            for (const { event } of page.events) {
+                if (event.type === 'input.accepted')
+                    lines.push(`User: ${event.text}`);
+                if (event.type === 'turn.completed' && event.text)
+                    lines.push(`Agent: ${event.text}`);
+            }
+            if (!page.hasMore || page.events.length === 0)
+                break;
+            after = page.events.at(-1).seq;
+        }
+        const context = lines.slice(-turns * 2).map((line) => line.slice(0, 4_000)).join('\n\n');
+        return context ? `Context from the delegating agent's conversation:\n\n${context}\n\n---\n\nYour task:\n${params.prompt}` : params.prompt;
+    }
+}

package/dist/agent-runtime/session/application/output-buffer.d.ts

@@ -0,0 +1,43 @@
+import type { SessionEventBody } from '../domain/events.js';
+import type { OutputChannel } from '../domain/types.js';
+export interface OutputLimits {
+    /** Flush buffered deltas once they reach this many characters. */
+    flushChars: number;
+    /** Stored characters per turn before output is elided. */
+    turnCap: number;
+    /** Stored characters per sub-agent before output is elided. */
+    subagentCap: number;
+}
+export declare const DEFAULT_OUTPUT_LIMITS: OutputLimits;
+/**
+ * Coalesces streaming text deltas and enforces per-turn / per-sub-agent caps.
+ * Deltas for the same target are merged until a size threshold, a timer, or any
+ * non-delta event forces a flush (which preserves ordering). Beyond the cap,
+ * deltas are counted but not stored; `drain*` reports one `output.truncated`.
+ */
+export declare class OutputBuffer {
+    private readonly limits;
+    private readonly pending;
+    private readonly budgets;
+    constructor(limits?: OutputLimits);
+    /** Buffer a delta. Returns events that must be committed now (size-based flush). */
+    add(body: {
+        type: 'turn.output';
+        turnId: string;
+        channel: OutputChannel;
+        delta: string;
+    } | {
+        type: 'subagent.output';
+        subagentId: string;
+        channel: 'text';
+        delta: string;
+    }): SessionEventBody[];
+    hasPending(): boolean;
+    /** All buffered deltas, in first-buffered order. */
+    flush(): SessionEventBody[];
+    /** Truncation report for a finished turn (and forget its budget). */
+    drainTurn(turnId: string): SessionEventBody[];
+    /** Truncation report for a sub-agent that stopped running (and reset its budget). */
+    drainSubagent(subagentId: string): SessionEventBody[];
+    private drain;
+}

package/dist/agent-runtime/session/application/output-buffer.js

@@ -0,0 +1,65 @@
+export const DEFAULT_OUTPUT_LIMITS = Object.freeze({ flushChars: 4_096, turnCap: 4 * 1024 * 1024, subagentCap: 1024 * 1024 });
+/**
+ * Coalesces streaming text deltas and enforces per-turn / per-sub-agent caps.
+ * Deltas for the same target are merged until a size threshold, a timer, or any
+ * non-delta event forces a flush (which preserves ordering). Beyond the cap,
+ * deltas are counted but not stored; `drain*` reports one `output.truncated`.
+ */
+export class OutputBuffer {
+    limits;
+    pending = new Map();
+    budgets = new Map();
+    constructor(limits = DEFAULT_OUTPUT_LIMITS) {
+        this.limits = limits;
+    }
+    /** Buffer a delta. Returns events that must be committed now (size-based flush). */
+    add(body) {
+        const scope = body.type === 'turn.output' ? { turnId: body.turnId } : { subagentId: body.subagentId };
+        const budgetKey = body.type === 'turn.output' ? `turn:${body.turnId}` : `subagent:${body.subagentId}`;
+        const cap = body.type === 'turn.output' ? this.limits.turnCap : this.limits.subagentCap;
+        const budget = this.budgets.get(budgetKey) ?? { stored: 0, droppedEvents: 0, droppedBytes: 0, scope };
+        this.budgets.set(budgetKey, budget);
+        if (budget.stored + body.delta.length > cap) {
+            budget.droppedEvents += 1;
+            budget.droppedBytes += body.delta.length;
+            return [];
+        }
+        budget.stored += body.delta.length;
+        const key = `${budgetKey}:${body.channel}`;
+        const existing = this.pending.get(key);
+        if (existing)
+            existing.body.delta += body.delta;
+        else
+            this.pending.set(key, { body: { ...body } });
+        const current = this.pending.get(key);
+        if (current.body.delta.length >= this.limits.flushChars) {
+            this.pending.delete(key);
+            return [current.body];
+        }
+        return [];
+    }
+    hasPending() {
+        return this.pending.size > 0;
+    }
+    /** All buffered deltas, in first-buffered order. */
+    flush() {
+        const bodies = [...this.pending.values()].map((entry) => entry.body);
+        this.pending.clear();
+        return bodies;
+    }
+    /** Truncation report for a finished turn (and forget its budget). */
+    drainTurn(turnId) {
+        return this.drain(`turn:${turnId}`);
+    }
+    /** Truncation report for a sub-agent that stopped running (and reset its budget). */
+    drainSubagent(subagentId) {
+        return this.drain(`subagent:${subagentId}`);
+    }
+    drain(key) {
+        const budget = this.budgets.get(key);
+        this.budgets.delete(key);
+        if (!budget || budget.droppedEvents === 0)
+            return [];
+        return [{ type: 'output.truncated', scope: budget.scope, droppedEvents: budget.droppedEvents, droppedBytes: budget.droppedBytes }];
+    }
+}

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

@@ -0,0 +1,121 @@
+import type { SessionEventEnvelope } from '../domain/events.js';
+import { type SessionPolicyInput } from '../domain/policy.js';
+import { type SessionSnapshot } from '../domain/snapshot.js';
+import type { Attachment, DriverDescriptor } from '../domain/types.js';
+import type { RateCard } from '../domain/usage.js';
+import type { Clock, DriverCatalog, Ids, SessionJournal, SessionSummary } from '../ports.js';
+import { type DelegateParams, type DelegatedResult } from './delegation.js';
+import type { OutputLimits } from './output-buffer.js';
+export interface SessionServiceOptions {
+    journal: SessionJournal;
+    drivers: DriverCatalog;
+    clock: Clock;
+    ids: Ids;
+    /** Host-supplied rate cards for estimating cost when a provider reports none. */
+    rateCard?: (driver: string, model: string) => RateCard | null;
+    /** Resident processes kept alive while idle; busy sessions are never evicted. */
+    maxResident?: number;
+    outputLimits?: OutputLimits;
+    interruptGraceMs?: number;
+}
+export interface OpenParams {
+    sessionId?: string;
+    /** Reattach to an open session of this scope (e.g. after a host restart). */
+    resume?: {
+        sessionId: string;
+    };
+    driver: string;
+    model: string;
+    effort?: string;
+    cwd: string;
+    systemPrompt?: string;
+    policy: SessionPolicyInput;
+    /** Continue an existing provider conversation (e.g. a session created before Core sessions existed). */
+    providerSessionRef?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface SendParams {
+    inputId: string;
+    text: string;
+    attachments?: Attachment[];
+    delivery: 'queue' | 'steer';
+}
+export type SessionListener = (envelopes: SessionEventEnvelope[]) => void;
+export declare 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 declare class SessionService {
+    private readonly options;
+    private readonly active;
+    private readonly locks;
+    private readonly listeners;
+    private shuttingDown;
+    private readonly delegation;
+    constructor(options: SessionServiceOptions);
+    drivers(): DriverDescriptor[];
+    subscribe(listener: SessionListener): () => void;
+    /**
+     * Mark work a previous host left running as interrupted. Called once at
+     * startup before serving requests; never starts a provider process.
+     */
+    recover(reason?: 'restart' | 'host_lost'): string[];
+    open(params: OpenParams): Promise<{
+        sessionId: string;
+        snapshot: SessionSnapshot;
+    }>;
+    send(sessionId: string, input: SendParams): Promise<{
+        inputId: string;
+        state: string;
+    }>;
+    interrupt(sessionId: string): Promise<{
+        turnId: string | null;
+    }>;
+    stopSubagents(sessionId: string, subagentIds?: string[]): Promise<{
+        stopped: string[];
+    }>;
+    /** Launch a sub-agent as a child session (delegated runtime). */
+    delegate(sessionId: string, params: DelegateParams): Promise<{
+        subagentId: string;
+    }>;
+    /** Wait for delegated sub-agents; never holds the session lock while waiting. */
+    waitSubagents(sessionId: string, subagentIds: string[] | undefined, timeoutMs: number): Promise<{
+        results: DelegatedResult[];
+        running: string[];
+    }>;
+    update(sessionId: string, changes: {
+        model?: string;
+        effort?: string;
+        systemPrompt?: string;
+        policy?: SessionPolicyInput;
+    }): Promise<{
+        outcome: 'applied' | 'deferred';
+    }>;
+    close(sessionId: string, reason: string): Promise<void>;
+    snapshot(sessionId: string): SessionSnapshot;
+    events(sessionId: string, afterSeq: number, limit?: number): {
+        events: SessionEventEnvelope[];
+        nextSeq: number;
+        hasMore: boolean;
+    };
+    list(state?: 'open' | 'closed' | 'all'): SessionSummary[];
+    stats(): {
+        sessions: number;
+        residentProcesses: number;
+    };
+    /** Retire every provider process; running work is recorded as interrupted. */
+    shutdown(): Promise<void>;
+    private resume;
+    private activate;
+    private session;
+    private configFrom;
+    private deps;
+    private requireFactory;
+    /** Keep-alive cap: retire least-recently-used idle processes; never busy ones. */
+    private enforceResidentCap;
+    private publish;
+    /** Serialize operations per session. */
+    private exclusive;
+    private assertRunning;
+}