@yeaft/webchat-agent 0.1.780 → 0.1.785

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.780",
+  "version": "0.1.785",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",

package/unify/session.js

@@ -50,7 +50,7 @@ import { openSegmentIndex } from './memory/index-db.js';
 import { syncAll as syncSegmentIndex } from './memory/segment-sync.js';
 import { openAmsRegistry } from './memory/ams-registry.js';
 import { join } from 'path';
-import { existsSync as existsSyncSafe, readFileSync as readFileSyncSafe } from 'fs';
+import { existsSync as existsSyncSafe, readFileSync as readFileSyncSafe, mkdirSync as mkdirSyncSafe } from 'fs';
 
 /**
  * @typedef {Object} SessionOptions
@@ -80,6 +80,33 @@ import { existsSync as existsSyncSafe, readFileSync as readFileSyncSafe } from '
  * @property {() => Promise<void>} shutdown — Graceful shutdown
  */
 
+/**
+ * Eagerly create `<yeaftDir>/stats/` and surface failures as a warn.
+ *
+ * Returns the resolved path either way — the caller can still pass it
+ * to `ToolUsageStats`, which keeps an in-memory counter path even when
+ * the disk is read-only.
+ *
+ * NOTE: this knowledge ("stats lives under `stats/`") belongs inside
+ * `ToolUsageStats.init()`. Once that exists, delete this helper and
+ * the call site collapses to `await toolStats.init(yeaftDir)`.
+ *
+ * @param {string} yeaftDir
+ * @returns {string} statsDir
+ */
+function prepareToolStatsDir(yeaftDir) {
+  const statsDir = join(yeaftDir, 'stats');
+  try {
+    mkdirSyncSafe(statsDir, { recursive: true });
+  } catch (err) {
+    console.warn(
+      `[Unify] Could not create stats dir ${statsDir}: ${err?.message || err}. ` +
+      `Tool-usage counters will live in memory only.`
+    );
+  }
+  return statsDir;
+}
+
 /**
  * Load (or initialize) a Yeaft session.
  *
@@ -320,8 +347,24 @@ export async function loadSession(options = {}) {
   // Tool-call usage statistics: persisted to <yeaftDir>/stats/tool-usage.json.
   // Loaded synchronously at boot so the first turn already sees prior counts.
   // Threaded into the engine so it can `record` each tool_exec event.
+  //
+  // 2026-05-16: eagerly create the `stats/` directory at boot. The
+  // ToolUsageStats writer does `fsp.mkdir(..., {recursive:true})` lazily
+  // inside `#doFlush()` and swallows any mkdir error, which meant an
+  // unwritable parent (perm denied, ENOSPC) was silently invisible
+  // until the user filed a support ticket. Doing it here surfaces the
+  // failure as a console.warn while still leaving the in-memory
+  // counter path functional — the engine keeps recording even if the
+  // disk is read-only.
+  //
+  // FOLLOW-UP: this leaks `ToolUsageStats`'s storage layout (its
+  // directory name) into the session orchestrator. The right home is
+  // a `ToolUsageStats.init()` that owns the mkdir + the warn + a
+  // `writesDisabled` flag. Tracking as future work; for now the helper
+  // below visually quarantines the leak so the migration is one delete.
+  const statsDir = prepareToolStatsDir(yeaftDir);
   const toolStats = new ToolUsageStats({
-    path: join(yeaftDir, 'stats', 'tool-usage.json'),
+    path: join(statsDir, 'tool-usage.json'),
   });
   toolStats.loadSync();
   const engine = new Engine({

package/unify/templates/plan-instruction.md

@@ -1,8 +1,9 @@
 # Planning Mode
 
-You have just entered **planning mode** for the topic below. Do NOT start
-executing yet. Your job in this turn is to **think through the work and produce
-a concrete plan**, then hand it off to `TodoWrite` so the steps are tracked.
+You have just entered **planning mode** for the topic below. Your job is to
+**think through the work, land a concrete plan via `TodoWrite`, and then
+continue executing the first step in the same turn**. Don't stop after writing
+the plan — keep going.
 
 ## How to think
 
@@ -20,7 +21,7 @@ a concrete plan**, then hand it off to `TodoWrite` so the steps are tracked.
 
 ## Output shape
 
-Reply in two parts:
+Reply in three parts, all in the **same turn**:
 
 **Part 1 — Plan (prose, short).** 5–10 lines covering the problem, the chosen
 approach, and the key risks. No filler. Skip if the topic is trivial.
@@ -32,9 +33,15 @@ array. Status rule:
 - Use the **imperative** form for `content` ("Write failing test"), and the
   **present-continuous** form for `activeForm` ("Writing failing test").
 
-**Do not execute the steps in this turn.** This turn ends after the `TodoWrite`
-call returns. On the next turn, the user (or you) will pick up the
-`in_progress` item and start work.
+**Part 3 — Start executing the first step.** Immediately after `TodoWrite`
+returns, begin work on the `in_progress` item by calling whatever tool(s) that
+step needs (bash, file-edit, grep, etc.). Don't end the turn just because the
+plan is written — the plan is the runway, not the destination.
+
+**Exception — stop after the plan only if** the very first step is "ask the
+user / wait for input" (e.g. an unresolved unknown that genuinely blocks
+every other step). In that case, call the `ask_user` tool with the
+question and end the turn. Otherwise keep moving.
 
 ## Tone
 

package/unify/tools/start-plan.js

@@ -3,11 +3,14 @@
  *
  * Lightweight planning entry point inspired by Claude Code's plan mode.
  * Unlike Claude Code, we do NOT swap tools or change conversation state —
- * `StartPlan` is a regular tool. Its only job is to push a planning
- * instruction back into the model's tool-result stream so the very next
- * turn produces a structured plan plus a `TodoWrite` call.
+ * `StartPlan` is a regular tool. Its job is to push a planning instruction
+ * back into the model's tool-result stream so the same turn produces a
+ * short prose plan, a `TodoWrite` call to land the steps, and then keeps
+ * going by starting the first step. The plan is the runway, not the
+ * destination — the loop continues until the work is done (or until the
+ * model legitimately needs the user, e.g. an unresolved unknown).
  *
- * Design (locked 2026-05-13):
+ * Design:
  *   - Anyone can call it; the tool description tells the LLM when to.
  *   - The instruction text comes from one of two places, in order:
  *       1. The active VP's `planInstruction` frontmatter override
@@ -20,13 +23,16 @@
  *     are echoed back in the tool result so the planning turn can read
  *     them without re-asking the user.
  *   - Output is plain text (the instruction + the echo). No side effects,
- *     no persistence — the LLM's next turn does the actual planning and
- *     calls TodoWrite to land structured steps.
+ *     no persistence — the same turn that called StartPlan produces the
+ *     plan, lands the steps via TodoWrite, and starts executing the first
+ *     step (unless that first step is "ask the user", which is the one
+ *     legitimate reason to stop here).
  *
- * The expected integration is TodoWrite: after the planning turn the LLM
- * issues a `TodoWrite` call enumerating the 1..N steps. The frontend
- * already renders TodoWrite as a checkbox-style list, so the user sees
- * the plan materialize without any new UI.
+ * The expected integration is TodoWrite: during the planning turn the LLM
+ * issues a `TodoWrite` call enumerating the 1..N steps, then keeps going
+ * and works the first step. The frontend already renders TodoWrite as a
+ * checkbox-style list, so the user sees the plan materialize without any
+ * new UI.
  */
 
 import { defineTool } from './types.js';
@@ -36,9 +42,10 @@ export default defineTool({
   name: 'StartPlan',
   description: `Enter planning mode for a non-trivial task. Use BEFORE you start working when the request needs multiple steps, has unclear scope, or the user said "make a plan" / "think through this first".
 
-This tool does NOT execute the work. It returns a planning instruction; on the next turn you should:
+This tool returns a planning instruction. Use it to land a structured plan, then keep working in the same turn. The expected flow is:
 1. Produce a short prose plan (problem, approach, risks).
 2. Call \`TodoWrite\` with the ordered steps. Mark the first concrete step "in_progress", the rest "pending".
+3. Start executing that first step — call whatever tools the work needs. Do not end the turn just because the plan is written; the plan is the runway.
 
 WHEN TO USE:
 - Multi-step implementation (3+ steps), refactor, or open-ended investigation.
@@ -49,6 +56,8 @@ WHEN NOT TO USE:
 - Single trivial change, single command run, lookup-style question.
 - Mid-execution — once you're past the first step, use TodoWrite directly.
 
+EXCEPTION — stop after the plan only if the first step is genuinely "ask the user" (an unresolved unknown that blocks every other step). Otherwise keep moving.
+
 The tool takes the topic plus optional guiding fields (stuckAt, userProblem, expectedScale, additionalContext) that help you think; they're echoed back verbatim, so don't repeat the full user request in \`topic\`.`,
   parameters: {
     type: 'object',
@@ -126,7 +135,7 @@ The tool takes the topic plus optional guiding fields (stuckAt, userProblem, exp
       lines.push('</guiding-context>');
     }
     lines.push('');
-    lines.push('Next: produce the plan as described above, then call `TodoWrite` to land the ordered steps. Do NOT start executing the steps in this turn.');
+    lines.push('Next: produce the plan, call `TodoWrite` to land the ordered steps, then keep going — start executing the first step in this same turn. Only stop after the plan if the first step is "ask the user".');
 
     return lines.join('\n');
   },