@dcyfr/ai 1.0.4 → 2.1.0

package/dist/ai/delegation/security-middleware-chain.js

@@ -0,0 +1,163 @@
+/**
+ * Security Middleware Chain
+ * TLP:AMBER - Internal Use Only
+ *
+ * Composable pipeline that runs a registered set of SecurityMiddleware
+ * implementations against a SecurityContext.  The chain:
+ *
+ *  1. Iterates middleware in registration order.
+ *  2. Short-circuits on the first `block` verdict.
+ *  3. Accumulates `warn` verdicts and continues.
+ *  4. Returns a SecurityChainResult with full audit detail.
+ *
+ * Design decision D1: Fixed-order middleware chain — simpler to reason about
+ * than a DAG; the canonical order is enforced by the builder helpers exported
+ * at the bottom of this file.
+ *
+ * @module delegation/security-middleware-chain
+ * @version 1.0.0
+ * @date 2026-02-24
+ */
+import { EventEmitter } from 'events';
+// ──────────────────────────────────────────────────────────────────────────────
+// Chain class
+// ──────────────────────────────────────────────────────────────────────────────
+/**
+ * SecurityMiddlewareChain
+ *
+ * Usage:
+ * ```typescript
+ * const chain = new SecurityMiddlewareChain();
+ * chain.use(new FeatureFlagMiddleware(flagManager));
+ * chain.use(new IdentityMiddleware(agentRegistry));
+ * chain.use(new TLPMiddleware(tlpEngine));
+ * // …
+ *
+ * const result = await chain.evaluate(context);
+ * if (result.action === 'block') { throw … }
+ * ```
+ *
+ * Alternatively use `buildDefaultChain()` for the canonical ordering.
+ */
+export class SecurityMiddlewareChain extends EventEmitter {
+    middleware = [];
+    /** Add a middleware to the END of the chain */
+    use(mw) {
+        this.middleware.push(mw);
+        return this;
+    }
+    /** Add a middleware at a specific index (for patching canonical order) */
+    insert(index, mw) {
+        this.middleware.splice(index, 0, mw);
+        return this;
+    }
+    /** Return a snapshot of registered middleware names */
+    get names() {
+        return this.middleware.map(m => m.name);
+    }
+    /**
+     * Evaluate all middleware against `context`.
+     *
+     * Events emitted:
+     * - `security_warning`  { middleware, verdict, context }
+     * - `security_blocked`  { middleware, verdict, context }
+     * - `chain_evaluated`   { result, context }
+     */
+    async evaluate(context) {
+        const start = Date.now();
+        const middlewareResults = [];
+        const warnings = [];
+        let blockingVerdict;
+        let blockedBy;
+        for (const mw of this.middleware) {
+            // Skip if feature flag is absent/false
+            if (mw.featureFlag && !context.feature_flags?.[mw.featureFlag]) {
+                middlewareResults.push({
+                    middleware: mw.name,
+                    verdict: { action: 'allow' },
+                    elapsed_ms: 0,
+                });
+                continue;
+            }
+            // Skip if operations filter doesn't match
+            if (mw.appliesTo && !mw.appliesTo.includes(context.operation)) {
+                middlewareResults.push({
+                    middleware: mw.name,
+                    verdict: { action: 'allow' },
+                    elapsed_ms: 0,
+                });
+                continue;
+            }
+            const mwStart = Date.now();
+            let verdict;
+            try {
+                verdict = await mw.evaluate(context);
+            }
+            catch (err) {
+                // Middleware threw — treat as a blocking error to fail safe
+                verdict = {
+                    action: 'block',
+                    reason: `Middleware '${mw.name}' threw an unexpected error: ${err.message}`,
+                    threat_type: 'anomaly',
+                    severity: 'critical',
+                    evidence: { error: String(err) },
+                };
+            }
+            const elapsed_ms = Date.now() - mwStart;
+            middlewareResults.push({ middleware: mw.name, verdict, elapsed_ms });
+            if (verdict.action === 'warn') {
+                warnings.push(verdict);
+                this.emit('security_warning', { middleware: mw.name, verdict, context });
+            }
+            else if (verdict.action === 'block') {
+                blockingVerdict = verdict;
+                blockedBy = mw.name;
+                this.emit('security_blocked', { middleware: mw.name, verdict, context });
+                break; // short-circuit
+            }
+        }
+        const evaluation_time_ms = Date.now() - start;
+        const action = blockingVerdict ? 'block' : warnings.length > 0 ? 'warn' : 'allow';
+        const result = {
+            action,
+            blocking_verdict: blockingVerdict,
+            warnings,
+            blocked_by: blockedBy,
+            evaluation_time_ms,
+            middleware_results: middlewareResults,
+        };
+        this.emit('chain_evaluated', { result, context });
+        return result;
+    }
+}
+// ──────────────────────────────────────────────────────────────────────────────
+// Internal stub middleware (used during bootstrap before real engines load)
+// ──────────────────────────────────────────────────────────────────────────────
+/** Always allows — useful as a placeholder / no-op in tests */
+export class AllowAllMiddleware {
+    name;
+    constructor(name) {
+        this.name = name;
+    }
+    async evaluate() {
+        return { action: 'allow' };
+    }
+}
+/** Always blocks with a fixed reason — useful in tests */
+export class BlockAllMiddleware {
+    name;
+    reason;
+    constructor(name, reason = 'blocked by test fixture') {
+        this.name = name;
+        this.reason = reason;
+    }
+    async evaluate() {
+        return {
+            action: 'block',
+            reason: this.reason,
+            threat_type: 'anomaly',
+            severity: 'critical',
+        };
+    }
+}
+//# sourceMappingURL=security-middleware-chain.js.map

package/dist/ai/delegation/security-middleware-chain.js.map

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

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

@@ -0,0 +1,77 @@
+/**
+ * DCYFR Session Checkpoint System
+ * TLP:AMBER - Internal Use Only
+ *
+ * Manages point-in-time snapshots of delegation session state.
+ * Checkpoints are persisted to disk for crash recovery and handoff.
+ *
+ * Checkpoint triggers:
+ *   - Every 5 conversation messages (automatic rolling checkpoint)
+ *   - Immediately before a session handoff
+ *   - Immediately before verification begins
+ *
+ * Storage path: `logs/delegation/checkpoints/<session-id>-<timestamp>.json`
+ *
+ * @module delegation/session-checkpoint
+ * @version 1.0.0
+ */
+import type { SessionState } from '../types/agent-capabilities.js';
+/** Auto-checkpoint every N messages. */
+export declare const CHECKPOINT_MESSAGE_INTERVAL = 5;
+/** Reasons a checkpoint can be created. */
+export type CheckpointReason = 'automatic' | 'pre-handoff' | 'pre-verification' | 'manual';
+/** Serialised checkpoint written to disk. */
+export interface CheckpointRecord {
+    /** Unique checkpoint identifier: `<sessionId>-<timestamp>` */
+    id: string;
+    sessionId: string;
+    contractId: string;
+    reason: CheckpointReason;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+    /** Message index at the time of the checkpoint. */
+    messageIndex: number;
+    /** Full session state snapshot. */
+    sessionState: SessionState;
+    /** Arbitrary key/value metadata. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Manages session checkpoints for crash recovery and handoff.
+ */
+export declare class SessionCheckpoint {
+    private readonly checkpointDir;
+    /**
+     * @param checkpointBaseDir - Base directory for checkpoints.
+     *   Defaults to `<workspace-root>/logs/delegation/checkpoints`.
+     */
+    constructor(checkpointBaseDir?: string);
+    /**
+     * Create and persist a checkpoint for a session.
+     *
+     * @returns The persisted checkpoint record.
+     */
+    create(sessionId: string, contractId: string, sessionState: SessionState, reason: CheckpointReason, messageIndex: number, metadata?: Record<string, unknown>): CheckpointRecord;
+    /**
+     * Determine whether a checkpoint should be created based on the current
+     * message index (automatic rolling checkpoints every 5 messages).
+     */
+    shouldCheckpoint(messageIndex: number): boolean;
+    /**
+     * Load the most recent checkpoint for a given session.
+     * Returns `undefined` if no checkpoints exist.
+     */
+    loadLatest(sessionId: string): CheckpointRecord | undefined;
+    /**
+     * List all checkpoint records for a given session, ordered oldest-first.
+     */
+    listAll(sessionId: string): CheckpointRecord[];
+    /**
+     * Return the absolute path of a checkpoint file given its ID.
+     */
+    checkpointPath(id: string): string;
+    private _persist;
+    private _listSessionCheckpoints;
+    private _load;
+}
+//# sourceMappingURL=session-checkpoint.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-checkpoint.d.ts","sourceRoot":"","sources":["../../../packages/ai/delegation/session-checkpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAEnE,wCAAwC;AACxC,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C,2CAA2C;AAC3C,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,aAAa,GAAG,kBAAkB,GAAG,QAAQ,CAAC;AAE3F,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,gBAAgB,CAAC;IACzB,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,YAAY,EAAE,MAAM,CAAC;IACrB,mCAAmC;IACnC,YAAY,EAAE,YAAY,CAAC;IAC3B,oCAAoC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IAEvC;;;OAGG;gBACS,iBAAiB,CAAC,EAAE,MAAM;IActC;;;;OAIG;IACH,MAAM,CACJ,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,YAAY,EAC1B,MAAM,EAAE,gBAAgB,EACxB,YAAY,EAAE,MAAM,EACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,gBAAgB;IAqBnB;;;OAGG;IACH,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IAI/C;;;OAGG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAU3D;;OAEG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,EAAE;IAM9C;;OAEG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM;IAMlC,OAAO,CAAC,QAAQ;IAMhB,OAAO,CAAC,uBAAuB;IAW/B,OAAO,CAAC,KAAK;CASd"}

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

@@ -0,0 +1,131 @@
+/**
+ * DCYFR Session Checkpoint System
+ * TLP:AMBER - Internal Use Only
+ *
+ * Manages point-in-time snapshots of delegation session state.
+ * Checkpoints are persisted to disk for crash recovery and handoff.
+ *
+ * Checkpoint triggers:
+ *   - Every 5 conversation messages (automatic rolling checkpoint)
+ *   - Immediately before a session handoff
+ *   - Immediately before verification begins
+ *
+ * Storage path: `logs/delegation/checkpoints/<session-id>-<timestamp>.json`
+ *
+ * @module delegation/session-checkpoint
+ * @version 1.0.0
+ */
+import { writeFileSync, mkdirSync, readFileSync, readdirSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+/** Auto-checkpoint every N messages. */
+export const CHECKPOINT_MESSAGE_INTERVAL = 5;
+/**
+ * Manages session checkpoints for crash recovery and handoff.
+ */
+export class SessionCheckpoint {
+    checkpointDir;
+    /**
+     * @param checkpointBaseDir - Base directory for checkpoints.
+     *   Defaults to `<workspace-root>/logs/delegation/checkpoints`.
+     */
+    constructor(checkpointBaseDir) {
+        if (checkpointBaseDir) {
+            this.checkpointDir = checkpointBaseDir;
+        }
+        else {
+            // Resolve workspace root relative to this file (packages/ai/delegation/)
+            const thisDir = dirname(fileURLToPath(import.meta.url));
+            // packages/ai/ → ../../.. → workspace root
+            const workspaceRoot = join(thisDir, '..', '..', '..', '..', '..', '..');
+            this.checkpointDir = join(workspaceRoot, 'logs', 'delegation', 'checkpoints');
+        }
+    }
+    // ───────────── Public API ─────────────
+    /**
+     * Create and persist a checkpoint for a session.
+     *
+     * @returns The persisted checkpoint record.
+     */
+    create(sessionId, contractId, sessionState, reason, messageIndex, metadata) {
+        const now = new Date().toISOString();
+        // Use compact timestamp for filename compatibility (replace colons)
+        const safeTimestamp = now.replace(/[:.]/g, '-');
+        const id = `${sessionId}-${safeTimestamp}`;
+        const record = {
+            id,
+            sessionId,
+            contractId,
+            reason,
+            createdAt: now,
+            messageIndex,
+            sessionState,
+            ...(metadata !== undefined && { metadata }),
+        };
+        this._persist(id, record);
+        return record;
+    }
+    /**
+     * Determine whether a checkpoint should be created based on the current
+     * message index (automatic rolling checkpoints every 5 messages).
+     */
+    shouldCheckpoint(messageIndex) {
+        return messageIndex > 0 && messageIndex % CHECKPOINT_MESSAGE_INTERVAL === 0;
+    }
+    /**
+     * Load the most recent checkpoint for a given session.
+     * Returns `undefined` if no checkpoints exist.
+     */
+    loadLatest(sessionId) {
+        const files = this._listSessionCheckpoints(sessionId);
+        if (files.length === 0)
+            return undefined;
+        // Files are named `<sessionId>-<timestamp>.json`; sort descending by name
+        files.sort((a, b) => b.localeCompare(a));
+        const latest = files[0];
+        return this._load(latest);
+    }
+    /**
+     * List all checkpoint records for a given session, ordered oldest-first.
+     */
+    listAll(sessionId) {
+        const files = this._listSessionCheckpoints(sessionId);
+        files.sort((a, b) => a.localeCompare(b));
+        return files.map((f) => this._load(f)).filter(Boolean);
+    }
+    /**
+     * Return the absolute path of a checkpoint file given its ID.
+     */
+    checkpointPath(id) {
+        return join(this.checkpointDir, `${id}.json`);
+    }
+    // ───────────── Private helpers ─────────────
+    _persist(id, record) {
+        mkdirSync(this.checkpointDir, { recursive: true });
+        const path = this.checkpointPath(id);
+        writeFileSync(path, JSON.stringify(record, null, 2), 'utf8');
+    }
+    _listSessionCheckpoints(sessionId) {
+        if (!existsSync(this.checkpointDir))
+            return [];
+        try {
+            return readdirSync(this.checkpointDir)
+                .filter((f) => f.startsWith(`${sessionId}-`) && f.endsWith('.json'))
+                .map((f) => f.replace(/\.json$/, ''));
+        }
+        catch {
+            return [];
+        }
+    }
+    _load(id) {
+        const path = this.checkpointPath(id);
+        try {
+            const raw = readFileSync(path, 'utf8');
+            return JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+//# sourceMappingURL=session-checkpoint.js.map

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

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

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

@@ -0,0 +1,131 @@
+/**
+ * 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 type { SessionState, ExecutionMode } from '../types/agent-capabilities.js';
+/** Visibility / workflow status that is user-facing (separate from lifecycle). */
+export type SessionStatus = 'unread' | 'in-progress' | 'blocked';
+/** Full lifecycle state for a managed session. */
+export interface ManagedSession {
+    sessionId: string;
+    contractId: string;
+    executionMode: ExecutionMode;
+    /** Lifecycle phase (maps to `SessionState.status`). */
+    lifeCycle: 'active' | 'paused' | 'archived';
+    /** User-visible workflow indicator. */
+    status: SessionStatus;
+    state: SessionState;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+    /** ISO 8601 last-updated timestamp. */
+    updatedAt: string;
+    /** ISO 8601 archive timestamp. */
+    archivedAt?: string;
+    /** Optional block reason when status is 'blocked'. */
+    blockReason?: string;
+}
+/** Options passed to `SessionManager` constructor. */
+export interface SessionManagerOptions {
+    /** Override base directory for persisted session archives. */
+    archiveBaseDir?: string;
+    /** Flush interval in milliseconds (default: 60 000 ms / 1 minute). */
+    flushIntervalMs?: number;
+}
+/**
+ * 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 declare class SessionManager extends EventEmitter {
+    private readonly sessions;
+    private readonly archiveBaseDir;
+    private flushTimer;
+    constructor(options?: SessionManagerOptions);
+    /**
+     * Register a new session (initial status: 'unread', lifecycle: 'active').
+     */
+    register(sessionId: string, contractId: string, executionMode: ExecutionMode, initialState: SessionState): ManagedSession;
+    /**
+     * Update the in-memory state for an existing session.
+     * Automatically marks lifecycle as 'active' if it was 'paused'.
+     */
+    updateState(sessionId: string, newState: Partial<SessionState>): ManagedSession;
+    /**
+     * Pause a session (lifecycle: 'paused').
+     */
+    pause(sessionId: string): ManagedSession;
+    /**
+     * 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: string): ManagedSession;
+    /**
+     * Mark a session as 'in-progress' (user has read it and work is active).
+     */
+    markInProgress(sessionId: string): ManagedSession;
+    /**
+     * Mark a session as 'blocked' with an optional reason.
+     */
+    block(sessionId: string, reason?: string): ManagedSession;
+    /**
+     * Clear a 'blocked' status — transitions back to 'in-progress'.
+     */
+    unblock(sessionId: string): ManagedSession;
+    /** Retrieve a session by ID. Returns `undefined` if not found. */
+    get(sessionId: string): ManagedSession | undefined;
+    /** Return all in-memory sessions. */
+    getAll(): ManagedSession[];
+    /** Return sessions filtered by lifecycle. */
+    getByLifeCycle(lifeCycle: ManagedSession['lifeCycle']): ManagedSession[];
+    /** Return sessions filtered by workflow status. */
+    getByStatus(status: SessionStatus): ManagedSession[];
+    /** Return all unread sessions. */
+    getUnread(): ManagedSession[];
+    /** Return all in-progress sessions. */
+    getInProgress(): ManagedSession[];
+    /** Return all blocked sessions. */
+    getBlocked(): ManagedSession[];
+    /** Return sessions by execution mode. */
+    getByMode(mode: ExecutionMode): ManagedSession[];
+    /** Return all active sessions associated with a given contract ID. */
+    getByContractId(contractId: string): ManagedSession[];
+    /** Return the first active session for a contract, or undefined if none found. */
+    getActiveSessionForContract(contractId: string): ManagedSession | undefined;
+    /** Total count of in-memory sessions. */
+    get size(): number;
+    /**
+     * Stop the background flush timer and release resources.
+     */
+    destroy(): void;
+    private _requireSession;
+    /**
+     * Write an archived session as a JSONL line to the date-based archive file.
+     * Path: `<archiveBaseDir>/YYYY-MM-DD/<session-id>.jsonl`
+     */
+    private _writeArchivedSession;
+    /**
+     * Periodic flush: nothing to flush for in-memory only — the archive write
+     * happens inline in `archive()`. This hook is reserved for future batching.
+     */
+    private _flushArchived;
+}
+//# sourceMappingURL=session-manager.d.ts.map

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

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