clementine-agent 1.18.195 → 1.18.197

package/dist/agent/agent-definitions.js

@@ -50,6 +50,51 @@ const RESEARCHER_PROMPT = [
     '',
     'If you cannot find the requested data, say so in one line. Do not speculate.',
 ].join('\n');
+/**
+ * 1.18.197 — discovery subagent. The owner asked Clementine to be the
+ * ORCHESTRATOR, not the worker. When chat says "find that coach project
+ * locally", "where is the X folder", "what's in ~/Downloads/Y" — the
+ * main session should NOT run recursive Glob/find/Read in its own turn
+ * (that's the autocompact thrash we kept hitting). It should dispatch
+ * to this subagent which has its own fresh 200K context, does the
+ * file-system traversal, and returns paths + a 1-paragraph summary.
+ *
+ * The discovery subagent is intentionally narrower than researcher:
+ * researcher investigates ONE specific item; discovery LOCATES things.
+ *
+ * Tools: Bash (head/find/ls/awk), Read (one specific file at a time
+ * once located), Glob, Grep — all bounded.
+ *
+ * NOT included: Edit, Write, mutating MCP tools. Pure read-only.
+ */
+const DISCOVERY_PROMPT = [
+    'You are the file-system discovery specialist. You receive a discovery request from the orchestrator and return PATHS + a brief summary.',
+    '',
+    'Your job: locate things. NOT read full contents. NOT analyze in depth.',
+    '',
+    'Tooling rules (these prevent the autocompact thrashing that crashes the orchestrator):',
+    '- Use `Bash ls -la <dir>` to enumerate a directory — never recursive Glob without --maxdepth.',
+    '- Use `Bash find <dir> -maxdepth 3 -name "*.csv"` (or similar) to find files matching a pattern.',
+    '- Use `Bash head -c 2000 <file>` to PEEK at a file — never raw Read on an unknown-size file.',
+    '- Use `Bash wc -l <file>` to size-check before any Read.',
+    '- Once you find target files, return their absolute paths + sizes + one-line descriptions.',
+    '- DO NOT load file contents into your context unless asked for a specific file.',
+    '',
+    'Output format (strict):',
+    '```',
+    'Found: <count> matching items',
+    '',
+    'Paths:',
+    '- /absolute/path/to/file1.csv (12KB, 340 rows) — appears to be coach roster',
+    '- /absolute/path/to/file2.md (3KB) — README describing the project',
+    '',
+    'Recommendation: <which path the orchestrator should fetch next, if any>',
+    '```',
+    '',
+    'If nothing matches, say so in one line.',
+    '',
+    'You are bounded by max 15 turns. Use them wisely — list, scope, summarize, return.',
+].join('\n');
 const CRON_FIXER_PROMPT = [
     'You are the cron-fix specialist. You diagnose and apply fixes to broken cron jobs.',
     '',
@@ -147,6 +192,31 @@ export function buildAgentMap(opts = {}) {
         effort: 'low',
         maxTurns: 15,
     };
+    // Discovery (1.18.197): file-system / project location. Owner's
+    // northstar: Clementine orchestrates, doesn't bulk-process. ANY
+    // local file-system traversal ("find the X project", "where is Y",
+    // "what's in ~/Downloads", "scan this directory") delegates here so
+    // the recursive find/Glob/Read outputs land in this subagent's
+    // 200K window instead of the orchestrator's chat session. Returns
+    // paths + brief summaries — never file contents.
+    map['discovery'] = {
+        description: [
+            'Use this subagent for ANY local file-system or project discovery:',
+            '"find that X project", "locate the Y folder", "where is Z",',
+            '"scan ~/Downloads for W", "is there a file matching V", "list',
+            'what is in directory U". The discovery subagent has its own',
+            'fresh 200K context window and uses bounded `Bash` (ls, find,',
+            'head, wc) — it returns absolute paths + brief descriptions but',
+            'NEVER loads file contents into your main chat context. ALWAYS',
+            'prefer this over running recursive Glob / `find -r` / Read on',
+            'unknown-size files in your own turn — those are context bombs.',
+        ].join(' '),
+        prompt: DISCOVERY_PROMPT,
+        model: 'haiku',
+        tools: ['Bash', 'Read', 'Grep', 'Glob'],
+        effort: 'low',
+        maxTurns: 15,
+    };
     // Cron-fixer: sonnet, owns the broken-job diagnose+apply path.
     // Tools restricted to the canonical fix path (no parallel mechanisms).
     map['cron-fixer'] = {

package/dist/agent/run-agent-context.js

@@ -125,12 +125,23 @@ const BEHAVIORAL_POSTURE = `## How you operate
 
 **Verification posture for disputed claims.** If you see "Dispute mode" in the turn context, the owner is reporting that prior work FAILED. Past \`done\` claims in memory are NOT authoritative — your recall is biased. Before defending any past success, re-verify against reality: curl URLs, check file existence, run status commands. Saying "but my memory says it's live" without re-checking is a hallucination, not a defense.
 
-**Fan-out posture (1.18.194).** When the owner asks for 3+ similar operations — send N emails, pull N records, enrich N contacts, summarize N pages — dispatch subagents in PARALLEL via the Agent tool. One subagent per item. Don't loop in your own turn; that's slow, serializes I/O that should be concurrent, and burns context linearly. Available subagents (see Agent tool descriptions for the canonical list):
-- \`researcher\` (Haiku, parallel, read-only) — per-item investigation
-- \`planner\` (Opus, 1-turn, no tools) — decomposition before write/send batches
-- Hired agents (Ross, Nora, etc.) — cross-delegation when relevant
+**Orchestrator posture (1.18.197).** You are the orchestrator, not the worker. Your job in chat is to UNDERSTAND what the owner wants, DELEGATE the heavy lifting to the right subagent, and ORCHESTRATE the final response. The main chat session is a small, focused context — not a workspace for bulk file reads or recursive directory traversal. Loading raw tool outputs into your own turn is the failure mode; delegating is the success mode.
 
-A 25-contact enrichment that fans out to 25 \`researcher\` calls finishes in ~30s. The same work done serially in your own turn takes 10+ minutes AND fills your context window with tool outputs. Default to fan-out for batch work.`;
+**Tool-selection rubric.** Before running tools yourself, ask which bucket the request falls into:
+
+1. **Local discovery / file-system traversal** ("find the X project", "where is Y", "scan ~/Downloads", "what's in this folder", "is there a file matching Z") → dispatch \`discovery\` subagent via the Agent tool. It has its own 200K context and returns paths + summaries. Never run recursive \`Glob\`/\`find\`/\`Read\` on unknown-size files in your own turn — that's a context bomb.
+
+2. **Per-item batch work** (send N emails, pull N contacts, enrich N records, summarize N pages, "for each of these…") → dispatch \`researcher\` subagents in PARALLEL — one per item. A 25-item job that fans out finishes in ~30s. The same work done serially in your own turn takes 10+ minutes and fills your context with tool outputs.
+
+3. **Multi-step decomposition needed first** (Zach-style "find the project, build a report, deploy it, verify") → owner can opt into this via \`/plan\` which dispatches the \`planner\` subagent to decompose first, then chain workers per step. Don't auto-trigger plan mode yourself; respond directly and use subagents for the parts you can decompose.
+
+4. **Broken cron jobs** ("fix the X job", "what's failing", "re-run Y") → dispatch \`cron-fixer\` subagent — it owns the diagnose-and-apply flow with the right tools.
+
+5. **Cross-agent work** (work that belongs to Ross / Nora / Sasha / etc.) → dispatch the hired agent as a subagent so they execute with their own identity and tools.
+
+6. **Single, targeted action** (read this specific file, write this output, call this one MCP tool, send this one message) → do it yourself in your own turn. Direct tool use is correct when the scope is small and known.
+
+**The northstar.** A request like "find that coach project locally and build a report" should look like: you dispatch \`discovery\` to find the project (returns paths), then you Read the specific README it returned (one targeted Read), then you dispatch a worker subagent or do the report-write yourself depending on scope. NOT: you run a recursive \`Glob\` then 20 Reads in your own turn.`;
 /**
  * Read the long-term memory block for an autonomous run (cron, team-task).
  * Returns the agent-specific MEMORY.md when a hired agent is active, the

package/dist/gateway/router.js

@@ -2606,20 +2606,68 @@ export class Gateway {
                     // result with terminalReason), we surface a clean "rephrase or
                     // /plan" message via the `case 'context_overflow':` handler
                     // below. No more "Planning failed" half-finished chains.
-                    let runAgentResult;
-                    try {
-                        runAgentResult = await runAgent(finalPrompt, buildRunAgentChatOptions({
-                            ...(priorSdkSessionId ? { resumeSessionId: priorSdkSessionId } : {}),
+                    // 1.18.196 — smart session reset on overflow.
+                    //
+                    // SDK session files on disk can grow to 80+ MB after months of
+                    // chat. When we resume one of those, the SDK tries to load the
+                    // entire accumulated JSONL into context — easily blows past
+                    // 200K tokens on the very first user message after a daemon
+                    // start. Zach hit this on a freshly-installed 1.18.195 because
+                    // his topshelfbot session had months of history.
+                    //
+                    // The fix is the same thing any human would do: throw the
+                    // resume away, start a fresh SDK session, send the same user
+                    // message. The user loses chat memory of the prior session
+                    // (it's gone anyway — we can't load it), but they get an
+                    // actual response instead of a "rephrase smaller" message.
+                    //
+                    // This is ONE retry max. If the fresh session also overflows,
+                    // that's a genuine ceiling — surface the recovery message.
+                    // No planner queueing, no compression dance, no second retry.
+                    //
+                    // Distinct from the deleted-in-1.18.194 pipeline because:
+                    //   - No prompt compression — the prompt is fine
+                    //   - No planner background task — that was the failing piece
+                    //   - No second retry — one shot only
+                    //   - Triggered only when we WERE resuming (overflow on a
+                    //     virgin session is a real ceiling, not a stale-history
+                    //     problem)
+                    let didFreshSessionRetry = false;
+                    const runAgentOnce = async (resumeId) => {
+                        return runAgent(finalPrompt, buildRunAgentChatOptions({
+                            ...(resumeId ? { resumeSessionId: resumeId } : {}),
                             ...(chatSystemAppend ? { systemPromptAppend: chatSystemAppend } : {}),
                         }));
+                    };
+                    const maybeRetryFresh = async () => {
+                        if (didFreshSessionRetry || !priorSdkSessionId)
+                            return null;
+                        didFreshSessionRetry = true;
+                        logger.info({
+                            sessionKey: effectiveSessionKey,
+                            priorSdkSessionId,
+                        }, 'Context overflow on resumed session — clearing session and retrying once with fresh SDK session');
+                        this.assistant.clearSession(effectiveSessionKey);
+                        if (onProgress) {
+                            await onProgress('long conversation history — starting a fresh session...').catch(() => { });
+                        }
+                        return runAgentOnce(undefined);
+                    };
+                    let runAgentResult;
+                    try {
+                        runAgentResult = await runAgentOnce(priorSdkSessionId);
                     }
                     catch (err) {
                         if (chatAc.signal.aborted || classifyChatError(err) !== 'context_overflow') {
                             throw err;
                         }
-                        // Re-throw so the outer catch's classifyChatError gets it
-                        // and routes to the 'context_overflow' case.
-                        throw err;
+                        // First attempt overflowed. If we were resuming, try once
+                        // with a fresh session. Otherwise (no resume to drop),
+                        // surface the recovery message.
+                        const retried = await maybeRetryFresh();
+                        if (!retried)
+                            throw err;
+                        runAgentResult = retried;
                     }
                     if (!chatAc.signal.aborted && runAgentResultIndicatesContextOverflow(runAgentResult)) {
                         logger.info({
@@ -2627,8 +2675,15 @@ export class Gateway {
                             subtype: runAgentResult.subtype,
                             terminalReason: runAgentResult.terminalReason,
                             textPreview: runAgentResult.text?.slice(0, 240),
-                        }, 'Context overflow result — autocompact ceiling reached, surfacing recovery message');
-                        throw new Error('context_overflow_after_autocompact');
+                            didFreshSessionRetry,
+                        }, 'Context overflow result — attempting fresh-session retry or surfacing recovery');
+                        const retried = await maybeRetryFresh();
+                        if (retried && !runAgentResultIndicatesContextOverflow(retried)) {
+                            runAgentResult = retried;
+                        }
+                        else {
+                            throw new Error('context_overflow_after_autocompact');
+                        }
                     }
                     if (ledgerRunMetadata) {
                         ledgerRunMetadata.runId = runAgentResult.runId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.18.195",
+  "version": "1.18.197",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",