@planningo/duul 1.0.0

package/build/services/providers/openai.js

@@ -0,0 +1,395 @@
+import OpenAI from 'openai';
+import { zodTextFormat } from 'openai/helpers/zod';
+import { validateProjectRoot } from '../filesystem.js';
+import { executeFilesystemTool } from '../filesystem-tools.js';
+import { estimateCost } from '../pricing.js';
+const MAX_INPUT_CHARS = 400_000;
+const MAX_TOOL_ROUNDS = 10;
+const MAX_RETRIES = 3;
+const MAX_REPEAT_CALLS = 3;
+const LINKED_PATH_HINT = ' To access a linked root, prefix with "linked:<index>:<path>" (e.g. "linked:0:src/types.ts").';
+const FILESYSTEM_TOOLS = [
+    {
+        type: 'function',
+        name: 'read_file',
+        description: 'Read a file from the project being reviewed. Use this to examine type definitions, ' +
+            'data models, interfaces, utility functions, and any code you need for thorough review context. ' +
+            'Returns file contents as text.' + LINKED_PATH_HINT,
+        parameters: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Relative path from project root (e.g. "src/types.ts"), or "linked:<index>:<path>" for linked roots',
+                },
+            },
+            required: ['path'],
+            additionalProperties: false,
+        },
+        strict: true,
+    },
+    {
+        type: 'function',
+        name: 'list_directory',
+        description: 'List files and directories at a path in the project. Use this to understand project structure.' + LINKED_PATH_HINT,
+        parameters: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Relative path from project root. Use "." for project root, or "linked:<index>:<path>" for linked roots.',
+                },
+            },
+            required: ['path'],
+            additionalProperties: false,
+        },
+        strict: true,
+    },
+    {
+        type: 'function',
+        name: 'search_in_files',
+        description: 'Search for a pattern across project files. Uses ripgrep when available, falls back to git grep. ' +
+            'PREFER this over read_file when you need to find specific symbols, keywords, or patterns. ' +
+            'Returns matching lines with file paths and line numbers. ' +
+            'Search is restricted to allowed working directories when configured.',
+        parameters: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Search pattern (literal string or regex)' },
+                paths: { type: ['array', 'null'], items: { type: 'string' }, description: 'Optional: restrict search to these relative paths/directories' },
+                glob: { type: ['string', 'null'], description: 'Optional: glob pattern to filter files (e.g. "*.ts", "src/**/*.js")' },
+            },
+            required: ['query', 'paths', 'glob'],
+            additionalProperties: false,
+        },
+        strict: true,
+    },
+    {
+        type: 'function',
+        name: 'read_file_range',
+        description: 'Read a specific line range from a file. PREFER this over read_file for large files. Returns numbered lines. Max 200 lines per call.' + LINKED_PATH_HINT,
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Relative path from project root, or "linked:<index>:<path>" for linked roots' },
+                start_line: { type: 'number', description: 'First line to read (1-based)' },
+                end_line: { type: 'number', description: 'Last line to read (1-based, inclusive)' },
+            },
+            required: ['path', 'start_line', 'end_line'],
+            additionalProperties: false,
+        },
+        strict: true,
+    },
+    {
+        type: 'function',
+        name: 'stat_file',
+        description: 'Get file metadata: size, type, and modification time. Use this before read_file to check if a file is too large.' + LINKED_PATH_HINT,
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Relative path from project root, or "linked:<index>:<path>" for linked roots' },
+            },
+            required: ['path'],
+            additionalProperties: false,
+        },
+        strict: true,
+    },
+    {
+        type: 'function',
+        name: 'read_json',
+        description: 'Read a JSON file, optionally extracting a value at a JSON pointer path. Use this for package.json, tsconfig.json, etc.' + LINKED_PATH_HINT,
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Relative path to a JSON file, or "linked:<index>:<path>" for linked roots' },
+                json_pointer: { type: ['string', 'null'], description: 'Optional: JSON pointer (e.g. "/dependencies", "/scripts/build")' },
+            },
+            required: ['path', 'json_pointer'],
+            additionalProperties: false,
+        },
+        strict: true,
+    },
+    {
+        type: 'function',
+        name: 'list_tracked_files',
+        description: 'List git-tracked files, optionally filtered by a directory prefix. Only shows files committed to git.',
+        parameters: {
+            type: 'object',
+            properties: {
+                prefix: { type: ['string', 'null'], description: 'Optional: directory prefix to filter (e.g. "src/")' },
+            },
+            required: ['prefix'],
+            additionalProperties: false,
+        },
+        strict: true,
+    },
+    {
+        type: 'function',
+        name: 'get_git_diff',
+        description: 'Get git diff output for the workspace. Use this to see exactly what changed — ' +
+            'PREFER this over reading full files when reviewing modifications. ' +
+            'Returns unified diff format. Defaults to comparing against HEAD (current workspace changes). Also includes untracked new files.',
+        parameters: {
+            type: 'object',
+            properties: {
+                base: { type: ['string', 'null'], description: 'Base ref to diff against (e.g. "HEAD~1", "main", a commit SHA). Defaults to HEAD.' },
+                paths: { type: ['array', 'null'], items: { type: 'string' }, description: 'Optional: restrict diff to these relative paths' },
+            },
+            required: ['base', 'paths'],
+            additionalProperties: false,
+        },
+        strict: true,
+    },
+];
+// Guard: strict: true requires every property key to be in required.
+// Catches the mistake at module load time, not at OpenAI call time.
+for (const tool of FILESYSTEM_TOOLS) {
+    if (!('strict' in tool) || !tool.strict)
+        continue;
+    const props = Object.keys(tool.parameters.properties);
+    const req = new Set(tool.parameters.required);
+    const missing = props.filter((k) => !req.has(k));
+    if (missing.length > 0) {
+        throw new Error(`[duul] Tool "${tool.name}" has strict: true but properties [${missing.join(', ')}] are not in required. ` +
+            `Use type union with null for optional params.`);
+    }
+}
+function validateInputLength(systemPrompt, userMessage) {
+    const totalChars = systemPrompt.length + userMessage.length;
+    if (totalChars > MAX_INPUT_CHARS) {
+        const estimatedTokens = Math.ceil(totalChars / 4);
+        const maxTokens = Math.ceil(MAX_INPUT_CHARS / 4);
+        throw new Error(`Input too large (~${estimatedTokens} estimated tokens, max ~${maxTokens}). ` +
+            `Total input: ${totalChars} chars (system: ${systemPrompt.length}, user: ${userMessage.length}). ` +
+            `Reduce the size of your input fields — try trimming file_tree, plan, or code content.`);
+    }
+}
+export class OpenAIProvider {
+    name = 'openai';
+    capabilities = {
+        structuredOutputs: true,
+        toolCalling: true,
+        previousResponseId: true,
+        jsonSchemaStrict: true,
+    };
+    client;
+    model;
+    temperature;
+    topP;
+    constructor(config) {
+        const apiKey = config?.apiKey ?? process.env.OPENAI_API_KEY;
+        if (!apiKey) {
+            throw new Error('OPENAI_API_KEY environment variable is not set');
+        }
+        this.client = new OpenAI({
+            apiKey,
+            ...(config?.baseUrl ? { baseURL: config.baseUrl } : {}),
+        });
+        this.model = config?.model ?? process.env.REVIEW_MODEL ?? 'gpt-5.4';
+        this.temperature = config?.temperature ?? 0.2;
+        this.topP = config?.topP ?? 0.1;
+    }
+    async review(options) {
+        const { systemPrompt, userMessage, schemaName, outputSchema, workspaceScope, previousReviewId } = options;
+        validateInputLength(systemPrompt, userMessage);
+        const effectiveRoot = workspaceScope?.root ?? null;
+        if (effectiveRoot && !workspaceScope) {
+            validateProjectRoot(effectiveRoot);
+        }
+        const tools = effectiveRoot ? FILESYSTEM_TOOLS : undefined;
+        let allUsedTools = [];
+        // Accumulate token usage across all API calls
+        let totalInputTokens = 0;
+        let totalOutputTokens = 0;
+        let totalCachedInputTokens = 0;
+        let apiCallCount = 0;
+        const accumulateUsage = (response) => {
+            apiCallCount++;
+            const u = response.usage;
+            if (u) {
+                totalInputTokens += u.input_tokens ?? 0;
+                totalOutputTokens += u.output_tokens ?? 0;
+                totalCachedInputTokens += u.input_tokens_details?.cached_tokens ?? 0;
+            }
+        };
+        const buildUsage = () => ({
+            input_tokens: totalInputTokens,
+            output_tokens: totalOutputTokens,
+            total_tokens: totalInputTokens + totalOutputTokens,
+            api_calls: apiCallCount,
+            provider: 'openai',
+            model: this.model,
+            estimated_cost_usd: estimateCost(this.model, totalInputTokens, totalOutputTokens, totalCachedInputTokens),
+            ...(totalCachedInputTokens > 0 ? { cached_input_tokens: totalCachedInputTokens } : {}),
+        });
+        const baseParams = {
+            model: this.model,
+            instructions: systemPrompt,
+            temperature: this.temperature,
+            top_p: this.topP,
+            max_output_tokens: 16384,
+            text: { format: zodTextFormat(outputSchema, schemaName) },
+            ...(tools ? { tools } : {}),
+        };
+        let response = await this.apiCallWithRetry({
+            ...baseParams,
+            input: [{ role: 'user', content: [{ type: 'input_text', text: userMessage }] }],
+            ...(previousReviewId ? { previous_response_id: previousReviewId } : {}),
+        });
+        accumulateUsage(response);
+        console.error(`[duul] response.id=${response.id} model=${this.model} provider=openai`);
+        // Agentic tool-calling loop
+        if (effectiveRoot) {
+            const toolReadBudget = MAX_INPUT_CHARS - (systemPrompt.length + userMessage.length);
+            let accumulatedToolChars = 0;
+            const FULL_READ_TOOLS = new Set(['read_file', 'get_git_diff']);
+            const SEARCH_ONLY_TOOLS = new Set(['search_in_files', 'list_tracked_files', 'stat_file']);
+            const getStrategyLevel = () => {
+                const ratio = accumulatedToolChars / toolReadBudget;
+                if (ratio < 0.5)
+                    return 0;
+                if (ratio < 0.8)
+                    return 1;
+                if (ratio < 1.0)
+                    return 2;
+                return 3;
+            };
+            const isToolAllowed = (toolName, level) => {
+                if (level >= 3)
+                    return false;
+                if (level >= 2)
+                    return SEARCH_ONLY_TOOLS.has(toolName);
+                if (level >= 1)
+                    return !FULL_READ_TOOLS.has(toolName);
+                return true;
+            };
+            const budgetMessage = (toolName, level) => {
+                if (level >= 3)
+                    return 'Budget exhausted. You must produce your final review verdict now with the context you already have.';
+                if (level >= 2)
+                    return `[Budget Level 2] Only search/stat tools allowed. "${toolName}" blocked.`;
+                if (level >= 1)
+                    return `[Budget Level 1] Full file reads blocked. "${toolName}" not allowed. Use read_file_range or search_in_files.`;
+                return '';
+            };
+            const toolCache = new Map();
+            const callCounts = new Map();
+            for (let round = 0; round < MAX_TOOL_ROUNDS; round++) {
+                const functionCalls = this.getFunctionCalls(response);
+                if (functionCalls.length === 0)
+                    break;
+                const strategyLevel = getStrategyLevel();
+                console.error(`[duul] Tool round ${round + 1}: ${functionCalls.length} call(s), budget ${accumulatedToolChars}/${toolReadBudget} (level ${strategyLevel})`);
+                const toolResults = [];
+                for (const call of functionCalls) {
+                    if (call.type !== 'function_call')
+                        continue;
+                    const args = JSON.parse(call.arguments);
+                    const cacheKey = `${call.name}:${call.arguments}`;
+                    const argSummary = args.path ?? args.query ?? args.prefix ?? '';
+                    const count = (callCounts.get(cacheKey) ?? 0) + 1;
+                    callCounts.set(cacheKey, count);
+                    if (count > MAX_REPEAT_CALLS) {
+                        toolResults.push({ type: 'function_call_output', call_id: call.call_id, output: 'You have already read this content multiple times. Use the context you already have to complete your review.' });
+                        continue;
+                    }
+                    if (toolCache.has(cacheKey)) {
+                        toolResults.push({ type: 'function_call_output', call_id: call.call_id, output: toolCache.get(cacheKey) });
+                        continue;
+                    }
+                    const currentLevel = getStrategyLevel();
+                    if (!isToolAllowed(call.name, currentLevel)) {
+                        toolResults.push({ type: 'function_call_output', call_id: call.call_id, output: budgetMessage(call.name, currentLevel) });
+                        continue;
+                    }
+                    const result = await executeFilesystemTool(effectiveRoot, call.name, args, workspaceScope);
+                    toolCache.set(cacheKey, result);
+                    allUsedTools.push(`${call.name}(${argSummary})`);
+                    accumulatedToolChars += result.length;
+                    console.error(`[duul]   ${call.name}(${argSummary}) -> ${result.length} chars (total: ${accumulatedToolChars}/${toolReadBudget}, level ${getStrategyLevel()})`);
+                    toolResults.push({ type: 'function_call_output', call_id: call.call_id, output: result });
+                }
+                response = await this.apiCallWithRetry({ ...baseParams, previous_response_id: response.id, input: toolResults });
+                accumulateUsage(response);
+                console.error(`[duul] response.id=${response.id} (after tool round ${round + 1})`);
+                if (getStrategyLevel() >= 3 && this.hasPendingFunctionCalls(response)) {
+                    const stopResults = this.getFunctionCalls(response).filter((c) => c.type === 'function_call').map((c) => ({
+                        type: 'function_call_output', call_id: c.call_id,
+                        output: 'No more file reads allowed. You must produce your final review verdict now.',
+                    }));
+                    response = await this.apiCallWithRetry({ ...baseParams, previous_response_id: response.id, input: stopResults });
+                    accumulateUsage(response);
+                    break;
+                }
+                if (getStrategyLevel() >= 3)
+                    break;
+            }
+            if (this.hasPendingFunctionCalls(response)) {
+                const stopResults = this.getFunctionCalls(response).filter((c) => c.type === 'function_call').map((c) => ({
+                    type: 'function_call_output', call_id: c.call_id,
+                    output: 'Tool call limit reached. You must produce your final review verdict now.',
+                }));
+                response = await this.apiCallWithRetry({ ...baseParams, previous_response_id: response.id, input: stopResults });
+                accumulateUsage(response);
+            }
+        }
+        const usage = buildUsage();
+        const costStr = usage.estimated_cost_usd !== null ? ` (~$${usage.estimated_cost_usd.toFixed(4)})` : '';
+        const cachedStr = usage.cached_input_tokens ? ` [cached: ${usage.cached_input_tokens}]` : '';
+        console.error(`[duul] Token usage: ${usage.input_tokens} in + ${usage.output_tokens} out = ${usage.total_tokens} total (${usage.api_calls} API calls)${cachedStr}${costStr}`);
+        // Extract structured output
+        const parsed = this.extractStructuredOutput(response, outputSchema);
+        if (parsed !== null) {
+            return { parsed, reviewId: response.id, usage };
+        }
+        if (options.createFallback) {
+            const reason = this.hasPendingFunctionCalls(response) ? 'round_limit' : 'budget';
+            const fallback = options.createFallback(reason, allUsedTools);
+            console.error(`[duul] Returning structured fallback (reason: ${reason}).`);
+            return { parsed: fallback, reviewId: response.id, usage };
+        }
+        throw new Error('Review failed: could not obtain structured verdict after tool loop.');
+    }
+    async apiCallWithRetry(params) {
+        for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 120_000);
+            try {
+                const response = await this.client.responses.create({ ...params, stream: false }, { signal: controller.signal });
+                clearTimeout(timeout);
+                return response;
+            }
+            catch (error) {
+                clearTimeout(timeout);
+                const isRetryable = error instanceof Error && ('status' in error ? (error.status === 429 || error.status >= 500) : error.name === 'AbortError');
+                if (isRetryable && attempt < MAX_RETRIES - 1) {
+                    const delay = 1000 * Math.pow(2, attempt);
+                    console.error(`[duul] Retry ${attempt + 1}/${MAX_RETRIES} after ${delay}ms`);
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                    continue;
+                }
+                throw error;
+            }
+        }
+        throw new Error('Unreachable: exhausted retries');
+    }
+    extractStructuredOutput(response, outputSchema) {
+        for (const item of response.output) {
+            if (item.type === 'message' && 'content' in item) {
+                const msg = item;
+                for (const content of msg.content) {
+                    if (content.type === 'output_text' && content.text) {
+                        return outputSchema.parse(JSON.parse(content.text));
+                    }
+                }
+            }
+        }
+        return null;
+    }
+    hasPendingFunctionCalls(response) {
+        return response.output.some((item) => item.type === 'function_call');
+    }
+    getFunctionCalls(response) {
+        return response.output.filter((item) => item.type === 'function_call');
+    }
+}

package/build/services/providers/types.d.ts

@@ -0,0 +1,82 @@
+import type { z } from 'zod';
+import type { WorkspaceScope } from '../filesystem.js';
+export type ExhaustionReason = 'budget' | 'repeat' | 'round_limit';
+/**
+ * Token usage from a single review call.
+ * Accumulated across all API calls (including tool loop rounds).
+ */
+export interface TokenUsage {
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    /** Number of API calls made (1 + tool loop rounds) */
+    api_calls: number;
+    provider: string;
+    model: string;
+    /** Estimated cost in USD (null if pricing unknown for this model) */
+    estimated_cost_usd: number | null;
+    /** Input tokens served from provider prompt cache (billed at ~0.1× input). */
+    cached_input_tokens?: number;
+    /** Input tokens written to the provider prompt cache (Anthropic only; billed at ~1.25× input). */
+    cache_creation_input_tokens?: number;
+}
+/**
+ * A single conversation turn, used to simulate previous_response_id
+ * for providers that don't support it natively (Anthropic, Google).
+ */
+export interface ConversationTurn {
+    role: 'user' | 'assistant';
+    content: unknown;
+}
+export interface ReviewCallOptions<T extends z.ZodType> {
+    systemPrompt: string;
+    userMessage: string;
+    schemaName: string;
+    outputSchema: T;
+    workspaceScope?: WorkspaceScope | null;
+    previousReviewId?: string;
+    /** Conversation history from previous rounds (for providers without native context persistence) */
+    conversationHistory?: ConversationTurn[];
+    /** Factory to create a structured fallback when the tool loop is exhausted */
+    createFallback?: (reason: ExhaustionReason, usedTools: string[]) => z.infer<T>;
+}
+export interface ReviewCallResult<T> {
+    parsed: T;
+    reviewId: string;
+    usage: TokenUsage;
+    /** Conversation turns from this review (for storage/replay in subsequent rounds) */
+    conversationTurns?: ConversationTurn[];
+}
+/**
+ * Describes what a provider supports.
+ * Used for capability-aware degradation.
+ */
+export interface ProviderCapabilities {
+    /** Supports structured output (JSON schema enforcement) */
+    structuredOutputs: boolean;
+    /** Supports tool/function calling */
+    toolCalling: boolean;
+    /** Supports previous_response_id for conversation continuity */
+    previousResponseId: boolean;
+    /** Supports strict JSON schema mode */
+    jsonSchemaStrict: boolean;
+}
+/**
+ * Common interface for all reviewer providers.
+ */
+export interface ReviewerProvider {
+    readonly name: string;
+    readonly capabilities: ProviderCapabilities;
+    review<T extends z.ZodType>(options: ReviewCallOptions<T>): Promise<ReviewCallResult<z.infer<T>>>;
+}
+/**
+ * Configuration for creating a provider instance.
+ */
+export interface ProviderConfig {
+    provider: 'openai' | 'anthropic' | 'google' | 'openrouter' | 'compatible';
+    model?: string;
+    apiKey?: string;
+    baseUrl?: string;
+    temperature?: number;
+    topP?: number;
+}

package/build/services/providers/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,83 @@
+/**
+ * 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.
+ */
+import type { ArtifactRef } from '../schemas/common.js';
+export type GateSeverity = 'revise' | 'human';
+export interface GateResult {
+    name: string;
+    severity: GateSeverity;
+    blocking_issue: {
+        description: string;
+        suggestion: string;
+    };
+}
+interface SymptomImpactShape {
+    before?: unknown;
+    after?: unknown;
+    causal_chain?: unknown;
+}
+/**
+ * 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 declare function detectScopePunting(notes?: string | null): GateResult[];
+/**
+ * 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 declare function detectTestOnlyChanges(changedFiles?: string[] | null, gitDiff?: string | null, userOriginalRequest?: string | null): GateResult[];
+/**
+ * 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 declare function detectDiagnosisHandoff(userOriginalRequest?: string | null, notes?: string | null): GateResult[];
+/**
+ * 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 declare function detectRenderingSymptom(userOriginalRequest?: string | null, artifactRefs?: ArtifactRef[] | null, changedFiles?: string[] | null, gitDiff?: string | null, symptomImpact?: SymptomImpactShape | null): GateResult[];
+/**
+ * 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 declare function enforceSymptomImpact(userOriginalRequest?: string | null, symptomImpact?: SymptomImpactShape | null): GateResult[];
+export interface ApplyGatesArgs {
+    phase: 'plan' | 'code';
+    userOriginalRequest?: string | null;
+    notesToReviewer?: string | null;
+    changedFiles?: string[] | null;
+    gitDiff?: string | null;
+    artifactRefs?: ArtifactRef[] | null;
+    symptomImpact?: SymptomImpactShape | null;
+}
+export interface ApplyGatesResult {
+    extraBlockingIssues: Array<{
+        description: string;
+        suggestion: string;
+    }>;
+    forcedVerdict?: 'REVISE';
+    forcedHumanReview?: boolean;
+    tripped: string[];
+}
+export declare function applyGates(args: ApplyGatesArgs): ApplyGatesResult;
+export {};