@dcyfr/ai 1.0.4 → 2.1.1

package/dist/ai/delegation/session-manager.js

@@ -0,0 +1,243 @@
+/**
+ * DCYFR Session Manager
+ * TLP:AMBER - Internal Use Only
+ *
+ * Lifecycle tracking for delegation sessions.
+ *
+ * Manages:
+ *   - In-memory session store with periodic flush to disk
+ *   - Session state transitions: active → paused → archived
+ *   - Status indicators: unread | in-progress | blocked
+ *   - Archived session persistence at `logs/delegation/sessions/YYYY-MM-DD/<session-id>.jsonl`
+ *
+ * @module delegation/session-manager
+ * @version 1.0.0
+ */
+import { EventEmitter } from 'events';
+import { appendFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+// ─────────────────────────────────────────────────────────────────────────────
+// SessionManager
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Tracks delegation session lifecycle and status indicators.
+ *
+ * Emits:
+ *   - `session:created`   — A new session was registered.
+ *   - `session:updated`   — A session's state or status changed.
+ *   - `session:paused`    — A session transitioned to paused.
+ *   - `session:archived`  — A session was archived (written to disk).
+ *   - `session:blocked`   — A session became blocked.
+ *   - `session:unblocked` — A blocked session was cleared.
+ *   - `flush`             — Periodic background flush completed.
+ */
+export class SessionManager extends EventEmitter {
+    sessions = new Map();
+    archiveBaseDir;
+    flushTimer = null;
+    constructor(options = {}) {
+        super();
+        if (options.archiveBaseDir) {
+            this.archiveBaseDir = options.archiveBaseDir;
+        }
+        else {
+            const thisDir = dirname(fileURLToPath(import.meta.url));
+            const workspaceRoot = join(thisDir, '..', '..', '..', '..', '..', '..');
+            this.archiveBaseDir = join(workspaceRoot, 'logs', 'delegation', 'sessions');
+        }
+        const flushMs = options.flushIntervalMs ?? 60_000;
+        if (flushMs > 0) {
+            this.flushTimer = setInterval(() => this._flushArchived(), flushMs);
+            // Don't block the process for the background flush timer.
+            if (typeof this.flushTimer.unref === 'function') {
+                this.flushTimer.unref();
+            }
+        }
+    }
+    // ─────────────── Lifecycle ───────────────
+    /**
+     * Register a new session (initial status: 'unread', lifecycle: 'active').
+     */
+    register(sessionId, contractId, executionMode, initialState) {
+        const now = new Date().toISOString();
+        const session = {
+            sessionId,
+            contractId,
+            executionMode,
+            lifeCycle: 'active',
+            status: 'unread',
+            state: { ...initialState },
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.sessions.set(sessionId, session);
+        this.emit('session:created', session);
+        return session;
+    }
+    /**
+     * Update the in-memory state for an existing session.
+     * Automatically marks lifecycle as 'active' if it was 'paused'.
+     */
+    updateState(sessionId, newState) {
+        const session = this._requireSession(sessionId);
+        session.state = { ...session.state, ...newState, lastActivity: new Date().toISOString() };
+        session.updatedAt = new Date().toISOString();
+        if (session.lifeCycle === 'paused') {
+            session.lifeCycle = 'active';
+        }
+        this.emit('session:updated', session);
+        return session;
+    }
+    /**
+     * Pause a session (lifecycle: 'paused').
+     */
+    pause(sessionId) {
+        const session = this._requireSession(sessionId);
+        if (session.lifeCycle === 'archived') {
+            throw new Error(`Cannot pause archived session ${sessionId}`);
+        }
+        session.lifeCycle = 'paused';
+        session.state.status = 'paused';
+        session.updatedAt = new Date().toISOString();
+        this.emit('session:paused', session);
+        return session;
+    }
+    /**
+     * Archive a session — transitions to 'archived' and queues disk write.
+     * Archived sessions are dropped from the in-memory store after the next flush.
+     */
+    archive(sessionId) {
+        const session = this._requireSession(sessionId);
+        session.lifeCycle = 'archived';
+        session.state.status = 'archived';
+        session.archivedAt = new Date().toISOString();
+        session.updatedAt = session.archivedAt;
+        this._writeArchivedSession(session);
+        this.sessions.delete(sessionId);
+        this.emit('session:archived', session);
+        return session;
+    }
+    // ─────────────── Status indicators ───────────────
+    /**
+     * Mark a session as 'in-progress' (user has read it and work is active).
+     */
+    markInProgress(sessionId) {
+        const session = this._requireSession(sessionId);
+        session.status = 'in-progress';
+        session.updatedAt = new Date().toISOString();
+        this.emit('session:updated', session);
+        return session;
+    }
+    /**
+     * Mark a session as 'blocked' with an optional reason.
+     */
+    block(sessionId, reason) {
+        const session = this._requireSession(sessionId);
+        session.status = 'blocked';
+        session.blockReason = reason;
+        session.updatedAt = new Date().toISOString();
+        this.emit('session:blocked', session);
+        return session;
+    }
+    /**
+     * Clear a 'blocked' status — transitions back to 'in-progress'.
+     */
+    unblock(sessionId) {
+        const session = this._requireSession(sessionId);
+        if (session.status !== 'blocked')
+            return session;
+        session.status = 'in-progress';
+        delete session.blockReason;
+        session.updatedAt = new Date().toISOString();
+        this.emit('session:unblocked', session);
+        return session;
+    }
+    // ─────────────── Queries ───────────────
+    /** Retrieve a session by ID. Returns `undefined` if not found. */
+    get(sessionId) {
+        return this.sessions.get(sessionId);
+    }
+    /** Return all in-memory sessions. */
+    getAll() {
+        return Array.from(this.sessions.values());
+    }
+    /** Return sessions filtered by lifecycle. */
+    getByLifeCycle(lifeCycle) {
+        return this.getAll().filter((s) => s.lifeCycle === lifeCycle);
+    }
+    /** Return sessions filtered by workflow status. */
+    getByStatus(status) {
+        return this.getAll().filter((s) => s.status === status);
+    }
+    /** Return all unread sessions. */
+    getUnread() {
+        return this.getByStatus('unread');
+    }
+    /** Return all in-progress sessions. */
+    getInProgress() {
+        return this.getByStatus('in-progress');
+    }
+    /** Return all blocked sessions. */
+    getBlocked() {
+        return this.getByStatus('blocked');
+    }
+    /** Return sessions by execution mode. */
+    getByMode(mode) {
+        return this.getAll().filter((s) => s.executionMode === mode);
+    }
+    /** Return all active sessions associated with a given contract ID. */
+    getByContractId(contractId) {
+        return this.getAll().filter((s) => s.contractId === contractId);
+    }
+    /** Return the first active session for a contract, or undefined if none found. */
+    getActiveSessionForContract(contractId) {
+        return this.getByContractId(contractId).find((s) => s.lifeCycle === 'active');
+    }
+    /** Total count of in-memory sessions. */
+    get size() {
+        return this.sessions.size;
+    }
+    // ─────────────── Cleanup ───────────────
+    /**
+     * Stop the background flush timer and release resources.
+     */
+    destroy() {
+        if (this.flushTimer !== null) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        this.removeAllListeners();
+    }
+    // ─────────────── Private ───────────────
+    _requireSession(sessionId) {
+        const s = this.sessions.get(sessionId);
+        if (!s)
+            throw new Error(`Session not found: ${sessionId}`);
+        return s;
+    }
+    /**
+     * Write an archived session as a JSONL line to the date-based archive file.
+     * Path: `<archiveBaseDir>/YYYY-MM-DD/<session-id>.jsonl`
+     */
+    _writeArchivedSession(session) {
+        try {
+            const date = (session.archivedAt ?? new Date().toISOString()).slice(0, 10);
+            const dayDir = join(this.archiveBaseDir, date);
+            mkdirSync(dayDir, { recursive: true });
+            const filePath = join(dayDir, `${session.sessionId}.jsonl`);
+            appendFileSync(filePath, JSON.stringify(session) + '\n', 'utf8');
+        }
+        catch {
+            // Non-fatal — session is removed from memory regardless
+        }
+    }
+    /**
+     * Periodic flush: nothing to flush for in-memory only — the archive write
+     * happens inline in `archive()`. This hook is reserved for future batching.
+     */
+    _flushArchived() {
+        this.emit('flush', { timestamp: new Date().toISOString(), activeSessions: this.sessions.size });
+    }
+}
+//# sourceMappingURL=session-manager.js.map

package/dist/ai/delegation/session-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.js","sourceRoot":"","sources":["../../../packages/ai/delegation/session-manager.ts"],"names":[],"mappings":"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"}

package/dist/ai/delegation/session-queue.d.ts

@@ -0,0 +1,95 @@
+/**
+ * DCYFR Background Session Queue
+ * TLP:AMBER - Internal Use Only
+ *
+ * FIFO queue managing the 10-slot background session concurrency limit.
+ * Prevents resource exhaustion while providing observability into queue state.
+ *
+ * @module delegation/session-queue
+ * @version 1.0.0
+ */
+import { EventEmitter } from 'events';
+/** Maximum concurrent background sessions. */
+export declare const MAX_BACKGROUND_SESSIONS = 10;
+/** Status of the background session queue. */
+export interface BackgroundQueueStatus {
+    /** Number of active background sessions. */
+    activeCount: number;
+    /** Remaining capacity for new background sessions. */
+    remainingCapacity: number;
+    /** Whether the queue is at maximum capacity. */
+    atCapacity: boolean;
+    /** List of currently active session IDs. */
+    activeSessionIds: string[];
+    /** List of session IDs waiting to be processed (queue depth). */
+    queuedSessionIds: string[];
+}
+/** Entry stored in the queue. */
+export interface QueueEntry {
+    sessionId: string;
+    contractId: string;
+    /** ISO 8601 timestamp when the entry was enqueued. */
+    enqueuedAt: string;
+    /** Optional resolve function called when a slot opens. */
+    resolve?: () => void;
+}
+/**
+ * FIFO queue managing concurrent background delegation sessions.
+ *
+ * Emits the following events:
+ * - `enqueued`   — A new session entered the queue (waiting for slot).
+ * - `activated`  — A session moved from queue to active set.
+ * - `released`   — A session slot was released.
+ * - `status`     — Queue status changed (active/queued counts changed).
+ */
+export declare class BackgroundSessionQueue extends EventEmitter {
+    private readonly maxSlots;
+    /** Set of session IDs currently occupying an active slot. */
+    private readonly activeSessions;
+    /** FIFO queue of sessions waiting for a slot. */
+    private readonly waitQueue;
+    /** Map of sessionId → QueueEntry for active sessions. */
+    private readonly activeEntries;
+    constructor(maxSlots?: number);
+    /**
+     * Attempt to acquire a background slot for the given session.
+     *
+     * - If capacity is available, resolves immediately and marks the slot active.
+     * - If at capacity, enqueues the session and resolves when a slot opens.
+     *
+     * @returns A promise that resolves when the session has an active slot.
+     */
+    acquire(sessionId: string, contractId: string): Promise<void>;
+    /**
+     * Release a background slot previously acquired for `sessionId`.
+     * If there are queued sessions, the next one is activated immediately.
+     */
+    release(sessionId: string): void;
+    /**
+     * Returns `true` if there is at least one free background slot.
+     */
+    hasCapacity(): boolean;
+    /**
+     * Number of active background sessions.
+     */
+    get activeCount(): number;
+    /**
+     * Number of sessions waiting for a slot.
+     */
+    get queueDepth(): number;
+    /**
+     * Current queue snapshot for observability.
+     */
+    getStatus(): BackgroundQueueStatus;
+    /**
+     * Whether a given sessionId currently holds an active slot.
+     */
+    isActive(sessionId: string): boolean;
+    /**
+     * Whether a given sessionId is waiting in the queue.
+     */
+    isQueued(sessionId: string): boolean;
+    private _activate;
+    private _emitStatus;
+}
+//# sourceMappingURL=session-queue.d.ts.map

package/dist/ai/delegation/session-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-queue.d.ts","sourceRoot":"","sources":["../../../packages/ai/delegation/session-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAGtC,8CAA8C;AAC9C,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C,8CAA8C;AAC9C,MAAM,WAAW,qBAAqB;IACpC,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gDAAgD;IAChD,UAAU,EAAE,OAAO,CAAC;IACpB,4CAA4C;IAC5C,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,iEAAiE;IACjE,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,iCAAiC;AACjC,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,qBAAa,sBAAuB,SAAQ,YAAY;IAU1C,OAAO,CAAC,QAAQ,CAAC,QAAQ;IATrC,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IAEpD,iDAAiD;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAE9C,yDAAyD;IACzD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAiC;gBAElC,QAAQ,GAAE,MAAgC;IAMvE;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB7D;;;OAGG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAiBhC;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;OAEG;IACH,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;OAEG;IACH,SAAS,IAAI,qBAAqB;IAUlC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAIpC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAMpC,OAAO,CAAC,SAAS;IAWjB,OAAO,CAAC,WAAW;CAGpB"}

package/dist/ai/delegation/session-queue.js

@@ -0,0 +1,136 @@
+/**
+ * DCYFR Background Session Queue
+ * TLP:AMBER - Internal Use Only
+ *
+ * FIFO queue managing the 10-slot background session concurrency limit.
+ * Prevents resource exhaustion while providing observability into queue state.
+ *
+ * @module delegation/session-queue
+ * @version 1.0.0
+ */
+import { EventEmitter } from 'events';
+/** Maximum concurrent background sessions. */
+export const MAX_BACKGROUND_SESSIONS = 10;
+/**
+ * FIFO queue managing concurrent background delegation sessions.
+ *
+ * Emits the following events:
+ * - `enqueued`   — A new session entered the queue (waiting for slot).
+ * - `activated`  — A session moved from queue to active set.
+ * - `released`   — A session slot was released.
+ * - `status`     — Queue status changed (active/queued counts changed).
+ */
+export class BackgroundSessionQueue extends EventEmitter {
+    maxSlots;
+    /** Set of session IDs currently occupying an active slot. */
+    activeSessions = new Set();
+    /** FIFO queue of sessions waiting for a slot. */
+    waitQueue = [];
+    /** Map of sessionId → QueueEntry for active sessions. */
+    activeEntries = new Map();
+    constructor(maxSlots = MAX_BACKGROUND_SESSIONS) {
+        super();
+        this.maxSlots = maxSlots;
+    }
+    // ───────────── Public API ─────────────
+    /**
+     * Attempt to acquire a background slot for the given session.
+     *
+     * - If capacity is available, resolves immediately and marks the slot active.
+     * - If at capacity, enqueues the session and resolves when a slot opens.
+     *
+     * @returns A promise that resolves when the session has an active slot.
+     */
+    acquire(sessionId, contractId) {
+        if (this.activeSessions.size < this.maxSlots) {
+            this._activate({ sessionId, contractId, enqueuedAt: new Date().toISOString() });
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            const entry = {
+                sessionId,
+                contractId,
+                enqueuedAt: new Date().toISOString(),
+                resolve,
+            };
+            this.waitQueue.push(entry);
+            this.emit('enqueued', { sessionId, contractId, queuePosition: this.waitQueue.length });
+            this._emitStatus();
+        });
+    }
+    /**
+     * Release a background slot previously acquired for `sessionId`.
+     * If there are queued sessions, the next one is activated immediately.
+     */
+    release(sessionId) {
+        if (!this.activeSessions.has(sessionId))
+            return;
+        this.activeSessions.delete(sessionId);
+        this.activeEntries.delete(sessionId);
+        this.emit('released', { sessionId });
+        // Promote next waiting session
+        if (this.waitQueue.length > 0) {
+            const next = this.waitQueue.shift();
+            this._activate(next);
+            next.resolve?.();
+        }
+        this._emitStatus();
+    }
+    /**
+     * Returns `true` if there is at least one free background slot.
+     */
+    hasCapacity() {
+        return this.activeSessions.size < this.maxSlots;
+    }
+    /**
+     * Number of active background sessions.
+     */
+    get activeCount() {
+        return this.activeSessions.size;
+    }
+    /**
+     * Number of sessions waiting for a slot.
+     */
+    get queueDepth() {
+        return this.waitQueue.length;
+    }
+    /**
+     * Current queue snapshot for observability.
+     */
+    getStatus() {
+        return {
+            activeCount: this.activeSessions.size,
+            remainingCapacity: this.maxSlots - this.activeSessions.size,
+            atCapacity: this.activeSessions.size >= this.maxSlots,
+            activeSessionIds: Array.from(this.activeSessions),
+            queuedSessionIds: this.waitQueue.map((e) => e.sessionId),
+        };
+    }
+    /**
+     * Whether a given sessionId currently holds an active slot.
+     */
+    isActive(sessionId) {
+        return this.activeSessions.has(sessionId);
+    }
+    /**
+     * Whether a given sessionId is waiting in the queue.
+     */
+    isQueued(sessionId) {
+        return this.waitQueue.some((e) => e.sessionId === sessionId);
+    }
+    // ───────────── Private helpers ─────────────
+    _activate(entry) {
+        this.activeSessions.add(entry.sessionId);
+        this.activeEntries.set(entry.sessionId, entry);
+        this.emit('activated', {
+            sessionId: entry.sessionId,
+            contractId: entry.contractId,
+            activatedAt: new Date().toISOString(),
+        });
+        this._emitStatus();
+    }
+    _emitStatus() {
+        this.emit('status', this.getStatus());
+    }
+}
+//# sourceMappingURL=session-queue.js.map

package/dist/ai/delegation/session-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-queue.js","sourceRoot":"","sources":["../../../packages/ai/delegation/session-queue.ts"],"names":[],"mappings":"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"}

package/dist/ai/delegation/timeout-watchdog.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Contract Timeout Watchdog
+ * TLP:AMBER - Internal Use Only
+ *
+ * Design decision D3: Periodic watchdog model.
+ * Scans all active contracts on a configurable interval and fires timeout events
+ * for contracts whose `timeout_ms` has elapsed.  Also exposes `heartbeat()` so
+ * long-running delegations can extend their deadline.
+ *
+ * @module delegation/timeout-watchdog
+ * @version 1.0.0
+ * @date 2026-02-24
+ */
+import { EventEmitter } from 'events';
+export interface WatchdogConfig {
+    /** How often the watchdog ticks. Default: 30 000 ms */
+    intervalMs?: number;
+    /** Grace period added to a heartbeat. Default: 30 000 ms */
+    heartbeatGraceMs?: number;
+}
+export interface WatchdogContract {
+    contract_id: string;
+    created_at: string;
+    timeout_ms: number;
+    last_heartbeat_at?: string;
+    status: string;
+}
+export interface TimeoutEvent {
+    contract_id: string;
+    created_at: string;
+    timeout_ms: number;
+    elapsed_ms: number;
+}
+/**
+ * ContractTimeoutWatchdog emits:
+ *   - `contract_timeout`  when a contract's deadline has passed
+ *   - `heartbeat_updated` when heartbeat() extends a deadline
+ *   - `watchdog_tick`     on every scan cycle (for observability)
+ */
+export declare class ContractTimeoutWatchdog extends EventEmitter {
+    private readonly intervalMs;
+    private readonly heartbeatGraceMs;
+    private timer;
+    /** Contracts registered for timeout monitoring */
+    private readonly tracked;
+    /** Per-contract extended deadline (heartbeat grants extra time) */
+    private readonly extendedDeadlines;
+    constructor(config?: WatchdogConfig);
+    start(): void;
+    stop(): void;
+    track(contract: WatchdogContract): void;
+    untrack(contractId: string): void;
+    /**
+     * Extend the deadline for a contract by `heartbeatGraceMs`.
+     * Called by the contract-manager's heartbeat endpoint.
+     */
+    heartbeat(contractId: string): void;
+    private tick;
+}
+//# sourceMappingURL=timeout-watchdog.d.ts.map

package/dist/ai/delegation/timeout-watchdog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeout-watchdog.d.ts","sourceRoot":"","sources":["../../../packages/ai/delegation/timeout-watchdog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAEtC,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,qBAAa,uBAAwB,SAAQ,YAAY;IACvD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,KAAK,CAA+C;IAE5D,kDAAkD;IAClD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA6B;gBAEnD,MAAM,GAAE,cAAmB;IAUvC,KAAK,IAAI,IAAI;IASb,IAAI,IAAI,IAAI;IAWZ,KAAK,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAIvC,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAKjC;;;OAGG;IACH,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAUnC,OAAO,CAAC,IAAI;CA6Bb"}

package/dist/ai/delegation/timeout-watchdog.js

@@ -0,0 +1,100 @@
+/**
+ * Contract Timeout Watchdog
+ * TLP:AMBER - Internal Use Only
+ *
+ * Design decision D3: Periodic watchdog model.
+ * Scans all active contracts on a configurable interval and fires timeout events
+ * for contracts whose `timeout_ms` has elapsed.  Also exposes `heartbeat()` so
+ * long-running delegations can extend their deadline.
+ *
+ * @module delegation/timeout-watchdog
+ * @version 1.0.0
+ * @date 2026-02-24
+ */
+import { EventEmitter } from 'events';
+/**
+ * ContractTimeoutWatchdog emits:
+ *   - `contract_timeout`  when a contract's deadline has passed
+ *   - `heartbeat_updated` when heartbeat() extends a deadline
+ *   - `watchdog_tick`     on every scan cycle (for observability)
+ */
+export class ContractTimeoutWatchdog extends EventEmitter {
+    intervalMs;
+    heartbeatGraceMs;
+    timer = null;
+    /** Contracts registered for timeout monitoring */
+    tracked = new Map();
+    /** Per-contract extended deadline (heartbeat grants extra time) */
+    extendedDeadlines = new Map();
+    constructor(config = {}) {
+        super();
+        this.intervalMs = config.intervalMs ?? 30_000;
+        this.heartbeatGraceMs = config.heartbeatGraceMs ?? 30_000;
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // Lifecycle
+    // ──────────────────────────────────────────────────────────────────────────
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => this.tick(), this.intervalMs);
+        // Use unref() if available (Node.js) so watchdog doesn't block process exit
+        if (this.timer && typeof this.timer.unref === 'function') {
+            this.timer.unref();
+        }
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // Contract tracking
+    // ──────────────────────────────────────────────────────────────────────────
+    track(contract) {
+        this.tracked.set(contract.contract_id, contract);
+    }
+    untrack(contractId) {
+        this.tracked.delete(contractId);
+        this.extendedDeadlines.delete(contractId);
+    }
+    /**
+     * Extend the deadline for a contract by `heartbeatGraceMs`.
+     * Called by the contract-manager's heartbeat endpoint.
+     */
+    heartbeat(contractId) {
+        const extended = Date.now() + this.heartbeatGraceMs;
+        this.extendedDeadlines.set(contractId, extended);
+        this.emit('heartbeat_updated', { contract_id: contractId, extended_until: new Date(extended).toISOString() });
+    }
+    // ──────────────────────────────────────────────────────────────────────────
+    // Internal tick
+    // ──────────────────────────────────────────────────────────────────────────
+    tick() {
+        const now = Date.now();
+        const expired = [];
+        for (const contract of this.tracked.values()) {
+            if (contract.status !== 'active')
+                continue;
+            const extendedDeadline = this.extendedDeadlines.get(contract.contract_id);
+            const baseline = new Date(contract.created_at).getTime() + contract.timeout_ms;
+            const deadline = extendedDeadline !== undefined ? Math.max(baseline, extendedDeadline) : baseline;
+            if (now > deadline) {
+                expired.push({
+                    contract_id: contract.contract_id,
+                    created_at: contract.created_at,
+                    timeout_ms: contract.timeout_ms,
+                    elapsed_ms: now - new Date(contract.created_at).getTime(),
+                });
+            }
+        }
+        this.emit('watchdog_tick', { checked: this.tracked.size, expired: expired.length, timestamp_ms: now });
+        for (const ev of expired) {
+            // Untrack before emitting so re-entrant calls don't double-fire
+            this.untrack(ev.contract_id);
+            this.emit('contract_timeout', ev);
+        }
+    }
+}
+//# sourceMappingURL=timeout-watchdog.js.map

package/dist/ai/delegation/timeout-watchdog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeout-watchdog.js","sourceRoot":"","sources":["../../../packages/ai/delegation/timeout-watchdog.ts"],"names":[],"mappings":"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"}