iterate-plugin 2.12.0 → 2.12.2

package/src/review.ts

@@ -20,6 +20,7 @@
 import type {
   IterateConfig,
   KnownIntentional,
+  ReviewAttachment,
   ReviewFinding,
   ReviewReport,
   ReviewRound,
@@ -546,6 +547,39 @@ export function sanitizeRounds(
   })
 }
 
+/**
+ * Build the "attached visual context" instruction block for a reviewer prompt.
+ *
+ * ``path``/``data`` attachments (screenshots, mockups, failure repros) are
+ * evidence a reviewer must weigh alongside the code — this clause names each
+ * one and mandates that the reviewer inspect/consider it (e.g. by opening the
+ * file with a vision-capable tool or the ``image_to_text`` bridge) before
+ * judging. Pure string construction; returns ``""`` when there are none.
+ */
+export function attachmentClause(attachments: ReviewAttachment[] | undefined): string {
+  if (!attachments || attachments.length === 0) return ''
+  const lines: string[] = []
+  for (const a of attachments) {
+    if (!a || typeof a !== 'object') continue
+    if (typeof a.path === 'string' && a.path) {
+      lines.push(`- ${a.path}${typeof a.caption === 'string' && a.caption ? ` (${a.caption})` : ''}`)
+    } else if (typeof a.data === 'string' && a.data) {
+      const kind = typeof a.media_type === 'string' && a.media_type ? a.media_type : 'image'
+      lines.push(`- inline ${kind} image${typeof a.caption === 'string' && a.caption ? ` (${a.caption})` : ''}`)
+    }
+  }
+  if (lines.length === 0) return ''
+  return (
+    'ATTACHED VISUAL CONTEXT (mandatory): the following image attachment(s) were provided ' +
+    'with this review — each one is part of the evidence you must weigh:\n' +
+    lines.join('\n') +
+    '\nYou MUST inspect/consider EVERY attachment before judging your dimension (open it ' +
+    'with a vision-capable tool, or use image_to_text if your model cannot see images). ' +
+    'If an attachment is inaccessible, state that and judge solely on the code. Do not ' +
+    'ignore an attachment just because it is not code.'
+  )
+}
+
 /**
  * Build the task prompt for one dimension's reviewer subagent.
  * In dry-run mode, pass `alreadyKnown` (the findings from earlier rounds) so the
@@ -581,6 +615,12 @@ export function reviewerTaskPrompt(input: {
    * review concentrates on the areas the user cares about.
    */
   focus?: string
+  /**
+   * Image/visual attachments to weigh alongside the code (screenshots,
+   * mockups, failure repros). Injected as a mandatory review-aware clause so
+   * every dimension reviewer inspects/considers them before judging.
+   */
+  attachments?: ReviewAttachment[]
 }): string {
   const parts: string[] = []
   parts.push(
@@ -591,6 +631,10 @@ export function reviewerTaskPrompt(input: {
   if (input.focus) {
     parts.push(`FOCUS: ${input.focus}`)
   }
+  const attached = attachmentClause(input.attachments)
+  if (attached) {
+    parts.push(attached)
+  }
   if (input.scopeFiles && input.scopeFiles.length > 0) {
     parts.push(
       'COVERAGE RULE (mandatory): below is the exact file inventory you are ' +
@@ -672,6 +716,12 @@ export function buildReviewPlan(input: {
    * complete inventory it must open file-by-file.
    */
   scopeFiles?: string[]
+  /**
+   * Image/visual attachments to thread into the review. Injected as a
+   * mandatory clause into every dimension's reviewer prompt and surfaced on
+   * the returned plan so the orchestrator/report can reference them.
+   */
+  attachments?: ReviewAttachment[]
 }): {
   mode: 'normal' | 'dry-run'
   goal: string
@@ -683,6 +733,8 @@ export function buildReviewPlan(input: {
   changedFiles: string[]
   /** True when scope was `changed-only` but no changes were found. */
   fallbackToFull: boolean
+  /** The attachments threaded into every reviewer prompt (empty when none). */
+  attachments: ReviewAttachment[]
 } {
   // Defensive reads: a malformed config (e.g. `dimensions` as a non-array, or
   // `review`/`atomic` missing) must degrade to sane defaults instead of
@@ -693,6 +745,16 @@ export function buildReviewPlan(input: {
   const dimensions = Array.isArray(input.config.dimensions) ? input.config.dimensions : []
   const maxLines = input.config.atomic?.max_lines ?? 20
   const changedFiles = Array.isArray(input.changedFiles) ? input.changedFiles : []
+  // Defensive parse: keep only well-formed attachment entries (path or data).
+  const attachments = Array.isArray(input.attachments)
+    ? input.attachments.filter(
+        (a): a is ReviewAttachment =>
+          Boolean(a) &&
+          typeof a === 'object' &&
+          ((typeof a.path === 'string' && a.path.length > 0) ||
+            (typeof a.data === 'string' && a.data.length > 0)),
+      )
+    : []
   // changed-only with zero detected changes → auto-fallback to full scope.
   const effectiveChangedOnly = configuredScope === 'changed-only' && changedFiles.length > 0
   const scope: 'full' | 'changed-only' = effectiveChangedOnly ? 'changed-only' : 'full'
@@ -744,6 +806,7 @@ export function buildReviewPlan(input: {
           changedFiles: effectiveChangedOnly ? changedFiles : undefined,
           scopeFiles: batch,
           focus: focusMap.get(d),
+          attachments,
         }),
         findingsSchema: findingsSchema(),
       })
@@ -759,5 +822,6 @@ export function buildReviewPlan(input: {
     knownIntentional: input.knownIntentional ?? [],
     changedFiles: effectiveChangedOnly ? changedFiles : [],
     fallbackToFull,
+    attachments,
   }
 }

package/src/tools/fix.ts

@@ -22,6 +22,7 @@ import { join, sep } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
 import { loadEffectiveConfig, resolveProjectRootForExec } from '../config-loader.ts'
+import { runWithJob } from '../jobs.ts'
 import { countTouchedMethods } from '../method-scope.ts'
 import { fixBackupPath, fixRegistryPath, fixesDir } from '../paths.ts'
 import { appendDecisionEntry } from './decision-log.ts'
@@ -335,6 +336,7 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
       },
 
       async execute(args, exec) {
+        const { result } = await runWithJob(ctx, 'iterate-fix', `iterate_fix ${typeof args.file === 'string' && args.file ? args.file : '(?)'}`, async () => {
         const resolved = resolveProjectRootForExec(exec, args.path)
         if (!resolved.ok) return { ok: false, error: resolved.reason }
         const projectRoot = resolved.root
@@ -504,6 +506,8 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
           diffSummary: record.diffSummary,
           backupPath,
         }
+        })
+        return result
       },
     }),
   )

package/src/tools/review.ts

@@ -1,6 +1,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
 import { loadEffectiveConfig, resolveProjectRootForExec } from '../config-loader.ts'
+import { runWithJob } from '../jobs.ts'
 import {
   buildReviewPlan,
   buildReviewReport,
@@ -15,7 +16,7 @@ import {
   coverageToDict,
 } from '../review-scope.ts'
 import { resolveChangedFiles } from '../git-scope.ts'
-import type { KnownIntentional, ReviewFinding, ReviewReport, ReviewRound } from '../types.ts'
+import type { KnownIntentional, ReviewAttachment, ReviewFinding, ReviewReport, ReviewRound } from '../types.ts'
 import type { CoverageResult } from '../review-scope.ts'
 
 /** Default round cap when neither the arg nor config provides one. */
@@ -85,6 +86,16 @@ export function registerReviewTool(ctx: { tools: { register: (def: ReturnType<ty
             'For `meta-review`: the ReviewReport JSON (as returned by `aggregate`) to audit for ' +
             'internal consistency and produce the final review report.',
         },
+        attachments: {
+          type: 'json',
+          description:
+            'Optional (plan only): image/visual attachments to thread into the review, e.g. ' +
+            '[{"path":"screens/hits.png","caption":"reproduced layout bug"}]. Each entry: ' +
+            '{path?, data?, media_type?, caption?} — path resolves relative to the project root, ' +
+            'data is a base64 payload (media_type e.g. image/png), caption gives human context. ' +
+            'Injected as a mandatory clause into every dimension reviewer prompt so screenshots/' +
+            'mockups/failure repros are weighed alongside the code.',
+        },
         fixedCount: {
           type: 'integer',
           description:
@@ -132,6 +143,7 @@ export function registerReviewTool(ctx: { tools: { register: (def: ReturnType<ty
       },
 
       async execute(args, exec) {
+        const { result } = await runWithJob(ctx, 'iterate-review', `iterate_review ${String(args.operation ?? '')} (${String(args.mode ?? 'dry-run')})`, async () => {
         const resolved = resolveProjectRootForExec(exec, args.path)
         if (!resolved.ok) {
           return { operation: args.operation, error: resolved.reason }
@@ -162,7 +174,18 @@ export function registerReviewTool(ctx: { tools: { register: (def: ReturnType<ty
           if (config.review?.scope === 'full') {
             scopeFiles = collectScopeFiles(projectRoot, { scope: 'full' })
           }
-          const plan = buildReviewPlan({ config, mode, maxReviewRounds, knownIntentional, changedFiles, scopeFiles })
+          // Thread image/visual attachments (screenshots/mockups/failure repros)
+          // into the plan so every reviewer prompt weighs them alongside code.
+          const attachments = Array.isArray(args.attachments)
+            ? (args.attachments as ReviewAttachment[]).filter(
+                (a): a is ReviewAttachment =>
+                  Boolean(a) &&
+                  typeof a === 'object' &&
+                  ((typeof a.path === 'string' && a.path.length > 0) ||
+                    (typeof a.data === 'string' && a.data.length > 0)),
+              )
+            : []
+          const plan = buildReviewPlan({ config, mode, maxReviewRounds, knownIntentional, changedFiles, scopeFiles, attachments })
           return { operation: 'plan', mode, found: true, plan: plan as unknown as JsonValue }
         }
 
@@ -268,6 +291,8 @@ export function registerReviewTool(ctx: { tools: { register: (def: ReturnType<ty
           operation: args.operation,
           error: `Unknown operation "${args.operation}". Use "plan", "aggregate", or "meta-review".`,
         }
+        })
+        return result
       },
     }),
   )

package/src/types.ts

@@ -16,6 +16,13 @@ export interface IterateConfig {
     command_whitelist: string[]
     commands: Record<string, string[]>
   }
+  /**
+   * LLM reasoning effort for review passes ('low' | 'medium' | 'high').
+   * Absent → follow the provider default. The harness forwards it into the
+   * OpenAI-compatible request body; the plugin surfaces it in the settings
+   * panel and review plan (dsh 0.1.1-rc.7+ exposes the same 'low' effort).
+   */
+  reasoning_effort?: 'low' | 'medium' | 'high'
   reviewer: {
     output_schema_validation: boolean
     evidence_validation: boolean
@@ -70,6 +77,25 @@ export interface ValidationResult {
   durationMs: number
 }
 
+/**
+ * An image (or other visual) attachment threaded into a review.
+ *
+ * The user/context can attach screenshots, UI mockups, or reproduced-failure
+ * images that reviewers should weigh alongside the code. Only ``path`` or
+ * ``data`` need be present; ``media_type`` describes ``data`` (base64);
+ * ``caption`` supplies human context for the reviewer prompt.
+ */
+export interface ReviewAttachment {
+  /** Local path to the image (resolved relative to the project root). */
+  path?: string
+  /** Base64-encoded image content (alternative to ``path``). */
+  data?: string
+  /** MIME type of ``data`` (e.g. image/png, image/jpeg, image/webp). */
+  media_type?: string
+  /** Short human caption explaining what the attachment shows and why it matters. */
+  caption?: string
+}
+
 /** A single finding from a dimension review */
 export interface ReviewFinding {
   dimension: string