@planningo/duul 1.0.0

package/build/services/review-gates.js

@@ -0,0 +1,200 @@
+/**
+ * Post-LLM review gates.
+ *
+ * Each detector returns zero or more GateResult objects. The applyGates
+ * orchestrator merges them into a single delta that the tool handler can
+ * fold into the reviewer's response.
+ *
+ * Motivation: empirical analysis of DUUL sessions showed that the reviewer
+ * reliably APPROVES plans/code that are internally consistent but fail to
+ * address the user's reported symptom. These gates enforce the final
+ * symptom-match check that the model skips under pressure.
+ */
+const SCOPE_PUNT_EN = /out of scope|pre[- ]?existing|unrelated|ignore this|not my job|skip this|isn'?t relevant|isn'?t related/i;
+const SCOPE_PUNT_KO = /범위\s*(바|밖)|무시해|관련\s*없|상관\s*없|제외하고|신경\s*쓰지/;
+const RENDERING_KEYWORDS = /안\s*보|안\s*떠|화면|렌더|display|render|visible|blank|empty screen|\bui\b|버튼|색|회색|gray|disabled|표시|보이지/i;
+const RENDERING_PATH = /(^|\/)(components?|views?|pages?|ui|styles?|render|templates?|layouts?|screens?|frontend|client|web)(\/|$)/i;
+const IMAGE_PATH = /\.(png|jpe?g|gif|webp|svg|bmp|heic|heif|tiff?)$/i;
+const TEST_PATH = /(^|\/)(tests?|__tests__|specs?|e2e|integration[- ]?tests?|unit[- ]?tests?)\//i;
+const TEST_FILE = /\.(test|spec)\.[cm]?[jt]sx?$/i;
+const TEST_REQUEST = /\b(add|write|improve|expand|increase|fix|repair|update|refactor|migrate|unbreak|unflake|restore)\b[^.]*\b(test|coverage|spec|fixture|snapshot)s?\b|\b(failing|broken|flaky|flaking|skipped)\s+(tests?|specs?)\b|테스트.*(추가|작성|보강|확대|개선|수정|고치|고침|리팩|복구)|(고장\s*난|깨진|실패하는)\s*테스트|\bcoverage\b/i;
+/**
+ * Detect scope-punting language in caller notes.
+ * Weak signal: tier REVISE, not HUMAN, because legitimate out-of-scope
+ * notes do exist (e.g. "out of scope — tracked as TICKET-123").
+ */
+export function detectScopePunting(notes) {
+    if (!notes || !notes.trim())
+        return [];
+    const hitEn = SCOPE_PUNT_EN.exec(notes);
+    const hitKo = SCOPE_PUNT_KO.exec(notes);
+    const hit = hitEn?.[0] ?? hitKo?.[0];
+    if (!hit)
+        return [];
+    return [
+        {
+            name: 'scope-punting',
+            severity: 'revise',
+            blocking_issue: {
+                description: `Caller notes contain scope-punt phrase ${JSON.stringify(hit)}. This phrasing often suppresses legitimate blockers.`,
+                suggestion: 'Verify the punted concern independently using file-exploration tools. If it cannot be verified, keep it as a blocking issue rather than dropping it.',
+            },
+        },
+    ];
+}
+/**
+ * Detect changes that only touch test files.
+ * Hard tier HUMAN: real bug fixes almost always touch non-test code.
+ * Skipped when userOriginalRequest explicitly asks for tests (coverage PRs).
+ */
+export function detectTestOnlyChanges(changedFiles, gitDiff, userOriginalRequest) {
+    if (userOriginalRequest && TEST_REQUEST.test(userOriginalRequest)) {
+        return [];
+    }
+    const hasFiles = Array.isArray(changedFiles) && changedFiles.length > 0;
+    const hasDiff = typeof gitDiff === 'string' && gitDiff.length > 0;
+    if (!hasFiles && !hasDiff)
+        return [];
+    const filesTestOnly = hasFiles && changedFiles.every((f) => TEST_PATH.test(f) || TEST_FILE.test(f));
+    let diffTestOnly = false;
+    if (!hasFiles && hasDiff) {
+        const paths = extractDiffPaths(gitDiff);
+        diffTestOnly =
+            paths.length > 0 && paths.every((p) => TEST_PATH.test(p) || TEST_FILE.test(p));
+    }
+    if (!filesTestOnly && !diffTestOnly)
+        return [];
+    return [
+        {
+            name: 'test-only',
+            severity: 'human',
+            blocking_issue: {
+                description: 'All changed files are tests. Fixing the test instead of the underlying bug is a known failure pattern.',
+                suggestion: 'If the original request was to fix a bug, the non-test source file that produces the symptom must also change. If the request really was to add test coverage, set user_original_request accordingly.',
+            },
+        },
+    ];
+}
+/**
+ * Detect caller-pre-diagnosed handoff: short user request + very long
+ * caller notes. The caller may have rewritten the problem in a way that
+ * anchors the reviewer on an incorrect diagnosis.
+ */
+export function detectDiagnosisHandoff(userOriginalRequest, notes) {
+    if (!userOriginalRequest || !notes)
+        return [];
+    const reqLen = userOriginalRequest.trim().length;
+    const notesLen = notes.trim().length;
+    if (reqLen === 0 || reqLen >= 300)
+        return [];
+    if (notesLen <= reqLen * 5)
+        return [];
+    return [
+        {
+            name: 'diagnosis-handoff',
+            severity: 'human',
+            blocking_issue: {
+                description: `Short user request (${reqLen} chars) paired with a long caller diagnosis (${notesLen} chars). The caller may have pre-diagnosed the problem incorrectly.`,
+                suggestion: "Re-derive the problem directly from user_original_request before trusting the caller's notes. Human review recommended.",
+            },
+        },
+    ];
+}
+/**
+ * Detect rendering/UI symptoms when the change does not plausibly touch
+ * rendering code AND the reviewer has not articulated a causal chain.
+ *
+ * Suppressed when any of the following is true:
+ *   - An `artifact_refs` entry has an image path (screenshot documents the bug).
+ *   - A rendering-adjacent path shows up in `changedFiles` OR in `gitDiff`.
+ *   - The reviewer filled `symptom_impact` (before/after/causal_chain all non-empty),
+ *     committing on paper to how the change produces the visual effect. This lets
+ *     backend-only fixes (e.g. "chart is empty" → API fix) pass without a false trip.
+ */
+export function detectRenderingSymptom(userOriginalRequest, artifactRefs, changedFiles, gitDiff, symptomImpact) {
+    if (!userOriginalRequest)
+        return [];
+    if (!RENDERING_KEYWORDS.test(userOriginalRequest))
+        return [];
+    const hasImageArtifact = (artifactRefs ?? []).some((a) => IMAGE_PATH.test(a.path));
+    if (hasImageArtifact)
+        return [];
+    if (isFullyPopulatedSymptomImpact(symptomImpact))
+        return [];
+    const paths = [
+        ...(changedFiles ?? []),
+        ...(typeof gitDiff === 'string' && gitDiff.length > 0 ? extractDiffPaths(gitDiff) : []),
+    ];
+    if (paths.some((p) => RENDERING_PATH.test(p)))
+        return [];
+    return [
+        {
+            name: 'rendering-symptom',
+            severity: 'human',
+            blocking_issue: {
+                description: 'User reports a visual/UI symptom but the change does not touch any rendering-adjacent path, no screenshot artifact was attached, and the reviewer did not articulate how the change produces the visual effect.',
+                suggestion: 'Either (a) confirm the fix touches the rendering/state path that produces the symptom, (b) attach a screenshot as an artifact_ref, or (c) fill `symptom_impact.causal_chain` with the data→UI path so the reviewer commits to the reasoning on paper.',
+            },
+        },
+    ];
+}
+/**
+ * Enforce that the reviewer filled symptom_impact when user_original_request
+ * was supplied. Tier REVISE — the reviewer should self-correct on the
+ * next round.
+ */
+export function enforceSymptomImpact(userOriginalRequest, symptomImpact) {
+    if (!userOriginalRequest)
+        return [];
+    if (isFullyPopulatedSymptomImpact(symptomImpact))
+        return [];
+    return [
+        {
+            name: 'symptom-impact-missing',
+            severity: 'revise',
+            blocking_issue: {
+                description: 'user_original_request was supplied but symptom_impact is missing or incomplete. The reviewer did not commit to what the fix will make the user observe.',
+                suggestion: "Return symptom_impact with non-empty before/after/causal_chain fields, phrased in the user's own vocabulary.",
+            },
+        },
+    ];
+}
+export function applyGates(args) {
+    const results = [
+        ...detectScopePunting(args.notesToReviewer),
+        ...detectTestOnlyChanges(args.changedFiles, args.gitDiff, args.userOriginalRequest),
+        ...detectDiagnosisHandoff(args.userOriginalRequest, args.notesToReviewer),
+        ...detectRenderingSymptom(args.userOriginalRequest, args.artifactRefs, args.changedFiles, args.gitDiff, args.symptomImpact),
+        ...enforceSymptomImpact(args.userOriginalRequest, args.symptomImpact),
+    ];
+    if (results.length === 0) {
+        return { extraBlockingIssues: [], tripped: [] };
+    }
+    const forcedHumanReview = results.some((r) => r.severity === 'human');
+    return {
+        extraBlockingIssues: results.map((r) => r.blocking_issue),
+        forcedVerdict: 'REVISE',
+        forcedHumanReview,
+        tripped: results.map((r) => r.name),
+    };
+}
+function isFullyPopulatedSymptomImpact(impact) {
+    if (!impact || typeof impact !== 'object')
+        return false;
+    const fields = ['before', 'after', 'causal_chain'];
+    return fields.every((f) => {
+        const v = impact[f];
+        return typeof v === 'string' && v.trim() !== '';
+    });
+}
+function extractDiffPaths(diff) {
+    const paths = new Set();
+    const re = /^\+\+\+ b\/(.+)$/gm;
+    let m;
+    while ((m = re.exec(diff)) !== null) {
+        const p = m[1].trim();
+        if (p && p !== '/dev/null')
+            paths.add(p);
+    }
+    return [...paths];
+}

package/build/services/review-limits.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Resolve iteration limits from env vars and per-request overrides.
+ */
+export type ReviewPhase = 'plan' | 'code' | 'partition';
+/**
+ * Get the effective iteration limit for a phase.
+ * Priority: per-request override > env var > default.
+ */
+export declare function getIterationLimit(phase: ReviewPhase, requestOverride?: number): number;
+export interface IterationMeta {
+    iteration_count: number;
+    iteration_limit: number;
+    iteration_limit_reached: boolean;
+}
+/**
+ * Compute iteration metadata for a tool response.
+ * Returns the metadata to merge into the MCP output.
+ *
+ * `iteration_limit_reached` is true when `count > limit`, meaning the current
+ * call was short-circuited (not sent to the reviewer). This matches the
+ * semantics of `isIterationLimitExceeded`.
+ *
+ * When `count === limit`, the review still runs (last allowed iteration),
+ * and `iteration_limit_reached` is false. The caller should note that the
+ * NEXT call will be blocked.
+ */
+export declare function computeIterationMeta(phase: ReviewPhase, callerIterationCount?: number, requestMaxOverride?: number): IterationMeta;
+/**
+ * Check if iteration limit is exceeded BEFORE calling the reviewer.
+ * Returns true when `count > limit` — the call should be short-circuited
+ * with `requires_human_review: true`.
+ *
+ * When `count === limit`, this returns false — the review still runs
+ * (last allowed iteration).
+ */
+export declare function isIterationLimitExceeded(phase: ReviewPhase, callerIterationCount?: number, requestMaxOverride?: number): boolean;

package/build/services/review-limits.js

@@ -0,0 +1,65 @@
+/**
+ * Resolve iteration limits from env vars and per-request overrides.
+ */
+const DEFAULT_PLAN_LIMIT = 7;
+const DEFAULT_CODE_LIMIT = 7;
+const DEFAULT_PARTITION_LIMIT = 5;
+function envInt(name) {
+    const val = process.env[name];
+    if (!val)
+        return undefined;
+    const n = parseInt(val, 10);
+    return isNaN(n) ? undefined : n;
+}
+/**
+ * Get the effective iteration limit for a phase.
+ * Priority: per-request override > env var > default.
+ */
+export function getIterationLimit(phase, requestOverride) {
+    if (requestOverride !== undefined && requestOverride >= 1 && requestOverride <= 20) {
+        return requestOverride;
+    }
+    switch (phase) {
+        case 'plan':
+            return envInt('MAX_PLAN_REVIEW_ITERATIONS') ?? DEFAULT_PLAN_LIMIT;
+        case 'code':
+            return envInt('MAX_CODE_REVIEW_ITERATIONS') ?? DEFAULT_CODE_LIMIT;
+        case 'partition':
+            return envInt('MAX_PARTITION_ITERATIONS') ?? DEFAULT_PARTITION_LIMIT;
+    }
+}
+/**
+ * Compute iteration metadata for a tool response.
+ * Returns the metadata to merge into the MCP output.
+ *
+ * `iteration_limit_reached` is true when `count > limit`, meaning the current
+ * call was short-circuited (not sent to the reviewer). This matches the
+ * semantics of `isIterationLimitExceeded`.
+ *
+ * When `count === limit`, the review still runs (last allowed iteration),
+ * and `iteration_limit_reached` is false. The caller should note that the
+ * NEXT call will be blocked.
+ */
+export function computeIterationMeta(phase, callerIterationCount, requestMaxOverride) {
+    const limit = getIterationLimit(phase, requestMaxOverride);
+    const count = callerIterationCount ?? 1;
+    return {
+        iteration_count: count,
+        iteration_limit: limit,
+        iteration_limit_reached: count > limit,
+    };
+}
+/**
+ * Check if iteration limit is exceeded BEFORE calling the reviewer.
+ * Returns true when `count > limit` — the call should be short-circuited
+ * with `requires_human_review: true`.
+ *
+ * When `count === limit`, this returns false — the review still runs
+ * (last allowed iteration).
+ */
+export function isIterationLimitExceeded(phase, callerIterationCount, requestMaxOverride) {
+    if (callerIterationCount === undefined)
+        return false;
+    const limit = getIterationLimit(phase, requestMaxOverride);
+    return callerIterationCount > limit;
+}

package/build/services/reviewer.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Main reviewer entry point.
+ * Resolves the appropriate provider and delegates the review call.
+ */
+import type { z } from 'zod';
+import type { WorkspaceScope } from './filesystem.js';
+import type { ReviewerProvider, ReviewCallResult, ExhaustionReason, TokenUsage } from './providers/types.js';
+export type { ReviewerProvider, ReviewCallResult, ExhaustionReason, TokenUsage };
+export interface ReviewOptions<T extends z.ZodType> {
+    systemPrompt: string;
+    userMessage: string;
+    schemaName: string;
+    outputSchema: T;
+    workspaceScope?: WorkspaceScope | null;
+    previousReviewId?: string;
+    reviewerConfig?: {
+        provider?: string;
+        model?: string;
+        base_url?: string;
+        api_key?: string;
+        temperature?: number;
+        top_p?: number;
+    };
+    createFallback?: (reason: ExhaustionReason, usedTools: string[]) => z.infer<T>;
+}
+/**
+ * Main entry point for all review calls.
+ * Resolves provider from config, delegates the call.
+ */
+export declare function callReview<T extends z.ZodType>(options: ReviewOptions<T>): Promise<ReviewCallResult<z.infer<T>>>;

package/build/services/reviewer.js

@@ -0,0 +1,243 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { OpenAIProvider } from './providers/openai.js';
+import { AnthropicProvider } from './providers/anthropic.js';
+import { GoogleProvider } from './providers/google.js';
+/**
+ * Resolve the effective provider name from config and env vars.
+ * Priority: per-request config > env REVIEW_PROVIDER > "openai"
+ */
+function resolveProviderName(configProvider) {
+    const name = configProvider ?? process.env.REVIEW_PROVIDER ?? 'openai';
+    const valid = ['openai', 'anthropic', 'google', 'openrouter', 'compatible'];
+    if (!valid.includes(name)) {
+        console.error(`[duul] Unknown provider "${name}", falling back to openai`);
+        return 'openai';
+    }
+    return name;
+}
+/**
+ * Resolve the API key for a provider from environment variables.
+ * For 'compatible', checks REVIEW_API_KEY first, then falls back to OPENAI_API_KEY.
+ */
+function resolveApiKey(provider) {
+    switch (provider) {
+        case 'openai':
+            return process.env.OPENAI_API_KEY;
+        case 'anthropic':
+            return process.env.ANTHROPIC_API_KEY;
+        case 'google':
+            return process.env.GOOGLE_API_KEY;
+        case 'openrouter':
+            return process.env.OPENROUTER_API_KEY;
+        case 'compatible':
+            return process.env.REVIEW_API_KEY ?? process.env.OPENAI_API_KEY;
+        default:
+            return undefined;
+    }
+}
+// Cache providers by config signature to avoid re-creating clients.
+// Capped at MAX_CACHE_SIZE; oldest entries evicted on overflow.
+// Per-request api_key bypasses the cache entirely (ephemeral credentials).
+const MAX_CACHE_SIZE = 10;
+const providerCache = new Map();
+/**
+ * Short fingerprint of an API key for cache identity.
+ * Uses prefix + suffix to detect key changes without storing the full key.
+ */
+function apiKeyFingerprint(key) {
+    if (!key)
+        return 'none';
+    if (key.length <= 8)
+        return key;
+    return `${key.slice(0, 4)}...${key.slice(-4)}`;
+}
+function getProviderCacheKey(provider, config) {
+    const apiKey = config?.api_key ?? resolveApiKey(provider);
+    return JSON.stringify({
+        provider,
+        model: config?.model,
+        base_url: config?.base_url,
+        temperature: config?.temperature,
+        top_p: config?.top_p,
+        key_fp: apiKeyFingerprint(apiKey),
+    });
+}
+/**
+ * Create or retrieve a cached provider instance.
+ */
+function getProvider(reviewerConfig) {
+    const providerName = resolveProviderName(reviewerConfig?.provider);
+    const hasEphemeralKey = !!reviewerConfig?.api_key;
+    // Per-request api_key → skip cache (ephemeral credential, don't leak into shared cache)
+    if (!hasEphemeralKey) {
+        const cacheKey = getProviderCacheKey(providerName, reviewerConfig);
+        if (providerCache.has(cacheKey)) {
+            return providerCache.get(cacheKey);
+        }
+    }
+    const apiKey = reviewerConfig?.api_key ?? resolveApiKey(providerName);
+    const constructorConfig = {
+        apiKey,
+        baseUrl: reviewerConfig?.base_url,
+        model: reviewerConfig?.model,
+        temperature: reviewerConfig?.temperature,
+        topP: reviewerConfig?.top_p,
+    };
+    let provider;
+    switch (providerName) {
+        case 'openai':
+            provider = new OpenAIProvider(constructorConfig);
+            break;
+        case 'anthropic':
+            provider = new AnthropicProvider(constructorConfig);
+            break;
+        case 'google':
+            provider = new GoogleProvider(constructorConfig);
+            break;
+        case 'openrouter':
+            // OpenRouter is OpenAI-compatible
+            provider = new OpenAIProvider({
+                ...constructorConfig,
+                apiKey: constructorConfig.apiKey ?? process.env.OPENROUTER_API_KEY,
+                baseUrl: constructorConfig.baseUrl ?? 'https://openrouter.ai/api/v1',
+            });
+            break;
+        case 'compatible':
+            // Generic OpenAI-compatible endpoint
+            provider = new OpenAIProvider(constructorConfig);
+            break;
+        default:
+            throw new Error(`Unknown provider: ${providerName}`);
+    }
+    // Only cache env-based providers (not ephemeral per-request keys)
+    if (!hasEphemeralKey) {
+        // Evict oldest entry if cache is full
+        if (providerCache.size >= MAX_CACHE_SIZE) {
+            const oldestKey = providerCache.keys().next().value;
+            providerCache.delete(oldestKey);
+            console.error(`[duul] Provider cache full, evicted oldest entry`);
+        }
+        const cacheKey = getProviderCacheKey(providerName, reviewerConfig);
+        providerCache.set(cacheKey, provider);
+    }
+    console.error(`[duul] Created ${providerName} provider (model: ${reviewerConfig?.model ?? 'default'}${hasEphemeralKey ? ', ephemeral key' : ''})`);
+    return provider;
+}
+// --- Conversation history store (disk-persisted per workspace) ---
+const MAX_CONVERSATION_ENTRIES = 20;
+const CONVERSATIONS_DIR = '.duul';
+const CONVERSATIONS_FILE = 'conversations.json';
+/**
+ * In-memory cache backed by disk. Keyed by reviewId.
+ * On every write, the full store is flushed to <workspace_root>/.duul/conversations.json.
+ * On read-miss, attempts to load from disk first.
+ */
+const memoryCache = new Map();
+let diskLoaded = false;
+let lastWorkspaceRoot = null;
+function conversationsPath(workspaceRoot) {
+    return join(workspaceRoot, CONVERSATIONS_DIR, CONVERSATIONS_FILE);
+}
+async function loadFromDisk(workspaceRoot) {
+    if (diskLoaded && lastWorkspaceRoot === workspaceRoot)
+        return;
+    lastWorkspaceRoot = workspaceRoot;
+    diskLoaded = true;
+    try {
+        const raw = await readFile(conversationsPath(workspaceRoot), 'utf-8');
+        const data = JSON.parse(raw);
+        for (const [key, entry] of Object.entries(data)) {
+            if (!memoryCache.has(key)) {
+                memoryCache.set(key, entry);
+            }
+        }
+        console.error(`[duul] Loaded ${Object.keys(data).length} conversation(s) from disk`);
+    }
+    catch {
+        // File doesn't exist yet or is corrupt — start fresh
+    }
+}
+async function flushToDisk(workspaceRoot) {
+    const filePath = conversationsPath(workspaceRoot);
+    try {
+        await mkdir(dirname(filePath), { recursive: true });
+        const data = {};
+        for (const [key, entry] of memoryCache) {
+            data[key] = entry;
+        }
+        await writeFile(filePath, JSON.stringify(data), 'utf-8');
+        console.error(`[duul] Flushed ${memoryCache.size} conversation(s) to ${filePath}`);
+    }
+    catch (error) {
+        console.error(`[duul] Warning: Failed to flush conversations to disk: ${error instanceof Error ? error.message : error}`);
+    }
+}
+function evictOldest() {
+    if (memoryCache.size < MAX_CONVERSATION_ENTRIES)
+        return;
+    let oldestKey = null;
+    let oldestTime = Infinity;
+    for (const [key, entry] of memoryCache) {
+        if (entry.lastAccessed < oldestTime) {
+            oldestTime = entry.lastAccessed;
+            oldestKey = key;
+        }
+    }
+    if (oldestKey) {
+        memoryCache.delete(oldestKey);
+        console.error(`[duul] Conversation store full, evicted oldest entry`);
+    }
+}
+async function getConversationHistory(reviewId, workspaceRoot) {
+    if (workspaceRoot)
+        await loadFromDisk(workspaceRoot);
+    const entry = memoryCache.get(reviewId);
+    if (!entry)
+        return undefined;
+    entry.lastAccessed = Date.now();
+    return entry.turns;
+}
+async function storeConversation(reviewId, turns, workspaceRoot) {
+    evictOldest();
+    memoryCache.set(reviewId, { turns, lastAccessed: Date.now() });
+    if (workspaceRoot) {
+        await flushToDisk(workspaceRoot);
+    }
+}
+/**
+ * Main entry point for all review calls.
+ * Resolves provider from config, delegates the call.
+ */
+export async function callReview(options) {
+    const provider = getProvider(options.reviewerConfig);
+    // Log capability warnings for non-full-featured providers
+    if (!provider.capabilities.toolCalling && options.workspaceScope?.root) {
+        console.error(`[duul] Warning: ${provider.name} provider does not support tool calling. ` +
+            'Reviewer will not be able to explore the workspace. Consider providing more context via relevant_code/artifact_refs.');
+    }
+    if (!provider.capabilities.previousResponseId && options.previousReviewId) {
+        console.error(`[duul] Warning: ${provider.name} provider does not support previous_response_id. ` +
+            'Reviewer context from previous rounds will not be available.');
+    }
+    const workspaceRoot = options.workspaceScope?.root;
+    // Retrieve conversation history for providers that use simulated context
+    // OpenAI uses native previous_response_id, so skip for it
+    let conversationHistory;
+    if (options.previousReviewId && provider.capabilities.previousResponseId && provider.name !== 'openai') {
+        conversationHistory = await getConversationHistory(options.previousReviewId, workspaceRoot);
+        if (conversationHistory) {
+            console.error(`[duul] Loaded conversation history for ${options.previousReviewId} (${conversationHistory.length} turns)`);
+        }
+        else {
+            console.error(`[duul] Warning: No conversation history found for ${options.previousReviewId}`);
+        }
+    }
+    const result = await provider.review({ ...options, conversationHistory });
+    // Store conversation turns for future rounds (non-OpenAI providers)
+    if (result.conversationTurns?.length && provider.name !== 'openai') {
+        await storeConversation(result.reviewId, result.conversationTurns, workspaceRoot);
+        console.error(`[duul] Stored conversation (${result.conversationTurns.length} turns) for ${result.reviewId}`);
+    }
+    return result;
+}

package/build/services/usage-logger.d.ts

@@ -0,0 +1,2 @@
+import type { TokenUsage } from './providers/types.js';
+export declare function logUsage(tool: string, usage: TokenUsage, meta?: Record<string, unknown>): void;

package/build/services/usage-logger.js

@@ -0,0 +1,42 @@
+/**
+ * Appends token usage records to a JSONL log file for historical tracking.
+ *
+ * Gated by $DUUL_DEBUG_TOKEN (truthy: "1", "true", "yes", "on").
+ * Log file location: $DUUL_USAGE_LOG or ~/.duul/usage.jsonl
+ * Each line is a JSON object with timestamp, tool, usage, and metadata.
+ *
+ * This is fire-and-forget — logging failures are silently ignored
+ * to avoid disrupting the review flow.
+ */
+import { appendFile, mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+function getLogPath() {
+    if (process.env.DUUL_USAGE_LOG)
+        return process.env.DUUL_USAGE_LOG;
+    return join(homedir(), '.duul', 'usage.jsonl');
+}
+function isDebugTokenEnabled() {
+    const v = process.env.DUUL_DEBUG_TOKEN?.toLowerCase();
+    return v === '1' || v === 'true' || v === 'yes' || v === 'on';
+}
+export function logUsage(tool, usage, meta = {}) {
+    if (!isDebugTokenEnabled())
+        return;
+    // Fire-and-forget — don't block the review response
+    writeEntry(tool, usage, meta).catch(() => {
+        // Silently ignore logging failures
+    });
+}
+async function writeEntry(tool, usage, meta) {
+    const logPath = getLogPath();
+    await mkdir(dirname(logPath), { recursive: true });
+    const entry = {
+        timestamp: new Date().toISOString(),
+        tool,
+        usage,
+        meta,
+    };
+    await appendFile(logPath, JSON.stringify(entry) + '\n', 'utf-8');
+    console.error(`[duul] Usage logged to ${logPath}`);
+}

package/build/tools/code-review.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerCodeReviewTool(server: McpServer): void;