@planningo/duul 1.0.0 → 1.1.0

package/build/schemas/common.js

@@ -14,9 +14,16 @@ export const ReviewerConfigSchema = z.object({
         .optional()
         .describe('Review provider. Default: env REVIEW_PROVIDER or "openai".'),
     model: z
-        .string()
+        .union([
+        z.string(),
+        z.object({
+            plan: z.string().optional(),
+            code: z.string().optional(),
+            partition: z.string().optional(),
+        }),
+    ])
         .optional()
-        .describe('Model to use. Default: env REVIEW_MODEL or provider default.'),
+        .describe('Model to use. Either a single string applied to all tools, or an object with per-tool overrides (plan/code/partition). Default: env REVIEW_MODEL or provider default.'),
     base_url: z
         .string()
         .optional()
@@ -45,6 +52,13 @@ export const IterationMetaOutputSchema = z.object({
     iteration_count: z.number().describe('Current iteration number (1-based) as reported by the caller.'),
     iteration_limit: z.number().describe('Maximum iterations allowed for this phase.'),
     iteration_limit_reached: z.boolean().describe('Whether the iteration limit has been reached.'),
+    cost_warning: z
+        .string()
+        .optional()
+        .nullable()
+        .describe('Soft warning string emitted once iteration_count crosses ~60% of iteration_limit. ' +
+        'Includes the current round cost so the orchestrator can decide whether to accept a near-verdict or escalate. ' +
+        'Null when below the threshold.'),
 });
 /**
  * Token usage fields — added to MCP output for cost/usage tracking.

package/build/schemas/execution-partition.d.ts

@@ -1,7 +1,8 @@
 import { z } from 'zod';
 export declare const ExecutionPartitionInputSchema: z.ZodObject<{
-    approved_plan: z.ZodString;
-    workspace_root: z.ZodString;
+    approved_plan: z.ZodOptional<z.ZodString>;
+    approved_plan_file: z.ZodOptional<z.ZodString>;
+    workspace_root: z.ZodOptional<z.ZodString>;
     working_directories: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     changed_files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     entrypoints: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -25,32 +26,51 @@ export declare const ExecutionPartitionInputSchema: z.ZodObject<{
     max_review_iterations: z.ZodOptional<z.ZodNumber>;
     reviewer_config: z.ZodOptional<z.ZodObject<{
         provider: z.ZodOptional<z.ZodEnum<["openai", "anthropic", "google", "openrouter", "compatible"]>>;
-        model: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodObject<{
+            plan: z.ZodOptional<z.ZodString>;
+            code: z.ZodOptional<z.ZodString>;
+            partition: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            code?: string | undefined;
+            plan?: string | undefined;
+            partition?: string | undefined;
+        }, {
+            code?: string | undefined;
+            plan?: string | undefined;
+            partition?: string | undefined;
+        }>]>>;
         base_url: z.ZodOptional<z.ZodString>;
         api_key: z.ZodOptional<z.ZodString>;
         temperature: z.ZodOptional<z.ZodNumber>;
         top_p: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         provider?: "openai" | "anthropic" | "google" | "openrouter" | "compatible" | undefined;
-        model?: string | undefined;
+        model?: string | {
+            code?: string | undefined;
+            plan?: string | undefined;
+            partition?: string | undefined;
+        } | undefined;
         base_url?: string | undefined;
         api_key?: string | undefined;
         temperature?: number | undefined;
         top_p?: number | undefined;
     }, {
         provider?: "openai" | "anthropic" | "google" | "openrouter" | "compatible" | undefined;
-        model?: string | undefined;
+        model?: string | {
+            code?: string | undefined;
+            plan?: string | undefined;
+            partition?: string | undefined;
+        } | undefined;
         base_url?: string | undefined;
         api_key?: string | undefined;
         temperature?: number | undefined;
         top_p?: number | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    workspace_root: string;
-    approved_plan: string;
     iteration_count?: number | undefined;
     changed_files?: string[] | undefined;
     constraints?: string[] | undefined;
+    workspace_root?: string | undefined;
     working_directories?: string[] | undefined;
     entrypoints?: string[] | undefined;
     artifact_refs?: {
@@ -62,19 +82,24 @@ export declare const ExecutionPartitionInputSchema: z.ZodObject<{
     max_review_iterations?: number | undefined;
     reviewer_config?: {
         provider?: "openai" | "anthropic" | "google" | "openrouter" | "compatible" | undefined;
-        model?: string | undefined;
+        model?: string | {
+            code?: string | undefined;
+            plan?: string | undefined;
+            partition?: string | undefined;
+        } | undefined;
         base_url?: string | undefined;
         api_key?: string | undefined;
         temperature?: number | undefined;
         top_p?: number | undefined;
     } | undefined;
+    approved_plan?: string | undefined;
+    approved_plan_file?: string | undefined;
     max_parallelism?: number | undefined;
 }, {
-    workspace_root: string;
-    approved_plan: string;
     iteration_count?: number | undefined;
     changed_files?: string[] | undefined;
     constraints?: string[] | undefined;
+    workspace_root?: string | undefined;
     working_directories?: string[] | undefined;
     entrypoints?: string[] | undefined;
     artifact_refs?: {
@@ -86,12 +111,18 @@ export declare const ExecutionPartitionInputSchema: z.ZodObject<{
     max_review_iterations?: number | undefined;
     reviewer_config?: {
         provider?: "openai" | "anthropic" | "google" | "openrouter" | "compatible" | undefined;
-        model?: string | undefined;
+        model?: string | {
+            code?: string | undefined;
+            plan?: string | undefined;
+            partition?: string | undefined;
+        } | undefined;
         base_url?: string | undefined;
         api_key?: string | undefined;
         temperature?: number | undefined;
         top_p?: number | undefined;
     } | undefined;
+    approved_plan?: string | undefined;
+    approved_plan_file?: string | undefined;
     max_parallelism?: number | undefined;
 }>;
 export declare const ExecutionPartitionOutputSchema: z.ZodObject<{
@@ -154,13 +185,6 @@ export declare const ExecutionPartitionOutputSchema: z.ZodObject<{
         review_focus: z.ZodArray<z.ZodString, "many">;
         risk_level: z.ZodEnum<["high", "medium", "low"]>;
     }, "strip", z.ZodTypeAny, {
-        id: string;
-        title: string;
-        goal: string;
-        can_run_in_parallel: boolean;
-        depends_on: string[];
-        workspace_name_hint: string;
-        spawn_strategy: "new_workspace" | "reuse_workspace";
         scope: {
             changed_files?: string[] | undefined;
             working_directories?: string[] | undefined;
@@ -172,11 +196,6 @@ export declare const ExecutionPartitionOutputSchema: z.ZodObject<{
                 priority: "high" | "medium" | "low";
             }[] | undefined;
         };
-        handoff_contract: string[];
-        completion_criteria: string[];
-        review_focus: string[];
-        risk_level: "high" | "medium" | "low";
-    }, {
         id: string;
         title: string;
         goal: string;
@@ -184,6 +203,11 @@ export declare const ExecutionPartitionOutputSchema: z.ZodObject<{
         depends_on: string[];
         workspace_name_hint: string;
         spawn_strategy: "new_workspace" | "reuse_workspace";
+        handoff_contract: string[];
+        completion_criteria: string[];
+        review_focus: string[];
+        risk_level: "high" | "medium" | "low";
+    }, {
         scope: {
             changed_files?: string[] | undefined;
             working_directories?: string[] | undefined;
@@ -195,6 +219,13 @@ export declare const ExecutionPartitionOutputSchema: z.ZodObject<{
                 priority: "high" | "medium" | "low";
             }[] | undefined;
         };
+        id: string;
+        title: string;
+        goal: string;
+        can_run_in_parallel: boolean;
+        depends_on: string[];
+        workspace_name_hint: string;
+        spawn_strategy: "new_workspace" | "reuse_workspace";
         handoff_contract: string[];
         completion_criteria: string[];
         review_focus: string[];
@@ -233,13 +264,6 @@ export declare const ExecutionPartitionOutputSchema: z.ZodObject<{
     handoff_artifact_pattern: string;
     subtask_result_schema_version: "1.0";
     subtasks: {
-        id: string;
-        title: string;
-        goal: string;
-        can_run_in_parallel: boolean;
-        depends_on: string[];
-        workspace_name_hint: string;
-        spawn_strategy: "new_workspace" | "reuse_workspace";
         scope: {
             changed_files?: string[] | undefined;
             working_directories?: string[] | undefined;
@@ -251,6 +275,13 @@ export declare const ExecutionPartitionOutputSchema: z.ZodObject<{
                 priority: "high" | "medium" | "low";
             }[] | undefined;
         };
+        id: string;
+        title: string;
+        goal: string;
+        can_run_in_parallel: boolean;
+        depends_on: string[];
+        workspace_name_hint: string;
+        spawn_strategy: "new_workspace" | "reuse_workspace";
         handoff_contract: string[];
         completion_criteria: string[];
         review_focus: string[];
@@ -275,13 +306,6 @@ export declare const ExecutionPartitionOutputSchema: z.ZodObject<{
     handoff_artifact_pattern: string;
     subtask_result_schema_version: "1.0";
     subtasks: {
-        id: string;
-        title: string;
-        goal: string;
-        can_run_in_parallel: boolean;
-        depends_on: string[];
-        workspace_name_hint: string;
-        spawn_strategy: "new_workspace" | "reuse_workspace";
         scope: {
             changed_files?: string[] | undefined;
             working_directories?: string[] | undefined;
@@ -293,6 +317,13 @@ export declare const ExecutionPartitionOutputSchema: z.ZodObject<{
                 priority: "high" | "medium" | "low";
             }[] | undefined;
         };
+        id: string;
+        title: string;
+        goal: string;
+        can_run_in_parallel: boolean;
+        depends_on: string[];
+        workspace_name_hint: string;
+        spawn_strategy: "new_workspace" | "reuse_workspace";
         handoff_contract: string[];
         completion_criteria: string[];
         review_focus: string[];
@@ -369,13 +400,6 @@ export declare const ExecutionPartitionMcpOutputSchema: z.ZodObject<{
         review_focus: z.ZodArray<z.ZodString, "many">;
         risk_level: z.ZodEnum<["high", "medium", "low"]>;
     }, "strip", z.ZodTypeAny, {
-        id: string;
-        title: string;
-        goal: string;
-        can_run_in_parallel: boolean;
-        depends_on: string[];
-        workspace_name_hint: string;
-        spawn_strategy: "new_workspace" | "reuse_workspace";
         scope: {
             changed_files?: string[] | undefined;
             working_directories?: string[] | undefined;
@@ -387,11 +411,6 @@ export declare const ExecutionPartitionMcpOutputSchema: z.ZodObject<{
                 priority: "high" | "medium" | "low";
             }[] | undefined;
         };
-        handoff_contract: string[];
-        completion_criteria: string[];
-        review_focus: string[];
-        risk_level: "high" | "medium" | "low";
-    }, {
         id: string;
         title: string;
         goal: string;
@@ -399,6 +418,11 @@ export declare const ExecutionPartitionMcpOutputSchema: z.ZodObject<{
         depends_on: string[];
         workspace_name_hint: string;
         spawn_strategy: "new_workspace" | "reuse_workspace";
+        handoff_contract: string[];
+        completion_criteria: string[];
+        review_focus: string[];
+        risk_level: "high" | "medium" | "low";
+    }, {
         scope: {
             changed_files?: string[] | undefined;
             working_directories?: string[] | undefined;
@@ -410,6 +434,13 @@ export declare const ExecutionPartitionMcpOutputSchema: z.ZodObject<{
                 priority: "high" | "medium" | "low";
             }[] | undefined;
         };
+        id: string;
+        title: string;
+        goal: string;
+        can_run_in_parallel: boolean;
+        depends_on: string[];
+        workspace_name_hint: string;
+        spawn_strategy: "new_workspace" | "reuse_workspace";
         handoff_contract: string[];
         completion_criteria: string[];
         review_focus: string[];
@@ -445,6 +476,7 @@ export declare const ExecutionPartitionMcpOutputSchema: z.ZodObject<{
     iteration_count: z.ZodNumber;
     iteration_limit: z.ZodNumber;
     iteration_limit_reached: z.ZodBoolean;
+    cost_warning: z.ZodNullable<z.ZodOptional<z.ZodString>>;
 } & {
     token_usage: z.ZodObject<{
         input_tokens: z.ZodNumber;
@@ -501,13 +533,6 @@ export declare const ExecutionPartitionMcpOutputSchema: z.ZodObject<{
     handoff_artifact_pattern: string;
     subtask_result_schema_version: "1.0";
     subtasks: {
-        id: string;
-        title: string;
-        goal: string;
-        can_run_in_parallel: boolean;
-        depends_on: string[];
-        workspace_name_hint: string;
-        spawn_strategy: "new_workspace" | "reuse_workspace";
         scope: {
             changed_files?: string[] | undefined;
             working_directories?: string[] | undefined;
@@ -519,6 +544,13 @@ export declare const ExecutionPartitionMcpOutputSchema: z.ZodObject<{
                 priority: "high" | "medium" | "low";
             }[] | undefined;
         };
+        id: string;
+        title: string;
+        goal: string;
+        can_run_in_parallel: boolean;
+        depends_on: string[];
+        workspace_name_hint: string;
+        spawn_strategy: "new_workspace" | "reuse_workspace";
         handoff_contract: string[];
         completion_criteria: string[];
         review_focus: string[];
@@ -534,6 +566,7 @@ export declare const ExecutionPartitionMcpOutputSchema: z.ZodObject<{
         on_blocker: "escalate_to_human";
         on_max_retries_exceeded: "abort_subtask_and_report";
     };
+    cost_warning?: string | null | undefined;
 }, {
     iteration_count: number;
     iteration_limit: number;
@@ -558,13 +591,6 @@ export declare const ExecutionPartitionMcpOutputSchema: z.ZodObject<{
     handoff_artifact_pattern: string;
     subtask_result_schema_version: "1.0";
     subtasks: {
-        id: string;
-        title: string;
-        goal: string;
-        can_run_in_parallel: boolean;
-        depends_on: string[];
-        workspace_name_hint: string;
-        spawn_strategy: "new_workspace" | "reuse_workspace";
         scope: {
             changed_files?: string[] | undefined;
             working_directories?: string[] | undefined;
@@ -576,6 +602,13 @@ export declare const ExecutionPartitionMcpOutputSchema: z.ZodObject<{
                 priority: "high" | "medium" | "low";
             }[] | undefined;
         };
+        id: string;
+        title: string;
+        goal: string;
+        can_run_in_parallel: boolean;
+        depends_on: string[];
+        workspace_name_hint: string;
+        spawn_strategy: "new_workspace" | "reuse_workspace";
         handoff_contract: string[];
         completion_criteria: string[];
         review_focus: string[];
@@ -591,6 +624,7 @@ export declare const ExecutionPartitionMcpOutputSchema: z.ZodObject<{
         on_blocker: "escalate_to_human";
         on_max_retries_exceeded: "abort_subtask_and_report";
     };
+    cost_warning?: string | null | undefined;
 }>;
 export type ExecutionPartitionInput = z.infer<typeof ExecutionPartitionInputSchema>;
 export type ExecutionPartitionOutput = z.infer<typeof ExecutionPartitionOutputSchema>;

package/build/schemas/execution-partition.js

@@ -3,11 +3,21 @@ import { ArtifactRefSchema, ReviewerConfigSchema, IterationMetaOutputSchema, Tok
 export const ExecutionPartitionInputSchema = z.object({
     approved_plan: z
         .string()
-        .min(1, 'approved_plan must not be empty')
-        .describe('The previously approved plan to partition into execution units'),
+        .optional()
+        .describe('Full text of the approved plan to partition into subtasks. REQUIRED unless approved_plan_file is provided. ' +
+        'Pass the entire approved plan markdown so the partitioner can analyze dependencies and split work. ' +
+        'If the plan is large, prefer approved_plan_file — inlining a very large string here can make the tool call fail to serialize.'),
+    approved_plan_file: z
+        .string()
+        .optional()
+        .describe('Relative path (within workspace_root) to a markdown file containing the approved plan, ' +
+        'e.g. ".duul/plan.md". Use this instead of inlining `approved_plan` when it is large. ' +
+        'Exactly one of `approved_plan` or `approved_plan_file` is required. Must be a relative path.'),
     workspace_root: z
         .string()
-        .describe('Absolute path to the workspace root directory'),
+        .optional()
+        .describe('Absolute path to the workspace root directory. REQUIRED (enforced by the handler). ' +
+        'Example: "/Users/me/project". The partitioner uses this to verify file paths exist.'),
     working_directories: z
         .array(z.string())
         .optional()

package/build/schemas/plan-review.d.ts

@@ -31,7 +31,8 @@ export declare const ProjectContextSchema: z.ZodObject<{
     }[] | undefined;
 }>;
 export declare const PlanReviewInputSchema: z.ZodObject<{
-    plan: z.ZodString;
+    plan: z.ZodOptional<z.ZodString>;
+    plan_file: z.ZodOptional<z.ZodString>;
     project_context: z.ZodOptional<z.ZodObject<{
         file_tree: z.ZodOptional<z.ZodString>;
         changed_files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -99,30 +100,51 @@ export declare const PlanReviewInputSchema: z.ZodObject<{
     max_review_iterations: z.ZodOptional<z.ZodNumber>;
     reviewer_config: z.ZodOptional<z.ZodObject<{
         provider: z.ZodOptional<z.ZodEnum<["openai", "anthropic", "google", "openrouter", "compatible"]>>;
-        model: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodObject<{
+            plan: z.ZodOptional<z.ZodString>;
+            code: z.ZodOptional<z.ZodString>;
+            partition: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            code?: string | undefined;
+            plan?: string | undefined;
+            partition?: string | undefined;
+        }, {
+            code?: string | undefined;
+            plan?: string | undefined;
+            partition?: string | undefined;
+        }>]>>;
         base_url: z.ZodOptional<z.ZodString>;
         api_key: z.ZodOptional<z.ZodString>;
         temperature: z.ZodOptional<z.ZodNumber>;
         top_p: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         provider?: "openai" | "anthropic" | "google" | "openrouter" | "compatible" | undefined;
-        model?: string | undefined;
+        model?: string | {
+            code?: string | undefined;
+            plan?: string | undefined;
+            partition?: string | undefined;
+        } | undefined;
         base_url?: string | undefined;
         api_key?: string | undefined;
         temperature?: number | undefined;
         top_p?: number | undefined;
     }, {
         provider?: "openai" | "anthropic" | "google" | "openrouter" | "compatible" | undefined;
-        model?: string | undefined;
+        model?: string | {
+            code?: string | undefined;
+            plan?: string | undefined;
+            partition?: string | undefined;
+        } | undefined;
         base_url?: string | undefined;
         api_key?: string | undefined;
         temperature?: number | undefined;
         top_p?: number | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    plan: string;
+    plan?: string | undefined;
     iteration_count?: number | undefined;
     changed_files?: string[] | undefined;
+    plan_file?: string | undefined;
     project_context?: {
         file_tree?: string | undefined;
         changed_files?: string[] | undefined;
@@ -158,16 +180,21 @@ export declare const PlanReviewInputSchema: z.ZodObject<{
     max_review_iterations?: number | undefined;
     reviewer_config?: {
         provider?: "openai" | "anthropic" | "google" | "openrouter" | "compatible" | undefined;
-        model?: string | undefined;
+        model?: string | {
+            code?: string | undefined;
+            plan?: string | undefined;
+            partition?: string | undefined;
+        } | undefined;
         base_url?: string | undefined;
         api_key?: string | undefined;
         temperature?: number | undefined;
         top_p?: number | undefined;
     } | undefined;
 }, {
-    plan: string;
+    plan?: string | undefined;
     iteration_count?: number | undefined;
     changed_files?: string[] | undefined;
+    plan_file?: string | undefined;
     project_context?: {
         file_tree?: string | undefined;
         changed_files?: string[] | undefined;
@@ -203,7 +230,11 @@ export declare const PlanReviewInputSchema: z.ZodObject<{
     max_review_iterations?: number | undefined;
     reviewer_config?: {
         provider?: "openai" | "anthropic" | "google" | "openrouter" | "compatible" | undefined;
-        model?: string | undefined;
+        model?: string | {
+            code?: string | undefined;
+            plan?: string | undefined;
+            partition?: string | undefined;
+        } | undefined;
         base_url?: string | undefined;
         api_key?: string | undefined;
         temperature?: number | undefined;
@@ -389,6 +420,7 @@ export declare const PlanReviewMcpOutputSchema: z.ZodObject<{
     iteration_count: z.ZodNumber;
     iteration_limit: z.ZodNumber;
     iteration_limit_reached: z.ZodBoolean;
+    cost_warning: z.ZodNullable<z.ZodOptional<z.ZodString>>;
 } & {
     token_usage: z.ZodObject<{
         input_tokens: z.ZodNumber;
@@ -469,6 +501,7 @@ export declare const PlanReviewMcpOutputSchema: z.ZodObject<{
     symptom_match_notes: string | null;
     gates_tripped: string[] | null;
     review_id: string;
+    cost_warning?: string | null | undefined;
 }, {
     iteration_count: number;
     iteration_limit: number;
@@ -517,6 +550,7 @@ export declare const PlanReviewMcpOutputSchema: z.ZodObject<{
     symptom_match_notes: string | null;
     gates_tripped: string[] | null;
     review_id: string;
+    cost_warning?: string | null | undefined;
 }>;
 export type PlanReviewInput = z.infer<typeof PlanReviewInputSchema>;
 export type PlanReviewOutput = z.infer<typeof PlanReviewOutputSchema>;

package/build/schemas/plan-review.js

@@ -25,7 +25,21 @@ export const ProjectContextSchema = z.object({
         'that are relevant to the plan but not part of the change itself.'),
 });
 export const PlanReviewInputSchema = z.object({
-    plan: z.string().min(1, 'plan must not be empty').describe('Detailed implementation plan'),
+    plan: z
+        .string()
+        .optional()
+        .describe('Full implementation plan text (markdown). REQUIRED unless plan_file is provided. ' +
+        'Include: problem statement (quote user request), files to create/modify with paths, ' +
+        'approach, edge cases, dependencies. ' +
+        'If the plan is large, prefer writing it to a file and passing plan_file instead — ' +
+        'inlining a very large plan string here can make the tool call fail to serialize.'),
+    plan_file: z
+        .string()
+        .optional()
+        .describe('Relative path (within workspace_root) to a markdown file containing the full plan, ' +
+        'e.g. ".duul/plan.md". Use this instead of inlining `plan` when the plan is large: ' +
+        'write the plan to the file first, then pass its path here. ' +
+        'Exactly one of `plan` or `plan_file` is required. Requires workspace_root. Must be a relative path.'),
     project_context: ProjectContextSchema.optional().describe('Structured project context'),
     constraints: z
         .array(z.string())

package/build/services/filesystem-tools.d.ts

@@ -3,4 +3,22 @@
  * Handles all 8 standard tools + get_git_diff.
  */
 import { type WorkspaceScope } from './filesystem.js';
-export declare function executeFilesystemTool(projectRoot: string, toolName: string, args: Record<string, unknown>, scope?: WorkspaceScope | null): Promise<string>;
+/**
+ * Mutable per-review byte counter. Passed by reference into executeFilesystemTool
+ * so every successful tool return adds to `used`, and calls short-circuit once
+ * `used >= cap`.
+ */
+export interface ReviewerByteBudget {
+    used: number;
+    cap: number;
+}
+/**
+ * Resolve the reviewer file-read cap from env. Opt-in: if DUUL_MAX_REVIEWER_BYTES
+ * is unset/invalid, returns Infinity (no cap). Measurements showed a 200KB default
+ * was too tight — ~1/3 of code reviews hit the cap and spent extra rounds.
+ * Cost-conscious setups can opt in explicitly; 200000–500000 is a reasonable
+ * starting range, tune based on typical review complexity (see README).
+ */
+export declare function getMaxReviewerBytes(): number;
+export declare function createReviewerByteBudget(cap?: number): ReviewerByteBudget;
+export declare function executeFilesystemTool(projectRoot: string, toolName: string, args: Record<string, unknown>, scope?: WorkspaceScope | null, budget?: ReviewerByteBudget): Promise<string>;

package/build/services/filesystem-tools.js

@@ -3,35 +3,72 @@
  * Handles all 8 standard tools + get_git_diff.
  */
 import { readProjectFile, listProjectDirectory, searchInFiles, readProjectFileRange, statProjectFile, readJsonValue, listTrackedFiles, getGitDiff, } from './filesystem.js';
-export async function executeFilesystemTool(projectRoot, toolName, args, scope) {
+/**
+ * Resolve the reviewer file-read cap from env. Opt-in: if DUUL_MAX_REVIEWER_BYTES
+ * is unset/invalid, returns Infinity (no cap). Measurements showed a 200KB default
+ * was too tight — ~1/3 of code reviews hit the cap and spent extra rounds.
+ * Cost-conscious setups can opt in explicitly; 200000–500000 is a reasonable
+ * starting range, tune based on typical review complexity (see README).
+ */
+export function getMaxReviewerBytes() {
+    const raw = process.env.DUUL_MAX_REVIEWER_BYTES;
+    if (!raw)
+        return Infinity;
+    const parsed = parseInt(raw, 10);
+    if (isNaN(parsed) || parsed <= 0)
+        return Infinity;
+    return parsed;
+}
+export function createReviewerByteBudget(cap) {
+    return { used: 0, cap: cap ?? getMaxReviewerBytes() };
+}
+function budgetExhaustedMessage(budget) {
+    return `Reviewer file budget exhausted (used ${budget.used} / cap ${budget.cap} bytes). Rely on context already gathered. Do NOT request more files — submit your verdict.`;
+}
+export async function executeFilesystemTool(projectRoot, toolName, args, scope, budget) {
+    if (budget && budget.used >= budget.cap) {
+        return budgetExhaustedMessage(budget);
+    }
     try {
+        let result;
         switch (toolName) {
             case 'read_file': {
-                const result = await readProjectFile(projectRoot, args.path, scope);
-                if (result.length > 50_000) {
-                    return `\u26a0\ufe0f This file is large (${result.length} chars). Consider using read_file_range or search_in_files instead.\n\n${result}`;
-                }
-                return result;
+                const content = await readProjectFile(projectRoot, args.path, scope);
+                result = content.length > 50_000
+                    ? `\u26a0\ufe0f This file is large (${content.length} chars). Consider using read_file_range or search_in_files instead.\n\n${content}`
+                    : content;
+                break;
             }
             case 'list_directory':
-                return await listProjectDirectory(projectRoot, args.path, scope);
+                result = await listProjectDirectory(projectRoot, args.path, scope);
+                break;
             case 'search_in_files':
-                return await searchInFiles(projectRoot, args.query, args.paths, args.glob, scope?.trackedOnly, scope?.workingDirectories, scope);
+                result = await searchInFiles(projectRoot, args.query, args.paths, args.glob, scope?.trackedOnly, scope?.workingDirectories, scope);
+                break;
             case 'read_file_range':
-                return await readProjectFileRange(projectRoot, args.path, args.start_line, args.end_line, scope);
+                result = await readProjectFileRange(projectRoot, args.path, args.start_line, args.end_line, scope);
+                break;
             case 'stat_file':
-                return await statProjectFile(projectRoot, args.path, scope);
+                result = await statProjectFile(projectRoot, args.path, scope);
+                break;
             case 'read_json':
-                return await readJsonValue(projectRoot, args.path, args.json_pointer, scope);
+                result = await readJsonValue(projectRoot, args.path, args.json_pointer, scope);
+                break;
             case 'list_tracked_files': {
                 const files = await listTrackedFiles(projectRoot, args.prefix, scope);
-                return files.join('\n') || 'No tracked files found.';
+                result = files.join('\n') || 'No tracked files found.';
+                break;
             }
             case 'get_git_diff':
-                return await getGitDiff(projectRoot, args.base, args.paths, scope);
+                result = await getGitDiff(projectRoot, args.base, args.paths, scope);
+                break;
             default:
                 return `Unknown tool: ${toolName}`;
         }
+        if (budget && Number.isFinite(budget.cap)) {
+            budget.used += Buffer.byteLength(result, 'utf8');
+        }
+        return result;
     }
     catch (error) {
         return `Error: ${error instanceof Error ? error.message : String(error)}`;