iterate-plugin 2.8.4 → 2.9.1

package/src/tools/checkpoint.ts

@@ -42,6 +42,7 @@ export function validateCheckpoint(input: {
   maxRounds: unknown
   fixedCount: unknown
   architecturalCount: unknown
+  resumeCount?: unknown
 }): string | null {
   if (input.mode !== 'dry-run' && input.mode !== 'normal') {
     return 'mode must be "dry-run" or "normal"'
@@ -58,6 +59,12 @@ export function validateCheckpoint(input: {
   if (typeof input.architecturalCount !== 'number' || !Number.isInteger(input.architecturalCount) || input.architecturalCount < 0) {
     return 'architecturalCount must be a non-negative integer'
   }
+  if (
+    input.resumeCount !== undefined &&
+    (typeof input.resumeCount !== 'number' || !Number.isInteger(input.resumeCount) || input.resumeCount < 0)
+  ) {
+    return 'resumeCount must be a non-negative integer'
+  }
   return null
 }
 
@@ -103,6 +110,10 @@ export function computeStatus(input: {
     findingsCount: checkpoint?.findings.length ?? 0,
     totalDecisionLogEntries: entries.length,
     hasCheckpoint: checkpoint !== null,
+    // A checkpoint left on disk means the previous run was interrupted before
+    // it could clear it — this is the durable "interruption" signal.
+    interrupted: checkpoint !== null,
+    resumeCount: checkpoint?.resumeCount ?? 0,
     checkpoint,
     lastUpdated,
   }
@@ -133,6 +144,7 @@ export function registerCheckpointTool(ctx: { tools: { register: (def: ReturnTyp
         maxRounds: { type: 'integer', description: 'Required for save: total round cap.' },
         fixedCount: { type: 'integer', description: 'Required for save: number of fixes applied so far.' },
         architecturalCount: { type: 'integer', description: 'Required for save: architectural findings left unfixed.' },
+        resumeCount: { type: 'integer', description: 'Optional for save: how many times this checkpoint has already been resumed after an interruption (default 0).' },
         findings: { type: 'json', description: 'Optional for save: the current deduped findings to resume from.' },
         path: { type: 'string', description: 'Project root directory (default: current working directory).' },
       },
@@ -181,6 +193,7 @@ export function registerCheckpointTool(ctx: { tools: { register: (def: ReturnTyp
             maxRounds: args.maxRounds,
             fixedCount: args.fixedCount,
             architecturalCount: args.architecturalCount,
+            resumeCount: args.resumeCount,
           })
           if (invalid) return { operation: 'save', ok: false, error: invalid }
           const checkpoint: IterationCheckpoint = {
@@ -189,6 +202,7 @@ export function registerCheckpointTool(ctx: { tools: { register: (def: ReturnTyp
             maxRounds: args.maxRounds as number,
             fixedCount: args.fixedCount as number,
             architecturalCount: args.architecturalCount as number,
+            resumeCount: (typeof args.resumeCount === 'number' ? args.resumeCount : 0),
             findings: (Array.isArray(args.findings) ? args.findings : []) as unknown as IterationCheckpoint['findings'],
             startedAt: readCheckpoint(projectRoot)?.startedAt ?? new Date().toISOString(),
             updatedAt: new Date().toISOString(),
@@ -239,6 +253,8 @@ export function registerStatusTool(ctx: { tools: { register: (def: ReturnType<ty
             findingsCount: { type: 'integer' },
             totalDecisionLogEntries: { type: 'integer' },
             hasCheckpoint: { type: 'boolean' },
+            interrupted: { type: 'boolean', description: 'True when a checkpoint exists, meaning the previous run was interrupted before finishing.' },
+            resumeCount: { type: 'integer', description: 'How many times the current checkpoint has already been resumed.' },
             lastUpdated: { type: 'string' },
             error: { type: 'string' },
           },
@@ -251,7 +267,7 @@ export function registerStatusTool(ctx: { tools: { register: (def: ReturnType<ty
             `Fixed: ${value.fixedCount} · Architectural remaining: ${value.architecturalCount}`,
             `Findings in checkpoint: ${value.findingsCount}`,
             `Decision-log entries: ${value.totalDecisionLogEntries}`,
-            `Checkpoint: ${value.hasCheckpoint ? 'yes' : 'no'}`,
+            `Checkpoint: ${value.hasCheckpoint ? 'yes' : 'no'}${value.interrupted ? ' (interrupted — resumable)' : ''}${value.resumeCount ? ` · resumed ${value.resumeCount}x` : ''}`,
             value.lastUpdated ? `Last updated: ${value.lastUpdated}` : '',
           ]
           return [{ type: 'text', text: lines.filter(Boolean).join('\n') }]
@@ -277,6 +293,8 @@ export function registerStatusTool(ctx: { tools: { register: (def: ReturnType<ty
           findingsCount: status.findingsCount,
           totalDecisionLogEntries: status.totalDecisionLogEntries,
           hasCheckpoint: status.hasCheckpoint,
+          interrupted: status.interrupted,
+          resumeCount: status.resumeCount,
           lastUpdated: status.lastUpdated ?? undefined,
         }
       },

package/src/tools/context.ts

@@ -7,6 +7,103 @@ import { resolveProjectRoot } from '../config-loader.ts'
 /** How many ancestor directories we walk up looking for a SKILL.md. */
 const MAX_SKILL_DIR_LOOKUP_DEPTH = 12
 
+/** Maximum number of image attachments relayed into the context in one call. */
+const MAX_ATTACHMENTS = 8
+
+/** Maximum intrinsic width/height (px) accepted for an attached image. */
+const MAX_ATTACHMENT_DIMENSION = 16384
+
+/** A validated, normalized image-attachment entry carried into review context. */
+export interface NormalizedAttachment {
+  name?: string
+  mediaType?: string
+  width?: number
+  height?: number
+  note?: string
+}
+
+/** Validation result for a raw attachment entry. */
+export type AttachmentValidationResult =
+  | { ok: true; value: NormalizedAttachment }
+  | { ok: false; error: string }
+
+/**
+ * Validate and normalize one raw image-attachment entry passed by the
+ * orchestrator. The top-level model observes user-attached images in its own
+ * context (as image blocks) and relays their metadata here so reviewers get the
+ * same visual evidence. Pure — exported for unit tests.
+ */
+export function normalizeAttachment(raw: unknown): AttachmentValidationResult {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { ok: false, error: 'attachment must be an object' }
+  }
+  const entry = raw as Record<string, unknown>
+  const out: NormalizedAttachment = {}
+  if (entry.name !== undefined) {
+    if (typeof entry.name !== 'string' || entry.name.length > 256) {
+      return { ok: false, error: 'attachment.name must be a string (≤ 256 chars)' }
+    }
+    out.name = entry.name
+  }
+  if (entry.mediaType !== undefined) {
+    if (typeof entry.mediaType !== 'string' || !/^image\/(png|jpeg|webp|gif)$/.test(entry.mediaType)) {
+      return { ok: false, error: 'attachment.mediaType must be image/png, image/jpeg, image/webp, or image/gif' }
+    }
+    out.mediaType = entry.mediaType
+  }
+  for (const dim of ['width', 'height'] as const) {
+    if (entry[dim] !== undefined) {
+      if (typeof entry[dim] !== 'number' || !Number.isInteger(entry[dim]) || entry[dim] < 0 || entry[dim] > MAX_ATTACHMENT_DIMENSION) {
+        return { ok: false, error: `attachment.${dim} must be an integer in [0, ${MAX_ATTACHMENT_DIMENSION}]` }
+      }
+      out[dim] = entry[dim]
+    }
+  }
+  if (entry.note !== undefined) {
+    if (typeof entry.note !== 'string' || entry.note.length > 1000) {
+      return { ok: false, error: 'attachment.note must be a string (≤ 1000 chars)' }
+    }
+    out.note = entry.note
+  }
+  return { ok: true, value: out }
+}
+
+/**
+ * Validate a whole attachments array, dropping invalid entries.
+ * Returns the normalized list plus the reasons for any dropped entries.
+ */
+export function normalizeAttachments(raw: unknown): {
+  attachments: NormalizedAttachment[]
+  errors: string[]
+} {
+  const attachments: NormalizedAttachment[] = []
+  const errors: string[] = []
+  if (raw === undefined || raw === null) return { attachments, errors }
+  if (!Array.isArray(raw)) return { attachments, errors: ['attachments must be an array'] }
+  for (let i = 0; i < raw.length; i++) {
+    if (attachments.length >= MAX_ATTACHMENTS) {
+      errors.push(`attachments capped at ${MAX_ATTACHMENTS}; entry ${i} dropped`)
+      break
+    }
+    const result = normalizeAttachment(raw[i])
+    if (result.ok) attachments.push(result.value)
+    else errors.push(`attachments[${i}]: ${result.error}`)
+  }
+  return { attachments, errors }
+}
+
+/**
+ * Render a normalized attachment as a compact text block for the model.
+ */
+export function renderAttachment(a: NormalizedAttachment, index: number): string {
+  const bits: string[] = [`[${index + 1}]`]
+  if (a.name) bits.push(a.name)
+  if (a.mediaType) bits.push(a.mediaType)
+  if (typeof a.width === 'number' && typeof a.height === 'number') bits.push(`${a.width}x${a.height}`)
+  if (a.note) bits.push(a.note)
+  return bits.join(' · ')
+}
+
 /**
  * The directory this source file lives in (…/src/tools). The plugin's own
  * package root is one level up (…/src), and the skill root is typically a few
@@ -86,7 +183,9 @@ export function registerContextTool(ctx: { tools: { register: (def: ReturnType<t
         'SKILL.md contains the original iterate skill instructions; it is searched in ' +
         'the skill directory (auto-detected), the project root, or an explicit `skillDir`. ' +
         'ITERATE.md contains the project-specific knowledge base and onboarding information. ' +
-        'Use this to understand the skill workflow and project context.',
+        'Also relays user-attached image metadata (e.g. UI screenshots, error dialogs) into ' +
+        'the review context so reviewers can treat them as visual evidence. ' +
+        'Use this to understand the skill workflow, project context, and any attached visuals.',
 
       parameters: {
         files: {
@@ -105,6 +204,25 @@ export function registerContextTool(ctx: { tools: { register: (def: ReturnType<t
             'Custom directory to search for SKILL.md (highest priority). ' +
             'When omitted, SKILL.md is auto-detected from the skill directory, then the project root.',
         },
+        attachments: {
+          type: 'array',
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              name: { type: 'string', description: 'Optional display name of the attached image.' },
+              mediaType: { type: 'string', enum: ['image/png', 'image/jpeg', 'image/webp', 'image/gif'], description: 'Optional media type of the image.' },
+              width: { type: 'integer', description: 'Optional intrinsic width in pixels.' },
+              height: { type: 'integer', description: 'Optional intrinsic height in pixels.' },
+              note: { type: 'string', description: 'Optional short description of what the image shows and why it matters for this review.' },
+            },
+          },
+          description:
+            'Optional: image attachments observed in the session (e.g. UI screenshots, error ' +
+            'dialogs, design references) relayed into the review context. The top-level model ' +
+            'sees these images natively and passes their metadata here so reviewers get the same ' +
+            'visual evidence. Up to 8 entries; invalid entries are dropped and reported.',
+        },
       },
 
       output: {
@@ -118,15 +236,23 @@ export function registerContextTool(ctx: { tools: { register: (def: ReturnType<t
             skillSource: { oneOf: [{ type: 'string' }, { type: 'null' }] },
             error: { type: 'string' },
             searched: { type: 'array', items: { type: 'string' } },
+            attachments: { type: 'array', items: { type: 'string' }, description: 'Normalized attached-image descriptions relayed to reviewers.' },
+            attachmentErrors: { type: 'array', items: { type: 'string' }, description: 'Reasons for any attachment entries that were dropped.' },
           },
         },
         render: (_args, value) => {
           const parts: string[] = []
           if (value.skill) parts.push(`--- SKILL.md (${value.skillSource ?? '?source?'}) ---\n${value.skill}`)
           if (value.project) parts.push(`--- ITERATE.md ---\n${value.project}`)
-          if (!value.skill && !value.project) {
+          if (Array.isArray(value.attachments) && value.attachments.length > 0) {
+            parts.push(`--- User-attached images (${value.attachments.length}) ---\n${value.attachments.join('\n')}`)
+          }
+          if (!value.skill && !value.project && !(Array.isArray(value.attachments) && value.attachments.length > 0)) {
             parts.push('No files found. Searched: ' + (value.searched?.join(', ') ?? 'none'))
           }
+          if (Array.isArray(value.attachmentErrors) && value.attachmentErrors.length > 0) {
+            parts.push('Attachment warnings: ' + value.attachmentErrors.join('; '))
+          }
           return [{ type: 'text', text: parts.join('\n\n') }]
         },
       },
@@ -148,8 +274,21 @@ export function registerContextTool(ctx: { tools: { register: (def: ReturnType<t
           project?: string | null
           skillSource?: string | null
           searched: string[]
+          attachments?: string[]
+          attachmentErrors?: string[]
         } = { found: true, searched: [] }
 
+        // Relay user-attached image metadata into the review context. The
+        // orchestrator observes attached images in the session and passes their
+        // metadata here; invalid entries are dropped with a reported reason.
+        const attachments = normalizeAttachments(args.attachments)
+        if (attachments.attachments.length > 0) {
+          result.attachments = attachments.attachments.map(renderAttachment)
+        }
+        if (attachments.errors.length > 0) {
+          result.attachmentErrors = attachments.errors
+        }
+
         if (requested.includes('skill') || requested.includes('skill.md')) {
           // Candidate dirs in priority order: custom path → auto-detected skill
           // root → project root. This is how "skill 目录、项目根、自定义路径"

package/src/tools/decision-log.ts

@@ -19,6 +19,7 @@ const VALID_ENTRY_TYPES = new Set<DecisionLogEntry['type']>([
   'validation',
   'decision',
   'report',
+  'resume',
 ])
 
 /**
@@ -111,7 +112,7 @@ export function registerDecisionLogTool(ctx: { tools: { register: (def: ReturnTy
           type: 'string',
           description:
             'Entry type (required for append): round_start, review_result, atomic_fix, ' +
-            'architectural_fix, revert, round_failed, validation, decision, report.',
+            'architectural_fix, revert, round_failed, validation, decision, report, resume.',
           enum: [
             'round_start',
             'review_result',
@@ -122,6 +123,7 @@ export function registerDecisionLogTool(ctx: { tools: { register: (def: ReturnTy
             'validation',
             'decision',
             'report',
+            'resume',
           ],
         },
         round: {

package/src/types.ts

@@ -40,6 +40,7 @@ export interface DecisionLogEntry {
     | 'decision'
     | 'report'
     | 'round_failed'
+    | 'resume'
   data: Record<string, unknown>
 }
 
@@ -151,6 +152,8 @@ export interface IterationCheckpoint {
   maxRounds: number
   fixedCount: number
   architecturalCount: number
+  /** How many times this checkpoint has been resumed after an interruption/abort. */
+  resumeCount: number
   findings: ReviewFinding[]
   startedAt: string
   updatedAt: string
@@ -167,6 +170,10 @@ export interface IterationStatus {
   findingsCount: number
   totalDecisionLogEntries: number
   hasCheckpoint: boolean
+  /** True when a checkpoint is present — i.e. the previous run was interrupted before finishing. */
+  interrupted: boolean
+  /** How many times the current checkpoint has already been resumed. */
+  resumeCount: number
   checkpoint: IterationCheckpoint | null
   lastUpdated: string | null
 }