iterate-plugin 2.12.0 → 2.12.2

package/dist/jobs.js

@@ -0,0 +1,68 @@
+/**
+ * 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.
+ */
+/**
+ * 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(ctx, kind, label, fn) {
+    const jobs = ctx?.jobs;
+    if (!jobs || typeof jobs.start !== 'function') {
+        return { result: await fn(), jobId: null };
+    }
+    let settle;
+    const done = new Promise((resolve) => {
+        settle = resolve;
+    });
+    let jobId = 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/dist/review.js

@@ -464,6 +464,40 @@ export function sanitizeRounds(rounds, schemaValidation) {
         };
     });
 }
+/**
+ * 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) {
+    if (!attachments || attachments.length === 0)
+        return '';
+    const lines = [];
+    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
@@ -475,6 +509,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 ' +
             'assigned to review. You MUST open EVERY file in this inventory with ' +
@@ -528,6 +566,13 @@ 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) => 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 = effectiveChangedOnly ? 'changed-only' : 'full';
@@ -575,6 +620,7 @@ export function buildReviewPlan(input) {
                     changedFiles: effectiveChangedOnly ? changedFiles : undefined,
                     scopeFiles: batch,
                     focus: focusMap.get(d),
+                    attachments,
                 }),
                 findingsSchema: findingsSchema(),
             });
@@ -589,5 +635,6 @@ export function buildReviewPlan(input) {
         knownIntentional: input.knownIntentional ?? [],
         changedFiles: effectiveChangedOnly ? changedFiles : [],
         fallbackToFull,
+        attachments,
     };
 }

package/dist/tools/fix.js

@@ -20,6 +20,7 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writeF
 import { join, sep } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { loadEffectiveConfig, resolveProjectRootForExec } from "../config-loader.js";
+import { runWithJob } from "../jobs.js";
 import { countTouchedMethods } from "../method-scope.js";
 import { fixBackupPath, fixRegistryPath, fixesDir } from "../paths.js";
 import { appendDecisionEntry } from "./decision-log.js";
@@ -331,170 +332,173 @@ export function registerFixTool(ctx) {
             ],
         },
         async execute(args, exec) {
-            const resolved = resolveProjectRootForExec(exec, args.path);
-            if (!resolved.ok)
-                return { ok: false, error: resolved.reason };
-            const projectRoot = resolved.root;
-            const { config } = loadEffectiveConfig(projectRoot);
-            const maxLines = config.atomic?.max_lines ?? 20;
-            const maxAdjacentMethods = config.atomic?.max_adjacent_methods ?? 3;
-            const file = typeof args.file === 'string' ? args.file : '';
-            if (!file)
-                return { ok: false, error: 'file is required' };
-            if (typeof args.content !== 'string')
-                return { ok: false, error: 'content must be a string' };
-            if (args.content.length > MAX_FIX_CONTENT_CHARS) {
-                return {
-                    ok: false,
-                    error: `content exceeds the ${MAX_FIX_CONTENT_CHARS}-character limit (got ${args.content.length})`,
-                };
-            }
-            if (typeof args.round !== 'number' || !Number.isInteger(args.round) || args.round < 1) {
-                return { ok: false, error: 'round must be a positive integer' };
-            }
-            const finding = args.finding;
-            if (!finding || typeof finding !== 'object') {
-                return { ok: false, error: 'finding must be an object' };
-            }
-            if (typeof finding.file !== 'string' || finding.file.trim().length === 0) {
-                return { ok: false, error: 'finding.file must be a non-empty string' };
-            }
-            if (typeof finding.dimension !== 'string' || finding.dimension.trim().length === 0) {
-                return { ok: false, error: 'finding.dimension must be a non-empty string' };
-            }
-            // The finding must reference the file being fixed — the fix id and the
-            // rollback/diff target are derived from finding.file, so a mismatch
-            // would back up/restore the WRONG file.
-            if (finding.file !== file) {
-                return { ok: false, error: `finding.file ("${finding.file}") must match the file being fixed ("${file}")` };
-            }
-            // Full finding validation, mirroring the review schema: malformed
-            // findings would produce lossy registry/log entries and a degraded id.
-            const SEVERITY_SET = new Set(['critical', 'high', 'medium', 'low']);
-            if (!SEVERITY_SET.has(finding.severity)) {
-                return { ok: false, error: 'finding.severity must be one of critical/high/medium/low' };
-            }
-            if (typeof finding.summary !== 'string' || finding.summary.trim().length === 0) {
-                return { ok: false, error: 'finding.summary must be a non-empty string' };
-            }
-            if (typeof finding.is_atomic !== 'boolean') {
-                return { ok: false, error: 'finding.is_atomic must be a boolean' };
-            }
-            if (finding.line !== undefined && finding.line !== null &&
-                (typeof finding.line !== 'number' || !Number.isInteger(finding.line) || finding.line < 0)) {
-                return { ok: false, error: 'finding.line must be a non-negative integer (0 = whole-file)' };
-            }
-            const current = readProjectFile(projectRoot, file);
-            if (!current.ok)
-                return { ok: false, error: current.reason };
-            const hunks = diffLines(current.content, args.content);
-            const { added, removed } = countChangedLines(current.content, args.content);
-            if (!args.force && (added > maxLines || removed > maxLines)) {
-                return {
-                    ok: false,
-                    error: `Change to ${file} exceeds the atomic threshold (max_lines=${maxLines}, change is +${added}/-${removed}). ` +
-                        'Either split it into smaller atomic fixes or pass force:true if this is a deliberate architectural change.',
-                };
-            }
-            const touchedMethods = countTouchedMethods(current.content, args.content, hunks);
-            if (!args.force && touchedMethods > maxAdjacentMethods) {
-                return {
-                    ok: false,
-                    error: `Change to ${file} touches ${touchedMethods} adjacent method(s), exceeds atomic.max_adjacent_methods (${maxAdjacentMethods}). ` +
-                        'Split it into smaller atomic fixes or pass force:true if this is a deliberate multi-method change.',
-                };
-            }
-            const id = fixId(finding);
-            const registry = readRegistry(projectRoot);
-            if (findFixRecord(registry, id)) {
-                return { ok: false, error: `finding already fixed this run (id: ${id})`, id };
-            }
-            const target = resolveProjectFile(projectRoot, file);
-            if (!target.ok)
-                return { ok: false, error: target.reason };
-            // Personalization guards (SKILL.md Phase 2): protected_paths veto the
-            // fix outright; forbidden_fixes veto fix approaches appearing in the
-            // new content. Both are security-relevant, so they are enforced here
-            // in the tool, not left to the model.
-            const pers = config.personalization;
-            const protectedPaths = Array.isArray(pers?.protected_paths)
-                ? pers.protected_paths.filter((p) => typeof p === 'string' && p.length > 0)
-                : [];
-            for (const pattern of protectedPaths) {
-                if (globMatch(file, pattern)) {
-                    return { ok: false, error: `skipped: ${file} matches protected path "${pattern}" (personalization.protected_paths forbids modifying it)` };
+            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;
+                const { config } = loadEffectiveConfig(projectRoot);
+                const maxLines = config.atomic?.max_lines ?? 20;
+                const maxAdjacentMethods = config.atomic?.max_adjacent_methods ?? 3;
+                const file = typeof args.file === 'string' ? args.file : '';
+                if (!file)
+                    return { ok: false, error: 'file is required' };
+                if (typeof args.content !== 'string')
+                    return { ok: false, error: 'content must be a string' };
+                if (args.content.length > MAX_FIX_CONTENT_CHARS) {
+                    return {
+                        ok: false,
+                        error: `content exceeds the ${MAX_FIX_CONTENT_CHARS}-character limit (got ${args.content.length})`,
+                    };
                 }
-            }
-            const forbiddenFixes = Array.isArray(pers?.forbidden_fixes)
-                ? pers.forbidden_fixes.filter((f) => typeof f === 'string' && f.length > 0)
-                : [];
-            for (const forbidden of forbiddenFixes) {
-                if (args.content.includes(forbidden)) {
-                    return { ok: false, error: `fix uses a forbidden approach: "${forbidden}" appears in the new content (personalization.forbidden_fixes)` };
+                if (typeof args.round !== 'number' || !Number.isInteger(args.round) || args.round < 1) {
+                    return { ok: false, error: 'round must be a positive integer' };
                 }
-            }
-            const timestamp = new Date().toISOString();
-            const backupPath = fixBackupPath(projectRoot, id, timestamp);
-            try {
-                mkdirSync(fixesDir(projectRoot), { recursive: true });
-                copyFileSync(target.resolved, backupPath);
-            }
-            catch (err) {
-                return { ok: false, error: `failed to create backup: ${String(err)}` };
-            }
-            try {
-                writeFileSync(target.resolved, args.content, 'utf-8');
-            }
-            catch (err) {
-                return { ok: false, error: `failed to write file: ${String(err)}` };
-            }
-            const record = {
-                id,
-                timestamp,
-                round: args.round,
-                finding,
-                backupPath,
-                diffSummary: buildDiffSummary(hunks),
-                linesAdded: added,
-                linesRemoved: removed,
-                success: true,
-            };
-            const nextRegistry = upsertRecord(registry, record);
-            try {
-                writeFileSync(fixRegistryPath(projectRoot), JSON.stringify(nextRegistry, null, 2), 'utf-8');
-            }
-            catch (err) {
-                // Registry write failed → the file was already modified but no record
-                // exists, so a later rollback/diff could never see it and a retry would
-                // back up the already-fixed content as "original". Restore the file
-                // from the backup to leave the tree exactly as it was.
-                try {
-                    copyFileSync(backupPath, target.resolved);
+                const finding = args.finding;
+                if (!finding || typeof finding !== 'object') {
+                    return { ok: false, error: 'finding must be an object' };
+                }
+                if (typeof finding.file !== 'string' || finding.file.trim().length === 0) {
+                    return { ok: false, error: 'finding.file must be a non-empty string' };
+                }
+                if (typeof finding.dimension !== 'string' || finding.dimension.trim().length === 0) {
+                    return { ok: false, error: 'finding.dimension must be a non-empty string' };
+                }
+                // The finding must reference the file being fixed — the fix id and the
+                // rollback/diff target are derived from finding.file, so a mismatch
+                // would back up/restore the WRONG file.
+                if (finding.file !== file) {
+                    return { ok: false, error: `finding.file ("${finding.file}") must match the file being fixed ("${file}")` };
                 }
-                catch (restoreErr) {
+                // Full finding validation, mirroring the review schema: malformed
+                // findings would produce lossy registry/log entries and a degraded id.
+                const SEVERITY_SET = new Set(['critical', 'high', 'medium', 'low']);
+                if (!SEVERITY_SET.has(finding.severity)) {
+                    return { ok: false, error: 'finding.severity must be one of critical/high/medium/low' };
+                }
+                if (typeof finding.summary !== 'string' || finding.summary.trim().length === 0) {
+                    return { ok: false, error: 'finding.summary must be a non-empty string' };
+                }
+                if (typeof finding.is_atomic !== 'boolean') {
+                    return { ok: false, error: 'finding.is_atomic must be a boolean' };
+                }
+                if (finding.line !== undefined && finding.line !== null &&
+                    (typeof finding.line !== 'number' || !Number.isInteger(finding.line) || finding.line < 0)) {
+                    return { ok: false, error: 'finding.line must be a non-negative integer (0 = whole-file)' };
+                }
+                const current = readProjectFile(projectRoot, file);
+                if (!current.ok)
+                    return { ok: false, error: current.reason };
+                const hunks = diffLines(current.content, args.content);
+                const { added, removed } = countChangedLines(current.content, args.content);
+                if (!args.force && (added > maxLines || removed > maxLines)) {
                     return {
                         ok: false,
-                        error: `failed to write fix registry: ${String(err)}; additionally failed to restore ${file} from backup: ${String(restoreErr)}`,
+                        error: `Change to ${file} exceeds the atomic threshold (max_lines=${maxLines}, change is +${added}/-${removed}). ` +
+                            'Either split it into smaller atomic fixes or pass force:true if this is a deliberate architectural change.',
                     };
                 }
-                return { ok: false, error: `failed to write fix registry: ${String(err)} (file restored from backup)` };
-            }
-            appendDecisionEntry(projectRoot, {
-                timestamp,
-                round: args.round,
-                type: 'atomic_fix',
-                data: { id, file, finding: finding.summary, linesAdded: added, linesRemoved: removed },
+                const touchedMethods = countTouchedMethods(current.content, args.content, hunks);
+                if (!args.force && touchedMethods > maxAdjacentMethods) {
+                    return {
+                        ok: false,
+                        error: `Change to ${file} touches ${touchedMethods} adjacent method(s), exceeds atomic.max_adjacent_methods (${maxAdjacentMethods}). ` +
+                            'Split it into smaller atomic fixes or pass force:true if this is a deliberate multi-method change.',
+                    };
+                }
+                const id = fixId(finding);
+                const registry = readRegistry(projectRoot);
+                if (findFixRecord(registry, id)) {
+                    return { ok: false, error: `finding already fixed this run (id: ${id})`, id };
+                }
+                const target = resolveProjectFile(projectRoot, file);
+                if (!target.ok)
+                    return { ok: false, error: target.reason };
+                // Personalization guards (SKILL.md Phase 2): protected_paths veto the
+                // fix outright; forbidden_fixes veto fix approaches appearing in the
+                // new content. Both are security-relevant, so they are enforced here
+                // in the tool, not left to the model.
+                const pers = config.personalization;
+                const protectedPaths = Array.isArray(pers?.protected_paths)
+                    ? pers.protected_paths.filter((p) => typeof p === 'string' && p.length > 0)
+                    : [];
+                for (const pattern of protectedPaths) {
+                    if (globMatch(file, pattern)) {
+                        return { ok: false, error: `skipped: ${file} matches protected path "${pattern}" (personalization.protected_paths forbids modifying it)` };
+                    }
+                }
+                const forbiddenFixes = Array.isArray(pers?.forbidden_fixes)
+                    ? pers.forbidden_fixes.filter((f) => typeof f === 'string' && f.length > 0)
+                    : [];
+                for (const forbidden of forbiddenFixes) {
+                    if (args.content.includes(forbidden)) {
+                        return { ok: false, error: `fix uses a forbidden approach: "${forbidden}" appears in the new content (personalization.forbidden_fixes)` };
+                    }
+                }
+                const timestamp = new Date().toISOString();
+                const backupPath = fixBackupPath(projectRoot, id, timestamp);
+                try {
+                    mkdirSync(fixesDir(projectRoot), { recursive: true });
+                    copyFileSync(target.resolved, backupPath);
+                }
+                catch (err) {
+                    return { ok: false, error: `failed to create backup: ${String(err)}` };
+                }
+                try {
+                    writeFileSync(target.resolved, args.content, 'utf-8');
+                }
+                catch (err) {
+                    return { ok: false, error: `failed to write file: ${String(err)}` };
+                }
+                const record = {
+                    id,
+                    timestamp,
+                    round: args.round,
+                    finding,
+                    backupPath,
+                    diffSummary: buildDiffSummary(hunks),
+                    linesAdded: added,
+                    linesRemoved: removed,
+                    success: true,
+                };
+                const nextRegistry = upsertRecord(registry, record);
+                try {
+                    writeFileSync(fixRegistryPath(projectRoot), JSON.stringify(nextRegistry, null, 2), 'utf-8');
+                }
+                catch (err) {
+                    // Registry write failed → the file was already modified but no record
+                    // exists, so a later rollback/diff could never see it and a retry would
+                    // back up the already-fixed content as "original". Restore the file
+                    // from the backup to leave the tree exactly as it was.
+                    try {
+                        copyFileSync(backupPath, target.resolved);
+                    }
+                    catch (restoreErr) {
+                        return {
+                            ok: false,
+                            error: `failed to write fix registry: ${String(err)}; additionally failed to restore ${file} from backup: ${String(restoreErr)}`,
+                        };
+                    }
+                    return { ok: false, error: `failed to write fix registry: ${String(err)} (file restored from backup)` };
+                }
+                appendDecisionEntry(projectRoot, {
+                    timestamp,
+                    round: args.round,
+                    type: 'atomic_fix',
+                    data: { id, file, finding: finding.summary, linesAdded: added, linesRemoved: removed },
+                });
+                return {
+                    ok: true,
+                    id,
+                    file,
+                    round: args.round,
+                    linesAdded: added,
+                    linesRemoved: removed,
+                    diffSummary: record.diffSummary,
+                    backupPath,
+                };
             });
-            return {
-                ok: true,
-                id,
-                file,
-                round: args.round,
-                linesAdded: added,
-                linesRemoved: removed,
-                diffSummary: record.diffSummary,
-                backupPath,
-            };
+            return result;
         },
     }));
 }