thincoder 0.12.2 → 0.12.3

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"