onbuzz 4.8.1 → 4.8.2

package/src/tools/__tests__/taskManagerTool.test.js

@@ -481,6 +481,147 @@ describe('TaskManagerTool', () => {
       expect(result.error).toContain('Invalid status');
     });
 
+    // ── Destructive-sync guardrail ───────────────────────────────────
+    // Real production failure: post-compaction, an agent forgot it had
+    // a 9-task plan and called sync with 4 unrelated tasks → all 9
+    // were silently dropped. These tests pin the guardrail.
+
+    describe('REGRESSION: destructive-sync guardrail', () => {
+      // Helper: seed the agent with two pending + one in_progress task,
+      // then attempt to sync with a totally different list.
+      async function setupAgentWithPlan() {
+        const { tool, context } = createTestSetup();
+        await tool.execute({
+          action: 'sync',
+          tasks: [
+            { title: 'Char select bg', status: 'in_progress', priority: 'high' },
+            { title: 'Board art',      status: 'pending',     priority: 'high' },
+            { title: 'Dice animation', status: 'pending',     priority: 'medium' },
+          ],
+        }, context);
+        return { tool, context };
+      }
+
+      test('REFUSES sync that would drop pending/in_progress tasks without confirmReplace', async () => {
+        const { tool, context } = await setupAgentWithPlan();
+        const result = await tool.execute({
+          action: 'sync',
+          tasks: [
+            { title: 'Add Settings UI', status: 'pending', priority: 'high' },
+            { title: 'Add Settings logic', status: 'pending', priority: 'high' },
+          ],
+        }, context);
+        expect(result.success).toBe(false);
+        expect(result.error).toMatch(/Sync would drop 3 non-terminal task/);
+        // Must name the at-risk tasks so the agent can see them.
+        expect(result.error).toContain('Char select bg');
+        expect(result.error).toContain('Board art');
+        expect(result.error).toContain('Dice animation');
+        // Must explain the escape hatch.
+        expect(result.error).toContain('confirmReplace: true');
+      });
+
+      test('PROCEEDS when confirmReplace=true is explicitly set', async () => {
+        const { tool, context } = await setupAgentWithPlan();
+        const result = await tool.execute({
+          action: 'sync',
+          confirmReplace: true,
+          tasks: [
+            { title: 'Add Settings UI', status: 'pending', priority: 'high' },
+          ],
+        }, context);
+        expect(result.success).toBe(true);
+        expect(result.result.summary.total).toBe(1);
+        expect(result.result.summary.removed).toBe(3);
+      });
+
+      test('does NOT trigger when the incoming list keeps every open task (rename only)', async () => {
+        const { tool, context } = await setupAgentWithPlan();
+        // Update statuses, but keep all titles. No drops.
+        const result = await tool.execute({
+          action: 'sync',
+          tasks: [
+            { title: 'Char select bg', status: 'completed',   priority: 'high' },
+            { title: 'Board art',      status: 'in_progress', priority: 'high' },
+            { title: 'Dice animation', status: 'pending',     priority: 'medium' },
+          ],
+        }, context);
+        expect(result.success).toBe(true);
+        expect(result.result.summary.updated).toBe(3);
+        expect(result.result.summary.removed).toBe(0);
+      });
+
+      test('does NOT trigger when only completed/cancelled tasks would be dropped', async () => {
+        const { tool, context } = createTestSetup();
+        // Seed with one done task + one pending.
+        await tool.execute({
+          action: 'sync',
+          tasks: [
+            { title: 'Already done',   status: 'completed', priority: 'low' },
+            { title: 'Still going',    status: 'pending',   priority: 'high' },
+          ],
+        }, context);
+        // New sync drops the completed one but keeps the pending one.
+        const result = await tool.execute({
+          action: 'sync',
+          tasks: [{ title: 'Still going', status: 'in_progress', priority: 'high' }],
+        }, context);
+        // No guardrail trip — completed task is safe to drop.
+        expect(result.success).toBe(true);
+      });
+
+      test('error response includes droppedTasks metadata for programmatic recovery', async () => {
+        const { tool, context } = await setupAgentWithPlan();
+        const result = await tool.execute({
+          action: 'sync',
+          tasks: [{ title: 'New thing', status: 'pending', priority: 'high' }],
+        }, context);
+        expect(result.success).toBe(false);
+        // BaseTool's execute() catches the thrown Error; the message
+        // carries the human-readable hint. We assert on the hint
+        // contents — that's what the agent sees.
+        expect(result.error).toMatch(/3 non-terminal task/);
+      });
+
+      test('REGRESSION: the exact Talisman failure scenario is now blocked', async () => {
+        // Reproduce the production failure: agent has a 9-task plan
+        // reflecting the user's UI revision request. Post-compaction,
+        // agent loses context and tries to sync a 4-task Settings plan.
+        const { tool, context } = createTestSetup();
+        await tool.execute({
+          action: 'sync',
+          tasks: [
+            { title: 'Explore current code and image assets', status: 'in_progress', priority: 'high' },
+            { title: 'Generate character select background',  status: 'pending',     priority: 'high' },
+            { title: 'Generate board space art for all nodes', status: 'pending',    priority: 'high' },
+            { title: 'Generate adventure card art',           status: 'pending',     priority: 'medium' },
+            { title: 'Fix board to rectangular layout',       status: 'pending',     priority: 'high' },
+            { title: 'Fix character select sticky buttons',   status: 'pending',     priority: 'medium' },
+            { title: 'Fix dice animation and combat',         status: 'pending',     priority: 'high' },
+            { title: 'Remove all emojis from UI',             status: 'pending',     priority: 'medium' },
+            { title: 'Test and verify all changes',           status: 'pending',     priority: 'medium' },
+          ],
+        }, context);
+        // The agent now (mistakenly) tries to sync a Settings plan.
+        const result = await tool.execute({
+          action: 'sync',
+          tasks: [
+            { title: 'Add Settings UI to index.html', status: 'pending', priority: 'high' },
+            { title: 'Add Settings logic to game.js', status: 'pending', priority: 'high' },
+            { title: 'Wire Settings to title screen', status: 'pending', priority: 'medium' },
+            { title: 'Test Settings persistence',     status: 'pending', priority: 'medium' },
+          ],
+        }, context);
+        expect(result.success).toBe(false);
+        // ALL 9 original tasks must be named so the agent sees them.
+        expect(result.error).toContain('Explore current code');
+        expect(result.error).toContain('Generate character select background');
+        expect(result.error).toContain('Fix dice animation and combat');
+        expect(result.error).toContain('Remove all emojis from UI');
+        expect(result.error).toMatch(/Sync would drop 9 non-terminal task/);
+      });
+    });
+
     test('enforces only one in_progress task', async () => {
       const { tool, agent, context } = createTestSetup();
       await tool.execute({

package/src/tools/baseTool.js

@@ -852,14 +852,20 @@ class ToolsRegistry {
       }
 
       if (hasMemory) {
-        description += '**When you recognize the work is multi-turn or multi-session:**\n';
-        description += '- Save a `memory` entry with title starting `plan/` (e.g. `plan/refactor-auth`). The content auto-injects into your system prompt every turn under "AGENT WORKING PLAN" until you delete it. This is how you survive compaction — anything important enough to remember next session belongs here.\n';
-        description += '- Update or delete the plan as the situation changes. A stale plan is worse than no plan.\n\n';
-      }
-
-      if (hasMemory) {
-        description += '**When you learn something durable** (a user preference, a non-obvious constraint, an architectural fact the next agent will want):\n';
-        description += '- Save it as a `memory` (non-`plan/` title). One-shot facts go here, NOT in your reply.\n\n';
+        // Concrete event-based write triggers. The previous version asked
+        // the agent to "save a memory when you recognize the work is
+        // multi-turn" — that's a judgment call, and in practice agents
+        // never made the call. Observed in production: 670 messages,
+        // 0 memory writes, despite the OPERATING POSTURE block being
+        // present in the system prompt. The fix is to replace "when
+        // you recognize" with concrete event triggers the model can
+        // pattern-match on without judgment.
+        description += '**WRITE memory on these events (not "when you think it\'s a good idea" — these are mandatory):**\n';
+        description += '- **A new user message contains a numbered list, a multi-bullet ask, OR more than ~30 words of substantive request.** Your VERY NEXT tool call must be `memory` → `add` with title `plan/<short-topic>` and content = the user\'s entire message verbatim. Do this BEFORE any other tool call, including taskmanager. Why mandatory: compaction may later destroy that message and the agent (you, next session) will not remember what the user actually asked for.\n';
+        description += '- **You are about to call `taskmanager` → `sync` with more than 3 tasks at once.** First, save a `memory` titled `plan/<feature>` containing the user\'s original request + your rationale for the plan. The task list is fragile (it can be wiped by a later sync); the plan/* memory is the source of truth.\n';
+        description += '- **You made a non-obvious decision** (chose approach A over B, fixed a tricky bug, discovered a constraint while exploring code, hit an unexpected error and figured out the cause). Save it as a `memory` with a non-`plan/` title before the next tool call. Format: title = the conclusion, content = the evidence. The next agent will not re-derive it.\n';
+        description += '- **The user gave you a preference or rule that should apply to all future work** ("never use emojis", "always use Tailwind", "the API base URL is X"). Save it immediately as a `memory`.\n\n';
+        description += '**`plan/*` memories auto-inject into your system prompt every turn under `## AGENT WORKING PLAN` — that\'s how they survive compaction. Update or delete them as the situation evolves; a stale plan is worse than no plan.**\n\n';
       }
 
       description += '**Distinction:**\n';

package/src/tools/taskManagerTool.js

@@ -219,7 +219,7 @@ ACTIONS:
 
 EXAMPLES:
 
-Sync task list (RECOMMENDED):
+Sync task list (RECOMMENDED — but BEWARE: replaces the whole list):
 \`\`\`json
 {
   "toolId": "taskmanager",
@@ -234,6 +234,27 @@ Sync task list (RECOMMENDED):
 }
 \`\`\`
 
+⚠️ **DESTRUCTIVE-SYNC GUARDRAIL** — sync replaces the entire task list. Any existing pending/in_progress task whose title doesn't match an incoming task is dropped. If you don't intend to drop those tasks, sync will REFUSE the call and tell you which tasks were at risk.
+
+To proceed with a destructive sync intentionally, add \`"confirmReplace": true\`:
+\`\`\`json
+{
+  "toolId": "taskmanager",
+  "actions": [{
+    "type": "sync",
+    "confirmReplace": true,
+    "tasks": [ /* the full new plan */ ]
+  }]
+}
+\`\`\`
+
+**Before issuing sync, prefer one of these instead** (they don't risk dropping tasks):
+- \`{"type": "list"}\` first — see what tasks already exist before deciding to replace them.
+- \`{"type": "create", "title": "..."}\` — add a single task without touching the rest.
+- \`{"type": "update", "taskId": "...", "status": "in_progress"}\` — change one task.
+
+This matters most right after compaction: the conversation history that mentioned your previous sync may have been compressed, but your task list is still there. Always \`list\` before \`sync\` if you suspect context loss.
+
 Create a task:
 \`\`\`json
 {
@@ -650,7 +671,7 @@ Always use a detailed task description to provide context for the task, and leve
    * @private
    */
   async syncTasks(agent, params, context) {
-    let { tasks } = params;
+    let { tasks, confirmReplace } = params;
 
     // Parse tasks if provided as JSON string
     if (typeof tasks === 'string') {
@@ -669,6 +690,55 @@ Always use a detailed task description to provide context for the task, and leve
       throw new Error('Tasks array cannot be empty');
     }
 
+    // ── DESTRUCTIVE-SYNC GUARDRAIL ───────────────────────────────────
+    // Real failure observed in production: an agent (post-compaction)
+    // lost track of its existing 9-task plan and called sync with a
+    // 4-task list of unrelated work. sync silently dropped all 9
+    // → agent built the wrong thing → user had to repeat themselves
+    // multiple times before the agent finally re-read the user request.
+    //
+    // Rule: if this sync would drop ANY pending or in_progress task
+    // whose title doesn't match an incoming task, refuse the call
+    // unless the agent explicitly passes `confirmReplace: true`.
+    // Completed/cancelled tasks can be silently pruned — they're done.
+    //
+    // Why this isn't too strict: matching is fuzzy (case-insensitive
+    // title compare; see findExistingTask below). An honest plan
+    // refinement that renames a few tasks will hit this guard, which
+    // is correct — the agent should acknowledge it's replacing work.
+    const existingTasksForGuard = agent.taskList?.tasks || [];
+    const incomingTitles = new Set(
+      tasks
+        .map(t => (t.title || '').toLowerCase().trim())
+        .filter(Boolean)
+    );
+    const dropped = existingTasksForGuard.filter(t => {
+      // Already terminal — safe to drop.
+      if (t.status === 'completed' || t.status === 'cancelled') return false;
+      // Match against any incoming title — same fuzzy rule used below.
+      return !incomingTitles.has((t.title || '').toLowerCase().trim());
+    });
+
+    if (dropped.length > 0 && confirmReplace !== true) {
+      const summary = dropped
+        .map(t => `  - [${t.status}] ${t.title}`)
+        .join('\n');
+      const hint = [
+        `Sync would drop ${dropped.length} non-terminal task(s) that don't match any incoming title:`,
+        summary,
+        '',
+        'If this is intentional (you really mean to replace the plan), retry with `confirmReplace: true`.',
+        'If you instead want to ADD tasks without dropping existing ones, use action "create" per task.',
+        'If you want to keep an existing task, include its title verbatim in the incoming list.',
+        '',
+        'This guardrail prevents post-compaction context loss from silently destroying in-flight work.',
+      ].join('\n');
+      const err = new Error(hint);
+      err.code = 'SYNC_WOULD_DROP_OPEN_TASKS';
+      err.droppedTasks = dropped.map(t => ({ id: t.id, title: t.title, status: t.status, priority: t.priority }));
+      throw err;
+    }
+
     const timestamp = new Date().toISOString();
     const existingTasks = agent.taskList.tasks || [];
     const updatedTasks = [];