@proletariat/cli 0.3.105 → 0.3.109

package/dist/lib/orchestrate/escalation.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 3-Tier Escalation Pipeline
+ *
+ * Routes hook actions through a 3-tier decision hierarchy:
+ *
+ * Tier 1 (auto): Deterministic — fires immediately, no decision needed.
+ * Tier 2 (llm): LLM orchestrator decides — approve/deny/escalate.
+ * Tier 3 (human): Human decides — final authority.
+ *
+ * Escalation flows upward: auto → llm → human.
+ * Timeout on LLM response auto-escalates to human.
+ */
+import type { DecisionTier, LlmDecision } from '../work-lifecycle/hooks/types.js';
+/**
+ * Context provided to LLM and human decision-makers.
+ */
+export interface EscalationContext {
+    /** The hook name requesting a decision */
+    hookName: string;
+    /** The event that triggered the hook */
+    event: string;
+    /** The action to be executed if approved */
+    action: string;
+    /** Full event context (ticket, PR, branch, etc.) */
+    ctx: Record<string, unknown>;
+    /** Optional per-hook config */
+    config?: Record<string, unknown>;
+}
+/**
+ * A pending LLM decision queued when no onLlmDecision callback is provided.
+ */
+export interface PendingLlmDecision extends EscalationContext {
+    /** When the decision was queued */
+    queuedAt: number;
+    /** Timeout in ms after which the decision auto-escalates to human */
+    timeoutMs: number;
+}
+/**
+ * A pending human escalation queued when no onHumanEscalation callback is provided.
+ */
+export interface PendingHumanEscalation extends EscalationContext {
+    /** When the escalation was queued */
+    queuedAt: number;
+    /** Reason for escalation (direct human-mode hook, LLM escalated, LLM timed out) */
+    reason: EscalationReason;
+}
+/**
+ * Why a hook was escalated to human tier.
+ */
+export type EscalationReason = 'direct' | 'llm_escalate' | 'llm_timeout';
+/**
+ * Callbacks for the escalation pipeline.
+ */
+export interface EscalationCallbacks {
+    /**
+     * Called when a Tier 2 (LLM) decision is needed.
+     * Should return the LLM's decision: approve, deny, or escalate.
+     * If not provided, decisions are queued in pendingLlmDecisions.
+     */
+    onLlmDecision?: (context: EscalationContext) => Promise<LlmDecision>;
+    /**
+     * Called when a Tier 3 (human) decision is needed.
+     * Should return true to approve, false to deny.
+     * If not provided, decisions are queued in pendingHumanEscalations.
+     */
+    onHumanEscalation?: (context: EscalationContext, reason: EscalationReason) => Promise<boolean>;
+}
+/** Default timeout for LLM decisions before auto-escalating to human (5 minutes). */
+export declare const DEFAULT_LLM_TIMEOUT_MS: number;
+/**
+ * Resolve a HookMode to its decision tier.
+ *
+ * - auto, notify → Tier 1 (auto)
+ * - llm → Tier 2 (llm)
+ * - confirm, human → Tier 3 (human)
+ * - off → Tier 1 (auto) — handled separately as skip
+ */
+export declare function modeToTier(mode: string): DecisionTier;
+/**
+ * Check if a pending LLM decision has timed out.
+ */
+export declare function isLlmDecisionTimedOut(decision: PendingLlmDecision, now?: number): boolean;
+/**
+ * Get all timed-out LLM decisions from a list, returning them
+ * as human escalations with reason 'llm_timeout'.
+ */
+export declare function getTimedOutLlmDecisions(decisions: PendingLlmDecision[], now?: number): PendingHumanEscalation[];

package/dist/lib/orchestrate/escalation.js

@@ -0,0 +1,63 @@
+/**
+ * 3-Tier Escalation Pipeline
+ *
+ * Routes hook actions through a 3-tier decision hierarchy:
+ *
+ * Tier 1 (auto): Deterministic — fires immediately, no decision needed.
+ * Tier 2 (llm): LLM orchestrator decides — approve/deny/escalate.
+ * Tier 3 (human): Human decides — final authority.
+ *
+ * Escalation flows upward: auto → llm → human.
+ * Timeout on LLM response auto-escalates to human.
+ */
+// =============================================================================
+// Configuration
+// =============================================================================
+/** Default timeout for LLM decisions before auto-escalating to human (5 minutes). */
+export const DEFAULT_LLM_TIMEOUT_MS = 5 * 60 * 1000;
+// =============================================================================
+// Utility Functions
+// =============================================================================
+/**
+ * Resolve a HookMode to its decision tier.
+ *
+ * - auto, notify → Tier 1 (auto)
+ * - llm → Tier 2 (llm)
+ * - confirm, human → Tier 3 (human)
+ * - off → Tier 1 (auto) — handled separately as skip
+ */
+export function modeToTier(mode) {
+    switch (mode) {
+        case 'llm':
+            return 'llm';
+        case 'confirm':
+        case 'human':
+            return 'human';
+        default:
+            return 'auto';
+    }
+}
+/**
+ * Check if a pending LLM decision has timed out.
+ */
+export function isLlmDecisionTimedOut(decision, now = Date.now()) {
+    return (now - decision.queuedAt) >= decision.timeoutMs;
+}
+/**
+ * Get all timed-out LLM decisions from a list, returning them
+ * as human escalations with reason 'llm_timeout'.
+ */
+export function getTimedOutLlmDecisions(decisions, now = Date.now()) {
+    return decisions
+        .filter(d => isLlmDecisionTimedOut(d, now))
+        .map(d => ({
+        hookName: d.hookName,
+        event: d.event,
+        action: d.action,
+        ctx: d.ctx,
+        config: d.config,
+        queuedAt: d.queuedAt,
+        reason: 'llm_timeout',
+    }));
+}
+//# sourceMappingURL=escalation.js.map

package/dist/lib/orchestrate/escalation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escalation.js","sourceRoot":"","sources":["../../../src/lib/orchestrate/escalation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAuEH,gFAAgF;AAChF,gBAAgB;AAChB,gFAAgF;AAEhF,qFAAqF;AACrF,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAA;AAEnD,gFAAgF;AAChF,oBAAoB;AACpB,gFAAgF;AAEhF;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,KAAK;YACR,OAAO,KAAK,CAAA;QACd,KAAK,SAAS,CAAC;QACf,KAAK,OAAO;YACV,OAAO,OAAO,CAAA;QAChB;YACE,OAAO,MAAM,CAAA;IACjB,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAA4B,EAAE,MAAc,IAAI,CAAC,GAAG,EAAE;IAC1F,OAAO,CAAC,GAAG,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,SAAS,CAAA;AACxD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CACrC,SAA+B,EAC/B,MAAc,IAAI,CAAC,GAAG,EAAE;IAExB,OAAO,SAAS;SACb,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,qBAAqB,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;SAC1C,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACT,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,GAAG,EAAE,CAAC,CAAC,GAAG;QACV,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,MAAM,EAAE,aAAiC;KAC1C,CAAC,CAAC,CAAA;AACP,CAAC"}

package/dist/lib/orchestrate/index.d.ts

@@ -16,3 +16,5 @@ export { OrchestratePoller } from './poller.js';
 export type { PollerOptions } from './poller.js';
 export { SimplePoller } from './simple-poller.js';
 export type { SimplePollerOptions, PollChange, PollResult } from './simple-poller.js';
+export { createLlmDecisionHandler, buildDecisionPrompt, parseDecisionResponse, gatherDecisionContext, fetchPrDiff, fetchTicketDescription, fetchTestOutput, invokeClaudeLlm, } from './llm-agent.js';
+export type { DecisionContext, LlmAgentOptions } from './llm-agent.js';

package/dist/lib/orchestrate/index.js

@@ -12,4 +12,5 @@ export { ACTION_HANDLERS, executeBuiltinAction, } from './actions.js';
 export { OrchestrateEngine, initOrchestrateEngine, getOrchestrateEngine, stopOrchestrateEngine, } from './engine.js';
 export { OrchestratePoller } from './poller.js';
 export { SimplePoller } from './simple-poller.js';
+export { createLlmDecisionHandler, buildDecisionPrompt, parseDecisionResponse, gatherDecisionContext, fetchPrDiff, fetchTicketDescription, fetchTestOutput, invokeClaudeLlm, } from './llm-agent.js';
 //# sourceMappingURL=index.js.map

package/dist/lib/orchestrate/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/orchestrate/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAcH,OAAO,EACL,kBAAkB,EAClB,UAAU,EACV,eAAe,EACf,YAAY,GACb,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,OAAO,EACP,SAAS,GACV,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,iBAAiB,GAClB,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EACL,eAAe,EACf,oBAAoB,GACrB,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,aAAa,CAAA;AAIpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAG/C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/orchestrate/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAcH,OAAO,EACL,kBAAkB,EAClB,UAAU,EACV,eAAe,EACf,YAAY,GACb,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,OAAO,EACP,SAAS,GACV,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,iBAAiB,GAClB,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EACL,eAAe,EACf,oBAAoB,GACrB,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,aAAa,CAAA;AAIpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAG/C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAGjD,OAAO,EACL,wBAAwB,EACxB,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,WAAW,EACX,sBAAsB,EACtB,eAAe,EACf,eAAe,GAChB,MAAM,gBAAgB,CAAA"}

package/dist/lib/orchestrate/llm-agent.d.ts

@@ -0,0 +1,101 @@
+/**
+ * LLM Orchestrator Agent (Tier 2)
+ *
+ * Implements the onLlmDecision callback for the 3-tier supervision tree.
+ * When the daemon encounters a hook with mode=llm, this agent:
+ *
+ * 1. Gathers rich context — PR diff, ticket description, test output
+ * 2. Builds a structured decision prompt
+ * 3. Calls claude -p (print mode) to get a judgment
+ * 4. Parses the response to return approve/deny/escalate
+ *
+ * This is the bridge between the deterministic daemon (tier 1) and
+ * human escalation (tier 3). Without it, tier 2 is a pass-through.
+ */
+import type { EscalationContext } from './escalation.js';
+import type { LlmDecision } from '../work-lifecycle/hooks/types.js';
+/**
+ * Enriched context gathered for the LLM decision.
+ */
+export interface DecisionContext {
+    /** The original escalation context */
+    escalation: EscalationContext;
+    /** PR diff (truncated if too large) */
+    prDiff?: string;
+    /** Ticket description */
+    ticketDescription?: string;
+    /** Recent test/CI output */
+    testOutput?: string;
+    /** Branch name */
+    branch?: string;
+}
+/**
+ * Options for creating the LLM decision handler.
+ */
+export interface LlmAgentOptions {
+    /** Logger function */
+    log?: (msg: string) => void;
+    /** Maximum characters for PR diff in prompt (default: 8000) */
+    maxDiffChars?: number;
+    /** Maximum characters for test output in prompt (default: 4000) */
+    maxTestOutputChars?: number;
+    /** Timeout in ms for the LLM call (default: 60000) */
+    llmCallTimeoutMs?: number;
+    /** Override the LLM invocation for testing */
+    invokeLlm?: (prompt: string) => string;
+}
+/**
+ * Fetch the PR diff via `gh pr diff`.
+ * Returns undefined if no PR number is available or the command fails.
+ */
+export declare function fetchPrDiff(prNumber: number | undefined, maxChars: number): string | undefined;
+/**
+ * Fetch the ticket description via `prlt ticket show`.
+ * Returns undefined if no ticket ID is available or the command fails.
+ */
+export declare function fetchTicketDescription(ticketId: string | undefined): string | undefined;
+/**
+ * Fetch recent CI/test output via `gh pr checks` or `gh run list`.
+ * Returns undefined if unavailable.
+ */
+export declare function fetchTestOutput(prNumber: number | undefined, maxChars: number): string | undefined;
+/**
+ * Gather enriched context from all available sources.
+ */
+export declare function gatherDecisionContext(escalation: EscalationContext, options: {
+    maxDiffChars: number;
+    maxTestOutputChars: number;
+}): DecisionContext;
+/**
+ * Build the decision prompt for the LLM.
+ *
+ * The prompt is structured to get a clear approve/deny/escalate response
+ * with reasoning.
+ */
+export declare function buildDecisionPrompt(context: DecisionContext): string;
+/**
+ * Parse the LLM response to extract the decision.
+ *
+ * Looks for APPROVE, DENY, or ESCALATE as the first meaningful word.
+ * Falls back to 'escalate' if the response is ambiguous.
+ */
+export declare function parseDecisionResponse(response: string): LlmDecision;
+/**
+ * Invoke the LLM via `claude -p` (print mode).
+ * Returns the raw response text.
+ */
+export declare function invokeClaudeLlm(prompt: string, timeoutMs: number): string;
+/**
+ * Create an onLlmDecision callback for the OrchestrateEngine.
+ *
+ * This is the main entry point — wire this into the engine to activate tier 2.
+ *
+ * @example
+ * ```ts
+ * const engine = new OrchestrateEngine({
+ *   db,
+ *   onLlmDecision: createLlmDecisionHandler({ log: console.log }),
+ * })
+ * ```
+ */
+export declare function createLlmDecisionHandler(options?: LlmAgentOptions): (context: EscalationContext) => Promise<LlmDecision>;

package/dist/lib/orchestrate/llm-agent.js

@@ -0,0 +1,295 @@
+/**
+ * LLM Orchestrator Agent (Tier 2)
+ *
+ * Implements the onLlmDecision callback for the 3-tier supervision tree.
+ * When the daemon encounters a hook with mode=llm, this agent:
+ *
+ * 1. Gathers rich context — PR diff, ticket description, test output
+ * 2. Builds a structured decision prompt
+ * 3. Calls claude -p (print mode) to get a judgment
+ * 4. Parses the response to return approve/deny/escalate
+ *
+ * This is the bridge between the deterministic daemon (tier 1) and
+ * human escalation (tier 3). Without it, tier 2 is a pass-through.
+ */
+import { execSync } from 'node:child_process';
+// =============================================================================
+// Constants
+// =============================================================================
+const DEFAULT_MAX_DIFF_CHARS = 8000;
+const DEFAULT_MAX_TEST_OUTPUT_CHARS = 4000;
+const DEFAULT_LLM_CALL_TIMEOUT_MS = 60_000;
+// =============================================================================
+// Context Gathering (pure functions, individually testable)
+// =============================================================================
+/**
+ * Fetch the PR diff via `gh pr diff`.
+ * Returns undefined if no PR number is available or the command fails.
+ */
+export function fetchPrDiff(prNumber, maxChars) {
+    if (!prNumber)
+        return undefined;
+    try {
+        const diff = execSync(`gh pr diff ${prNumber} --color=never`, {
+            timeout: 15_000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            encoding: 'utf-8',
+        });
+        if (diff.length > maxChars) {
+            return diff.slice(0, maxChars) + `\n\n... [diff truncated at ${maxChars} chars, ${diff.length} total]`;
+        }
+        return diff || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Fetch the ticket description via `prlt ticket show`.
+ * Returns undefined if no ticket ID is available or the command fails.
+ */
+export function fetchTicketDescription(ticketId) {
+    if (!ticketId)
+        return undefined;
+    try {
+        const output = execSync(`prlt ticket show ${ticketId} --json`, {
+            timeout: 10_000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            encoding: 'utf-8',
+        });
+        try {
+            const parsed = JSON.parse(output);
+            const parts = [];
+            if (parsed.result?.title)
+                parts.push(`Title: ${parsed.result.title}`);
+            if (parsed.result?.description)
+                parts.push(`Description: ${parsed.result.description}`);
+            if (parsed.result?.acceptanceCriteria?.length) {
+                parts.push(`Acceptance Criteria:\n${parsed.result.acceptanceCriteria.map((ac) => `  - ${ac}`).join('\n')}`);
+            }
+            return parts.length > 0 ? parts.join('\n') : output;
+        }
+        catch {
+            return output || undefined;
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Fetch recent CI/test output via `gh pr checks` or `gh run list`.
+ * Returns undefined if unavailable.
+ */
+export function fetchTestOutput(prNumber, maxChars) {
+    if (!prNumber)
+        return undefined;
+    try {
+        const output = execSync(`gh pr checks ${prNumber}`, {
+            timeout: 15_000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            encoding: 'utf-8',
+        });
+        if (output.length > maxChars) {
+            return output.slice(0, maxChars) + `\n\n... [output truncated at ${maxChars} chars]`;
+        }
+        return output || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Gather enriched context from all available sources.
+ */
+export function gatherDecisionContext(escalation, options) {
+    const prNumber = escalation.ctx.pr;
+    const ticketId = escalation.ctx.ticket;
+    const branch = escalation.ctx.branch;
+    return {
+        escalation,
+        prDiff: fetchPrDiff(prNumber, options.maxDiffChars),
+        ticketDescription: fetchTicketDescription(ticketId),
+        testOutput: fetchTestOutput(prNumber, options.maxTestOutputChars),
+        branch,
+    };
+}
+// =============================================================================
+// Prompt Construction (pure function, testable)
+// =============================================================================
+/**
+ * Build the decision prompt for the LLM.
+ *
+ * The prompt is structured to get a clear approve/deny/escalate response
+ * with reasoning.
+ */
+export function buildDecisionPrompt(context) {
+    const { escalation, prDiff, ticketDescription, testOutput, branch } = context;
+    const sections = [];
+    sections.push(`# Orchestrator Decision Required
+
+You are an autonomous orchestrator agent making a tier-2 decision in a 3-tier supervision tree.
+Your role: review the context and decide whether to APPROVE, DENY, or ESCALATE this action.
+
+## Decision
+
+- **Hook:** ${escalation.hookName}
+- **Event:** ${escalation.event}
+- **Action:** ${escalation.action}
+${branch ? `- **Branch:** ${branch}` : ''}
+${escalation.config ? `- **Config:** ${JSON.stringify(escalation.config)}` : ''}`);
+    if (ticketDescription) {
+        sections.push(`## Ticket Context
+
+${ticketDescription}`);
+    }
+    if (prDiff) {
+        sections.push(`## PR Diff
+
+\`\`\`diff
+${prDiff}
+\`\`\``);
+    }
+    if (testOutput) {
+        sections.push(`## CI/Test Status
+
+\`\`\`
+${testOutput}
+\`\`\``);
+    }
+    sections.push(`## Decision Guidelines
+
+Consider these factors:
+1. **Safety** — Does the action risk data loss, downtime, or breaking changes?
+2. **Context match** — Does the action align with the event and ticket context?
+3. **CI status** — Are tests passing? Is the diff reasonable?
+4. **Scope** — Is the action proportional to the event?
+
+### When to APPROVE
+- CI is green and the action is a natural next step (e.g., merge after green CI)
+- Agent spawn for a ticket that's ready and has clear requirements
+- Respawn of a died agent with retries remaining
+
+### When to DENY
+- CI is failing and the action would advance the pipeline (e.g., merge a failing PR)
+- The diff contains suspicious changes (secrets, large deletions, unrelated files)
+- The action doesn't match the event context
+
+### When to ESCALATE
+- The situation is ambiguous or high-stakes (production deployments, large refactors)
+- You lack sufficient context to make a confident decision
+- The action involves irreversible operations on shared resources
+
+## Response Format
+
+Respond with EXACTLY one of these words on the first line, followed by your reasoning:
+
+APPROVE
+DENY
+ESCALATE
+
+Then explain your reasoning briefly.`);
+    return sections.join('\n\n');
+}
+// =============================================================================
+// Response Parsing (pure function, testable)
+// =============================================================================
+/**
+ * Parse the LLM response to extract the decision.
+ *
+ * Looks for APPROVE, DENY, or ESCALATE as the first meaningful word.
+ * Falls back to 'escalate' if the response is ambiguous.
+ */
+export function parseDecisionResponse(response) {
+    const trimmed = response.trim();
+    if (!trimmed)
+        return 'escalate';
+    // Check the first non-empty line for the decision keyword
+    const lines = trimmed.split('\n');
+    for (const line of lines) {
+        const cleaned = line.trim().toUpperCase();
+        if (!cleaned)
+            continue;
+        if (cleaned.startsWith('APPROVE'))
+            return 'approve';
+        if (cleaned.startsWith('DENY'))
+            return 'deny';
+        if (cleaned.startsWith('ESCALATE'))
+            return 'escalate';
+        // Only check the first non-empty line
+        break;
+    }
+    // Fallback: scan the full response for keywords (less reliable)
+    const upper = trimmed.toUpperCase();
+    if (upper.includes('APPROVE') && !upper.includes('DENY') && !upper.includes('ESCALATE')) {
+        return 'approve';
+    }
+    if (upper.includes('DENY') && !upper.includes('APPROVE') && !upper.includes('ESCALATE')) {
+        return 'deny';
+    }
+    // When in doubt, escalate to human
+    return 'escalate';
+}
+// =============================================================================
+// LLM Invocation
+// =============================================================================
+/**
+ * Invoke the LLM via `claude -p` (print mode).
+ * Returns the raw response text.
+ */
+export function invokeClaudeLlm(prompt, timeoutMs) {
+    return execSync(`claude -p --output-format text`, {
+        input: prompt,
+        timeout: timeoutMs,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        encoding: 'utf-8',
+        maxBuffer: 10 * 1024 * 1024,
+    });
+}
+// =============================================================================
+// Factory: onLlmDecision callback
+// =============================================================================
+/**
+ * Create an onLlmDecision callback for the OrchestrateEngine.
+ *
+ * This is the main entry point — wire this into the engine to activate tier 2.
+ *
+ * @example
+ * ```ts
+ * const engine = new OrchestrateEngine({
+ *   db,
+ *   onLlmDecision: createLlmDecisionHandler({ log: console.log }),
+ * })
+ * ```
+ */
+export function createLlmDecisionHandler(options = {}) {
+    const log = options.log ?? (() => { });
+    const maxDiffChars = options.maxDiffChars ?? DEFAULT_MAX_DIFF_CHARS;
+    const maxTestOutputChars = options.maxTestOutputChars ?? DEFAULT_MAX_TEST_OUTPUT_CHARS;
+    const llmCallTimeoutMs = options.llmCallTimeoutMs ?? DEFAULT_LLM_CALL_TIMEOUT_MS;
+    const callLlm = options.invokeLlm ?? ((prompt) => invokeClaudeLlm(prompt, llmCallTimeoutMs));
+    return async (context) => {
+        log(`[llm-agent] Decision requested: ${context.hookName} → ${context.action} (event: ${context.event})`);
+        try {
+            // 1. Gather enriched context
+            const enriched = gatherDecisionContext(context, { maxDiffChars, maxTestOutputChars });
+            // 2. Build the prompt
+            const prompt = buildDecisionPrompt(enriched);
+            log(`[llm-agent] Prompt built (${prompt.length} chars)`);
+            // 3. Call the LLM
+            const response = callLlm(prompt);
+            log(`[llm-agent] Response received (${response.length} chars)`);
+            // 4. Parse the decision
+            const decision = parseDecisionResponse(response);
+            log(`[llm-agent] Decision: ${decision} for ${context.hookName} → ${context.action}`);
+            return decision;
+        }
+        catch (err) {
+            // On any error, escalate to human rather than silently approving/denying
+            const errMsg = err instanceof Error ? err.message : String(err);
+            log(`[llm-agent] Error during decision — escalating to human: ${errMsg}`);
+            return 'escalate';
+        }
+    };
+}
+//# sourceMappingURL=llm-agent.js.map

package/dist/lib/orchestrate/llm-agent.js.map

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

package/dist/lib/orchestrate/presets.d.ts

@@ -2,10 +2,11 @@
  * Orchestrate Presets
  *
  * Pre-configured hook sets for common automation levels.
+ * Maps to the 3-tier supervision tree:
  *
- * - aggressive: auto-everything — no human needed
- * - conservative: confirm everything — human approves all
- * - supervised: auto for safe ops, confirm for destructive
+ * - aggressive: all auto (Tier 1) — no decision needed
+ * - supervised: safe=auto (Tier 1), destructive=llm (Tier 2)
+ * - conservative: safe=auto (Tier 1), destructive=human (Tier 3)
  */
 import type { HookMode, OrchestrateEvent, PresetName } from './types.js';
 interface PresetHook {

package/dist/lib/orchestrate/presets.js

@@ -2,10 +2,11 @@
  * Orchestrate Presets
  *
  * Pre-configured hook sets for common automation levels.
+ * Maps to the 3-tier supervision tree:
  *
- * - aggressive: auto-everything — no human needed
- * - conservative: confirm everything — human approves all
- * - supervised: auto for safe ops, confirm for destructive
+ * - aggressive: all auto (Tier 1) — no decision needed
+ * - supervised: safe=auto (Tier 1), destructive=llm (Tier 2)
+ * - conservative: safe=auto (Tier 1), destructive=human (Tier 3)
  */
 const SHARED_HOOKS = [
     // PR lifecycle
@@ -25,6 +26,7 @@ const SHARED_HOOKS = [
     { event: 'on_agent_died', action: 'respawn', config: { max_retries: 2 } },
     { event: 'on_agent_died', action: 'notify' },
     { event: 'on_agent_idle', action: 'health-check' },
+    { event: 'on_agent_idle', action: 'gc-sweep' },
     // Review lifecycle
     { event: 'on_review_approved', action: 'notify' },
     { event: 'on_changes_requested', action: 'spawn-fix-agent' },
@@ -32,6 +34,8 @@ const SHARED_HOOKS = [
     // CI lifecycle
     { event: 'on_ci_failed', action: 'notify' },
     { event: 'on_ci_failed', action: 'spawn-fix-agent' },
+    // Periodic cleanup
+    { event: 'on_agent_completed', action: 'gc-sweep' },
 ];
 /**
  * Safe actions that can be auto-executed even in supervised mode.
@@ -50,11 +54,12 @@ const SAFE_ACTIONS = new Set([
     'health-check',
     'rebase-conflicting-prs',
     'spawn-review-agent',
+    'gc-sweep',
 ]);
 export const PRESETS = {
     aggressive: {
         name: 'aggressive',
-        description: 'Auto everything — no human needed',
+        description: 'Auto everything — Tier 1 only, no decisions needed',
         hooks: SHARED_HOOKS.map(h => ({
             ...h,
             mode: 'auto',
@@ -62,18 +67,18 @@ export const PRESETS = {
     },
     conservative: {
         name: 'conservative',
-        description: 'Confirm everything — human approves all actions',
+        description: 'Safe=auto (Tier 1), destructive=human (Tier 3)',
         hooks: SHARED_HOOKS.map(h => ({
             ...h,
-            mode: 'confirm',
+            mode: (SAFE_ACTIONS.has(h.action) ? 'auto' : 'human'),
         })),
     },
     supervised: {
         name: 'supervised',
-        description: 'Auto for safe ops, confirm for destructive actions',
+        description: 'Safe=auto (Tier 1), destructive=llm (Tier 2)',
         hooks: SHARED_HOOKS.map(h => ({
             ...h,
-            mode: (SAFE_ACTIONS.has(h.action) ? 'auto' : 'confirm'),
+            mode: (SAFE_ACTIONS.has(h.action) ? 'auto' : 'llm'),
         })),
     },
 };