iterate-plugin 3.8.0 → 3.9.0

package/dist/session-record.js

@@ -0,0 +1,246 @@
+/**
+ * src/session-record.ts — dsh session-linked run records (dsh ≥ 0.2.1-rc.1).
+ *
+ * Upstream capability (dsh `0.2.1-rc.1`, released 2026-10-17): the *Session
+ * state-record API*. An experimental plugin may append its own record onto a
+ * session's append-only log with `appendPluginRecord(session, type, data)` and
+ * read it back with `pluginRecordOf(event)` (`@deepseek-ai/dsh-session`). The
+ * record is marked `ignorable`, never enters the model-visible surface, and is
+ * carried along by fork / resume / format migration.
+ *
+ * Why the plugin adopts it:
+ *   The iterate run state has, until now, lived ONLY under `<projectRoot>/.iterate/`.
+ *   That is correct for normal operation but has two blind spots the session
+ *   log closes:
+ *     1. **Loss recovery** — if `.iterate/` is deleted, moved, or the working
+ *        directory changes, the observatory goes blank even though the session
+ *        that produced the run is still open. A compact run record on the
+ *        session log lets `iterate_transcript read` rehydrate the run summary
+ *        instead of returning an empty view.
+ *     2. **Session anchoring** — run provenance is tied to the *session* that
+ *        produced it, not only to whatever directory the process happens to be
+ *        in when someone looks afterwards.
+ *
+ * Design (fail-safe, never a hard dependency):
+ *   - The API is loaded lazily via a dynamic `import()` and used structurally
+ *     (no compile-time coupling to `PluginRecordMap`), so a host whose copy of
+ *     `@deepseek-ai/dsh-session` predates the API simply reports
+ *     `supported: false` instead of failing to load the plugin.
+ *   - Every entry point returns a structured result; nothing throws. Writing a
+ *     record is best-effort — a run must never fail because the session log
+ *     could not accept a bookkeeping record.
+ *   - `normalizeRunRecord` re-validates a restored payload, because a record
+ *     read from a resumed session carries whatever JSON an earlier build wrote.
+ */
+/** The `plugin:` record type this plugin owns (grammar-checked by dsh). */
+export const ITERATE_RUN_RECORD_TYPE = 'plugin:iterate/run';
+/** Bump when the record payload shape changes incompatibly. */
+export const ITERATE_RUN_RECORD_VERSION = 1;
+// ─── Pure payload construction / validation ─────────────────────────────────
+/** Coerce an unknown to a finite non-negative integer, else `fallback`. */
+function nonNegInt(value, fallback = 0) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return fallback;
+    const n = Math.floor(value);
+    return n >= 0 ? n : fallback;
+}
+/** Extract a string, else `''`. */
+function str(value) {
+    return typeof value === 'string' ? value : '';
+}
+/** Extract one of the allowed literal values, else `null`. */
+function oneOf(value, allowed) {
+    return typeof value === 'string' && allowed.includes(value) ? value : null;
+}
+/**
+ * Build a run record from the fields a persisted transcript manifest exposes.
+ * Pure: the caller passes already-normalized values, so this is unit-testable
+ * without touching disk or a session.
+ */
+export function buildRunRecord(input) {
+    const convergence = Array.isArray(input.convergence)
+        ? input.convergence
+            .filter((n) => typeof n === 'number' && Number.isFinite(n) && n >= 0)
+            .slice(-1000)
+        : [];
+    const c = input.counts ?? {};
+    const stopped = str(input.stoppedReason);
+    return {
+        version: ITERATE_RUN_RECORD_VERSION,
+        project: str(input.project),
+        goal: str(input.goal),
+        mode: oneOf(input.mode, ['dry-run', 'normal']),
+        taskMode: oneOf(input.taskMode, ['code', 'iterate']),
+        round: nonNegInt(input.round),
+        maxRounds: nonNegInt(input.maxRounds),
+        active: input.active !== false,
+        stoppedReason: stopped ? stopped : null,
+        convergence,
+        findings: {
+            total: nonNegInt(c.total),
+            critical: nonNegInt(c.critical),
+            high: nonNegInt(c.high),
+            medium: nonNegInt(c.medium),
+            low: nonNegInt(c.low),
+        },
+        fixedCount: nonNegInt(input.fixedCount),
+        qualityStatus: oneOf(input.qualityStatus, ['pass', 'fail', 'pending']),
+        updatedAt: str(input.now) || new Date().toISOString(),
+    };
+}
+/**
+ * Owner-side validation of a payload read back from a session log.
+ * A restored record carries whatever JSON an earlier build of this plugin
+ * wrote, so every field is re-checked; anything unrecognizable returns `null`
+ * (the caller skips it) rather than surfacing junk to a renderer.
+ */
+export function normalizeRunRecord(data) {
+    if (!data || typeof data !== 'object' || Array.isArray(data))
+        return null;
+    const d = data;
+    // A record written by a future/incompatible build is skipped rather than
+    // coerced: the version gate is the contract that lets the payload evolve.
+    if (nonNegInt(d.version) !== ITERATE_RUN_RECORD_VERSION)
+        return null;
+    const findings = (d.findings && typeof d.findings === 'object' && !Array.isArray(d.findings)
+        ? d.findings
+        : {});
+    return buildRunRecord({
+        project: d.project,
+        goal: d.goal,
+        mode: d.mode,
+        taskMode: d.taskMode,
+        round: d.round,
+        maxRounds: d.maxRounds,
+        active: d.active,
+        stoppedReason: d.stoppedReason,
+        convergence: d.convergence,
+        counts: {
+            total: findings.total,
+            critical: findings.critical,
+            high: findings.high,
+            medium: findings.medium,
+            low: findings.low,
+        },
+        fixedCount: d.fixedCount,
+        qualityStatus: d.qualityStatus,
+        now: typeof d.updatedAt === 'string' ? d.updatedAt : undefined,
+    });
+}
+// ─── Session access (lazy, fail-safe) ────────────────────────────────────────
+/** Lazily-resolved production API; `undefined` = not yet attempted. */
+let cachedApi;
+/** Test override; when set (including `null`) the dynamic import is bypassed. */
+let testApiOverride;
+/** Resolve the `@deepseek-ai/dsh-session` record API, or `null` when absent. */
+export function loadSessionRecordApi() {
+    if (testApiOverride !== undefined)
+        return Promise.resolve(testApiOverride);
+    if (cachedApi === undefined) {
+        cachedApi = import('@deepseek-ai/dsh-session')
+            .then((mod) => {
+            const m = mod;
+            if (typeof m.appendPluginRecord !== 'function' || typeof m.pluginRecordOf !== 'function') {
+                return null;
+            }
+            return {
+                appendPluginRecord: m.appendPluginRecord.bind(mod),
+                pluginRecordOf: m.pluginRecordOf.bind(mod),
+            };
+        })
+            .catch(() => null);
+    }
+    return cachedApi;
+}
+/**
+ * Override the session-record API for tests. Pass `undefined` to restore the
+ * real dynamic import, or an object / `null` to force a deterministic result.
+ */
+export function setSessionRecordApiForTests(api) {
+    testApiOverride = api;
+}
+/** Extract the session from a tool execution (`exec.agent.session`), defensively. */
+export function sessionOf(exec) {
+    try {
+        const agent = exec?.agent;
+        const session = agent?.session;
+        if (!session || typeof session !== 'object')
+            return undefined;
+        const s = session;
+        if (typeof s.ownEvents === 'function' || typeof s.snapshotEvents === 'function')
+            return s;
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Read every event a session exposes (own events preferred, snapshot fallback). */
+function eventsOf(session) {
+    try {
+        if (typeof session.ownEvents === 'function')
+            return session.ownEvents() ?? [];
+    }
+    catch {
+        // fall through to snapshot
+    }
+    try {
+        if (typeof session.snapshotEvents === 'function')
+            return session.snapshotEvents() ?? [];
+    }
+    catch {
+        // no readable log
+    }
+    return [];
+}
+/**
+ * Best-effort append of one run record to the session log.
+ * Never throws: an absent API, a degraded session, or a rejected payload all
+ * surface as `{ ok: false }` so the surrounding tool call can continue.
+ */
+export async function appendRunRecord(session, record) {
+    const api = await loadSessionRecordApi();
+    if (!api)
+        return { ok: false, supported: false, error: 'session record API unavailable' };
+    if (!session)
+        return { ok: false, supported: true, error: 'no session in scope' };
+    try {
+        const seq = api.appendPluginRecord(session, ITERATE_RUN_RECORD_TYPE, record);
+        return { ok: true, supported: true, seq };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            supported: true,
+            error: `session rejected the run record: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+/** Read every iterate run record from the session log (oldest → newest). */
+export async function readRunRecords(session) {
+    const api = await loadSessionRecordApi();
+    if (!api)
+        return { supported: false, records: [] };
+    if (!session)
+        return { supported: true, records: [] };
+    try {
+        const records = [];
+        for (const event of eventsOf(session)) {
+            const rec = api.pluginRecordOf(event);
+            if (!rec || rec.type !== ITERATE_RUN_RECORD_TYPE)
+                continue;
+            const normalized = normalizeRunRecord(rec.data);
+            if (!normalized)
+                continue;
+            records.push({ ...normalized, seq: nonNegInt(rec.seq), time: nonNegInt(rec.time) });
+        }
+        return { supported: true, records };
+    }
+    catch (err) {
+        return {
+            supported: true,
+            records: [],
+            error: `failed to read session records: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}

package/dist/skill-prompt.js

@@ -22,7 +22,8 @@ You have the iterate plugin installed, which registers these tools:
 - \`iterate_status\` — summarize the current run: mode, round, fixes applied, architectural remaining, decision-log size, checkpoint presence, and whether the run was interrupted (a checkpoint on disk with no newer decision-log activity means the previous run was interrupted and can be resumed)
 - \`iterate_history\` — inspect the runtime state in detail: decision-log entries and applied fixes (optionally scoped to a round or a fixed file)
 - \`iterate_prune\` — remove stale runtime artifacts (\`.iterate/\` entries). Defaults to a read-only dry-run that reports what WOULD be removed; pass \`dryRun:false\` to actually prune.
-- \`iterate_transcript\` — runtime observatory file (\`.iterate/transcript.json\`). \`read\` fetches the persisted manifest including any steering \`nudge\` for this run's reviewers; \`capture\` (call once after the final report) persists the per-reviewer threads, convergence trend, findings, fixes, checkpoint, per-round validation results (\`validations\`: command + exitCode + allowed + rejectReason), and timeline so the client observatory panel reflects the run; \`nudge\` sets/clears steering text the next round's reviewers read. Purely local, never touches source files.
+- \`iterate_transcript\` — runtime observatory file (\`.iterate/transcript.json\`). \`read\` fetches the persisted manifest including any steering \`nudge\` for this run's reviewers — and, when the file is missing or malformed, recovers a summary manifest from the session log's run record (returns \`recovered:true\`); \`capture\` (call once after the final report) persists the per-reviewer threads, convergence trend, findings, fixes, checkpoint, per-round validation results (\`validations\`: command + exitCode + allowed + rejectReason), and timeline so the client observatory panel reflects the run, and links the run to the dsh session (\`sessionRecord\`); \`recall\` lists the run records linked to this session (newest first) so a run stays traceable after \`.iterate/\` is wiped; \`nudge\` sets/clears steering text the next round's reviewers read. Purely local, never touches source files.
+- \`iterate_report\` — export the current run as a portable report. \`format:"markdown"\` (default) renders a PR-pasteable report (run header, quality gate, findings, fixes, validations, defense events, experience bank); \`format:"sarif"\` renders a SARIF 2.1.0 log for CI / GitHub Code Scanning (one rule per review dimension, severity → error/warning/note, file+line locations, suggested fix attached). Set \`write:true\` to persist it under \`.iterate/report.md\` / \`.iterate/report.sarif\`; \`lang\` (zh | en) selects the report language. Read-only apart from the optional report file.
 - \`iterate_experience\` — experience bank (\`.iterate/experience.json\`): \`list\`/\`search\`/\`get\` recall verified fixes and patterns from past sessions (read the bank before fixing so proven fixes are applied first); \`add\` records a new verified fix — re-adding the same pattern+dimension bumps its hit count instead of duplicating it; \`remove\` deletes a stale or incorrect entry by \`id\` so bad experiences never resurface.
 - \`iterate_quality_gate\` — quality certificate: \`read\` loads the persisted dimension convergence rates / verification pass rate / PASS-FAIL status; \`compute\` recomputes a fresh snapshot from this round's findings + validation results (supply \`findingsByRound\` for real convergence) and persists it to \`.iterate/quality-gate.json\`; \`clear\` removes the persisted certificate to reset a stale gate before a fresh iteration.
 - \`iterate_defense_events\` — defense event stream (\`.iterate/defense-events.json\`): \`list\`/\`counts\` review precondition failures, rollbacks, invariant violations, and falsified assumptions; \`record\` logs a new event when a defense fires. Human-readable labels follow the project \`language\` (en/zh).

package/dist/tools/report.js

@@ -0,0 +1,239 @@
+/**
+ * src/tools/report.ts — `iterate_report` tool.
+ *
+ *   iterate_report — render the current iterate run into a portable report.
+ *
+ * Two formats, one normalized data model (shared with the client export
+ * buttons via `lib/parse.js`, so the on-screen export and this tool can never
+ * drift):
+ *
+ *   - `markdown` — a PR-pasteable run report: header (mode/round/status), the
+ *                  quality-gate table, the findings table, the fixes table,
+ *                  validations, defense events, and the experience bank.
+ *   - `sarif`    — a SARIF 2.1.0 log so CI / GitHub Code Scanning can consume
+ *                  iterate findings as code-scanning results (ruleId =
+ *                  dimension, severity → error/warning/note, file+line
+ *                  locations, suggested fix attached).
+ *
+ * Reads only local state (`.iterate/transcript.json` + the quality / experience
+ * / defense stores) and writes only `.iterate/report.<ext>` when `write:true`.
+ * Malformed or missing state is rendered as-is (empty tables) — an export must
+ * never fail because a run was partial.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { resolveProjectRootForExec } from "../config-loader.js";
+import { iterateDir, transcriptPath } from "../paths.js";
+import { readQualityGate } from "./quality-store.js";
+import { readExperienceBank } from "./experience-store.js";
+import { readDefenseEvents } from "./defense-store.js";
+import { resultHeadline } from "./present.js";
+import { renderRunReportMarkdown, renderRunReportSarif, REPORT_FORMATS } from "../report-render.js";
+/** Formats accepted by the tool (kept in sync with the shared renderer). */
+const FORMATS = new Set(REPORT_FORMATS);
+/** Read the persisted transcript manifest, tolerating a missing/garbled file. */
+function readManifest(projectRoot) {
+    const file = transcriptPath(projectRoot);
+    if (!existsSync(file))
+        return { manifest: {}, source: 'empty' };
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf-8'));
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return { manifest: parsed, source: 'disk' };
+        }
+        return { manifest: {}, source: 'empty' };
+    }
+    catch {
+        return { manifest: {}, source: 'empty' };
+    }
+}
+/**
+ * Register the `iterate_report` tool.
+ * Renders the current run into a Markdown or SARIF report.
+ */
+export function registerReportTool(ctx) {
+    ctx.tools.register(defineTool({
+        name: 'iterate_report',
+        // Result card: surface the report headline ("report: markdown · N findings")
+        // as the card title. Pure: reads only the rendered result (replay-safe).
+        presentResult: (_args, result) => {
+            const title = resultHeadline(result);
+            return title ? { card: 'generic', title } : undefined;
+        },
+        // `write:true` persists a file; a pure render joins a parallel group.
+        isConcurrencySafe: (args) => args.write !== true,
+        description: 'Export the current iterate run as a portable report. ' +
+            '`format:"markdown"` (default) renders a PR-pasteable report: run header (mode / round / status), ' +
+            'quality-gate table, findings table, fixes table, per-round validations, defense events, and the ' +
+            'experience bank. `format:"sarif"` renders a SARIF 2.1.0 log for CI / GitHub Code Scanning ' +
+            '(one rule per review dimension; finding severity maps to error/warning/note; findings carry ' +
+            'file + line locations and the suggested fix). ' +
+            'Set `write:true` to also persist the report under `.iterate/report.md` / `.iterate/report.sarif` ' +
+            'and get the path back. `lang` selects the report language (zh | en). ' +
+            'Read-only apart from the optional report file; never touches source files.',
+        parameters: {
+            format: {
+                type: 'string',
+                description: 'Report format: "markdown" (default) or "sarif".',
+                enum: ['markdown', 'sarif'],
+            },
+            write: {
+                type: 'boolean',
+                description: 'When true, persist the report to `.iterate/report.md` / `.iterate/report.sarif` and return its path. Default: false.',
+            },
+            lang: {
+                type: 'string',
+                description: 'Report language: "zh" (default) or "en". Affects labels/headings only.',
+                enum: ['zh', 'en'],
+            },
+            path: {
+                type: 'string',
+                description: 'Project root directory (default: current working directory).',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    ok: { type: 'boolean', required: true },
+                    kind: { type: 'string' },
+                    format: { type: 'string' },
+                    /** The rendered report text (Markdown, or pretty-printed SARIF JSON). */
+                    content: { type: 'string' },
+                    /** The SARIF log object, when format is "sarif". */
+                    sarif: { type: 'json' },
+                    /** Whether a source transcript manifest was found on disk. */
+                    source: { type: 'string' },
+                    written: { type: 'boolean' },
+                    reportPath: { type: 'string' },
+                    findings: { type: 'number' },
+                    error: { type: 'string' },
+                },
+            },
+            render: (_args, value) => {
+                if (!value.ok)
+                    return [{ type: 'text', text: `report export failed: ${value.error}` }];
+                const content = typeof value.content === 'string' ? value.content : '';
+                const header = [
+                    `report: ${String(value.format ?? 'markdown')} · ${String(value.findings ?? 0)} findings · source=${String(value.source ?? 'empty')}`,
+                    value.written ? `written to ${String(value.reportPath ?? '')}` : '',
+                ].filter(Boolean).join(' · ');
+                return [{ type: 'text', text: `${header}\n\n${content}` }];
+            },
+        },
+        async execute(args, exec) {
+            const resolved = resolveProjectRootForExec(exec, args.path);
+            if (!resolved.ok)
+                return { ok: false, kind: 'report', error: resolved.reason };
+            const projectRoot = resolved.root;
+            const rawFormat = typeof args.format === 'string' ? args.format : 'markdown';
+            const format = FORMATS.has(rawFormat) ? rawFormat : 'markdown';
+            const lang = args.lang === 'en' ? 'en' : 'zh';
+            const { manifest, source } = readManifest(projectRoot);
+            let qualityGate = null;
+            let experienceBank = null;
+            let defenseEvents = null;
+            try {
+                qualityGate = readQualityGate(projectRoot);
+            }
+            catch {
+                qualityGate = null;
+            }
+            try {
+                experienceBank = readExperienceBank(projectRoot);
+            }
+            catch {
+                experienceBank = null;
+            }
+            try {
+                defenseEvents = readDefenseEvents(projectRoot);
+            }
+            catch {
+                defenseEvents = null;
+            }
+            const extra = { qualityGate, experienceBank, defenseEvents };
+            let content;
+            let sarif;
+            let findings = 0;
+            try {
+                if (format === 'sarif') {
+                    const doc = renderRunReportSarif(manifest, extra, {
+                        toolVersion: pluginVersion(),
+                    });
+                    sarif = doc;
+                    content = JSON.stringify(doc, null, 2);
+                    findings = Array.isArray(doc?.runs?.[0]?.results) ? doc.runs[0].results.length : 0;
+                }
+                else {
+                    content = renderRunReportMarkdown(manifest, extra, { lang });
+                    findings = countMarkdownFindings(content);
+                }
+            }
+            catch (err) {
+                return {
+                    ok: false,
+                    kind: 'report',
+                    format,
+                    error: `failed to render report: ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+            let written = false;
+            let reportPath;
+            if (args.write === true) {
+                try {
+                    const dir = iterateDir(projectRoot);
+                    mkdirSync(dir, { recursive: true });
+                    reportPath = `${dir}/report.${format === 'sarif' ? 'sarif' : 'md'}`;
+                    writeFileSync(reportPath, content, 'utf-8');
+                    written = true;
+                }
+                catch (err) {
+                    return {
+                        ok: false,
+                        kind: 'report',
+                        format,
+                        error: `failed to write report: ${err instanceof Error ? err.message : String(err)}`,
+                    };
+                }
+            }
+            return {
+                ok: true,
+                kind: 'report',
+                format,
+                content,
+                ...(sarif !== undefined ? { sarif } : {}),
+                source,
+                written,
+                ...(reportPath ? { reportPath } : {}),
+                findings,
+            };
+        },
+    }));
+}
+/**
+ * Best-effort plugin version for the SARIF driver. Resolved from the package
+ * manifest next to this module (`src/tools` and `dist/tools` are both two
+ * levels below the root); an unreadable/unparsable manifest yields ''.
+ */
+function pluginVersion() {
+    try {
+        const raw = readFileSync(new URL('../../package.json', import.meta.url), 'utf-8');
+        const pkg = JSON.parse(raw);
+        return typeof pkg.version === 'string' ? pkg.version : '';
+    }
+    catch {
+        return '';
+    }
+}
+/** Count the findings table rows in a rendered Markdown report (for the card). */
+function countMarkdownFindings(markdown) {
+    const m = /##\s+.*?\((\d+)\)/.exec(markdown);
+    if (m && m[1]) {
+        const n = Number(m[1]);
+        if (Number.isFinite(n))
+            return n;
+    }
+    return 0;
+}