limen-ai 1.0.0

package/dist/api/agents/trust_progression.js

@@ -0,0 +1,124 @@
+/**
+ * Trust Progression Logic — I-09 (Trust is Earned)
+ * Store-level implementation: trust state machine + safety demotion.
+ *
+ * Phase: Sprint 2 (Trust & Learning)
+ * Spec ref: I-09 "No agent starts with admin trust. Progression:
+ *           untrusted → probationary → trusted → admin (human grant only).
+ *           Revocable on safety violation."
+ *
+ * Trust State Machine:
+ *   Forward: untrusted→probationary, probationary→trusted, trusted→admin
+ *   Admin requires actorType='human' (application-level AND trigger enforcement)
+ *   No skipping levels (untrusted→trusted is INVALID)
+ *   Retired agents cannot be promoted (blocked by retired terminal trigger)
+ *
+ * Demotion on Safety Violation:
+ *   critical/high on trusted/admin → untrusted
+ *   critical/high on probationary → untrusted
+ *   low/medium on trusted → probationary
+ *   low/medium on probationary → untrusted
+ *   low/medium on admin → trusted
+ *
+ * Security: Self-promotion prevention — agents cannot promote themselves.
+ */
+// ─── Trust State Machine Constants ───
+/**
+ * Valid forward transitions in the trust hierarchy.
+ * Each level can only advance to the immediately next level.
+ * I-09: "Progression: untrusted → probationary → trusted → admin"
+ */
+const NEXT_LEVEL = {
+    untrusted: 'probationary',
+    probationary: 'trusted',
+    trusted: 'admin',
+    admin: null, // admin is the terminal forward state
+};
+/**
+ * Determine the next trust level for a given current level.
+ * Returns null if already at admin (no forward progression possible).
+ */
+export function getNextTrustLevel(current) {
+    return NEXT_LEVEL[current];
+}
+/**
+ * Validate that a trust level transition is valid (single step forward).
+ * Returns { valid: true } if the transition is allowed,
+ * or { valid: false, reason: string } if not.
+ *
+ * Rules:
+ *   1. from !== to (no self-transition)
+ *   2. to must be exactly one step above from
+ *   3. admin requires human actor type
+ */
+export function validatePromotion(fromLevel, targetLevel, actorType) {
+    // Same level is not a promotion
+    if (fromLevel === targetLevel) {
+        return { valid: false, reason: `Already at trust level '${fromLevel}'.` };
+    }
+    // Verify the target is exactly one step up
+    const expected = NEXT_LEVEL[fromLevel];
+    if (expected === null) {
+        return { valid: false, reason: `Cannot promote beyond admin trust level.` };
+    }
+    if (targetLevel !== expected) {
+        return {
+            valid: false,
+            reason: `Invalid trust progression: '${fromLevel}' → '${targetLevel}'. Must advance to '${expected}' (no skipping levels).`,
+        };
+    }
+    // Admin requires human actor
+    if (targetLevel === 'admin' && actorType !== 'human') {
+        return {
+            valid: false,
+            reason: `Admin trust requires human actor (got '${actorType}'). I-09: "admin (human grant only)".`,
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Validate self-promotion is not occurring.
+ * Security-critical: agents cannot promote themselves.
+ *
+ * @param ctxAgentId - The agent ID from the operation context (caller's identity)
+ * @param targetAgentId - The agent being promoted
+ * @returns { allowed: true } if not self-promotion, { allowed: false } if blocked
+ */
+export function checkSelfPromotion(ctxAgentId, targetAgentId) {
+    if (ctxAgentId && ctxAgentId === targetAgentId) {
+        return {
+            allowed: false,
+            reason: 'SELF_PROMOTION_BLOCKED: agents cannot promote themselves.',
+        };
+    }
+    return { allowed: true };
+}
+/**
+ * Determine the demotion target level after a safety violation.
+ * Returns the new trust level if demotion is needed, or null if no demotion applies.
+ *
+ * Demotion matrix (I-09 spec):
+ *   critical/high on any level above untrusted → untrusted
+ *   low/medium on admin → trusted
+ *   low/medium on trusted → probationary
+ *   low/medium on probationary → untrusted
+ *   any on untrusted → null (already at lowest)
+ */
+export function getDemotionTarget(currentLevel, severity) {
+    // Already at lowest level — no demotion possible
+    if (currentLevel === 'untrusted') {
+        return null;
+    }
+    // Critical/high severity: drop to untrusted regardless of current level
+    if (severity === 'critical' || severity === 'high') {
+        return 'untrusted';
+    }
+    // Low/medium severity: drop one level
+    const demotionMap = {
+        admin: 'trusted',
+        trusted: 'probationary',
+        probationary: 'untrusted',
+    };
+    return demotionMap[currentLevel];
+}
+//# sourceMappingURL=trust_progression.js.map

package/dist/api/agents/trust_progression.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust_progression.js","sourceRoot":"","sources":["../../../src/api/agents/trust_progression.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAQH,wCAAwC;AAExC;;;;GAIG;AACH,MAAM,UAAU,GAA0C;IACxD,SAAS,EAAE,cAAc;IACzB,YAAY,EAAE,SAAS;IACvB,OAAO,EAAE,OAAO;IAChB,KAAK,EAAE,IAAI,EAAE,sCAAsC;CACpD,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAmB;IACnD,OAAO,UAAU,CAAC,OAAO,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAAqB,EACrB,WAAuB,EACvB,SAA6B;IAE7B,gCAAgC;IAChC,IAAI,SAAS,KAAK,WAAW,EAAE,CAAC;QAC9B,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,2BAA2B,SAAS,IAAI,EAAE,CAAC;IAC5E,CAAC;IAED,2CAA2C;IAC3C,MAAM,QAAQ,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC;IACvC,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,0CAA0C,EAAE,CAAC;IAC9E,CAAC;IAED,IAAI,WAAW,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,MAAM,EAAE,+BAA+B,SAAS,QAAQ,WAAW,uBAAuB,QAAQ,yBAAyB;SAC5H,CAAC;IACJ,CAAC;IAED,6BAA6B;IAC7B,IAAI,WAAW,KAAK,OAAO,IAAI,SAAS,KAAK,OAAO,EAAE,CAAC;QACrD,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,MAAM,EAAE,0CAA0C,SAAS,uCAAuC;SACnG,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACzB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,UAAsC,EACtC,aAAqB;IAErB,IAAI,UAAU,IAAI,UAAU,KAAK,aAAa,EAAE,CAAC;QAC/C,OAAO;YACL,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,2DAA2D;SACpE,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC3B,CAAC;AASD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAC/B,YAAwB,EACxB,QAA2B;IAE3B,iDAAiD;IACjD,IAAI,YAAY,KAAK,WAAW,EAAE,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,wEAAwE;IACxE,IAAI,QAAQ,KAAK,UAAU,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;QACnD,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,sCAAsC;IACtC,MAAM,WAAW,GAAyD;QACxE,KAAK,EAAE,SAAS;QAChB,OAAO,EAAE,cAAc;QACvB,YAAY,EAAE,WAAW;KAC1B,CAAC;IAEF,OAAO,WAAW,CAAC,YAAY,CAAC,CAAC;AACnC,CAAC"}

package/dist/api/chat/chat_pipeline.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Chat pipeline orchestration for the API surface.
+ * S ref: S27 (streaming model), SD-01 (sync return), I-26 (streaming equivalence),
+ *        I-28 (pipeline determinism), FPD-1 (why chat() returns synchronously),
+ *        FPD-8 (HITL approval-required disables streaming)
+ *
+ * Phase: 4 (API Surface)
+ * Implements: SDD §7 build order item 6
+ *
+ * The chat pipeline is the core conversational API. It:
+ *   1. Returns ChatResult SYNCHRONOUSLY (SD-01) -- fields are async
+ *   2. Produces identical ChatResult structure for streaming/non-streaming (I-26)
+ *   3. Delegates to substrate's LlmGateway for LLM generation
+ *   4. Maps LlmStreamChunk -> StreamChunk at the API boundary
+ *   5. Supports AbortSignal cancellation (S27)
+ *   6. Enforces per-call timeout (default 60s per S27)
+ *   7. Implements cooperative backpressure (4KB buffer, 30s stall timeout per S36)
+ *   8. Suppresses streaming in HITL approval-required mode (FPD-8)
+ *
+ * No database tables owned. All state mutations delegated to L2 Orchestration.
+ *
+ * Invariants enforced: I-26 (streaming equivalence), I-27 (conversation integrity),
+ *                      I-28 (pipeline determinism)
+ * Failure modes defended: FM-02 (cost explosion via budget checks),
+ *                         FM-06 (provider unavailability)
+ */
+import type { DatabaseConnection, RateLimiter, RbacEngine } from '../../kernel/interfaces/index.js';
+import type { TimeProvider } from '../../kernel/interfaces/time.js';
+import type { LlmGateway } from '../../substrate/interfaces/substrate.js';
+import type { OrchestrationEngine } from '../../orchestration/interfaces/orchestration.js';
+import type { AuditTrail } from '../../kernel/interfaces/index.js';
+import type { Substrate } from '../../substrate/interfaces/substrate.js';
+import type { ChatMessage, ChatOptions, ChatResult, BackpressureConfig } from '../interfaces/api.js';
+import type { SessionState } from '../sessions/session_manager.js';
+import type { TechniqueReader } from './technique_injector.js';
+/**
+ * S27, SD-01: Chat pipeline that returns ChatResult synchronously.
+ *
+ * Constructed once per createLimen() instance. Shared across all sessions
+ * within that instance, but state isolation is maintained via SessionState.
+ */
+export declare class ChatPipeline {
+    private readonly rbac;
+    private readonly rateLimiter;
+    private readonly orchestration;
+    private readonly gateway;
+    private readonly getConnection;
+    private readonly getAudit;
+    private readonly getSubstrate;
+    private readonly defaultTimeoutMs;
+    private readonly backpressure;
+    private readonly defaultModel;
+    private readonly techniqueReader?;
+    private readonly modelContextWindow;
+    private readonly time?;
+    constructor(rbac: RbacEngine, rateLimiter: RateLimiter, orchestration: OrchestrationEngine, gateway: LlmGateway, getConnection: () => DatabaseConnection, getAudit: () => AuditTrail, getSubstrate: () => Substrate, defaultTimeoutMs: number, backpressure: BackpressureConfig, defaultModel: string, techniqueReader?: TechniqueReader | undefined, modelContextWindow?: number, time?: TimeProvider | undefined);
+    private get clock();
+    /**
+     * S27, SD-01: Execute chat pipeline.
+     * Returns ChatResult SYNCHRONOUSLY (SD-01). The fields (text, stream, metadata)
+     * are individually async.
+     *
+     * FPD-1: Sync return enables immediate stream consumption without extra await.
+     * I-26: Same ChatResult structure regardless of streaming mode.
+     *
+     * @param sessionState - Active session context
+     * @param message - User message (string or ChatMessage)
+     * @param options - Chat options (streaming, timeout, signal, etc.)
+     * @returns ChatResult with async text, stream, and metadata fields
+     */
+    execute(sessionState: SessionState, message: string | ChatMessage, options?: Omit<ChatOptions, 'sessionId'>): ChatResult;
+    /**
+     * Build the async result components for ChatResult.
+     * The pipeline execution drives the stream generator, which in turn
+     * drives text accumulation and metadata collection.
+     */
+    private buildAsyncResult;
+    /**
+     * Run the pipeline and yield stream chunks.
+     *
+     * Delegates to the substrate's LlmGateway for generation.
+     * Maps LlmStreamChunk to public StreamChunk at the API boundary.
+     * Appends turn to conversation via L2 ConversationManager.
+     */
+    private runPipeline;
+    /**
+     * Build OrchestrationDeps for L2 subsystem calls.
+     */
+    private buildOrchDeps;
+}
+//# sourceMappingURL=chat_pipeline.d.ts.map

package/dist/api/chat/chat_pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat_pipeline.d.ts","sourceRoot":"","sources":["../../../src/api/chat/chat_pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EACQ,kBAAkB,EAAE,WAAW,EAAE,UAAU,EAC9D,MAAM,kCAAkC,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,KAAK,EAAE,UAAU,EAAc,MAAM,yCAAyC,CAAC;AACtF,OAAO,KAAK,EAAE,mBAAmB,EAAqB,MAAM,iDAAiD,CAAC;AAC9G,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EACV,WAAW,EAAE,WAAW,EAAE,UAAU,EACJ,kBAAkB,EACnD,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAInE,OAAO,KAAK,EAAE,eAAe,EAA4B,MAAM,yBAAyB,CAAC;AAczF;;;;;GAKG;AACH,qBAAa,YAAY;IAErB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC;IACjC,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IACnC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAZL,IAAI,EAAE,UAAU,EAChB,WAAW,EAAE,WAAW,EACxB,aAAa,EAAE,mBAAmB,EAClC,OAAO,EAAE,UAAU,EACnB,aAAa,EAAE,MAAM,kBAAkB,EACvC,QAAQ,EAAE,MAAM,UAAU,EAC1B,YAAY,EAAE,MAAM,SAAS,EAC7B,gBAAgB,EAAE,MAAM,EACxB,YAAY,EAAE,kBAAkB,EAChC,YAAY,EAAE,MAAM,EACpB,eAAe,CAAC,EAAE,eAAe,YAAA,EACjC,kBAAkB,GAAE,MAAgB,EACpC,IAAI,CAAC,EAAE,YAAY,YAAA;IAGtC,OAAO,KAAK,KAAK,GAEhB;IAED;;;;;;;;;;;;OAYG;IACH,OAAO,CACL,YAAY,EAAE,YAAY,EAC1B,OAAO,EAAE,MAAM,GAAG,WAAW,EAC7B,OAAO,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,GACvC,UAAU;IA4Eb;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAuCxB;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;IA0fnB;;OAEG;IACH,OAAO,CAAC,aAAa;CAQtB"}