iterate-plugin 2.11.0 → 2.12.0

package/lib/parse.js

@@ -310,6 +310,282 @@ export function scanSessionForReport(session) {
   return null
 }
 
+// ─── Runtime-observatory transcript detection ────────────────────────────────
+
+/**
+ * Check whether `obj` is a valid runtime-observatory TranscriptManifest.
+ * Discriminators vs a ReviewReport: `convergence` is a NUMBER ARRAY (the
+ * findings-per-round trend), not an object like ReviewReport.convergence, and
+ * `version` is a number. Requires `version` + `rounds` (array) + `convergence`
+ * (array) so a ReviewReport never collides with a manifest.
+ *
+ * @param {unknown} obj
+ * @returns {obj is Record<string, unknown>}
+ */
+export function isTranscriptManifest(obj) {
+  if (!obj || typeof obj !== 'object') return false
+  const o = /** @type {Record<string, unknown>} */ (obj)
+  return (
+    typeof safeGet(o, 'version') === 'number' &&
+    Array.isArray(safeGet(o, 'rounds')) &&
+    Array.isArray(safeGet(o, 'convergence'))
+  )
+}
+
+/**
+ * Attach the outer `live` array (sibling of `transcript` in an
+ * iterate_transcript result: `{ operation, found, live:[...], transcript }`) to
+ * a found manifest, so the secondary-subagent activity stream rides along with
+ * the manifest. Builds a defensive shallow copy (never mutates a possibly
+ * shared/proxied manifest). Returns the manifest unchanged when the source has
+ * no `live` array or the manifest already carries one.
+ *
+ * @param {Record<string, unknown> | null} manifest
+ * @param {unknown} source
+ * @returns {Record<string, unknown> | null}
+ */
+function attachLive(manifest, source) {
+  if (!manifest || typeof manifest !== 'object') return manifest
+  const live = source && typeof source === 'object' ? safeGet(source, 'live') : undefined
+  if (!Array.isArray(live)) return manifest
+  const m = /** @type {Record<string, unknown>} */ (manifest)
+  if (safeGet(m, 'live') !== undefined) return manifest
+  const copy = /** @type {Record<string, unknown>} */ ({})
+  for (const k of safeKeys(m)) copy[k] = safeGet(m, k)
+  copy.live = live
+  return copy
+}
+
+/**
+ * Pull a manifest out of a single tool-result node. Accepts either the raw
+ * manifest object, `{ operation: 'capture', transcript: manifest }`, a
+ * string-wrapped JSON payload, or a plain wrapper (e.g. `{ message: ... }`).
+ * Falls back to a shallow deep-find (findTranscriptInObject) so a nested
+ * manifest buried inside an arbitrary result still surfaces. Never throws.
+ *
+ * @param {unknown} obj
+ * @returns {Record<string, unknown> | null}
+ */
+function extractTranscript(obj) {
+  if (typeof obj === 'string') {
+    try {
+      const parsed = JSON.parse(obj)
+      return extractTranscript(parsed)
+    } catch {
+      return null
+    }
+  }
+  if (!obj || typeof obj !== 'object') return null
+
+  // Direct manifest.
+  if (isTranscriptManifest(obj)) return /** @type {Record<string, unknown>} */ (obj)
+
+  const o = /** @type {Record<string, unknown>} */ (obj)
+
+  // { operation: 'capture', transcript: manifest, live: [...] }.
+  if (safeGet(o, 'operation') === 'capture') {
+    const t = safeGet(o, 'transcript')
+    if (t && typeof t === 'object' && isTranscriptManifest(t)) {
+      return attachLive(/** @type {Record<string, unknown>} */ (t), o)
+    }
+  }
+
+  // Wrapper shapes the harness may emit: { message: ... }, { result: ... },
+  // { content: [...] } (an assistant tool-call block).
+  for (const key of ['message', 'result', 'content']) {
+    const val = safeGet(o, key)
+    if (val !== undefined) {
+      if (Array.isArray(val)) {
+        for (const item of val) {
+          const found = extractTranscript(item)
+          if (found) return attachLive(found, o)
+        }
+      } else {
+        const found = extractTranscript(val)
+        if (found) return attachLive(found, o)
+      }
+    }
+  }
+
+  // Generic deep find for resilience.
+  return attachLive(findTranscriptInObject(o), o)
+}
+
+/**
+ * Deep-scan an object tree for the first TranscriptManifest (same traversal
+ * semantics as `findReportInObject`: circular-reference + depth guards).
+ *
+ * @param {unknown} obj
+ * @param {Set<unknown>} [seen]
+ * @param {number} [maxDepth=20]
+ * @returns {Record<string, unknown> | null}
+ */
+export function findTranscriptInObject(obj, seen, maxDepth = 20) {
+  if (maxDepth <= 0) return null
+  if (!obj || typeof obj !== 'object') return null
+
+  const s = seen || new Set()
+  if (s.has(obj)) return null
+  s.add(obj)
+
+  if (isTranscriptManifest(obj)) return /** @type {Record<string, unknown>} */ (obj)
+
+  if (Array.isArray(obj)) {
+    for (const item of obj) {
+      const found = findTranscriptInObject(item, s, maxDepth - 1)
+      if (found) return found
+    }
+    return null
+  }
+
+  const o = /** @type {Record<string, unknown>} */ (obj)
+  for (const key of safeKeys(o)) {
+    const val = safeGet(o, key)
+    if (val && typeof val === 'object') {
+      const found = findTranscriptInObject(val, s, maxDepth - 1)
+      if (found) return found
+    }
+  }
+
+  return null
+}
+
+/**
+ * Scan a session snapshot (or any object) for the latest iterate_transcript
+ * tool result that carries a runtime-observatory TranscriptManifest. Prefers
+ * the most recent one (reverse chronological). Order of preference:
+ *   1. session.toolCalls[].result/.message wrapping the manifest;
+ *   2. session.messages[].content (assistant tool-call blocks / strings).
+ * Must work from the in-memory session stream because the client cannot read
+ * `.iterate/transcript.json` off disk.
+ *
+ * @param {unknown} session
+ * @returns {Record<string, unknown> | null}
+ */
+export function scanSessionForTranscript(session) {
+  if (!session || typeof session !== 'object') return null
+
+  const s = /** @type {Record<string, unknown>} */ (session)
+
+  // Common pattern: session.toolCalls[].result / .message.
+  const toolCalls = safeGet(s, 'toolCalls')
+  if (Array.isArray(toolCalls)) {
+    const calls = /** @type {Array<Record<string, unknown>>} */ (toolCalls)
+    for (let i = calls.length - 1; i >= 0; i--) {
+      const call = calls[i]
+      if (!call) continue
+      const tool = String(safeGet(call, 'tool') ?? '')
+      if (tool !== 'iterate_transcript' && !tool.endsWith('iterate_transcript')) continue
+      const found = extractTranscript(safeGet(call, 'result')) ||
+        extractTranscript(safeGet(call, 'message'))
+      if (found) return found
+    }
+  }
+
+  // Common pattern: assistant message content (tool-call blocks / strings).
+  const messages = safeGet(s, 'messages')
+  if (Array.isArray(messages)) {
+    const msgs = /** @type {Array<Record<string, unknown>>} */ (messages)
+    for (let i = msgs.length - 1; i >= 0; i--) {
+      const msg = msgs[i]
+      if (!msg) continue
+      // Prefer the explicit tool-call surface first, then generic content.
+      const calls = safeGet(msg, 'tool_calls')
+      if (Array.isArray(calls)) {
+        for (const call of calls) {
+          if (!call) continue
+          const args = safeGet(call, 'arguments')
+          if (typeof args === 'string') {
+            const found = extractTranscript(args)
+            if (found) return found
+          }
+        }
+      }
+      const found = extractTranscript(safeGet(msg, 'content'))
+      if (found) return found
+    }
+  }
+
+  return null
+}
+
+/**
+ * Normalize a TranscriptManifest into a plain, JSON-safe object so rendering
+ * never touches a live cordis proxy (which can throw on property reads). Every
+ * optional/missing field degrades to a safe default; the input is never
+ * mutated and unknown extra fields are dropped.
+ *
+ * @param {Record<string, unknown> | null | undefined} manifest
+ * @returns {Record<string, unknown>}
+ */
+export function normalizeTranscript(manifest) {
+  const src = manifest && typeof manifest === 'object'
+    ? /** @type {Record<string, unknown>} */ (manifest)
+    : {}
+  const asNum = (v) => (typeof v === 'number' ? v : 0)
+  const asStr = (v) => (typeof v === 'string' ? v : '')
+  const asBool = (v) => v === true
+  const asCount = (v) => (typeof v === 'number' ? v : 0)
+  const asArray = (v) => (Array.isArray(v) ? /** @type {Array<Record<string, unknown>>} */ (v) : [])
+
+  const rounds = asArray(safeGet(src, 'rounds')).map((r) => ({
+    round: asNum(safeGet(r, 'round')),
+    threads: asArray(safeGet(r, 'threads')).map((t) => ({
+      dimension: asStr(safeGet(t, 'dimension')),
+      attempt: asNum(safeGet(t, 'attempt')),
+      messages: asArray(safeGet(t, 'messages')).map((m) => (typeof m === 'string' ? m : '')),
+      readFiles: asArray(safeGet(t, 'readFiles')).map((f) => (typeof f === 'string' ? f : '')),
+      findings: asArray(safeGet(t, 'findings')).map((f) => ({ ...f })),
+    })),
+  }))
+
+  const cp = safeGet(src, 'checkpoint')
+  const checkpoint = cp && typeof cp === 'object'
+    ? {
+        mode: asStr(safeGet(cp, 'mode')),
+        round: asNum(safeGet(cp, 'round')),
+        maxRounds: asNum(safeGet(cp, 'maxRounds')),
+        fixedCount: asNum(safeGet(cp, 'fixedCount')),
+        resumeCount: asNum(safeGet(cp, 'resumeCount')),
+        updatedAt: asStr(safeGet(cp, 'updatedAt')),
+      }
+    : null
+
+  const ng = safeGet(src, 'nudge')
+  const nudge = ng && typeof ng === 'object'
+    ? { timestamp: asStr(safeGet(ng, 'timestamp')), text: asStr(safeGet(ng, 'text')) }
+    : null
+
+  const ap = safeGet(src, 'approval')
+  return {
+    version: asNum(safeGet(src, 'version')),
+    project: asStr(safeGet(src, 'project')),
+    updatedAt: asStr(safeGet(src, 'updatedAt')),
+    active: asBool(safeGet(src, 'active')),
+    mode: asStr(safeGet(src, 'mode')) || null,
+    goal: asStr(safeGet(src, 'goal')),
+    phases: asArray(safeGet(src, 'phases')).map((p) => (typeof p === 'string' ? p : '')),
+    round: asNum(safeGet(src, 'round')),
+    maxRounds: asNum(safeGet(src, 'maxRounds')),
+    rounds,
+    convergence: asArray(safeGet(src, 'convergence')).map((n) => asCount(n)),
+    findings: asArray(safeGet(src, 'findings')).map((f) => ({ ...f })),
+    fixes: asArray(safeGet(src, 'fixes')).map((f) => ({ ...f })),
+    live: asArray(safeGet(src, 'live')).map((e) => ({
+      ts: typeof safeGet(e, 'ts') === 'number' ? String(safeGet(e, 'ts')) : asStr(safeGet(e, 'ts')),
+      type: asStr(safeGet(e, 'type')),
+      tool: asStr(safeGet(e, 'tool')),
+      target: asStr(safeGet(e, 'target')),
+    })),
+    checkpoint,
+    timeline: asArray(safeGet(src, 'timeline')).map((t) => ({ ...t })),
+    nudge,
+    approval: ap && typeof ap === 'object'
+      ? { active: asBool(safeGet(ap, 'active')), policy: asStr(safeGet(ap, 'policy')) || 'ask' }
+      : { active: false, policy: 'ask' },
+  }
+}
+
 // ─── Run-summary / meta-review verdict detection ─────────────────────────────
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-plugin",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "dsh plugin that turns the iterate skill into an autonomous closed-loop harness: plan -> parallel review xN -> atomic fixes -> validate -> loop -> auto-stop, plus a dry-run pure-review mode with multi-round convergence and a meta-review that audits the report and emits a final review report.",
   "type": "module",
   "license": "MIT",

package/src/approval-gate.ts

@@ -0,0 +1,119 @@
+/**
+ * src/approval-gate.ts — pure policy gate for destructive iterate tool calls.
+ *
+ * Feeds dsh's `tools/pre-execute` waterfall (registered in `session-hooks.ts`).
+ * The gate classifies a tool execution and returns a typed decision without
+ * any I/O, so it is fully unit-testable:
+ *
+ *   - `{ kind: 'allow' }`        → run the call.
+ *   - `{ kind: 'ask', reason }`  → prompt the human via the dsh approval service.
+ *   - `{ kind: 'deny', reason }` → refuse; the caller surfaces the reason.
+ *
+ * Policy (config `observatory.approval`, default 'ask'):
+ *   - `allow` → destructive iterate calls always run (debug/trusted).
+ *   - `deny`  → destructive iterate calls are always refused (fail-closed).
+ *   - `ask`   → destructive iterate calls prompt the human first.
+ *
+ * Destructive calls are exactly the ones that mutate the workspace:
+ * `iterate_fix` (writes files), `iterate_rollback` (restores from backups),
+ * and `iterate_prune` with `dryRun !== true` (deletes `.iterate/` artifacts).
+ * Read-only calls are always allowed. Non-iterate calls are untouched — the
+ * gate only ever inspects iterate tools so it cannot alter unrelated behavior.
+ */
+
+export type ApprovalDecision =
+  | { kind: 'allow' }
+  | { kind: 'ask'; reason: string }
+  | { kind: 'deny'; reason: string }
+
+/** The subset of a tool execution the gate inspects. */
+export interface ToolExecutionLike {
+  name: string
+  arguments?: unknown
+}
+
+/** Destructive iterate tools subject to the gate. */
+const DESTRUCTIVE_TOOLS = new Set(['iterate_fix', 'iterate_rollback', 'iterate_prune'])
+
+/** Human-readable reason rendered in the approval prompt. */
+function describe(toolName: string, arguments0?: Record<string, unknown>): string {
+  const file =
+    arguments0 && typeof arguments0.file === 'string'
+      ? `\`${arguments0.file}\``
+      : 'the workspace'
+  switch (toolName) {
+    case 'iterate_fix':
+      return `Apply an atomic fix to ${file}`
+    case 'iterate_rollback': {
+      const id =
+        arguments0 && typeof arguments0.id === 'string' ? ` \`${arguments0.id}\`` : ''
+      return `Revert fix${id} (restore ${file} from backup)`
+    }
+    case 'iterate_prune':
+      return 'Delete stale `.iterate/` runtime artifacts'
+    default:
+      return `Run ${toolName}`
+  }
+}
+
+/**
+ * Decide whether a tool execution may proceed under the given policy.
+ * Returns `allow` for read-only prune (`dryRun: true`), for `allow`-policy
+ * deployments, and for any non-iterate tool.
+ */
+export function decideApproval(
+  execution: ToolExecutionLike,
+  policy: 'ask' | 'deny' | 'allow',
+): ApprovalDecision {
+  const name = typeof execution?.name === 'string' ? execution.name : ''
+  if (!name) return { kind: 'allow' }
+  if (!DESTRUCTIVE_TOOLS.has(name)) return { kind: 'allow' }
+
+  const rawArgs = execution.arguments
+  const args: Record<string, unknown> =
+    rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs)
+      ? (rawArgs as Record<string, unknown>)
+      : {}
+  // `iterate_prune` is read-only in its default dry-run mode — no gate needed.
+  if (name === 'iterate_prune' && args.dryRun === false) {
+    // falls through to the destructive path below
+  } else if (name === 'iterate_prune') {
+    return { kind: 'allow' }
+  }
+
+  if (policy === 'allow') return { kind: 'allow' }
+  const reason = describe(name, args)
+  if (policy === 'deny') return { kind: 'deny', reason }
+  return { kind: 'ask', reason }
+}
+
+/** True when any destructive iterate tool is listed in a name set. */
+export function isDestructiveIterateTool(name: unknown): boolean {
+  return typeof name === 'string' && DESTRUCTIVE_TOOLS.has(name)
+}
+
+/** Tool-facing gate result: run, or refuse (with an explicit human-approval signal). */
+export type ToolGateResult =
+  | { ok: true }
+  | { ok: false; requiresApproval: true; reason: string }
+  | { ok: false; error: string }
+
+/**
+ * Evaluate an iterate tool's own boundary gate for a destructive call.
+ * `approvedArg` is the caller-supplied `approved: true` flag (human consent
+ * already obtained). Returns a run / refuse result without any I/O.
+ */
+export function toolGate(
+  policy: 'ask' | 'deny' | 'allow',
+  execution: ToolExecutionLike,
+  approvedArg?: unknown,
+): ToolGateResult {
+  const decision = decideApproval(execution, policy)
+  if (decision.kind === 'allow') return { ok: true }
+  if (decision.kind === 'deny') {
+    return { ok: false, error: `Blocked by observatory approval policy: ${decision.reason}` }
+  }
+  // ask
+  if (approvedArg === true) return { ok: true }
+  return { ok: false, requiresApproval: true, reason: decision.reason }
+}