@kbediako/codex-orchestrator 0.1.0

package/dist/packages/orchestrator/src/exec/handle-service.js

@@ -0,0 +1,203 @@
+import { randomUUID } from 'node:crypto';
+const DEFAULT_MAX_STORED_FRAMES = 500;
+const DEFAULT_MAX_QUEUE_SIZE = 32;
+export class RemoteExecHandleService {
+    handles = new Map();
+    maxStoredFrames;
+    now;
+    guard;
+    constructor(options = {}) {
+        this.maxStoredFrames = options.maxStoredFrames ?? DEFAULT_MAX_STORED_FRAMES;
+        this.now = options.now ?? (() => new Date());
+        this.guard = options.guard;
+    }
+    setGuard(guard) {
+        this.guard = guard;
+    }
+    issueHandle(correlationId) {
+        const id = randomUUID();
+        const createdAt = this.now().toISOString();
+        const handle = {
+            id,
+            correlationId,
+            createdAt,
+            frames: [],
+            status: 'open',
+            observers: new Map(),
+            nextSequence: 1,
+            decisions: []
+        };
+        this.handles.set(id, handle);
+        return this.describeHandle(handle);
+    }
+    async append(handleId, event) {
+        const handle = this.getHandle(handleId);
+        if (handle.status === 'closed') {
+            return;
+        }
+        const frame = {
+            sequence: handle.nextSequence,
+            event,
+            timestamp: event.timestamp
+        };
+        handle.nextSequence += 1;
+        const processed = this.guard
+            ? await this.guard.process(frame, { handleId })
+            : { frame, decision: { action: 'allow' } };
+        handle.decisions.push({ sequence: frame.sequence, decision: processed.decision });
+        if (processed.frame) {
+            handle.frames.push(processed.frame);
+            if (handle.frames.length > this.maxStoredFrames) {
+                handle.frames.splice(0, handle.frames.length - this.maxStoredFrames);
+            }
+            this.notifyObservers(handle, processed.frame);
+        }
+        this.pruneDecisions(handle);
+    }
+    close(handleId) {
+        const handle = this.getHandle(handleId);
+        handle.status = 'closed';
+    }
+    subscribe(handleId, observerId, options, onFrame) {
+        const handle = this.getHandle(handleId);
+        const state = {
+            id: observerId,
+            queue: [],
+            maxQueueSize: Math.max(1, options.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE),
+            delivered: 0,
+            dropped: 0,
+            flushing: false,
+            callback: onFrame
+        };
+        handle.observers.set(observerId, state);
+        // Replay frames from requested sequence.
+        const fromSequence = options.fromSequence ?? 1;
+        const startIndex = this.findFrameStartIndex(handle.frames, fromSequence);
+        for (let index = startIndex; index < handle.frames.length; index += 1) {
+            const frame = handle.frames[index];
+            if (!frame) {
+                continue;
+            }
+            this.enqueueFrame(state, frame);
+        }
+        const unsubscribe = () => {
+            handle.observers.delete(observerId);
+        };
+        return {
+            unsubscribe,
+            stats: () => ({ delivered: state.delivered, dropped: state.dropped })
+        };
+    }
+    getSnapshot(handleId, fromSequence = 1) {
+        const handle = this.getHandle(handleId);
+        const startIndex = this.findFrameStartIndex(handle.frames, fromSequence);
+        return handle.frames.slice(startIndex);
+    }
+    getDescriptor(handleId) {
+        const handle = this.getHandle(handleId);
+        return this.describeHandle(handle);
+    }
+    getDecisions(handleId) {
+        const handle = this.getHandle(handleId);
+        return [...handle.decisions];
+    }
+    getHandle(handleId) {
+        const handle = this.handles.get(handleId);
+        if (!handle) {
+            throw new Error(`Exec handle ${handleId} not found.`);
+        }
+        return handle;
+    }
+    enqueueFrame(observer, frame) {
+        if (observer.queue.length >= observer.maxQueueSize) {
+            observer.queue.shift();
+            observer.dropped += 1;
+        }
+        observer.queue.push(frame);
+        this.flush(observer);
+    }
+    notifyObservers(handle, frame) {
+        for (const observer of handle.observers.values()) {
+            this.enqueueFrame(observer, frame);
+        }
+    }
+    flush(observer) {
+        if (observer.flushing) {
+            return;
+        }
+        observer.flushing = true;
+        queueMicrotask(() => {
+            observer.flushing = false;
+            while (observer.queue.length > 0) {
+                const frame = observer.queue.shift();
+                if (!frame) {
+                    continue;
+                }
+                observer.delivered += 1;
+                observer.callback(frame);
+            }
+        });
+    }
+    describeHandle(handle) {
+        return {
+            id: handle.id,
+            correlationId: handle.correlationId,
+            createdAt: handle.createdAt,
+            frameCount: handle.frames.length,
+            status: handle.status,
+            latestSequence: handle.nextSequence - 1
+        };
+    }
+    pruneDecisions(handle) {
+        if (handle.decisions.length === 0) {
+            return;
+        }
+        if (this.maxStoredFrames <= 0) {
+            handle.decisions.length = 0;
+            return;
+        }
+        const slidingMinSequence = Math.max(1, handle.nextSequence - this.maxStoredFrames);
+        const preservedSequences = new Set();
+        for (const frame of handle.frames) {
+            preservedSequences.add(frame.sequence);
+        }
+        let writeIndex = 0;
+        for (let index = 0; index < handle.decisions.length; index += 1) {
+            const entry = handle.decisions[index];
+            if (!entry) {
+                continue;
+            }
+            const keep = entry.sequence >= slidingMinSequence || preservedSequences.has(entry.sequence);
+            if (keep) {
+                handle.decisions[writeIndex] = entry;
+                writeIndex += 1;
+            }
+        }
+        if (writeIndex < handle.decisions.length) {
+            handle.decisions.length = writeIndex;
+        }
+    }
+    findFrameStartIndex(frames, fromSequence) {
+        if (fromSequence <= 1 || frames.length === 0) {
+            return 0;
+        }
+        let low = 0;
+        let high = frames.length - 1;
+        let result = frames.length;
+        while (low <= high) {
+            const mid = (low + high) >> 1;
+            const frame = frames[mid];
+            if (!frame) {
+                break;
+            }
+            if (frame.sequence >= fromSequence) {
+                result = mid;
+                high = mid - 1;
+            }
+            else {
+                low = mid + 1;
+            }
+        }
+        return result;
+    }
+}

package/dist/packages/orchestrator/src/exec/session-manager.js

@@ -0,0 +1,147 @@
+import { EventEmitter } from 'node:events';
+import { randomUUID } from 'node:crypto';
+/**
+ * Manages reusable exec sessions (e.g. PTY handles) keyed by identifier while
+ * providing lifecycle hooks and environment snapshots for observability.
+ */
+export class ExecSessionManager {
+    sessions = new Map();
+    emitter = new EventEmitter({ captureRejections: false });
+    factory;
+    baseEnv;
+    now;
+    idGenerator;
+    constructor(options) {
+        this.factory = options.factory;
+        this.baseEnv = options.baseEnv ? { ...options.baseEnv } : { ...process.env };
+        this.now = options.now ?? (() => new Date());
+        this.idGenerator = options.idGenerator ?? (() => randomUUID());
+    }
+    async acquire(options = {}) {
+        const id = options.id ?? this.idGenerator();
+        const reuse = options.reuse ?? Boolean(options.id);
+        const persisted = options.persist ?? Boolean(options.id);
+        const envSnapshot = this.snapshotEnv(options.env);
+        if (persisted && reuse) {
+            const existing = this.sessions.get(id);
+            if (existing) {
+                existing.lastUsedAt = this.now().toISOString();
+                if (options.env !== undefined) {
+                    existing.envSnapshot = envSnapshot;
+                }
+                return this.createLease(existing, true, persisted);
+            }
+        }
+        if (!reuse && persisted) {
+            await this.dispose(id);
+        }
+        const managed = await this.createSession(id, envSnapshot, persisted);
+        if (persisted) {
+            this.sessions.set(id, managed);
+        }
+        return this.createLease(managed, false, persisted);
+    }
+    async dispose(id) {
+        const session = this.sessions.get(id);
+        if (!session) {
+            return;
+        }
+        this.sessions.delete(id);
+        await this.teardown(session);
+    }
+    async disposeAll() {
+        const disposals = Array.from(this.sessions.values()).map((session) => this.teardown(session));
+        this.sessions.clear();
+        await Promise.all(disposals);
+    }
+    getSnapshot(id) {
+        const session = this.sessions.get(id);
+        return session ? { ...session.envSnapshot } : undefined;
+    }
+    on(event, listener) {
+        this.emitter.on(event, listener);
+        return () => {
+            this.emitter.off(event, listener);
+        };
+    }
+    async createSession(id, envSnapshot, persisted) {
+        const createdAt = this.now().toISOString();
+        const handle = await this.factory({
+            id,
+            env: envSnapshot,
+            persisted,
+            createdAt
+        });
+        const managed = {
+            id,
+            handle,
+            envSnapshot,
+            createdAt,
+            lastUsedAt: createdAt,
+            persisted
+        };
+        this.emit('session:created', managed);
+        return managed;
+    }
+    createLease(session, reused, persisted) {
+        return {
+            id: session.id,
+            handle: session.handle,
+            envSnapshot: { ...session.envSnapshot },
+            createdAt: session.createdAt,
+            lastUsedAt: session.lastUsedAt,
+            persisted,
+            reused,
+            release: async () => {
+                if (!persisted) {
+                    await this.teardown(session);
+                }
+                else {
+                    session.lastUsedAt = this.now().toISOString();
+                }
+            }
+        };
+    }
+    async teardown(session) {
+        try {
+            await session.handle.dispose();
+        }
+        finally {
+            session.lastUsedAt = this.now().toISOString();
+            this.emit('session:disposed', session);
+        }
+    }
+    emit(event, session) {
+        const payload = {
+            type: event,
+            session: {
+                id: session.id,
+                envSnapshot: { ...session.envSnapshot },
+                createdAt: session.createdAt,
+                lastUsedAt: session.lastUsedAt,
+                persisted: session.persisted,
+                handle: session.handle
+            }
+        };
+        this.emitter.emit(event, payload);
+    }
+    snapshotEnv(overrides) {
+        const snapshot = {};
+        for (const [key, value] of Object.entries(this.baseEnv)) {
+            if (typeof value === 'string') {
+                snapshot[key] = value;
+            }
+        }
+        if (overrides) {
+            for (const [key, value] of Object.entries(overrides)) {
+                if (value === undefined) {
+                    delete snapshot[key];
+                }
+                else {
+                    snapshot[key] = value;
+                }
+            }
+        }
+        return snapshot;
+    }
+}