titan-agent 6.1.0-beta.3 → 6.1.0-beta.30

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Tony Elliott (https://github.com/Djtony707)
+Copyright (c) 2026 Tony Elliott
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -19,31 +19,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-
----
-
-ACKNOWLEDGMENTS
-
-TITAN's architecture is inspired by OpenClaw (https://github.com/openclaw/openclaw),
-an open-source personal AI assistant framework, licensed under the MIT License.
-Thank you to the OpenClaw team and all open-source contributors.
-
-Voice interface adapted from LiveKit Agent Starter React
-(https://github.com/livekit-examples/agent-starter-react).
-Copyright (c) 2025 LiveKit, Inc. Licensed under the MIT License.
-Thank you to the LiveKit team for their excellent real-time WebRTC platform.
-
-Mission Control v2 frontend built with React 19 (MIT), Vite (MIT),
-Tailwind CSS 4 (MIT), React Router v7 (MIT), react-markdown (MIT),
-Lucide React (ISC), and Motion (MIT).
-
-Voice infrastructure powered by faster-whisper (MIT), Kokoro FastAPI (MIT),
-Caddy (Apache-2.0), and the LiveKit Agents SDK (Apache-2.0).
-
-Temporal knowledge graph inspired by Graphiti (https://github.com/getzep/graphiti)
-by Zep AI, licensed under Apache-2.0.
-
-Browser automation patterns inspired by Skyvern (https://github.com/Skyvern-AI/skyvern)
-by Skyvern AI, licensed under AGPL-3.0 (separate service, not bundled).
-
-For the complete list of third-party dependencies, see THIRD_PARTY_NOTICES.md.

package/README.md

@@ -46,7 +46,7 @@
 
 ## 🪵 NEW in v6.1 — Mission Chat + Desk view
 
-> Status: `v6.1.0-beta.3` — live on npm at `@latest` and `@beta`. Alpha series concluded with `6.1.0-alpha.57`; the schema promoted to beta once features stabilized.
+> Status: `v6.1.0-beta.7` — live on npm at `@latest` and `@beta`. Alpha series concluded with `6.1.0-alpha.57`; the schema promoted to beta once features stabilized.
 > Install with `npm i -g titan-agent` (or `npm update -g titan-agent`).
 > The v6.0 "Presence" feature set below still applies — v6.1.0 layers
 > a beautiful new surface on top of it.

package/dist/agent/agentLessons.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync } from "fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync, unlinkSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
 import logger from "../utils/logger.js";
@@ -137,7 +137,7 @@ function __resetLessonsForTests(agentId) {
   const path = lessonsPath(agentId);
   if (existsSync(path)) {
     try {
-      require("fs").unlinkSync(path);
+      unlinkSync(path);
     } catch {
     }
   }

package/dist/agent/agentLessons.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/agent/agentLessons.ts"],"sourcesContent":["/**\n * TITAN — Per-agent lessons.md (Reflexion-style failure memory).\n *\n * Why this exists\n * ---------------\n * The audit of TITAN's Command Post (2026-05-11) found that retrospectives\n * were computed in-memory per goal but never persisted as a per-agent\n * lookup. That meant the next time the same agent took on similar work,\n * it walked into the same failure modes blind.\n *\n * This module is the persistence layer for the Reflexion pattern as\n * documented in awesome-agent-harness pattern #6:\n *\n *   \"When a step fails, a separate critic LLM writes a 1-3 sentence\n *    verbal lesson ('I forgot to check the schema before inserting')\n *    into lessons.md. Future planner turns read this file first.\"\n *\n * One file per agent at `~/.titan/agents/<agentId>/lessons.md`. Append-only\n * + dedup-on-content. The top-N most recent / highest-relevance entries\n * are injected into that agent's system prompt at the start of every run\n * via {@link renderAgentLessonsForPrompt}.\n *\n * Reference:\n *   - Shinn et al. \"Reflexion: Language agents with verbal reinforcement\n *     learning\" (NeurIPS 2023) — https://arxiv.org/abs/2303.11366\n *   - Picrew/awesome-agent-harness pattern #6\n *   - ~/.claude/projects/-Users-michaelelliott/memory/titan-v6-living-canvas.md\n */\nimport { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync } from 'fs';\nimport { join } from 'path';\nimport { homedir } from 'os';\nimport logger from '../utils/logger.js';\nimport { recordJournalEvent } from './durableJournal.js';\n\nconst COMPONENT = 'AgentLessons';\n\n/** Lazy path resolution so tests can swap HOME / TITAN_HOME. */\nfunction titanHome(): string {\n    const env = process.env.TITAN_HOME;\n    if (env) return env.startsWith('~/') ? join(homedir(), env.slice(2)) : env;\n    return join(homedir(), '.titan');\n}\nfunction lessonsPath(agentId: string): string {\n    return join(titanHome(), 'agents', agentId, 'lessons.md');\n}\n\n/** A single lesson the agent has learned from a past failure or success. */\nexport interface AgentLesson {\n    /** Short, verbal — the lesson the agent took away (1–3 sentences). */\n    text: string;\n    /** \"fail\" lessons come from things that went wrong; \"win\" lessons from\n     *  things that worked surprisingly well. Both are useful. Default fail. */\n    kind?: 'fail' | 'win';\n    /** Free-form context tag — what kind of task this was about (e.g.\n     *  \"merge-conflict\", \"json-extract\", \"vram-acquire\"). Used for fuzzy\n     *  lookup later. Optional. */\n    topic?: string;\n    /** Optional sessionId for traceback. */\n    sessionId?: string;\n    /** Optional goalId — when set, the lesson is also written into the\n     *  goal's durable journal so a resuming process can see it. */\n    goalId?: string;\n}\n\n/** Cap on lesson count per agent. Older entries roll off the head. */\nconst LESSONS_PER_AGENT_CAP = 200;\n/** Cap on lessons rendered into the system prompt at run time. */\nconst PROMPT_RENDER_CAP = 12;\n\n/**\n * Append a lesson to the agent's lessons.md. Idempotent on near-duplicate\n * text (lowercased, whitespace-collapsed match) so the same lesson written\n * twice in close succession doesn't pollute the file.\n */\nexport function recordLesson(agentId: string, lesson: AgentLesson): void {\n    if (!agentId || !lesson?.text || !lesson.text.trim()) return;\n    try {\n        const path = lessonsPath(agentId);\n        try { mkdirSync(join(path, '..'), { recursive: true }); } catch { /* exists */ }\n\n        const norm = (s: string) => s.toLowerCase().replace(/\\s+/g, ' ').trim();\n        const incomingNorm = norm(lesson.text);\n\n        // Read existing entries to dedup against recent ones.\n        const existingRaw = existsSync(path) ? readFileSync(path, 'utf-8') : '';\n        const recentNorms = parseLessonTexts(existingRaw)\n            .slice(-20) // only dedup against last 20 — older content fades\n            .map(norm);\n        if (recentNorms.includes(incomingNorm)) {\n            return; // already learned this lesson recently\n        }\n\n        // Append one entry in the documented format.\n        const ts = new Date().toISOString();\n        const kind = lesson.kind ?? 'fail';\n        const topic = lesson.topic ? ` topic=\"${escapeAttr(lesson.topic)}\"` : '';\n        const session = lesson.sessionId ? ` session=\"${escapeAttr(lesson.sessionId)}\"` : '';\n        const block = `\\n- [${ts}] **${kind}**${topic}${session} — ${lesson.text.trim()}\\n`;\n\n        // Make sure the file has a header on first write.\n        if (!existsSync(path)) {\n            writeFileSync(path, lessonsHeader(agentId), 'utf-8');\n        }\n        appendFileSync(path, block, 'utf-8');\n\n        // Trim to cap if exceeded.\n        trimIfOverCap(path);\n\n        logger.info(COMPONENT, `Recorded ${kind}-lesson for ${agentId}${topic} — \"${lesson.text.slice(0, 80)}\"`);\n\n        // v6.0 CP upgrade #4 — durable journal: surface lessons in the\n        // per-context replay so resuming agents can see what was learned.\n        recordJournalEvent(\n            { agentId, goalId: lesson.goalId, sessionId: lesson.sessionId },\n            'lesson_recorded',\n            { text: lesson.text.trim(), kind, topic: lesson.topic },\n        );\n    } catch (err) {\n        logger.warn(COMPONENT, `Failed to write lesson for ${agentId}: ${(err as Error).message}`);\n    }\n}\n\nfunction lessonsHeader(agentId: string): string {\n    return [\n        `# Lessons — ${agentId}`,\n        ``,\n        `Append-only verbal-reinforcement journal. Each entry is one lesson the`,\n        `agent learned from a past attempt (failure or surprising win). The top`,\n        `~${PROMPT_RENDER_CAP} most recent entries are injected into this agent's system`,\n        `prompt at the start of every run.`,\n        ``,\n        `Format: \\`- [iso-ts] **kind** [topic=\"…\"] [session=\"…\"] — verbal lesson\\``,\n        ``,\n        `---`,\n        ``,\n    ].join('\\n');\n}\n\nfunction escapeAttr(s: string): string {\n    return s.replace(/[\\\\\"\\n\\r]/g, c => c === '\\n' ? ' ' : c === '\\r' ? ' ' : '\\\\' + c).slice(0, 80);\n}\n\n/** Parse the lesson lines from the raw markdown. Returns text content only. */\nfunction parseLessonTexts(raw: string): string[] {\n    const lines = raw.split(/\\r?\\n/);\n    const out: string[] = [];\n    for (const l of lines) {\n        // Match the documented format. Capture everything after the trailing \" — \".\n        const m = l.match(/^- \\[[^\\]]+\\]\\s+\\*\\*(fail|win)\\*\\*(?:[^—]*)—\\s+(.+)$/);\n        if (m && m[2]) out.push(m[2]);\n    }\n    return out;\n}\n\nfunction trimIfOverCap(path: string): void {\n    try {\n        const raw = readFileSync(path, 'utf-8');\n        const lines = raw.split(/\\r?\\n/);\n        // Find the entries (lines starting with \"- [\")\n        const entryIdx: number[] = [];\n        for (let i = 0; i < lines.length; i++) {\n            if (lines[i].startsWith('- [')) entryIdx.push(i);\n        }\n        if (entryIdx.length <= LESSONS_PER_AGENT_CAP) return;\n        // Drop the oldest (LESSONS_PER_AGENT_CAP / 4) when we tip over.\n        const dropCount = Math.max(1, Math.floor(LESSONS_PER_AGENT_CAP / 4));\n        const cutAt = entryIdx[dropCount] ?? entryIdx[0];\n        // Header ends at first \"---\" line.\n        const headerEnd = lines.findIndex(l => l.trim() === '---');\n        const header = headerEnd >= 0 ? lines.slice(0, headerEnd + 2).join('\\n') : '';\n        const kept = lines.slice(cutAt).join('\\n');\n        writeFileSync(path, header + '\\n' + kept, 'utf-8');\n        logger.info(COMPONENT, `Trimmed ${dropCount} oldest lessons from ${path}`);\n    } catch { /* best-effort */ }\n}\n\n/**\n * Render the most relevant lessons for `agentId` as a prompt-ready block.\n * If `topic` is supplied, lessons matching that topic float to the top.\n * Returns empty string when there are no lessons yet (don't add a\n * prompt section with no content).\n */\nexport function renderAgentLessonsForPrompt(agentId: string, topic?: string): string {\n    if (!agentId) return '';\n    const path = lessonsPath(agentId);\n    if (!existsSync(path)) return '';\n    try {\n        const raw = readFileSync(path, 'utf-8');\n        const lines = raw.split(/\\r?\\n/);\n        // Parse structured entries: kind + topic + text.\n        const entries: Array<{ kind: string; topic: string; text: string; ts: string }> = [];\n        for (const l of lines) {\n            const m = l.match(/^- \\[([^\\]]+)\\]\\s+\\*\\*(fail|win)\\*\\*(?:\\s+topic=\"([^\"]+)\")?(?:[^—]*)—\\s+(.+)$/);\n            if (m) entries.push({ ts: m[1], kind: m[2], topic: m[3] || '', text: m[4] });\n        }\n        if (entries.length === 0) return '';\n\n        // Sort: most recent first, with topic match boost.\n        const wantsTopic = (topic || '').toLowerCase();\n        const scored = entries.map(e => ({\n            e,\n            score: (wantsTopic && e.topic.toLowerCase() === wantsTopic ? 1 : 0)\n                 + (wantsTopic && e.topic.toLowerCase().includes(wantsTopic) ? 0.5 : 0),\n        }));\n        scored.sort((a, b) => b.score - a.score || b.e.ts.localeCompare(a.e.ts));\n\n        const top = scored.slice(0, PROMPT_RENDER_CAP).map(s => s.e);\n        if (top.length === 0) return '';\n\n        const out: string[] = [`## Lessons you've learned (top ${top.length})`];\n        for (const e of top) {\n            const tag = e.topic ? ` *(${e.topic})*` : '';\n            out.push(`- **${e.kind}**${tag} — ${e.text}`);\n        }\n        return out.join('\\n');\n    } catch {\n        return '';\n    }\n}\n\n/** Convenience helper — read raw lessons.md content (used by tests + UI). */\nexport function readLessonsMarkdown(agentId: string): string {\n    const path = lessonsPath(agentId);\n    return existsSync(path) ? readFileSync(path, 'utf-8') : '';\n}\n\n/** Test helper — wipe an agent's lessons file. */\nexport function __resetLessonsForTests(agentId: string): void {\n    const path = lessonsPath(agentId);\n    if (existsSync(path)) {\n        try { require('fs').unlinkSync(path); } catch { /* fine */ }\n    }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/agent/agentLessons.ts"],"sourcesContent":["/**\n * TITAN — Per-agent lessons.md (Reflexion-style failure memory).\n *\n * Why this exists\n * ---------------\n * The audit of TITAN's Command Post (2026-05-11) found that retrospectives\n * were computed in-memory per goal but never persisted as a per-agent\n * lookup. That meant the next time the same agent took on similar work,\n * it walked into the same failure modes blind.\n *\n * This module is the persistence layer for the Reflexion pattern as\n * documented in awesome-agent-harness pattern #6:\n *\n *   \"When a step fails, a separate critic LLM writes a 1-3 sentence\n *    verbal lesson ('I forgot to check the schema before inserting')\n *    into lessons.md. Future planner turns read this file first.\"\n *\n * One file per agent at `~/.titan/agents/<agentId>/lessons.md`. Append-only\n * + dedup-on-content. The top-N most recent / highest-relevance entries\n * are injected into that agent's system prompt at the start of every run\n * via {@link renderAgentLessonsForPrompt}.\n *\n * Reference:\n *   - Shinn et al. \"Reflexion: Language agents with verbal reinforcement\n *     learning\" (NeurIPS 2023) — https://arxiv.org/abs/2303.11366\n *   - Picrew/awesome-agent-harness pattern #6\n *   - ~/.claude/projects/-Users-michaelelliott/memory/titan-v6-living-canvas.md\n */\nimport { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync, unlinkSync } from 'fs';\nimport { join } from 'path';\nimport { homedir } from 'os';\nimport logger from '../utils/logger.js';\nimport { recordJournalEvent } from './durableJournal.js';\n\nconst COMPONENT = 'AgentLessons';\n\n/** Lazy path resolution so tests can swap HOME / TITAN_HOME. */\nfunction titanHome(): string {\n    const env = process.env.TITAN_HOME;\n    if (env) return env.startsWith('~/') ? join(homedir(), env.slice(2)) : env;\n    return join(homedir(), '.titan');\n}\nfunction lessonsPath(agentId: string): string {\n    return join(titanHome(), 'agents', agentId, 'lessons.md');\n}\n\n/** A single lesson the agent has learned from a past failure or success. */\nexport interface AgentLesson {\n    /** Short, verbal — the lesson the agent took away (1–3 sentences). */\n    text: string;\n    /** \"fail\" lessons come from things that went wrong; \"win\" lessons from\n     *  things that worked surprisingly well. Both are useful. Default fail. */\n    kind?: 'fail' | 'win';\n    /** Free-form context tag — what kind of task this was about (e.g.\n     *  \"merge-conflict\", \"json-extract\", \"vram-acquire\"). Used for fuzzy\n     *  lookup later. Optional. */\n    topic?: string;\n    /** Optional sessionId for traceback. */\n    sessionId?: string;\n    /** Optional goalId — when set, the lesson is also written into the\n     *  goal's durable journal so a resuming process can see it. */\n    goalId?: string;\n}\n\n/** Cap on lesson count per agent. Older entries roll off the head. */\nconst LESSONS_PER_AGENT_CAP = 200;\n/** Cap on lessons rendered into the system prompt at run time. */\nconst PROMPT_RENDER_CAP = 12;\n\n/**\n * Append a lesson to the agent's lessons.md. Idempotent on near-duplicate\n * text (lowercased, whitespace-collapsed match) so the same lesson written\n * twice in close succession doesn't pollute the file.\n */\nexport function recordLesson(agentId: string, lesson: AgentLesson): void {\n    if (!agentId || !lesson?.text || !lesson.text.trim()) return;\n    try {\n        const path = lessonsPath(agentId);\n        try { mkdirSync(join(path, '..'), { recursive: true }); } catch { /* exists */ }\n\n        const norm = (s: string) => s.toLowerCase().replace(/\\s+/g, ' ').trim();\n        const incomingNorm = norm(lesson.text);\n\n        // Read existing entries to dedup against recent ones.\n        const existingRaw = existsSync(path) ? readFileSync(path, 'utf-8') : '';\n        const recentNorms = parseLessonTexts(existingRaw)\n            .slice(-20) // only dedup against last 20 — older content fades\n            .map(norm);\n        if (recentNorms.includes(incomingNorm)) {\n            return; // already learned this lesson recently\n        }\n\n        // Append one entry in the documented format.\n        const ts = new Date().toISOString();\n        const kind = lesson.kind ?? 'fail';\n        const topic = lesson.topic ? ` topic=\"${escapeAttr(lesson.topic)}\"` : '';\n        const session = lesson.sessionId ? ` session=\"${escapeAttr(lesson.sessionId)}\"` : '';\n        const block = `\\n- [${ts}] **${kind}**${topic}${session} — ${lesson.text.trim()}\\n`;\n\n        // Make sure the file has a header on first write.\n        if (!existsSync(path)) {\n            writeFileSync(path, lessonsHeader(agentId), 'utf-8');\n        }\n        appendFileSync(path, block, 'utf-8');\n\n        // Trim to cap if exceeded.\n        trimIfOverCap(path);\n\n        logger.info(COMPONENT, `Recorded ${kind}-lesson for ${agentId}${topic} — \"${lesson.text.slice(0, 80)}\"`);\n\n        // v6.0 CP upgrade #4 — durable journal: surface lessons in the\n        // per-context replay so resuming agents can see what was learned.\n        recordJournalEvent(\n            { agentId, goalId: lesson.goalId, sessionId: lesson.sessionId },\n            'lesson_recorded',\n            { text: lesson.text.trim(), kind, topic: lesson.topic },\n        );\n    } catch (err) {\n        logger.warn(COMPONENT, `Failed to write lesson for ${agentId}: ${(err as Error).message}`);\n    }\n}\n\nfunction lessonsHeader(agentId: string): string {\n    return [\n        `# Lessons — ${agentId}`,\n        ``,\n        `Append-only verbal-reinforcement journal. Each entry is one lesson the`,\n        `agent learned from a past attempt (failure or surprising win). The top`,\n        `~${PROMPT_RENDER_CAP} most recent entries are injected into this agent's system`,\n        `prompt at the start of every run.`,\n        ``,\n        `Format: \\`- [iso-ts] **kind** [topic=\"…\"] [session=\"…\"] — verbal lesson\\``,\n        ``,\n        `---`,\n        ``,\n    ].join('\\n');\n}\n\nfunction escapeAttr(s: string): string {\n    return s.replace(/[\\\\\"\\n\\r]/g, c => c === '\\n' ? ' ' : c === '\\r' ? ' ' : '\\\\' + c).slice(0, 80);\n}\n\n/** Parse the lesson lines from the raw markdown. Returns text content only. */\nfunction parseLessonTexts(raw: string): string[] {\n    const lines = raw.split(/\\r?\\n/);\n    const out: string[] = [];\n    for (const l of lines) {\n        // Match the documented format. Capture everything after the trailing \" — \".\n        const m = l.match(/^- \\[[^\\]]+\\]\\s+\\*\\*(fail|win)\\*\\*(?:[^—]*)—\\s+(.+)$/);\n        if (m && m[2]) out.push(m[2]);\n    }\n    return out;\n}\n\nfunction trimIfOverCap(path: string): void {\n    try {\n        const raw = readFileSync(path, 'utf-8');\n        const lines = raw.split(/\\r?\\n/);\n        // Find the entries (lines starting with \"- [\")\n        const entryIdx: number[] = [];\n        for (let i = 0; i < lines.length; i++) {\n            if (lines[i].startsWith('- [')) entryIdx.push(i);\n        }\n        if (entryIdx.length <= LESSONS_PER_AGENT_CAP) return;\n        // Drop the oldest (LESSONS_PER_AGENT_CAP / 4) when we tip over.\n        const dropCount = Math.max(1, Math.floor(LESSONS_PER_AGENT_CAP / 4));\n        const cutAt = entryIdx[dropCount] ?? entryIdx[0];\n        // Header ends at first \"---\" line.\n        const headerEnd = lines.findIndex(l => l.trim() === '---');\n        const header = headerEnd >= 0 ? lines.slice(0, headerEnd + 2).join('\\n') : '';\n        const kept = lines.slice(cutAt).join('\\n');\n        writeFileSync(path, header + '\\n' + kept, 'utf-8');\n        logger.info(COMPONENT, `Trimmed ${dropCount} oldest lessons from ${path}`);\n    } catch { /* best-effort */ }\n}\n\n/**\n * Render the most relevant lessons for `agentId` as a prompt-ready block.\n * If `topic` is supplied, lessons matching that topic float to the top.\n * Returns empty string when there are no lessons yet (don't add a\n * prompt section with no content).\n */\nexport function renderAgentLessonsForPrompt(agentId: string, topic?: string): string {\n    if (!agentId) return '';\n    const path = lessonsPath(agentId);\n    if (!existsSync(path)) return '';\n    try {\n        const raw = readFileSync(path, 'utf-8');\n        const lines = raw.split(/\\r?\\n/);\n        // Parse structured entries: kind + topic + text.\n        const entries: Array<{ kind: string; topic: string; text: string; ts: string }> = [];\n        for (const l of lines) {\n            const m = l.match(/^- \\[([^\\]]+)\\]\\s+\\*\\*(fail|win)\\*\\*(?:\\s+topic=\"([^\"]+)\")?(?:[^—]*)—\\s+(.+)$/);\n            if (m) entries.push({ ts: m[1], kind: m[2], topic: m[3] || '', text: m[4] });\n        }\n        if (entries.length === 0) return '';\n\n        // Sort: most recent first, with topic match boost.\n        const wantsTopic = (topic || '').toLowerCase();\n        const scored = entries.map(e => ({\n            e,\n            score: (wantsTopic && e.topic.toLowerCase() === wantsTopic ? 1 : 0)\n                 + (wantsTopic && e.topic.toLowerCase().includes(wantsTopic) ? 0.5 : 0),\n        }));\n        scored.sort((a, b) => b.score - a.score || b.e.ts.localeCompare(a.e.ts));\n\n        const top = scored.slice(0, PROMPT_RENDER_CAP).map(s => s.e);\n        if (top.length === 0) return '';\n\n        const out: string[] = [`## Lessons you've learned (top ${top.length})`];\n        for (const e of top) {\n            const tag = e.topic ? ` *(${e.topic})*` : '';\n            out.push(`- **${e.kind}**${tag} — ${e.text}`);\n        }\n        return out.join('\\n');\n    } catch {\n        return '';\n    }\n}\n\n/** Convenience helper — read raw lessons.md content (used by tests + UI). */\nexport function readLessonsMarkdown(agentId: string): string {\n    const path = lessonsPath(agentId);\n    return existsSync(path) ? readFileSync(path, 'utf-8') : '';\n}\n\n/** Test helper — wipe an agent's lessons file. */\nexport function __resetLessonsForTests(agentId: string): void {\n    const path = lessonsPath(agentId);\n    if (existsSync(path)) {\n        try { unlinkSync(path); } catch { /* fine */ }\n    }\n}\n"],"mappings":"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","names":[]}

package/dist/agent/autoModeClassifier.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import { getToolContract } from "./toolContract.js";
+import { loadConfig } from "../config/config.js";
+import logger from "../utils/logger.js";
+const COMPONENT = "autoMode";
+function getAutoModePolicy() {
+  const envPolicy = process.env.TITAN_AUTOMODE_POLICY;
+  if (envPolicy === "paranoid" || envPolicy === "permissive" || envPolicy === "yolo" || envPolicy === "standard") {
+    return envPolicy;
+  }
+  try {
+    const cfg = loadConfig();
+    const sec = cfg.security;
+    const am = sec?.autoMode;
+    const policy = am?.policy;
+    if (policy === "paranoid" || policy === "permissive" || policy === "yolo" || policy === "standard") {
+      return policy;
+    }
+  } catch {
+  }
+  return "standard";
+}
+function classifyToolCall(toolName) {
+  const policy = getAutoModePolicy();
+  const contract = getToolContract(toolName);
+  const riskLevel = contract?.riskLevel;
+  if (policy === "yolo") {
+    warnYoloOnce();
+    return {
+      decision: "auto",
+      reason: "yolo policy \u2014 gating disabled",
+      policy,
+      riskLevel
+    };
+  }
+  if (policy === "paranoid") {
+    return {
+      decision: "gate",
+      reason: "paranoid policy \u2014 every tool call requires approval",
+      policy,
+      riskLevel
+    };
+  }
+  if (!contract) {
+    return {
+      decision: "gate",
+      reason: `no contract registered for "${toolName}" \u2014 gating by default`,
+      policy
+    };
+  }
+  if (riskLevel === "safe") {
+    return { decision: "auto", reason: "contract riskLevel=safe", policy, riskLevel };
+  }
+  if (riskLevel === "moderate") {
+    if (policy === "permissive") {
+      return { decision: "auto", reason: "permissive policy \u2014 moderate risk auto-runs", policy, riskLevel };
+    }
+    return { decision: "notify", reason: "contract riskLevel=moderate", policy, riskLevel };
+  }
+  if (riskLevel === "high") {
+    return { decision: "gate", reason: "contract riskLevel=high", policy, riskLevel };
+  }
+  return {
+    decision: "gate",
+    reason: `unrecognised riskLevel "${riskLevel}" \u2014 gating defensively`,
+    policy,
+    riskLevel
+  };
+}
+let _yoloWarned = false;
+function warnYoloOnce() {
+  if (_yoloWarned) return;
+  _yoloWarned = true;
+  logger.warn(
+    COMPONENT,
+    "AUTO_MODE=yolo \u2014 every tool call will run without approval. This mode is ONLY intended for sandboxed eval runs. If you see this in production logs, something is misconfigured."
+  );
+}
+function _resetYoloWarning() {
+  _yoloWarned = false;
+}
+function shouldGate(result) {
+  return result.decision === "gate";
+}
+function formatBreadcrumb(toolName, result) {
+  return `automode:${result.decision} tool=${toolName} risk=${result.riskLevel ?? "unknown"} policy=${result.policy} (${result.reason})`;
+}
+export {
+  _resetYoloWarning,
+  classifyToolCall,
+  formatBreadcrumb,
+  getAutoModePolicy,
+  shouldGate
+};
+//# sourceMappingURL=autoModeClassifier.js.map

package/dist/agent/autoModeClassifier.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/agent/autoModeClassifier.ts"],"sourcesContent":["/**\n * TITAN — Auto-Mode Classifier (v6.1.0-beta.16, Phase D.4)\n *\n * Reads the tool contract registry to decide whether an incoming\n * tool call can run autonomously, deserves a passive notification,\n * or requires explicit human approval. Pattern from Anthropic's\n * \"Claude Code auto-mode\" blog (in the Picrew/awesome-agent-harness\n * featured-reading list): classifier-backed approval delegation\n * gives the agent autonomy on safe paths while keeping a kill\n * switch on the risky ones.\n *\n * THREE DECISIONS:\n *\n *   - 'auto'    — run without prompting. Read-only ops + workspace\n *                 writes. Most missions run mostly 'auto' calls.\n *   - 'notify'  — run, but record a passive notification so a\n *                 watcher (Mission Canvas, log tail) can see it\n *                 happened. Default for network calls.\n *   - 'gate'    — require explicit human approval before running.\n *                 Default for destructive ops (shell, delete, etc.)\n *                 AND for any tool without a registered contract\n *                 (unknown → conservative).\n *\n * POLICY OVERRIDES (config.security.autoMode.policy):\n *\n *   - 'standard'  (default) — riskLevel drives the decision per\n *                             the table above.\n *   - 'paranoid'             — every tool call is 'gate'. For\n *                             demos, regulated environments, or\n *                             when Tony is debugging a misbehaving\n *                             agent.\n *   - 'permissive'           — riskLevel 'moderate' is auto-run\n *                             (still 'gate' on 'high'). For\n *                             trusted hot loops where ping-the-user\n *                             on every web_search is annoying.\n *   - 'yolo'                 — everything auto, including 'high'.\n *                             ONLY for sandboxed eval runs. Logs\n *                             a loud warning on init.\n *\n * WHY this module exists:\n *\n *   - Phase D.3 added riskLevel + sideEffects metadata to the 9\n *     canonical contracts. D.4 makes the metadata actually do\n *     something — gating decisions, not just labels.\n *\n *   - The existing approval-gate path in toolRunner uses a hardcoded\n *     \"is this tool name dangerous?\" list. That's a string-match\n *     allowlist that doesn't scale and doesn't account for HOW the\n *     tool is being used. The classifier is the structural answer:\n *     contracts declare risk; the classifier reads contracts.\n *\n *   - Decoupling the policy from the runner means changing the\n *     gating semantics (e.g. add a new 'risky-during-business-hours'\n *     decision) is a one-file change — never a wholesale runner\n *     refactor.\n *\n * TRADE-OFFS:\n *\n *   - First cut keys decisions on contract.riskLevel alone. A\n *     follow-up could consider call ARGS (e.g. shell with\n *     `command: 'ls'` could be 'auto' while shell with\n *     `command: 'rm -rf'` is still 'gate'). Skipped for now to\n *     keep the surface small + predictable.\n *\n *   - Tools without a registered contract default to 'gate'. This\n *     is conservative but means the long-tail 239 skills will hit\n *     the approval gate on every call until their contracts ship.\n *     If that becomes painful, lift the default to 'notify' via\n *     the `unknownToolDefault` config field.\n *\n * FOLLOW-UP:\n *\n *   - Phase D.5 reads sideEffects==='destructive' to route the\n *     call into a worktree-isolated executor.\n *   - Args-aware classification (shell `rm -rf` vs shell `ls`).\n *   - Per-session policy override so a \"draft a quick email\"\n *     mission can opt into 'permissive' while a \"review and merge\n *     this PR\" mission stays on 'paranoid'.\n */\n\nimport { getToolContract, type RiskLevel } from './toolContract.js';\nimport { loadConfig } from '../config/config.js';\nimport logger from '../utils/logger.js';\n\nconst COMPONENT = 'autoMode';\n\n/* ──────────────────────────  Types  ────────────────────────── */\n\nexport type AutoModeDecision = 'auto' | 'notify' | 'gate';\nexport type AutoModePolicy = 'standard' | 'paranoid' | 'permissive' | 'yolo';\n\nexport interface ClassificationResult {\n    /** What the runner should do with the call. */\n    decision: AutoModeDecision;\n    /** Plain-english reason — logged and surfaced in the trajectory. */\n    reason: string;\n    /** Policy that produced this decision (drives observability). */\n    policy: AutoModePolicy;\n    /** Risk level from the contract, if any. Undefined for unknown tools. */\n    riskLevel?: RiskLevel;\n}\n\n/* ──────────────────────────  Policy loader  ────────────────────────── */\n\n/**\n * Resolve the current auto-mode policy. Reads\n * `config.security.autoMode.policy` if present; defaults to 'standard'.\n * Pure synchronous lookup — no IO, safe to call per-tool-call.\n */\nexport function getAutoModePolicy(): AutoModePolicy {\n    // beta.21 — env override. Lets the test suite (and any embedder\n    // that wants a process-wide policy without touching config files)\n    // short-circuit the classifier without mutating loaded config.\n    // Production callers should configure via `config.security.autoMode.policy`\n    // — this env hook is opt-in and silent when unset.\n    const envPolicy = process.env.TITAN_AUTOMODE_POLICY;\n    if (envPolicy === 'paranoid' || envPolicy === 'permissive' || envPolicy === 'yolo' || envPolicy === 'standard') {\n        return envPolicy;\n    }\n    try {\n        const cfg = loadConfig();\n        const sec = (cfg as Record<string, unknown>).security as Record<string, unknown> | undefined;\n        const am = sec?.autoMode as Record<string, unknown> | undefined;\n        const policy = am?.policy as string | undefined;\n        if (policy === 'paranoid' || policy === 'permissive' || policy === 'yolo' || policy === 'standard') {\n            return policy;\n        }\n    } catch { /* config unavailable — fall through */ }\n    return 'standard';\n}\n\n/* ──────────────────────────  Classifier  ────────────────────────── */\n\n/**\n * Decide whether a tool call should run automatically, with a\n * notification, or with explicit approval. The runner uses this to\n * decide whether to short-circuit the existing approval-gate path.\n *\n * Pure: no IO beyond reading the config + contract registry. Cheap\n * enough to call on every tool call without measuring.\n */\nexport function classifyToolCall(toolName: string): ClassificationResult {\n    const policy = getAutoModePolicy();\n    const contract = getToolContract(toolName);\n    const riskLevel = contract?.riskLevel;\n\n    // yolo short-circuit: regardless of risk, run. ONLY for sandboxed\n    // eval runs — logs a loud warning the first time per process.\n    if (policy === 'yolo') {\n        warnYoloOnce();\n        return {\n            decision: 'auto',\n            reason: 'yolo policy — gating disabled',\n            policy,\n            riskLevel,\n        };\n    }\n\n    // paranoid short-circuit: every call gated.\n    if (policy === 'paranoid') {\n        return {\n            decision: 'gate',\n            reason: 'paranoid policy — every tool call requires approval',\n            policy,\n            riskLevel,\n        };\n    }\n\n    // Unknown tool (no registered contract) → conservative 'gate'.\n    // The long-tail 239 skills without contracts hit this branch\n    // until their contracts ship. Override via config if the prompt\n    // pings become annoying.\n    if (!contract) {\n        return {\n            decision: 'gate',\n            reason: `no contract registered for \"${toolName}\" — gating by default`,\n            policy,\n        };\n    }\n\n    // Standard + permissive paths read riskLevel.\n    if (riskLevel === 'safe') {\n        return { decision: 'auto', reason: 'contract riskLevel=safe', policy, riskLevel };\n    }\n    if (riskLevel === 'moderate') {\n        if (policy === 'permissive') {\n            return { decision: 'auto', reason: 'permissive policy — moderate risk auto-runs', policy, riskLevel };\n        }\n        return { decision: 'notify', reason: 'contract riskLevel=moderate', policy, riskLevel };\n    }\n    if (riskLevel === 'high') {\n        return { decision: 'gate', reason: 'contract riskLevel=high', policy, riskLevel };\n    }\n\n    // Defensive fallback for an unknown future riskLevel value.\n    return {\n        decision: 'gate',\n        reason: `unrecognised riskLevel \"${riskLevel}\" — gating defensively`,\n        policy,\n        riskLevel,\n    };\n}\n\n/* ──────────────────────────  Helpers  ────────────────────────── */\n\nlet _yoloWarned = false;\nfunction warnYoloOnce(): void {\n    if (_yoloWarned) return;\n    _yoloWarned = true;\n    logger.warn(\n        COMPONENT,\n        'AUTO_MODE=yolo — every tool call will run without approval. This mode is ONLY intended for sandboxed eval runs. If you see this in production logs, something is misconfigured.',\n    );\n}\n\n/** For tests. */\nexport function _resetYoloWarning(): void {\n    _yoloWarned = false;\n}\n\n/**\n * Convenience: returns true iff the decision means the call should\n * NOT proceed without explicit human approval. Used by the runner\n * to short-circuit the existing approval-gate path on 'auto' /\n * 'notify' decisions.\n */\nexport function shouldGate(result: ClassificationResult): boolean {\n    return result.decision === 'gate';\n}\n\n/**\n * Format the classification as a one-line breadcrumb suitable for\n * the trajectory `note` event. Used by the runner on 'notify'\n * decisions so the trajectory captures what the agent did\n * autonomously vs what required a human prompt.\n */\nexport function formatBreadcrumb(toolName: string, result: ClassificationResult): string {\n    return `automode:${result.decision} tool=${toolName} risk=${result.riskLevel ?? 'unknown'} policy=${result.policy} (${result.reason})`;\n}\n"],"mappings":";AAgFA,SAAS,uBAAuC;AAChD,SAAS,kBAAkB;AAC3B,OAAO,YAAY;AAEnB,MAAM,YAAY;AAyBX,SAAS,oBAAoC;AAMhD,QAAM,YAAY,QAAQ,IAAI;AAC9B,MAAI,cAAc,cAAc,cAAc,gBAAgB,cAAc,UAAU,cAAc,YAAY;AAC5G,WAAO;AAAA,EACX;AACA,MAAI;AACA,UAAM,MAAM,WAAW;AACvB,UAAM,MAAO,IAAgC;AAC7C,UAAM,KAAK,KAAK;AAChB,UAAM,SAAS,IAAI;AACnB,QAAI,WAAW,cAAc,WAAW,gBAAgB,WAAW,UAAU,WAAW,YAAY;AAChG,aAAO;AAAA,IACX;AAAA,EACJ,QAAQ;AAAA,EAA0C;AAClD,SAAO;AACX;AAYO,SAAS,iBAAiB,UAAwC;AACrE,QAAM,SAAS,kBAAkB;AACjC,QAAM,WAAW,gBAAgB,QAAQ;AACzC,QAAM,YAAY,UAAU;AAI5B,MAAI,WAAW,QAAQ;AACnB,iBAAa;AACb,WAAO;AAAA,MACH,UAAU;AAAA,MACV,QAAQ;AAAA,MACR;AAAA,MACA;AAAA,IACJ;AAAA,EACJ;AAGA,MAAI,WAAW,YAAY;AACvB,WAAO;AAAA,MACH,UAAU;AAAA,MACV,QAAQ;AAAA,MACR;AAAA,MACA;AAAA,IACJ;AAAA,EACJ;AAMA,MAAI,CAAC,UAAU;AACX,WAAO;AAAA,MACH,UAAU;AAAA,MACV,QAAQ,+BAA+B,QAAQ;AAAA,MAC/C;AAAA,IACJ;AAAA,EACJ;AAGA,MAAI,cAAc,QAAQ;AACtB,WAAO,EAAE,UAAU,QAAQ,QAAQ,2BAA2B,QAAQ,UAAU;AAAA,EACpF;AACA,MAAI,cAAc,YAAY;AAC1B,QAAI,WAAW,cAAc;AACzB,aAAO,EAAE,UAAU,QAAQ,QAAQ,oDAA+C,QAAQ,UAAU;AAAA,IACxG;AACA,WAAO,EAAE,UAAU,UAAU,QAAQ,+BAA+B,QAAQ,UAAU;AAAA,EAC1F;AACA,MAAI,cAAc,QAAQ;AACtB,WAAO,EAAE,UAAU,QAAQ,QAAQ,2BAA2B,QAAQ,UAAU;AAAA,EACpF;AAGA,SAAO;AAAA,IACH,UAAU;AAAA,IACV,QAAQ,2BAA2B,SAAS;AAAA,IAC5C;AAAA,IACA;AAAA,EACJ;AACJ;AAIA,IAAI,cAAc;AAClB,SAAS,eAAqB;AAC1B,MAAI,YAAa;AACjB,gBAAc;AACd,SAAO;AAAA,IACH;AAAA,IACA;AAAA,EACJ;AACJ;AAGO,SAAS,oBAA0B;AACtC,gBAAc;AAClB;AAQO,SAAS,WAAW,QAAuC;AAC9D,SAAO,OAAO,aAAa;AAC/B;AAQO,SAAS,iBAAiB,UAAkB,QAAsC;AACrF,SAAO,YAAY,OAAO,QAAQ,SAAS,QAAQ,SAAS,OAAO,aAAa,SAAS,WAAW,OAAO,MAAM,KAAK,OAAO,MAAM;AACvI;","names":[]}

package/dist/agent/durableJournal.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync, appendFileSync, mkdirSync } from "fs";
+import { existsSync, readFileSync, appendFileSync, mkdirSync, unlinkSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
 import logger from "../utils/logger.js";
@@ -125,7 +125,7 @@ function __resetJournalForTests(scope, id) {
   const path = shardPath(scope, id);
   if (existsSync(path)) {
     try {
-      require("fs").unlinkSync(path);
+      unlinkSync(path);
     } catch {
     }
   }

package/dist/agent/durableJournal.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/agent/durableJournal.ts"],"sourcesContent":["/**\n * TITAN — Durable per-context event journal (Temporal-style replay).\n *\n * Why this exists\n * ---------------\n * Per awesome-agent-harness pattern #4 + Anthropic's \"Effective harnesses\n * for long-running agents\":\n *\n *   \"Build systems that can resume from where the agent was when the errors\n *    occurred… deterministic safeguards like retry logic and regular\n *    checkpoints.\"\n *\n * TITAN's pre-existing activity-log.jsonl is GLOBAL — every event from\n * every agent in one stream. Useful for the activity feed, useless for\n * crash-replay because you can't isolate \"what was THIS agent doing on\n * THIS goal.\" This module adds per-context shards:\n *\n *   `~/.titan/journals/goals/<goalId>.jsonl`     — per-goal event log\n *   `~/.titan/journals/agents/<agentId>.jsonl`   — per-agent event log\n *   `~/.titan/journals/sessions/<sessionId>.jsonl` — per-session event log\n *\n * Each line is one `{at, kind, payload}` event. Append-only — the file\n * is the source of truth, the in-memory state is derived. A fresh\n * process can call `replayGoal(goalId)` and reconstruct what the\n * previous agent was doing without losing work.\n *\n * Critically, this is NOT a replacement for the activity feed — that\n * stays as the UI-facing global stream. The journals are the AGENT's\n * own memory of its work.\n *\n * Reference:\n *   - Picrew/awesome-agent-harness pattern #4 (Durable event journal)\n *   - Anthropic \"Effective harnesses for long-running agents\"\n *   - Temporal Continue-As-New pattern\n *   - HumanLayer 12-factor agents §8 (Own Your Control Flow) + §12 (Stateless Reducer)\n */\nimport { existsSync, readFileSync, appendFileSync, mkdirSync } from 'fs';\nimport { join } from 'path';\nimport { homedir } from 'os';\nimport logger from '../utils/logger.js';\n\nconst COMPONENT = 'DurableJournal';\n\nfunction titanHome(): string {\n    const env = process.env.TITAN_HOME;\n    if (env) return env.startsWith('~/') ? join(homedir(), env.slice(2)) : env;\n    return join(homedir(), '.titan');\n}\nfunction shardDir(scope: 'goals' | 'agents' | 'sessions'): string {\n    return join(titanHome(), 'journals', scope);\n}\nfunction shardPath(scope: 'goals' | 'agents' | 'sessions', id: string): string {\n    return join(shardDir(scope), `${sanitizeId(id)}.jsonl`);\n}\nfunction sanitizeId(id: string): string {\n    // Belt + braces — never let an id traverse the filesystem.\n    // 1. Replace any char outside the safe alphabet with `_`.\n    // 2. Collapse any run of two or more dots (traversal segments) into `_`.\n    const cleaned = id.replace(/[^a-zA-Z0-9_.-]/g, '_').replace(/\\.{2,}/g, '_');\n    return cleaned.slice(0, 120) || '_';\n}\n\n/** The vocabulary of journal events. Add new kinds here as the agent\n *  loop grows. Keep them short, verb-past-tense, and grep-friendly. */\nexport type JournalEventKind =\n    | 'task_started'         // agent picked up a task\n    | 'task_completed'       // agent finished cleanly\n    | 'task_failed'          // agent reported failure\n    | 'task_abandoned'       // lease expired / different agent adopted\n    | 'tool_called'          // agent called a tool\n    | 'tool_result'          // tool returned (success or error)\n    | 'subagent_spawned'     // agent invoked a sub-agent\n    | 'subagent_returned'    // sub-agent reported back\n    | 'lesson_recorded'      // a Reflexion lesson was logged\n    | 'budget_warning'       // policy crossed warning threshold\n    | 'budget_breached'      // policy crossed limit\n    | 'checkpoint_saved'     // round-state snapshot persisted\n    | 'plan_step_updated'    // goal plan.md step changed status\n    | 'user_input'           // user sent a chat message\n    | 'agent_response';      // agent emitted final response text\n\n/** Single journal line — minimal, JSON-serialisable. */\nexport interface JournalEvent<P = Record<string, unknown>> {\n    at: string;              // ISO-8601 timestamp\n    kind: JournalEventKind;\n    payload: P;\n}\n\n/** Scope a single append can target. */\nexport interface JournalScope {\n    goalId?: string;\n    agentId?: string;\n    sessionId?: string;\n}\n\n/**\n * Append one event to every scope it applies to. Safe to call with all\n * three scopes set — the event is recorded in each shard. Idempotent on\n * write failures (best-effort, never throws). The single write per shard\n * is O(1) — one open / append / close, no read-modify-write cycle.\n */\nexport function recordJournalEvent<P extends Record<string, unknown>>(\n    scope: JournalScope,\n    kind: JournalEventKind,\n    payload: P = {} as P,\n): void {\n    if (!scope.goalId && !scope.agentId && !scope.sessionId) return;\n    const evt: JournalEvent<P> = {\n        at: new Date().toISOString(),\n        kind,\n        payload,\n    };\n    const line = JSON.stringify(evt) + '\\n';\n\n    const writeShard = (path: string) => {\n        try {\n            mkdirSync(join(path, '..'), { recursive: true });\n            appendFileSync(path, line, 'utf-8');\n        } catch (err) {\n            // Never let a journal write break the agent loop.\n            logger.warn(COMPONENT, `journal append failed: ${(err as Error).message}`);\n        }\n    };\n\n    if (scope.goalId)    writeShard(shardPath('goals', scope.goalId));\n    if (scope.agentId)   writeShard(shardPath('agents', scope.agentId));\n    if (scope.sessionId) writeShard(shardPath('sessions', scope.sessionId));\n}\n\n/** Read all events for a scope, in order. Returns [] when no journal exists. */\nexport function readJournal(scope: 'goals' | 'agents' | 'sessions', id: string): JournalEvent[] {\n    const path = shardPath(scope, id);\n    if (!existsSync(path)) return [];\n    try {\n        const raw = readFileSync(path, 'utf-8');\n        const lines = raw.split('\\n').filter(l => l.trim().length > 0);\n        const events: JournalEvent[] = [];\n        for (const l of lines) {\n            try { events.push(JSON.parse(l) as JournalEvent); }\n            catch { /* skip malformed line — never abort the whole replay */ }\n        }\n        return events;\n    } catch (err) {\n        logger.warn(COMPONENT, `journal read failed for ${scope}/${id}: ${(err as Error).message}`);\n        return [];\n    }\n}\n\n// ─── Replay primitives ─────────────────────────────────────────────\n\n/**\n * The state we derive from replaying a goal's journal. Intentionally\n * minimal — just the fields a resuming process needs to decide what to\n * do next. The agent runtime can stuff more derived fields into this\n * shape later; this is the floor.\n */\nexport interface GoalReplayState {\n    goalId: string;\n    /** True once a task_completed event has been seen for this goal. */\n    completed: boolean;\n    /** True if task_failed appears with no later task_started. */\n    failed: boolean;\n    /** Most-recent agent that picked up the goal. */\n    currentAgentId: string | null;\n    /** Tool calls observed (count). Used as a coarse progress signal. */\n    toolCallCount: number;\n    /** Sub-agents spawned (count). */\n    subAgentCount: number;\n    /** Most-recent plan-step status updates, keyed by stepId. */\n    stepStatus: Record<string, string>;\n    /** Lessons recorded during this goal (text only — full lesson lives\n     *  in agentLessons.ts). Lets a resuming agent see what it learned. */\n    lessonsRecorded: string[];\n    /** Last event timestamp — useful for staleness detection. */\n    lastEventAt: string | null;\n    /** Total event count (for telemetry). */\n    eventCount: number;\n}\n\n/** Pure reduction — apply one event to a state snapshot. Exported so the\n *  wakeup reducer (upgrade #5) can use the same fold. */\nexport function applyEventToGoalState(state: GoalReplayState, evt: JournalEvent): GoalReplayState {\n    const next: GoalReplayState = {\n        ...state,\n        stepStatus: { ...state.stepStatus },\n        lessonsRecorded: [...state.lessonsRecorded],\n        lastEventAt: evt.at,\n        eventCount: state.eventCount + 1,\n    };\n\n    switch (evt.kind) {\n        case 'task_started': {\n            const aid = (evt.payload as { agentId?: string }).agentId;\n            if (typeof aid === 'string' && aid) next.currentAgentId = aid;\n            next.failed = false;\n            break;\n        }\n        case 'task_completed':\n            next.completed = true;\n            next.failed = false;\n            break;\n        case 'task_failed':\n            next.failed = true;\n            break;\n        case 'task_abandoned':\n            next.currentAgentId = null;\n            break;\n        case 'tool_called':\n            next.toolCallCount = state.toolCallCount + 1;\n            break;\n        case 'subagent_spawned':\n            next.subAgentCount = state.subAgentCount + 1;\n            break;\n        case 'lesson_recorded': {\n            const text = (evt.payload as { text?: string }).text;\n            if (typeof text === 'string' && text) next.lessonsRecorded.push(text);\n            break;\n        }\n        case 'plan_step_updated': {\n            const sid = (evt.payload as { stepId?: string }).stepId;\n            const st = (evt.payload as { status?: string }).status;\n            if (typeof sid === 'string' && typeof st === 'string') next.stepStatus[sid] = st;\n            break;\n        }\n        default:\n            // tool_result, checkpoint_saved, budget_*, user_input, agent_response —\n            // currently no state derivation; just tick eventCount.\n            break;\n    }\n    return next;\n}\n\n/**\n * Replay a goal's journal into a derived state snapshot. O(n) in events.\n * A fresh process calls this on resume to know what's been done already.\n */\nexport function replayGoal(goalId: string): GoalReplayState {\n    const events = readJournal('goals', goalId);\n    const seed: GoalReplayState = {\n        goalId,\n        completed: false,\n        failed: false,\n        currentAgentId: null,\n        toolCallCount: 0,\n        subAgentCount: 0,\n        stepStatus: {},\n        lessonsRecorded: [],\n        lastEventAt: null,\n        eventCount: 0,\n    };\n    return events.reduce(applyEventToGoalState, seed);\n}\n\n/** Test helper — wipe a scope's journal. */\nexport function __resetJournalForTests(scope: 'goals' | 'agents' | 'sessions', id: string): void {\n    const path = shardPath(scope, id);\n    if (existsSync(path)) {\n        try { require('fs').unlinkSync(path); } catch { /* fine */ }\n    }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/agent/durableJournal.ts"],"sourcesContent":["/**\n * TITAN — Durable per-context event journal (Temporal-style replay).\n *\n * Why this exists\n * ---------------\n * Per awesome-agent-harness pattern #4 + Anthropic's \"Effective harnesses\n * for long-running agents\":\n *\n *   \"Build systems that can resume from where the agent was when the errors\n *    occurred… deterministic safeguards like retry logic and regular\n *    checkpoints.\"\n *\n * TITAN's pre-existing activity-log.jsonl is GLOBAL — every event from\n * every agent in one stream. Useful for the activity feed, useless for\n * crash-replay because you can't isolate \"what was THIS agent doing on\n * THIS goal.\" This module adds per-context shards:\n *\n *   `~/.titan/journals/goals/<goalId>.jsonl`     — per-goal event log\n *   `~/.titan/journals/agents/<agentId>.jsonl`   — per-agent event log\n *   `~/.titan/journals/sessions/<sessionId>.jsonl` — per-session event log\n *\n * Each line is one `{at, kind, payload}` event. Append-only — the file\n * is the source of truth, the in-memory state is derived. A fresh\n * process can call `replayGoal(goalId)` and reconstruct what the\n * previous agent was doing without losing work.\n *\n * Critically, this is NOT a replacement for the activity feed — that\n * stays as the UI-facing global stream. The journals are the AGENT's\n * own memory of its work.\n *\n * Reference:\n *   - Picrew/awesome-agent-harness pattern #4 (Durable event journal)\n *   - Anthropic \"Effective harnesses for long-running agents\"\n *   - Temporal Continue-As-New pattern\n *   - HumanLayer 12-factor agents §8 (Own Your Control Flow) + §12 (Stateless Reducer)\n */\nimport { existsSync, readFileSync, appendFileSync, mkdirSync, unlinkSync } from 'fs';\nimport { join } from 'path';\nimport { homedir } from 'os';\nimport logger from '../utils/logger.js';\n\nconst COMPONENT = 'DurableJournal';\n\nfunction titanHome(): string {\n    const env = process.env.TITAN_HOME;\n    if (env) return env.startsWith('~/') ? join(homedir(), env.slice(2)) : env;\n    return join(homedir(), '.titan');\n}\nfunction shardDir(scope: 'goals' | 'agents' | 'sessions'): string {\n    return join(titanHome(), 'journals', scope);\n}\nfunction shardPath(scope: 'goals' | 'agents' | 'sessions', id: string): string {\n    return join(shardDir(scope), `${sanitizeId(id)}.jsonl`);\n}\nfunction sanitizeId(id: string): string {\n    // Belt + braces — never let an id traverse the filesystem.\n    // 1. Replace any char outside the safe alphabet with `_`.\n    // 2. Collapse any run of two or more dots (traversal segments) into `_`.\n    const cleaned = id.replace(/[^a-zA-Z0-9_.-]/g, '_').replace(/\\.{2,}/g, '_');\n    return cleaned.slice(0, 120) || '_';\n}\n\n/** The vocabulary of journal events. Add new kinds here as the agent\n *  loop grows. Keep them short, verb-past-tense, and grep-friendly. */\nexport type JournalEventKind =\n    | 'task_started'         // agent picked up a task\n    | 'task_completed'       // agent finished cleanly\n    | 'task_failed'          // agent reported failure\n    | 'task_abandoned'       // lease expired / different agent adopted\n    | 'tool_called'          // agent called a tool\n    | 'tool_result'          // tool returned (success or error)\n    | 'subagent_spawned'     // agent invoked a sub-agent\n    | 'subagent_returned'    // sub-agent reported back\n    | 'lesson_recorded'      // a Reflexion lesson was logged\n    | 'budget_warning'       // policy crossed warning threshold\n    | 'budget_breached'      // policy crossed limit\n    | 'checkpoint_saved'     // round-state snapshot persisted\n    | 'plan_step_updated'    // goal plan.md step changed status\n    | 'user_input'           // user sent a chat message\n    | 'agent_response';      // agent emitted final response text\n\n/** Single journal line — minimal, JSON-serialisable. */\nexport interface JournalEvent<P = Record<string, unknown>> {\n    at: string;              // ISO-8601 timestamp\n    kind: JournalEventKind;\n    payload: P;\n}\n\n/** Scope a single append can target. */\nexport interface JournalScope {\n    goalId?: string;\n    agentId?: string;\n    sessionId?: string;\n}\n\n/**\n * Append one event to every scope it applies to. Safe to call with all\n * three scopes set — the event is recorded in each shard. Idempotent on\n * write failures (best-effort, never throws). The single write per shard\n * is O(1) — one open / append / close, no read-modify-write cycle.\n */\nexport function recordJournalEvent<P extends Record<string, unknown>>(\n    scope: JournalScope,\n    kind: JournalEventKind,\n    payload: P = {} as P,\n): void {\n    if (!scope.goalId && !scope.agentId && !scope.sessionId) return;\n    const evt: JournalEvent<P> = {\n        at: new Date().toISOString(),\n        kind,\n        payload,\n    };\n    const line = JSON.stringify(evt) + '\\n';\n\n    const writeShard = (path: string) => {\n        try {\n            mkdirSync(join(path, '..'), { recursive: true });\n            appendFileSync(path, line, 'utf-8');\n        } catch (err) {\n            // Never let a journal write break the agent loop.\n            logger.warn(COMPONENT, `journal append failed: ${(err as Error).message}`);\n        }\n    };\n\n    if (scope.goalId)    writeShard(shardPath('goals', scope.goalId));\n    if (scope.agentId)   writeShard(shardPath('agents', scope.agentId));\n    if (scope.sessionId) writeShard(shardPath('sessions', scope.sessionId));\n}\n\n/** Read all events for a scope, in order. Returns [] when no journal exists. */\nexport function readJournal(scope: 'goals' | 'agents' | 'sessions', id: string): JournalEvent[] {\n    const path = shardPath(scope, id);\n    if (!existsSync(path)) return [];\n    try {\n        const raw = readFileSync(path, 'utf-8');\n        const lines = raw.split('\\n').filter(l => l.trim().length > 0);\n        const events: JournalEvent[] = [];\n        for (const l of lines) {\n            try { events.push(JSON.parse(l) as JournalEvent); }\n            catch { /* skip malformed line — never abort the whole replay */ }\n        }\n        return events;\n    } catch (err) {\n        logger.warn(COMPONENT, `journal read failed for ${scope}/${id}: ${(err as Error).message}`);\n        return [];\n    }\n}\n\n// ─── Replay primitives ─────────────────────────────────────────────\n\n/**\n * The state we derive from replaying a goal's journal. Intentionally\n * minimal — just the fields a resuming process needs to decide what to\n * do next. The agent runtime can stuff more derived fields into this\n * shape later; this is the floor.\n */\nexport interface GoalReplayState {\n    goalId: string;\n    /** True once a task_completed event has been seen for this goal. */\n    completed: boolean;\n    /** True if task_failed appears with no later task_started. */\n    failed: boolean;\n    /** Most-recent agent that picked up the goal. */\n    currentAgentId: string | null;\n    /** Tool calls observed (count). Used as a coarse progress signal. */\n    toolCallCount: number;\n    /** Sub-agents spawned (count). */\n    subAgentCount: number;\n    /** Most-recent plan-step status updates, keyed by stepId. */\n    stepStatus: Record<string, string>;\n    /** Lessons recorded during this goal (text only — full lesson lives\n     *  in agentLessons.ts). Lets a resuming agent see what it learned. */\n    lessonsRecorded: string[];\n    /** Last event timestamp — useful for staleness detection. */\n    lastEventAt: string | null;\n    /** Total event count (for telemetry). */\n    eventCount: number;\n}\n\n/** Pure reduction — apply one event to a state snapshot. Exported so the\n *  wakeup reducer (upgrade #5) can use the same fold. */\nexport function applyEventToGoalState(state: GoalReplayState, evt: JournalEvent): GoalReplayState {\n    const next: GoalReplayState = {\n        ...state,\n        stepStatus: { ...state.stepStatus },\n        lessonsRecorded: [...state.lessonsRecorded],\n        lastEventAt: evt.at,\n        eventCount: state.eventCount + 1,\n    };\n\n    switch (evt.kind) {\n        case 'task_started': {\n            const aid = (evt.payload as { agentId?: string }).agentId;\n            if (typeof aid === 'string' && aid) next.currentAgentId = aid;\n            next.failed = false;\n            break;\n        }\n        case 'task_completed':\n            next.completed = true;\n            next.failed = false;\n            break;\n        case 'task_failed':\n            next.failed = true;\n            break;\n        case 'task_abandoned':\n            next.currentAgentId = null;\n            break;\n        case 'tool_called':\n            next.toolCallCount = state.toolCallCount + 1;\n            break;\n        case 'subagent_spawned':\n            next.subAgentCount = state.subAgentCount + 1;\n            break;\n        case 'lesson_recorded': {\n            const text = (evt.payload as { text?: string }).text;\n            if (typeof text === 'string' && text) next.lessonsRecorded.push(text);\n            break;\n        }\n        case 'plan_step_updated': {\n            const sid = (evt.payload as { stepId?: string }).stepId;\n            const st = (evt.payload as { status?: string }).status;\n            if (typeof sid === 'string' && typeof st === 'string') next.stepStatus[sid] = st;\n            break;\n        }\n        default:\n            // tool_result, checkpoint_saved, budget_*, user_input, agent_response —\n            // currently no state derivation; just tick eventCount.\n            break;\n    }\n    return next;\n}\n\n/**\n * Replay a goal's journal into a derived state snapshot. O(n) in events.\n * A fresh process calls this on resume to know what's been done already.\n */\nexport function replayGoal(goalId: string): GoalReplayState {\n    const events = readJournal('goals', goalId);\n    const seed: GoalReplayState = {\n        goalId,\n        completed: false,\n        failed: false,\n        currentAgentId: null,\n        toolCallCount: 0,\n        subAgentCount: 0,\n        stepStatus: {},\n        lessonsRecorded: [],\n        lastEventAt: null,\n        eventCount: 0,\n    };\n    return events.reduce(applyEventToGoalState, seed);\n}\n\n/** Test helper — wipe a scope's journal. */\nexport function __resetJournalForTests(scope: 'goals' | 'agents' | 'sessions', id: string): void {\n    const path = shardPath(scope, id);\n    if (existsSync(path)) {\n        try { unlinkSync(path); } catch { /* fine */ }\n    }\n}\n"],"mappings":"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","names":[]}

package/dist/agent/goalDriver.js

@@ -10,6 +10,7 @@ import { DEFAULT_BUDGET_CAPS, checkBudget, suggestDegradation, recordSpend } fro
 import { structuredSpawn } from "./structuredSpawn.js";
 import { verifyByKind } from "./verifier.js";
 import { isGenericQuestion, forceCommitDirective } from "./questionQuality.js";
+import { verificationEventsSince } from "./verification.js";
 import { onGoalCompleted, onGoalFailed, onGoalBlocked } from "./somaFeedback.js";
 import { emitAgentEvent } from "./agentEvents.js";
 const COMPONENT = "GoalDriver";
@@ -366,11 +367,48 @@ ${baseTask}` : baseTask;
       ...result.artifacts.map((a) => a.ref)
     ])];
     if (result.status === "done") {
+      subState.consecutiveNeedsInfoCount = 0;
+      try {
+        const spawnStartMs = subState.pendingSpawn?.attemptedAt ? new Date(subState.pendingSpawn.attemptedAt).getTime() : Date.now() - durationMs;
+        const events = verificationEventsSince(spawnStartMs);
+        const failed = events.filter((e) => !e.result.passed);
+        const passed = events.filter((e) => e.result.passed);
+        if (failed.length > 0 && passed.length === 0) {
+          subState.consecutiveAssertionFailures = (subState.consecutiveAssertionFailures ?? 0) + 1;
+          const count = subState.consecutiveAssertionFailures;
+          appendHistory(
+            state,
+            "observing",
+            `Spawn produced ${failed.length} verification failure(s) (counter=${count}): ${failed[0].result.reason.slice(0, 100)}`
+          );
+          if (count >= 3) {
+            try {
+              const { failSubtask } = await import("./goals.js");
+              failSubtask(
+                goal.id,
+                next.id,
+                `Subtask failed verification ${count}\xD7 in a row. Last failure: ${failed[0].result.reason.slice(0, 200)}. The specialist keeps producing artifacts that don't survive readback (byte-count drift, magic-header mismatch, partial write). Failing to break the loop.`
+              );
+            } catch {
+            }
+            subState.lastError = `Failed: ${count} consecutive verification failures`;
+            subState.pendingSpawn = void 0;
+            state.currentSubtaskId = void 0;
+            state.phase = "delegating";
+            appendHistory(state, "delegating", `Verification stuck-loop fail on ${next.id} (${count}\xD7 failures)`);
+            return;
+          }
+        } else if (passed.length > 0) {
+          subState.consecutiveAssertionFailures = 0;
+        }
+      } catch {
+      }
       state.phase = "verifying";
       appendHistory(state, "verifying", `Spawn returned done with ${result.artifacts.length} artifact(s), confidence ${result.confidence.toFixed(2)}`);
       subState.lastSpawnResult = result;
     } else if (result.status === "failed") {
       subState.lastError = result.reasoning || "failed";
+      subState.consecutiveNeedsInfoCount = 0;
       state.phase = "iterating";
       appendHistory(state, "iterating", `Spawn returned failed: ${subState.lastError.slice(0, 120)}`);
     } else if (result.status === "needs_info" || result.status === "blocked") {
@@ -379,6 +417,35 @@ ${baseTask}` : baseTask;
       const attemptCount = subState.attempts;
       const lastErr = subState.lastError;
       const rawQuestion = result.questions[0] ?? "";
+      subState.consecutiveNeedsInfoCount = (subState.consecutiveNeedsInfoCount || 0) + 1;
+      const trimmedQuestion = rawQuestion.trim();
+      const needsInfoCount = subState.consecutiveNeedsInfoCount;
+      if (trimmedQuestion.length === 0 && attemptCount >= 2) {
+        try {
+          const { failSubtask } = await import("./goals.js");
+          failSubtask(goal.id, next.id, `Specialist ${specialistName} returned needs_info with an empty question on attempt ${attemptCount}. No actionable signal \u2014 failing subtask to break the loop.`);
+        } catch {
+        }
+        subState.lastError = `Failed: empty needs_info on attempt ${attemptCount} (specialist ${specialistName})`;
+        state.currentSubtaskId = void 0;
+        state.phase = "delegating";
+        appendHistory(state, "delegating", `Empty needs_info fail on ${next.id} (attempt ${attemptCount})`);
+        subState.pendingSpawn = void 0;
+        return;
+      }
+      if (needsInfoCount >= 3) {
+        try {
+          const { failSubtask } = await import("./goals.js");
+          failSubtask(goal.id, next.id, `Specialist ${specialistName} returned needs_info ${needsInfoCount}\xD7 in a row on this subtask. Forcing failure to break the loop. Last question: "${trimmedQuestion.slice(0, 160)}"`);
+        } catch {
+        }
+        subState.lastError = `Failed: ${needsInfoCount} consecutive needs_info returns`;
+        state.currentSubtaskId = void 0;
+        state.phase = "delegating";
+        appendHistory(state, "delegating", `Consecutive needs_info fail on ${next.id} (${needsInfoCount}\xD7)`);
+        subState.pendingSpawn = void 0;
+        return;
+      }
       if (subState.commitOverride) {
         subState.commitOverride = false;
         try {