iterate-plugin 2.12.1 → 2.12.3

package/src/jobs.ts

@@ -0,0 +1,97 @@
+/**
+ * src/jobs.ts — dsh Job Panel integration for iterate tool executions.
+ *
+ * dsh's background-job registry (`ctx.jobs`, @deepseek-ai/dsh-jobs) lets
+ * plugins surface long-running work in the client's Job Panel
+ * (`conversation.session.header.actions` list). We register custom kinds via
+ * declaration merging and wrap tool executions so each `iterate_review` /
+ * `iterate_fix` call shows up as a tracked job (running -> completed/failed).
+ *
+ * Defensive by design (matches the plugin's overall philosophy):
+ * - `ctx.jobs` only exists when the dsh host loaded a job registry + a
+ *   controller serves the calling owner (`@deepseek-ai/dsh-tool-jobs` or an
+ *   equivalent). When it is missing, `start()` throws or is absent — we
+ *   detect both and fall through to plain execution, so the Job Panel is a
+ *   pure enhancement and never breaks a tool call.
+ * - The registry is memory-only and panel rows are read-only (no progress
+ *   updates), so these jobs are completion records, not control channels.
+ */
+
+import type { JobOutcome, JobRegistry } from '@deepseek-ai/dsh-jobs'
+
+/** Extend dsh's producer-kind registry with iterate's custom kinds. */
+declare module '@deepseek-ai/dsh-jobs' {
+  interface JobKindMap {
+    'iterate-review': 'iterate-review'
+    'iterate-fix': 'iterate-fix'
+  }
+}
+
+/** Custom job kinds this plugin registers. */
+export type IterateJobKind = 'iterate-review' | 'iterate-fix'
+
+/** Shape of the `ctx.jobs` surface we rely on (duck-typed for safety). */
+interface JobsLike {
+  start(spec: {
+    kind: IterateJobKind
+    label: string
+    run(): { done: Promise<JobOutcome>; cancel?: () => void }
+  }): string
+}
+
+/**
+ * Run `fn` wrapped in a dsh background job, settling it completed/failed
+ * with the execution's outcome. When the host exposes no job registry (or
+ * refuses the start), `fn` runs untouched and `null` is returned — the Job
+ * Panel is an enhancement, never a dependency.
+ *
+ * @param ctx      the dsh plugin context (may or may not expose `jobs`).
+ * @param kind     iterate job kind registered via {@link IterateJobKind}.
+ * @param label    one-line job label shown in the panel.
+ * @param fn       the tool execution to track.
+ * @returns the registry-issued job id, or `null` when unavailable.
+ */
+export async function runWithJob<T>(
+  ctx: unknown,
+  kind: IterateJobKind,
+  label: string,
+  fn: () => Promise<T> | T,
+): Promise<{ result: T; jobId: string | null }> {
+  const jobs = (ctx as { jobs?: JobsLike } | undefined)?.jobs
+  if (!jobs || typeof jobs.start !== 'function') {
+    return { result: await fn(), jobId: null }
+  }
+
+  let settle!: (outcome: JobOutcome) => void
+  const done = new Promise<JobOutcome>((resolve) => {
+    settle = resolve
+  })
+
+  let jobId: string | null = null
+  try {
+    jobId = jobs.start({
+      kind,
+      label,
+      run: () => ({
+        done,
+        cancel: () => settle({ status: 'killed', detail: 'cancelled' }),
+      }),
+    })
+  } catch {
+    // Registry present but refuses work (e.g. no controller serves this
+    // owner) — run without panel tracking.
+    return { result: await fn(), jobId: null }
+  }
+
+  try {
+    const result = await fn()
+    settle({ status: 'completed', detail: 'done' })
+    return { result, jobId }
+  } catch (error) {
+    settle({
+      status: 'failed',
+      detail: error instanceof Error ? error.message : 'execution failed',
+    })
+    throw error
+  }
+}

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/checkpoint.ts

@@ -11,7 +11,7 @@
 
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { JsonValue } from '@deepseek-ai/dsh-session'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { resolveProjectRootForExec } from '../config-loader.ts'
 import { checkpointPath, iterateDir } from '../paths.ts'
 import { readRegistry } from './fix.ts'

package/src/tools/config.ts

@@ -1,6 +1,6 @@
 import { join } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { JsonValue } from '@deepseek-ai/dsh-session'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { loadEffectiveConfig, validateConfig, resolveProjectRootForExec } from '../config-loader.ts'
 import {
   applyConfigUpdates,

package/src/tools/decision-log.ts

@@ -1,7 +1,7 @@
 import { appendFileSync, readFileSync, mkdirSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { JsonValue } from '@deepseek-ai/dsh-session'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { resolveProjectRootForExec } from '../config-loader.ts'
 import type { DecisionLogEntry } from '../types.ts'
 

package/src/tools/fix.ts

@@ -20,8 +20,9 @@
 import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
 import { join, sep } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { JsonValue } from '@deepseek-ai/dsh-session'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 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/history.ts

@@ -9,7 +9,7 @@
  */
 
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { JsonValue } from '@deepseek-ai/dsh-session'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { resolveProjectRootForExec } from '../config-loader.ts'
 import { readDecisionEntries } from './decision-log.ts'
 import { readRegistry } from './fix.ts'

package/src/tools/prune.ts

@@ -21,7 +21,7 @@
 import { existsSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { JsonValue } from '@deepseek-ai/dsh-session'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { resolveProjectRootForExec } from '../config-loader.ts'
 import { readDecisionEntries, appendDecisionEntry } from './decision-log.ts'
 import { readRegistry, removeRecord, recomputeRoundCounts } from './fix.ts'

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 type { JsonValue } from '@deepseek-ai/dsh-util-values'
 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/tools/transcript.ts

@@ -22,7 +22,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { dirname } from 'node:path'
-import type { JsonValue } from '@deepseek-ai/dsh-session'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import {
   loadEffectiveConfig,
   resolveProjectRootForExec,

package/src/tools/triage.ts

@@ -1,7 +1,7 @@
 import { copyFileSync, existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { JsonValue } from '@deepseek-ai/dsh-session'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import yaml from 'js-yaml'
 import { resolveProjectRootForExec } from '../config-loader.ts'
 import type { KnownIntentional } from '../types.ts'

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