@methodts/runtime 0.1.0

package/dist/sessions/diagnostics.js

@@ -0,0 +1,129 @@
+// SPDX-License-Identifier: Apache-2.0
+// ── PRD 012 Phase 1: Diagnostic Instrumentation ─────────────────
+// Per-session timing metrics and stall detection.
+/**
+ * Per-session diagnostics tracker. Created at spawn, collects metrics
+ * throughout the session lifetime, produces snapshots on demand.
+ */
+export class DiagnosticsTracker {
+    spawnedAt;
+    firstOutputAt = null;
+    firstToolAt = null;
+    _toolCallCount = 0;
+    _totalSettleOverheadMs = 0;
+    _falsePositiveSettles = 0;
+    _settleDelayMs;
+    _idleTransitions = 0;
+    _longestIdleMs = 0;
+    _idleStartedAt = null;
+    _permissionPromptDetected = false;
+    /** PRD 012 Phase 2: Optional adaptive settle reference for dynamic metrics. */
+    _adaptiveSettle;
+    constructor(settleDelayMs, adaptiveSettle) {
+        this.spawnedAt = Date.now();
+        this._settleDelayMs = settleDelayMs;
+        this._adaptiveSettle = adaptiveSettle ?? null;
+    }
+    /** Called on first PTY data chunk. */
+    recordFirstOutput() {
+        if (this.firstOutputAt === null) {
+            this.firstOutputAt = Date.now();
+        }
+    }
+    /** Called when PTY watcher detects a tool call. */
+    recordToolCall() {
+        this._toolCallCount++;
+        if (this.firstToolAt === null) {
+            this.firstToolAt = Date.now();
+        }
+        // Tool call ends any idle period
+        this.endIdlePeriod();
+    }
+    /** Called when PTY watcher detects an idle transition (prompt char after activity). */
+    recordIdleTransition() {
+        this._idleTransitions++;
+        this._idleStartedAt = Date.now();
+    }
+    /** Called when any non-idle activity is detected — ends the current idle period. */
+    recordActivity() {
+        this.endIdlePeriod();
+    }
+    /** Called when a permission prompt is detected in PTY output. */
+    recordPermissionPrompt() {
+        this._permissionPromptDetected = true;
+    }
+    /** Called after each prompt response completes. Adds one settle wait to overhead. */
+    recordPromptCompletion() {
+        // PRD 012 Phase 2: Use adaptive delay if available, otherwise fixed
+        const effectiveDelay = this._adaptiveSettle
+            ? this._adaptiveSettle.delayMs
+            : this._settleDelayMs;
+        this._totalSettleOverheadMs += effectiveDelay;
+    }
+    /** Returns current diagnostics snapshot. */
+    snapshot() {
+        // Compute longest idle including current idle period if active
+        let longestIdle = this._longestIdleMs;
+        if (this._idleStartedAt !== null) {
+            const currentIdle = Date.now() - this._idleStartedAt;
+            if (currentIdle > longestIdle)
+                longestIdle = currentIdle;
+        }
+        return {
+            time_to_first_output_ms: this.firstOutputAt !== null
+                ? this.firstOutputAt - this.spawnedAt
+                : null,
+            time_to_first_tool_ms: this.firstToolAt !== null
+                ? this.firstToolAt - this.spawnedAt
+                : null,
+            tool_call_count: this._toolCallCount,
+            total_settle_overhead_ms: this._totalSettleOverheadMs,
+            // PRD 012 Phase 2: Report false positives from adaptive settle
+            false_positive_settles: this._adaptiveSettle
+                ? this._adaptiveSettle.falsePositiveCount
+                : this._falsePositiveSettles,
+            // PRD 012 Phase 2: Report current adaptive delay if available
+            current_settle_delay_ms: this._adaptiveSettle
+                ? this._adaptiveSettle.delayMs
+                : this._settleDelayMs,
+            idle_transitions: this._idleTransitions,
+            longest_idle_ms: longestIdle,
+            permission_prompt_detected: this._permissionPromptDetected,
+            stall_reason: null, // Computed externally by pool when session is idle
+        };
+    }
+    /**
+     * Classify the stall reason for an idle session.
+     * Called by the pool when building status for a stale/idle session.
+     *
+     * PRD 012 heuristic:
+     * - No tool calls ever → permission_blocked
+     * - Tool calls + many idle transitions → task_complexity
+     * - Slow first output + other agents slow → resource_contention
+     * - None of above → unknown
+     */
+    classifyStall(otherSessionsSlow) {
+        if (this.firstToolAt === null) {
+            return 'permission_blocked';
+        }
+        if (this._toolCallCount > 0 && this._idleTransitions > 3) {
+            return 'task_complexity';
+        }
+        if (this.firstOutputAt !== null
+            && (this.firstOutputAt - this.spawnedAt) > 10_000
+            && otherSessionsSlow) {
+            return 'resource_contention';
+        }
+        return 'unknown';
+    }
+    endIdlePeriod() {
+        if (this._idleStartedAt !== null) {
+            const idleDuration = Date.now() - this._idleStartedAt;
+            if (idleDuration > this._longestIdleMs) {
+                this._longestIdleMs = idleDuration;
+            }
+            this._idleStartedAt = null;
+        }
+    }
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/sessions/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/sessions/diagnostics.ts"],"names":[],"mappings":"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"}

package/dist/sessions/diagnostics.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=diagnostics.test.d.ts.map

package/dist/sessions/diagnostics.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.test.d.ts","sourceRoot":"","sources":["../../src/sessions/diagnostics.test.ts"],"names":[],"mappings":""}

package/dist/sessions/diagnostics.test.js

@@ -0,0 +1,135 @@
+// SPDX-License-Identifier: Apache-2.0
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { DiagnosticsTracker } from './diagnostics.js';
+// ── DiagnosticsTracker Unit Tests ────────────────────────────────
+describe('DiagnosticsTracker (PRD 012)', () => {
+    let tracker;
+    beforeEach(() => {
+        tracker = new DiagnosticsTracker(1000);
+    });
+    describe('initial state', () => {
+        it('returns null for timing fields before any output', () => {
+            const snap = tracker.snapshot();
+            assert.equal(snap.time_to_first_output_ms, null);
+            assert.equal(snap.time_to_first_tool_ms, null);
+            assert.equal(snap.tool_call_count, 0);
+            assert.equal(snap.total_settle_overhead_ms, 0);
+            assert.equal(snap.false_positive_settles, 0);
+            assert.equal(snap.current_settle_delay_ms, 1000);
+            assert.equal(snap.idle_transitions, 0);
+            assert.equal(snap.longest_idle_ms, 0);
+            assert.equal(snap.permission_prompt_detected, false);
+            assert.equal(snap.stall_reason, null);
+        });
+    });
+    describe('recordFirstOutput()', () => {
+        it('records time_to_first_output_ms', () => {
+            tracker.recordFirstOutput();
+            const snap = tracker.snapshot();
+            assert.ok(snap.time_to_first_output_ms !== null);
+            assert.ok(snap.time_to_first_output_ms >= 0);
+        });
+        it('only records the first output', () => {
+            tracker.recordFirstOutput();
+            const first = tracker.snapshot().time_to_first_output_ms;
+            // Small delay
+            tracker.recordFirstOutput();
+            const second = tracker.snapshot().time_to_first_output_ms;
+            assert.equal(first, second);
+        });
+    });
+    describe('recordToolCall()', () => {
+        it('increments tool_call_count', () => {
+            tracker.recordToolCall();
+            tracker.recordToolCall();
+            tracker.recordToolCall();
+            assert.equal(tracker.snapshot().tool_call_count, 3);
+        });
+        it('records time_to_first_tool_ms', () => {
+            tracker.recordToolCall();
+            const snap = tracker.snapshot();
+            assert.ok(snap.time_to_first_tool_ms !== null);
+            assert.ok(snap.time_to_first_tool_ms >= 0);
+        });
+        it('only records timing for first tool call', () => {
+            tracker.recordToolCall();
+            const first = tracker.snapshot().time_to_first_tool_ms;
+            tracker.recordToolCall();
+            const second = tracker.snapshot().time_to_first_tool_ms;
+            assert.equal(first, second);
+        });
+    });
+    describe('recordIdleTransition()', () => {
+        it('increments idle_transitions count', () => {
+            tracker.recordIdleTransition();
+            tracker.recordIdleTransition();
+            assert.equal(tracker.snapshot().idle_transitions, 2);
+        });
+        it('tracks longest idle period', async () => {
+            tracker.recordIdleTransition();
+            // Wait a bit to accumulate idle time
+            await new Promise(r => setTimeout(r, 20));
+            tracker.recordActivity(); // End idle period
+            const snap = tracker.snapshot();
+            assert.ok(snap.longest_idle_ms >= 15); // at least ~15ms
+        });
+        it('includes current idle in longest_idle_ms if still idle', async () => {
+            tracker.recordIdleTransition();
+            await new Promise(r => setTimeout(r, 20));
+            // Don't end idle — snapshot should include current idle
+            const snap = tracker.snapshot();
+            assert.ok(snap.longest_idle_ms >= 15);
+        });
+    });
+    describe('recordPermissionPrompt()', () => {
+        it('sets permission_prompt_detected to true', () => {
+            assert.equal(tracker.snapshot().permission_prompt_detected, false);
+            tracker.recordPermissionPrompt();
+            assert.equal(tracker.snapshot().permission_prompt_detected, true);
+        });
+    });
+    describe('recordPromptCompletion()', () => {
+        it('accumulates settle overhead', () => {
+            tracker.recordPromptCompletion();
+            assert.equal(tracker.snapshot().total_settle_overhead_ms, 1000);
+            tracker.recordPromptCompletion();
+            assert.equal(tracker.snapshot().total_settle_overhead_ms, 2000);
+        });
+    });
+    describe('classifyStall()', () => {
+        it('returns permission_blocked when no tool calls ever detected', () => {
+            // No tool calls recorded
+            const reason = tracker.classifyStall(false);
+            assert.equal(reason, 'permission_blocked');
+        });
+        it('returns task_complexity when tool calls + many idle transitions', () => {
+            tracker.recordToolCall();
+            tracker.recordIdleTransition();
+            tracker.recordIdleTransition();
+            tracker.recordIdleTransition();
+            tracker.recordIdleTransition(); // > 3
+            const reason = tracker.classifyStall(false);
+            assert.equal(reason, 'task_complexity');
+        });
+        it('returns unknown when tool calls present but few idle transitions', () => {
+            tracker.recordToolCall();
+            tracker.recordIdleTransition();
+            // Only 1 idle transition, not > 3
+            const reason = tracker.classifyStall(false);
+            assert.equal(reason, 'unknown');
+        });
+        it('returns resource_contention when slow first output + other sessions slow', () => {
+            // Simulate slow first output: create tracker with known spawn time
+            // We can't easily fake Date.now(), so we test the logic indirectly
+            // by checking that the method accepts otherSessionsSlow parameter
+            tracker.recordFirstOutput();
+            tracker.recordToolCall();
+            // In this case, first output is fast (immediate), so resource_contention won't trigger
+            const reason = tracker.classifyStall(true);
+            // Should be 'unknown' because first output was fast
+            assert.equal(reason, 'unknown');
+        });
+    });
+});
+//# sourceMappingURL=diagnostics.test.js.map

package/dist/sessions/diagnostics.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.test.js","sourceRoot":"","sources":["../../src/sessions/diagnostics.test.ts"],"names":[],"mappings":"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"}

package/dist/sessions/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @methodts/runtime/sessions — session pool + providers + supporting
+ * machinery. PRD-057 / S2 §3.3 / C5 public surface.
+ *
+ * The pool stays transport-free. Bridge provides its PTY-spawning
+ * `SessionProviderFactory` (see `packages/bridge/src/domains/sessions/factory.ts`);
+ * agent-runtime (PRD-058) will provide a Cortex-backed factory.
+ */
+export { createPool } from './pool.js';
+export type { SessionPool, SessionSnapshot, SessionBudget, SessionChainInfo, SessionMode, IsolationMode, WorktreeAction, WorktreeInfo, StaleConfig, SessionStatusInfo, PoolStats, PoolOptions, StreamEvent, } from './pool.js';
+export { createPrintSession } from './print-session.js';
+export type { PtySession, PrintMetadata, SessionStatus, StreamChunkCallback, AdaptiveSettleDelay, PactaSessionParams, PrintSessionOptions, } from './print-session.js';
+export { createCognitiveSession } from './cognitive-provider.js';
+export type { CognitiveSessionConfig, CognitiveSessionOptions, } from './cognitive-provider.js';
+export { createBridgeReasonerActorModule, createBridgeReasonerActorModule as createReasonerActorModule, createBridgeMonitorModule, createBridgeMonitorModule as createMonitorModule, } from './cognitive-modules.js';
+export type { BridgeReasonerActorMonitoring, BridgeMonitorControl, } from './cognitive-modules.js';
+export { CognitiveEventBusSink } from './cognitive-sink.js';
+export { CognitiveEventBusSink as CognitiveSink } from './cognitive-sink.js';
+export type { CognitiveEventContext } from './cognitive-sink.js';
+export { createSessionChannels, appendMessage, readMessages, getChannelRing, ChannelRingBuffer, } from './channels.js';
+export type { SessionChannels, Channel, ChannelMessage } from './channels.js';
+export { DiagnosticsTracker } from './diagnostics.js';
+export type { SessionDiagnostics } from './diagnostics.js';
+export { installScopeHook } from './scope-hook.js';
+export { SpawnQueue } from './spawn-queue.js';
+export type { SpawnQueueOptions } from './spawn-queue.js';
+export { generateAutoRetro } from './auto-retro.js';
+export type { AutoRetroInput, ActivityObservation } from './auto-retro.js';
+export { createRuntimeToolProvider, createBridgeToolProvider, } from './runtime-tools.js';
+export { createCheckpointSink, createInMemorySessionStore, performResume, startLeaseHeartbeat, SESSION_LIFECYCLE_TYPES, SessionStoreError, isSessionStoreError, DEFAULT_SESSION_STORE_FIXTURES, resumeMidTurnFixture, staleLeaseTheftFixture, schemaVersionRejectionFixture, runSessionStoreConformance, } from './session-store/index.js';
+export type { SessionStore, CheckpointSink, CheckpointSinkOptions, CheckpointCapture, Checkpoint, CheckpointMeta, AgentStateBlob, BudgetReservation, EventCursor, NextAction, PactRef, ResumeOptions, ResumeContext, SessionSnapshot as PersistedSessionSnapshot, SessionStoreErrorCode, SessionStoreErrorOptions, BudgetEnforcer, ResumedPact, LeaseHeartbeat, PerformResumeArgs, ResumeOutcome, InMemorySessionStoreOptions, SessionStoreConformanceFixture, SessionStoreFactory, FixtureResult, } from './session-store/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/sessions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sessions/index.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAIH,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,YAAY,EACV,WAAW,EACX,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,aAAa,EACb,cAAc,EACd,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,SAAS,EACT,WAAW,EACX,WAAW,GACZ,MAAM,WAAW,CAAC;AAInB,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,YAAY,EACV,UAAU,EACV,aAAa,EACb,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACjE,YAAY,EACV,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,yBAAyB,CAAC;AAIjC,OAAO,EACL,+BAA+B,EAC/B,+BAA+B,IAAI,yBAAyB,EAC5D,yBAAyB,EACzB,yBAAyB,IAAI,mBAAmB,GACjD,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,6BAA6B,EAC7B,oBAAoB,GACrB,MAAM,wBAAwB,CAAC;AAIhC,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,IAAI,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAC7E,YAAY,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAIjE,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,YAAY,EACZ,cAAc,EACd,iBAAiB,GAClB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAI3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAInD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAI3E,OAAO,EACL,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,aAAa,EACb,mBAAmB,EACnB,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,EACnB,8BAA8B,EAC9B,oBAAoB,EACpB,sBAAsB,EACtB,6BAA6B,EAC7B,0BAA0B,GAC3B,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,YAAY,EACZ,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,WAAW,EACX,UAAU,EACV,OAAO,EACP,aAAa,EACb,aAAa,EACb,eAAe,IAAI,wBAAwB,EAC3C,qBAAqB,EACrB,wBAAwB,EACxB,cAAc,EACd,WAAW,EACX,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,2BAA2B,EAC3B,8BAA8B,EAC9B,mBAAmB,EACnB,aAAa,GACd,MAAM,0BAA0B,CAAC"}

package/dist/sessions/index.js

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * @methodts/runtime/sessions — session pool + providers + supporting
+ * machinery. PRD-057 / S2 §3.3 / C5 public surface.
+ *
+ * The pool stays transport-free. Bridge provides its PTY-spawning
+ * `SessionProviderFactory` (see `packages/bridge/src/domains/sessions/factory.ts`);
+ * agent-runtime (PRD-058) will provide a Cortex-backed factory.
+ */
+// ── Pool ────────────────────────────────────────────────────────
+export { createPool } from './pool.js';
+// ── Print session ───────────────────────────────────────────────
+export { createPrintSession } from './print-session.js';
+// ── Cognitive session ───────────────────────────────────────────
+export { createCognitiveSession } from './cognitive-provider.js';
+// ── Cognitive modules (registrable factories) ───────────────────
+export { createBridgeReasonerActorModule, createBridgeReasonerActorModule as createReasonerActorModule, createBridgeMonitorModule, createBridgeMonitorModule as createMonitorModule, } from './cognitive-modules.js';
+// ── Cognitive event-bus sink (PRD-057 / S2 §14 Q6 rename) ───────
+export { CognitiveEventBusSink } from './cognitive-sink.js';
+export { CognitiveEventBusSink as CognitiveSink } from './cognitive-sink.js';
+// ── Channels + diagnostics ──────────────────────────────────────
+export { createSessionChannels, appendMessage, readMessages, getChannelRing, ChannelRingBuffer, } from './channels.js';
+export { DiagnosticsTracker } from './diagnostics.js';
+// ── Scope enforcement ───────────────────────────────────────────
+export { installScopeHook } from './scope-hook.js';
+// ── Spawn queue + auto-retro ────────────────────────────────────
+export { SpawnQueue } from './spawn-queue.js';
+export { generateAutoRetro } from './auto-retro.js';
+// ── Runtime tool provider (ex bridge-tools) ─────────────────────
+export { createRuntimeToolProvider, createBridgeToolProvider, } from './runtime-tools.js';
+// ── Session store (PRD-061) ─────────────────────────────────────
+export { createCheckpointSink, createInMemorySessionStore, performResume, startLeaseHeartbeat, SESSION_LIFECYCLE_TYPES, SessionStoreError, isSessionStoreError, DEFAULT_SESSION_STORE_FIXTURES, resumeMidTurnFixture, staleLeaseTheftFixture, schemaVersionRejectionFixture, runSessionStoreConformance, } from './session-store/index.js';
+//# sourceMappingURL=index.js.map

package/dist/sessions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sessions/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC;;;;;;;GAOG;AAEH,mEAAmE;AAEnE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAiBvC,mEAAmE;AAEnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAWxD,mEAAmE;AAEnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAMjE,mEAAmE;AAEnE,OAAO,EACL,+BAA+B,EAC/B,+BAA+B,IAAI,yBAAyB,EAC5D,yBAAyB,EACzB,yBAAyB,IAAI,mBAAmB,GACjD,MAAM,wBAAwB,CAAC;AAMhC,mEAAmE;AAEnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,IAAI,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAG7E,mEAAmE;AAEnE,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,YAAY,EACZ,cAAc,EACd,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAGtD,mEAAmE;AAEnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnD,mEAAmE;AAEnE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGpD,mEAAmE;AAEnE,OAAO,EACL,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAE5B,mEAAmE;AAEnE,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,aAAa,EACb,mBAAmB,EACnB,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,EACnB,8BAA8B,EAC9B,oBAAoB,EACpB,sBAAsB,EACtB,6BAA6B,EAC7B,0BAA0B,GAC3B,MAAM,0BAA0B,CAAC"}

package/dist/sessions/pool.d.ts

@@ -0,0 +1,218 @@
+import { type PtySession, type PrintMetadata } from './print-session.js';
+import { type CognitiveSessionConfig } from './cognitive-provider.js';
+import { type SessionChannels } from './channels.js';
+import { type SessionDiagnostics } from './diagnostics.js';
+import type { FileSystemProvider } from '../ports/file-system.js';
+import type { EventBus } from '../ports/event-bus.js';
+import type { SessionProviderFactory } from '../ports/session-pool.js';
+import { CognitiveEventBusSink as CognitiveSink } from './cognitive-sink.js';
+export interface SessionBudget {
+    max_depth: number;
+    max_agents: number;
+    agents_spawned: number;
+}
+export interface SessionChainInfo {
+    parent_session_id: string | null;
+    depth: number;
+    children: string[];
+    budget: SessionBudget;
+}
+export type SessionMode = 'print' | 'cognitive-agent';
+export type IsolationMode = 'worktree' | 'shared';
+export type WorktreeAction = 'merge' | 'keep' | 'discard';
+export interface WorktreeInfo {
+    isolation: IsolationMode;
+    worktree_path: string | null;
+    worktree_branch: string | null;
+    metals_available: boolean;
+}
+export interface StaleConfig {
+    stale_timeout_ms: number;
+    kill_timeout_ms: number;
+}
+export interface SessionStatusInfo {
+    sessionId: string;
+    nickname: string;
+    purpose: string | null;
+    status: string;
+    queueDepth: number;
+    metadata?: Record<string, unknown>;
+    promptCount: number;
+    lastActivityAt: Date;
+    workdir: string;
+    chain: SessionChainInfo;
+    worktree: WorktreeInfo;
+    stale: boolean;
+    waiting_for: string | null;
+    /** PRD 028: Session mode — always 'print' after PTY removal. */
+    mode: SessionMode;
+    /** PRD 012: Per-session diagnostic metrics. */
+    diagnostics: SessionDiagnostics | null;
+}
+export interface PoolStats {
+    totalSpawned: number;
+    startedAt: Date;
+    maxSessions: number;
+    activeSessions: number;
+    deadSessions: number;
+}
+/** PRD 029: Snapshot of a session's state for recovery / restoration. */
+export interface SessionSnapshot {
+    sessionId: string;
+    nickname: string;
+    purpose?: string | null;
+    workdir: string;
+    mode: SessionMode | string;
+    depth: number;
+    parentSessionId?: string | null;
+    isolation: IsolationMode | string;
+    metadata?: Record<string, unknown>;
+    promptCount: number;
+    pid?: number;
+}
+/** SSE stream event emitted during a streaming prompt. */
+export interface StreamEvent {
+    type: 'text' | 'done' | 'error' | 'cycle-start' | 'cycle-action' | 'monitor' | 'affect' | 'memory' | 'reflection';
+    content?: string;
+    output?: string;
+    metadata?: Record<string, unknown> | null;
+    timed_out?: boolean;
+    error?: string;
+    cycle?: number;
+    maxCycles?: number;
+    action?: string;
+    confidence?: number;
+    tokens?: number;
+    intervention?: string;
+    restricted?: string[];
+    label?: string;
+    valence?: number;
+    arousal?: number;
+    retrieved?: number;
+    stored?: number;
+    totalCards?: number;
+    lessons?: string[];
+}
+export interface SessionPool {
+    create(options: {
+        workdir: string;
+        initialPrompt?: string;
+        spawnArgs?: string[];
+        metadata?: Record<string, unknown>;
+        parentSessionId?: string;
+        depth?: number;
+        budget?: Partial<SessionBudget>;
+        isolation?: IsolationMode;
+        timeout_ms?: number;
+        nickname?: string;
+        purpose?: string;
+        persistent?: boolean;
+        spawn_delay_ms?: number;
+        mode?: SessionMode;
+        /** PRD 014: Glob patterns of files the agent is allowed to modify. Empty array = no constraint. */
+        allowed_paths?: string[];
+        /** PRD 014: Scope enforcement mode. 'enforce' installs a pre-commit hook (requires worktree). 'warn' emits events only. Default: 'enforce'. */
+        scope_mode?: 'enforce' | 'warn';
+        /** Optional session ID — if provided, reuses this ID instead of generating a new UUID. Used for resuming sessions with Claude Code's --resume flag. */
+        session_id?: string;
+        /** PRD 033: Provider type — 'print' (default) or 'cognitive-agent'. */
+        provider_type?: 'print' | 'cognitive-agent';
+        /** PRD 033: Cognitive config name (e.g. 'baseline'). Only used when provider_type is 'cognitive-agent'. */
+        cognitive_config?: Partial<CognitiveSessionConfig>;
+        /** PRD 033: Cognitive pattern flags (e.g. ['P5', 'P6']). */
+        cognitive_patterns?: string[];
+        /** LLM provider for cognitive-agent mode. Default: 'anthropic'. */
+        llm_provider?: 'anthropic' | 'ollama';
+        /** LLM provider config overrides (e.g. Ollama baseUrl, model). */
+        llm_config?: {
+            baseUrl?: string;
+            model?: string;
+        };
+        /** PRD 041: Experiment ID for cognitive event tracing — creates a per-session CognitiveSink with context. */
+        experiment_id?: string;
+        /** PRD 041: Run ID for cognitive event tracing — paired with experiment_id. */
+        run_id?: string;
+    }): Promise<{
+        sessionId: string;
+        nickname: string;
+        status: string;
+        chain: SessionChainInfo;
+        worktree: WorktreeInfo;
+        mode: SessionMode;
+    }>;
+    prompt(sessionId: string, prompt: string, timeoutMs?: number, settleDelayMs?: number): Promise<{
+        output: string;
+        timedOut: boolean;
+        metadata: PrintMetadata | null;
+    }>;
+    /**
+     * Streaming prompt — sends a prompt and emits incremental output chunks via callback.
+     * The onEvent callback receives StreamEvent objects as output arrives.
+     * Returns a promise that resolves when the prompt completes.
+     */
+    promptStream(sessionId: string, prompt: string, onEvent: (event: StreamEvent) => void, timeoutMs?: number): Promise<void>;
+    status(sessionId: string): SessionStatusInfo;
+    kill(sessionId: string, worktreeAction?: WorktreeAction): {
+        sessionId: string;
+        killed: boolean;
+        worktree_cleaned: boolean;
+    };
+    list(): SessionStatusInfo[];
+    poolStats(): PoolStats;
+    removeDead(ttlMs: number): number;
+    getChannels(sessionId: string): SessionChannels;
+    getSession(sessionId: string): PtySession;
+    checkStale(): {
+        stale: string[];
+        killed: string[];
+    };
+    /** Return OS PIDs of all live child processes managed by this pool. */
+    childPids(): number[];
+    /** PRD 018: Set a pool-level observation hook for forwarding PTY observations to the trigger system. */
+    setObservationHook(hook: ((observation: {
+        category: string;
+        detail: Record<string, unknown>;
+        session_id: string;
+    }) => void) | null): void;
+    /** PRD 029: Restore a session from a persisted snapshot without spawning a process. */
+    restoreSession(snapshot: SessionSnapshot): void;
+    /** PRD 040 C-3: Kill any cognitive-agent sessions restored during startup — they are in-memory only and cannot survive a restart. */
+    cleanupStaleCognitiveSessions(): {
+        killed: string[];
+    };
+}
+export interface PoolOptions {
+    maxSessions?: number;
+    claudeBin?: string;
+    settleDelayMs?: number;
+    minSpawnGapMs?: number;
+    /** @deprecated PTY provider — no longer used after PTY removal (PRD 028 C-4). */
+    ptyProvider?: unknown;
+    /** @deprecated LLM provider — print-session creates its own provider internally (PRD 028 C-4). */
+    llmProvider?: unknown;
+    /** PRD 024 MG-1: FileSystem provider for auto-retro and other fs operations. */
+    fsProvider?: FileSystemProvider;
+    /** PRD 026: Event bus for unified event emission. */
+    eventBus?: EventBus;
+    /** PRD 041: CognitiveSink for routing typed CognitiveEvents to the event bus. */
+    cognitiveSink?: CognitiveSink;
+    /**
+     * PRD-057 / S2 §6 / C5: Injected session-creation factory. When supplied,
+     * the pool delegates "how does a prompt actually execute" to the factory
+     * (bridge supplies a PTY+print+cognitive factory; agent-runtime supplies a
+     * Cortex-`ctx.llm` factory). When absent, the pool falls back to its
+     * built-in print + cognitive session paths for backwards compatibility
+     * during the migration window.
+     */
+    providerFactory?: SessionProviderFactory;
+}
+/**
+ * Create a session pool that manages multiple Claude Code PTY sessions.
+ *
+ * The pool enforces a maximum session count and provides a uniform interface
+ * for creating, prompting, inspecting, and killing sessions.
+ *
+ * PRD 006: Sessions now track parent-child chains with budget enforcement.
+ */
+export declare function createPool(options?: PoolOptions): SessionPool;
+//# sourceMappingURL=pool.d.ts.map

package/dist/sessions/pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../src/sessions/pool.ts"],"names":[],"mappings":"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"}