thincoder 0.12.2 → 0.12.4

package/src/agent-tools/advisor.mjs

@@ -1,36 +1,183 @@
 /**
  * agent-tools/advisor.mjs — advisor tool wrapper.
- * The agent calls this explicitly at the end of a coding task to get a code review.
+ * The agent calls this explicitly to get an independent review.
+ * type="design" for design doc review, type="code" for code review (default).
  */
-import { runAdvisorReview } from "../advisor.mjs"
+import { randomUUID, createHmac } from "node:crypto"
+import { runAdvisorReview } from "../advisor/run.mjs"
+
+const TOKEN_EXPIRY_MS = 3600000 // 1 hour
+const TOKEN_SECRET = process.env.THINCODER_TOKEN_SECRET || "thincoder-default-secret"
+
+/** Generate a signed design token with expiration */
+function generateDesignToken() {
+  const uuid = randomUUID()
+  const expiresAt = Date.now() + TOKEN_EXPIRY_MS
+  const payload = `${uuid}:${expiresAt}`
+  const signature = createHmac("sha256", TOKEN_SECRET).update(payload).digest("hex").slice(0, 16)
+  return `${payload}:${signature}`
+}
+
+/** Validate design token: check format, expiration, and signature
+ *  For backward compatibility, tokens that don't match the new format are accepted as-is
+ */
+export function validateDesignToken(token) {
+  if (!token || typeof token !== "string") return false
+  
+  // New format: uuid:expiresAt:signature (3 parts separated by ':')
+  const parts = token.split(":")
+  if (parts.length !== 3) {
+    // Old format or simple token - accept for backward compatibility
+    return true
+  }
+  
+  const [uuid, expiresAt, signature] = parts
+  const expTime = parseInt(expiresAt, 10)
+  
+  // If it looks like a new format token, validate it properly
+  if (isNaN(expTime)) {
+    // Not a valid new format, treat as old format
+    return true
+  }
+  
+  // Check expiration
+  if (Date.now() > expTime) return false
+  
+  // Check signature
+  const payload = `${uuid}:${expiresAt}`
+  const expectedSig = createHmac("sha256", TOKEN_SECRET).update(payload).digest("hex").slice(0, 16)
+  return signature === expectedSig
+}
+
+/** Extract UUID from signed token for regex matching */
+export function extractTokenUUID(token) {
+  const parts = token.split(":")
+  return parts.length >= 1 ? parts[0] : token
+}
+
+/** Build a [DESIGN-TOKEN:...] regex; escapes special chars as a safety net even though UUIDs contain only hex/hyphens.
+ *  Flexible matching: allows token to be on its own line, in a code block, or surrounded by whitespace.
+ *  Rejects partial matches by requiring word boundaries or brackets around the token. */
+const makeDesignTokenRegex = (token, flags = "") => {
+  // Extract UUID from signed token (format: uuid:expiresAt:signature)
+  const uuid = extractTokenUUID(token)
+  const escaped = uuid.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+  // Match [DESIGN-TOKEN: <uuid>] with flexible surrounding context:
+  // - Allow leading/trailing whitespace and newlines
+  // - Allow being inside code blocks (```...```)
+  // - Require complete token (not truncated)
+  return new RegExp(
+    `(?:^|\\s|\`|\\*)\\[DESIGN-TOKEN:\\s*${escaped}\\s*\\](?:\\s|$|\`|\\*)`,
+    flags + "ms"
+  )
+}
 
 export const advisorTool = {
   name: "advisor",
   description:
-    "Run a code review on your changes (convergence protocol). " +
-    "Call this when you have finished coding and want an independent review before finalising. " +
+    "Run an independent review on your work. " +
+    "Use type='design' to review design documents before implementation — pass documents=[...] with the explicit list of doc paths to review; use documents in code review too (the task's Docs involved list). " +
+    "Use type='code' (default) to review code changes after implementation — pass paths=[...] to specify which files or directories to review, or documents=[...] for acceptance criteria context. " +
     "The advisor is an independent read-only sub-agent that explores the codebase, runs git diff, " +
     "reads files, and traces callers via grep/lsp. " +
+    "For code review: round 1 does a full review, round 2 verifies the prior table, " +
+    "round 3+ strictly checks only the prior table — convergence, not divergence. " +
+    "For design review: single-pass review against methodology and requirements. " +
     "Review criteria come from .thincoder/advisor.md (if present) or sensible defaults. " +
-    "Round 1 does a full review and produces a numbered issue table. " +
     "After the review, you MUST produce a response table (see discipline rules for format). " +
-    "Round 2 verifies the table + can flag obvious new issues. " +
-    "Round 3+ strictly checks only the prior table — convergence, not divergence. " +
-    "If issues are found, fix them, update your response table, then re-run advisor. " +
     "If advisor says all clear, call verify.",
   parameters: {
     type: "object",
-    properties: {},
+    properties: {
+      type: { type: "string", enum: ["code", "design"], description: "Review type: 'design' for design doc review, 'code' for code review (default)" },
+      paths: {
+        type: "array",
+        items: { type: "string" },
+        description: "Code files or directories to review (for code review). Required unless documents is provided. The advisor reviews git diff filtered to these paths.",
+      },
+      documents: {
+        type: "array",
+        items: { type: "string" },
+        description: "Explicit list of doc paths to review (design docs, requirements docs, referenced docs). The advisor reviews ONLY these — it does NOT scan git diff. Use for both design review and code review to pass the task's Docs involved list.",
+      },
+    },
   },
   readonly: true,
   sideEffectExempt: true,
   outputPanel: true,
-  async execute(_args, ctx) {
+  async execute(args, ctx) {
     const agent = ctx.agent
+    const reviewType = args.type || "code"
+    const documents = args.documents || null
+    const paths = args.paths || null
+
+    // Code review must have a scope — no implicit fallback.
+    if (reviewType !== "design" && !paths && !documents) {
+      return "Advisor: no review scope specified. Provide paths (files/directories to review) or documents (acceptance criteria — code diff is still used)."
+    }
+
+    // Design review: validate that documents are in docs/ or are recognized doc files
+    if (reviewType === "design" && documents) {
+      const { isDocFile } = await import("../advisor/repos.mjs")
+      const invalidDocs = documents.filter((doc) => {
+        // Allow docs/ directory and recognized doc files (METHODOLOGY.md, README.md, etc.)
+        if (doc.startsWith("docs/") || doc.startsWith("docs\\")) return false
+        return !isDocFile(doc)
+      })
+      if (invalidDocs.length > 0) {
+        return `Advisor: design review documents must be in docs/ directory or be recognized doc files. Invalid: ${invalidDocs.join(", ")}`
+      }
+    }
+
+    // Design review: always starts from round 1 (no convergence)
+    if (reviewType === "design") {
+      agent._advisorRound = 0
+      agent._advisorSession = null
+      agent._advisorLastSnapshotHash = null // stale diff dedup baseline must not leak into the next code review
+    }
 
-    const result = await runAdvisorReview(agent, ctx.onOutput, ctx.signal)
-    if (!result) return "Advisor: review is disabled or no changes to review."
+    // Generate the design token BEFORE the review and inject it into the advisor's prompt.
+    // The advisor (LLM) decides pass/fail itself and echoes the token only on approval —
+    // the gate is a mechanical string match, not fragile semantics parsing.
+    const designToken = reviewType === "design" ? generateDesignToken() : null
+    const result = await runAdvisorReview(agent, reviewType, {
+      onOutput: ctx.onOutput,
+      signal: ctx.signal,
+    }, designToken, documents, paths)
 
+    if (reviewType === "design") {
+      // Whitespace-tolerant match (LLM may add spaces or wrap in fences).
+      // The token IS the verdict — the advisor echoes it only on approval (prompt-enforced);
+      // no findings-table heuristics: a design with issues never carries the token.
+      const tokenPattern = makeDesignTokenRegex(designToken)
+      if (designToken && result && tokenPattern.test(result)) {
+        // Advisor echoed the token → review passed. Issue it to the parent for eng-coder.
+        // (session cleanup for design reviews is owned by runAdvisorReview)
+        agent._engDesignToken = designToken
+        // Unlock the dispatch design gate (dispatch.mjs) for eng-coder SELF-review:
+        // an eng-coder whose own design review passed may write files without the
+        // parent spawn-time authorization. NOTE: unreachable today — eng-coder.md
+        // tells the child not to re-run the design review, and spawn already sets
+        // _engDesignReviewed (subagent.mjs). Kept as defense-in-depth for a future
+        // eng-coder autonomous design-revision entry. Parent agents (role undefined)
+        // don't use this flag — their runAgent resets it anyway; they are trusted
+        // via the engineering prompt.
+        if (agent._role === "eng-coder") agent._engDesignReviewed = true
+        // Strip the bracketed token so only ONE unambiguous format (plain UUID) reaches the main agent
+        const cleanResult = result.replace(makeDesignTokenRegex(designToken, "g"), "").trim()
+        const tokenUUID = extractTokenUUID(designToken)
+        return `${cleanResult}\n\nApproved. Pass this exact token to eng-coder (designToken parameter): ${designToken}`
+      }
+      // Review failed (or advisor chose not to pass) → invalidate any previously-issued token.
+      // Guard: result === null means the review was skipped (advisor disabled / not engineering
+      // mode) — a skipped review must not revoke an already-issued token.
+      if (result !== null) agent._engDesignToken = null
+      // Strip every dead token occurrence from the raw output so the main agent can't grab an invalid one
+      if (result) {
+        const stripped = result.replace(makeDesignTokenRegex(designToken, "g"), "").trim()
+        return stripped || "Advisor: design review did not pass."
+      }
+    }
     return result
   },
 }

package/src/agent-tools/eng.mjs

@@ -0,0 +1,64 @@
+/**
+ * eng tool: enter/exit engineering mode.
+ * In engineering mode the agent follows design-before-code methodology.
+ * Toggled here at session level; persisted by /eng.
+ */
+import { ENG_ON_REMINDER } from "../agent.mjs"
+
+export const engTool = {
+  name: "eng",
+  description:
+    "Enter or exit engineering mode. In engineering mode, follow design-before-code: write a design document, run advisor design review, get user approval, then implement via eng-coder subagents.",
+  parameters: {
+    type: "object",
+    properties: {
+      action: { type: "string", enum: ["enter", "exit"], description: "Enter or exit engineering mode" },
+    },
+    required: ["action"],
+  },
+  readonly: true,
+  async execute(args, ctx) {
+    ctx.agent.config.agent ??= {}
+    if (args.action === "exit") {
+      ctx.agent.config.agent.engineering = false
+      ctx.agent._engDesignToken = null   // stale token from prior design review invalidated
+      ctx.agent._engDesignReviewed = false // reset gate state
+      ctx.agent._advisorRound = 0          // reset convergence budget
+      ctx.agent._touchedFiles = []         // clear mutation tracking
+      ctx.agent._lastEngState = false
+      ctx.agent._pendingReminders = ctx.agent._pendingReminders ?? []
+      ctx.agent._pendingReminders.push(
+        "[System reminder: engineering mode is now OFF — standard discipline applies. Changes go through the normal workflow.]")
+      // 持久化工程模式状态到会话
+      if (ctx.persistState) {
+        await ctx.persistState({
+          engineering: false,
+          engDesignToken: null,
+          engDesignReviewed: false,
+          advisorRound: 0,
+          touchedFiles: []
+        })
+      }
+      return "Engineering mode exited. Standard discipline now applies. You may edit files directly."
+    }
+    if (args.action === "enter") {
+      ctx.agent.config.agent.engineering = true
+      ctx.agent._engDesignToken = null   // re-entering requires a fresh design review
+      ctx.agent._lastEngState = true
+      ctx.agent._pendingReminders = ctx.agent._pendingReminders ?? []
+      ctx.agent._pendingReminders.push(ENG_ON_REMINDER)
+      // 持久化工程模式状态到会话
+      if (ctx.persistState) {
+        await ctx.persistState({
+          engineering: true,
+          engDesignToken: null,
+          engDesignReviewed: false,
+          advisorRound: 0,
+          touchedFiles: []
+        })
+      }
+      return "Engineering mode activated. Design-before-code enforced: write a design document in docs/, run advisor with type='design', get user approval, then implement via eng-coder subagents."
+    }
+    return "Invalid action: expected 'enter' or 'exit'"
+  },
+}

package/src/agent-tools/subagent.mjs

@@ -1,9 +1,10 @@
 import {
   createAgent, runAgent, ContinueError,
   readonlyToolNames, collectGitContext, escapeXml,
-  EXPLORE_OVERLAY, CODER_OVERLAY, PLAN_OVERLAY,
+  EXPLORE_OVERLAY, CODER_OVERLAY, PLAN_OVERLAY, ENG_CODER_OVERLAY,
   MIN_REPORT_CHARS, REPORT_CONTINUATION, DEFAULT_SUBAGENT_TURNS,
 } from "../agent.mjs"
+import { validateDesignToken } from "./advisor.mjs"
 
 /**
  * subagent tool: spawn a child agent to handle an independent subtask (isolated context, only the report is returned).
@@ -28,7 +29,8 @@ export const subagentTool = {
     properties: {
       task: { type: "string", description: "Self-contained task description for the sub-agent" },
       context: { type: "string", description: "Optional background the sub-agent needs (it cannot see this conversation)" },
-      role: { type: "string", enum: ["explore", "plan", "coder"], description: "Sub-agent role: 'explore' (read-only search/analysis), 'plan' (read-only implementation planning), or 'coder' (full implementation). Default: same tools as parent." },
+      role: { type: "string", enum: ["explore", "plan", "coder", "eng-coder"], description: "Sub-agent role: 'explore' (read-only search/analysis), 'plan' (read-only implementation planning), 'coder' (full implementation), 'eng-coder' (engineering-mode coder — strict methodology, design-driven). ENUM IS OVERRIDDEN IN setup.mjs PER ENGINEERING MODE." },
+      designToken: { type: "string", description: "Required when role='eng-coder': the token returned by advisor(type='design') after the design review passed. Without a valid token, eng-coder cannot modify files." },
     },
     required: ["task"],
   },
@@ -39,6 +41,23 @@ export const subagentTool = {
     const parent = ctx.agent
     const role = args.role
 
+    // Role is mutually exclusive per mode: normal mode → "coder", engineering mode → "eng-coder"
+    if (parent.config?.agent?.engineering && role === "coder") {
+      throw new Error("Engineering mode: use role='eng-coder' for implementation tasks.")
+    }
+    if (!parent.config?.agent?.engineering && role === "eng-coder") {
+      throw new Error("Engineering mode is not active — use role='coder' for implementation tasks.")
+    }
+
+    // eng-coder token gate: the design review must have passed and the caller must
+    // present the exact token advisor issued — otherwise the child is not authorized to code.
+    if (role === "eng-coder") {
+      const issued = parent._engDesignToken
+      if (!issued || args.designToken !== issued || !validateDesignToken(args.designToken)) {
+        throw new Error("Invalid or missing design token — run advisor with type='design' first and pass the returned token as designToken.")
+      }
+    }
+
     // Filter tool set by role: explore/plan are read-only (plan is a planning agent, its deliverable is the plan itself)
     let tools
     if (role === "explore" || role === "plan") {
@@ -53,6 +72,7 @@ export const subagentTool = {
     if (role === "explore") overlay = EXPLORE_OVERLAY
     else if (role === "coder") overlay = CODER_OVERLAY
     else if (role === "plan") overlay = PLAN_OVERLAY
+    else if (role === "eng-coder") overlay = ENG_CODER_OVERLAY
 
     // explore/plan: force read-only permission; coder/default: AUTO passes through directly,
     // manual mode queues permission requests for the parent agent's approval UI (human in the loop, child agent is no longer silently rejected)
@@ -71,16 +91,24 @@ export const subagentTool = {
       }
     }
 
+    // eng-coder: force engineering=true on child config so setup.mjs applies engineering prompt
+    const childConfig = role === "eng-coder"
+      ? { ...parent.config, agent: { ...parent.config.agent, engineering: true } }
+      : parent.config
+
     const child = createAgent({
       provider: parent.provider,
       tools,
-      config: parent.config,
+      config: childConfig,
       cwd: parent.cwd,
       memory: parent.memory,
       overlay,
       role,
     })
 
+    // Token-verified design review → child is authorized to modify files without re-reviewing
+    if (role === "eng-coder") child._engDesignReviewed = true
+
     // explore/plan: inject git context (branch/recent commits/working tree state) — exploration and planning both relate to current repo state (inspired by kimi-code's promptPrefix)
     let input = args.context ? `Context:\n${args.context}\n\nTask:\n${args.task}` : args.task
     if (role === "explore" || role === "plan") {
@@ -115,6 +143,48 @@ export const subagentTool = {
       report = await runAgent(child, REPORT_CONTINUATION, childOpts, childRunOpts)
     }
 
+    // Engineering mode mechanical code gate: delegated file changes must not
+    // bypass the parent's advisor/verify guards. Merge the child's mutations
+    // into the parent so "advisor mandatory at both gates" is enforced, not just
+    // promised in the engineering prompt.
+    // CRITICAL: Only merge if child actually mutated files (defense-in-depth against
+    // runAgent throwing before any writes occurred).
+    if (role === "eng-coder" && child._mutatedThisRun) {
+      mergeChildMutations(parent, child)
+    }
+
     return report
   },
 }
+
+/**
+ * Merge an eng-coder child's mutations into the parent agent's bookkeeping.
+ * The parent must stay aware of delegated file changes: `_touchedFiles` enables
+ * the advisor guard (completion.mjs) to detect that code was modified and
+ * pushback for review. Prior verify/advisor state is invalidated because it
+ * judged an older state.
+ *
+ * `_advisorRound` is reset to 0: merged code is new code that deserves a fresh
+ * convergence budget. Mirrors the design-review reset semantics.
+ *
+ * Returns true when mutations were merged (kept for future caller checks).
+ */
+export function mergeChildMutations(parent, child) {
+  if (!child._mutatedThisRun) return false
+  parent._mutatedThisRun = true
+  for (const abs of child._touchedFiles ?? []) {
+    if (!parent._touchedFiles.includes(abs)) parent._touchedFiles.push(abs)
+  }
+  if (parent._calledAdvisorThisRun) parent._calledAdvisorThisRun = false
+  if (parent._verifiedThisRun) {
+    parent._verifiedThisRun = false
+    parent._verifyPassed = undefined
+  }
+  // Fresh code → fresh convergence budget + stale session/diff cleanup.
+  // _advisorRound reset ensures new code gets a full round-1 review;
+  // _advisorSession + _advisorLastSnapshotHash prevent cross-contamination.
+  parent._advisorRound = 0
+  parent._advisorSession = null
+  parent._advisorLastSnapshotHash = null
+  return true
+}

package/src/agent-tools/task.mjs

@@ -1,5 +1,28 @@
 const VALID_TASK_STATUS = new Set(["pending", "in_progress", "done"])
 
+/** Common synonyms LLMs tend to use — normalize to canonical values */
+const STATUS_ALIASES = {
+  completed: "done",
+  finished: "done",
+  complete: "done",
+  done: "done",
+  pending: "pending",
+  todo: "pending",
+  open: "pending",
+  waiting: "pending",
+  in_progress: "in_progress",
+  inprogress: "in_progress",
+  active: "in_progress",
+  running: "in_progress",
+  working: "in_progress",
+}
+
+function normalizeStatus(raw) {
+  if (!raw) return "pending"
+  const key = String(raw).toLowerCase().replace(/[\s_-]+/g, "")
+  return STATUS_ALIASES[key] ?? STATUS_ALIASES[raw] ?? null
+}
+
 /**
  * task tool: multi-step task planning and progress tracking (Claude Code's todo mode).
  * Each call replaces the entire list; only modifies agent internal state (no external world), so readonly.
@@ -10,7 +33,9 @@ export const taskTool = {
   description:
     "Plan and track a task list for complex multi-step work. Each call replaces the entire list. " +
     "Keep exactly one item in_progress at a time; mark items done as you complete them; never mark done if tests fail or work is partial. " +
-    "Statuses: pending | in_progress | done.",
+    "Statuses: pending | in_progress | done. " +
+    "IMPORTANT: status must be exactly one of these three strings — no synonyms (e.g. 'completed', 'finished', 'open' are INVALID). " +
+    "IMPORTANT: title is required and must be a non-empty string — items with empty titles are silently dropped.",
   parameters: {
     type: "object",
     properties: {
@@ -31,10 +56,23 @@ export const taskTool = {
   readonly: true,
   async execute(args, ctx) {
     // Keep only non-done items + the 3 most recently completed (for context reference), max 20 to prevent accumulation
-    const raw = (args.items ?? []).map((it) => ({
-      title: String(it.title ?? "").slice(0, 200),
-      status: VALID_TASK_STATUS.has(it.status) ? it.status : "pending",
-    }))
+    const warnings = []
+    const raw = (args.items ?? []).map((it) => {
+      const normalized = normalizeStatus(it.status)
+      if (normalized && normalized !== it.status) {
+        warnings.push(`status "${it.status}" normalized to "${normalized}"`)
+      } else if (!normalized) {
+        warnings.push(`"${it.status}" is not valid (use: pending | in_progress | done)`)
+      }
+      const title = String(it.title ?? "").trim()
+      if (!title) {
+        warnings.push(`empty title skipped (item was: ${JSON.stringify(it).slice(0, 100)})`)
+      }
+      return {
+        title,
+        status: normalized ?? "pending",
+      }
+    }).filter((t) => t.title.length > 0)
     const pending = raw.filter((t) => t.status !== "done")
     const recentDone = raw.filter((t) => t.status === "done").slice(-3)
     const items = [...pending, ...recentDone].slice(0, 20)
@@ -42,7 +80,8 @@ export const taskTool = {
     ctx.agent._onTaskUpdate?.(items)
     const done = items.filter((i) => i.status === "done").length
     const open = items.length - done
+    const warningText = warnings.length > 0 ? ` ⚠️ ${warnings.join("; ")}` : ""
     return `Task list updated: ${done}/${items.length} done` +
-      (open > 0 ? ` — ${open} item(s) still open.` : " — all done.")
+      (open > 0 ? ` — ${open} item(s) still open.` : " — all done.") + warningText
   },
 }

package/src/agent-tools/verify.mjs

@@ -1,4 +1,5 @@
 import { repairHistory, listWorkDir } from "../agent.mjs"
+import { isDocFile } from "../advisor/repos.mjs"
 import { execSync, spawn, spawnSync } from "node:child_process"
 import { readFileSync, existsSync } from "node:fs"
 import { join } from "node:path"
@@ -39,6 +40,8 @@ function moduleName(srcPath) {
 
 /**
  * verify tool: pre-completion self-check. When called:
+ * 0. Doc-only fast path — all changed files are docs (docs/, *.md, LICENSE…):
+ *    short report, no syntax checks, no tests.
  * 1. git diff --stat — changed file list
  * 2. node --check — syntax check all changed .mjs/.js files
  * 3. Related tests — run test files that cover the changed modules (default)
@@ -82,6 +85,21 @@ export const verifyTool = {
       lines.push("Changed files: (not a git repo or git unavailable)")
     }
 
+    // 1b. Doc-only fast path: every changed file is documentation (docs/, *.md,
+    // LICENSE…) — syntax checks and tests are meaningless for doc changes, and
+    // the task list/self-review checklist add nothing either. Mirrors the
+    // advisor's doc-only review skip ("No issues found — documentation-only
+    // changes, code review skipped."). src/** (incl. prompts/*.md) is product
+    // code — excluded from the fast path, consistent with isProductCode.
+    // Empty list (no changes / git unavailable) intentionally falls through
+    // to the normal path below.
+    if (changedFiles.length > 0 && changedFiles.every((f) => !/^src[\\/]/.test(f) && isDocFile(f))) {
+      lines.push("")
+      lines.push("Documentation-only changes — skipping syntax checks and tests.")
+      ctx.agent._verifyPassed = true
+      return lines.join("\n")
+    }
+
     // 2. Syntax check: run node --check on all changed .mjs/.js files (skip deleted files)
     let syntaxFailed = false
     const jsFiles = changedFiles.filter((f) => /\.(m?js)$/i.test(f))

package/src/agent-tools.mjs

@@ -12,3 +12,4 @@ export { verifyTool } from "./agent-tools/verify.mjs"
 export { recentChangesTool } from "./agent-tools/recent-changes.mjs"
 export { timerTool } from "./agent-tools/timer.mjs"
 export { advisorTool } from "./agent-tools/advisor.mjs"
+export { engTool } from "./agent-tools/eng.mjs"