@theihtisham/agent-shadow-brain 7.2.0 → 7.22.1

package/README.md

@@ -1,68 +1,202 @@
-# Agent Shadow Brain
-
-Agent Shadow Brain is a shared local memory store for coding agents. Save a project's decisions, lessons, and source references in one place, then recall the useful parts when you switch tools, hand off work, or start a fresh session.
-
-![Concept diagram showing coding agents sharing project memories and receiving a scoped, size-limited context pack](docs/assets/context-flow-v7.2.png)
-
-*Concept illustration of the memory and context flow.*
-
-## Get started
-
-Use Node.js 22.12+ within 22.x, Node.js 24.x, or Node.js 26+.
-
-```bash
-npm install -g @theihtisham/agent-shadow-brain@7.2.0
-shadow-brain dash . --no-analysis
-```
-
-Run the dashboard command from your project directory. It opens the local workspace and skips background project analysis. Open the printed address if the browser does not start automatically. Use a second terminal for other commands while the dashboard is running.
-
-## Explore your memory
-
-Version 7.2 opens a five-view workspace that runs locally and works offline.
-
-- **Overview** shows memory and project counts, recent memories, and activity.
-- **Memories** lets you search and filter saved entries by project, category, and agent.
-- **Graph** shows which project each memory belongs to and which agent recorded it. Select a node to inspect it.
-- **Context** builds a copyable pack for a project and task, with selection reasons and recorded sources.
-- **Features** controls context packs, cross-project context, automatic briefings, and the dashboard activity feed.
-
-![Workspace overview with memory counts, projects, recent memories, and activity](docs/assets/workspace-overview-v7.2.png)
-
-![Workspace graph with project clusters, memory nodes, and a detail panel](docs/assets/workspace-graph-v7.2.png)
-
-*Screenshots from a running workspace populated with synthetic memories.*
-
-Open **Advanced tools** or visit `/advanced` for the previous dashboard. [Workspace guide](docs/WORKSPACE.md)
-
-## Build a context pack
-
-```bash
-shadow-brain context-pack "import retry behavior" --project . --token-budget 1200
-shadow-brain features list
-shadow-brain features set automaticBriefing off
-```
-
-A pack starts with the selected project's memories, collapses exact duplicates, and fits the rendered text to a size budget. Add `--json` to see why entries were selected or skipped. Cross-project context requires both an enabled feature setting and an explicit request. Token counts are estimates.
-
-Automatic briefings use the same context selection. Cached briefings follow the current task and feature settings, so disabling briefings takes effect on the next request.
-
-## Add skills to a project
-
-Six bundled skills cover workflow selection, implementation, debugging, review, research, and release. They help a client focus on the requested work, plan when useful, and verify the result.
-
-```bash
-shadow-brain skills list
-shadow-brain skills install . --target codex
-shadow-brain skills install . --target codex --apply
-```
-
-The first install command previews the files. The second applies the install and preserves your existing project instructions. Choose `claude-code`, `opencode`, `deepseek-harness`, or `portable` for other clients. Discovery depends on each client's skill support. [Skill integration guide](docs/WORKFLOW_INTEGRATION.md)
-
-## Upgrade and reference
-
-If you are upgrading from 6.x, back up `~/.shadow-brain/global.json` and stop older writers before using 7.x. The 7.x writers use a new lock protocol and keep memory schema version 1. [7.0 migration notes](docs/launch/RELEASE_NOTES_v7.0.0.md)
-
-- [7.2 release notes](docs/launch/RELEASE_NOTES_v7.2.0.md)
-- [Earlier CLI, MCP, seeding, and export guide](https://github.com/ihtishaam-dev/agent-shadow-brain/blob/v7.1.0/README.md)
-- [Changelog](CHANGELOG.md) · [MIT license](LICENSE)
+<h1 align="center">Agent Shadow Brain</h1>
+
+<p align="center">Created by <a href="https://github.com/theihtishaam">Ihtisham (@theihtishaam)</a> · <a href="https://github.com/theihtishaam/agents-brain">Explore the source and star Agent Shadow Brain</a></p>
+<p align="center"><strong>Your project memory. Shared across your AI tools.</strong></p>
+<p align="center">Save a fact once. Find useful context. Hand off work with its evidence intact.</p>
+
+<p align="center"><a href="https://trendshift.io"><img src="https://img.shields.io/badge/Trendshift-Explore%20trending%20projects-6366f1?style=for-the-badge" alt="Explore trending projects on Trendshift" /></a></p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@theihtisham/agent-shadow-brain"><img src="https://img.shields.io/npm/dt/%40theihtisham%2Fagent-shadow-brain?label=Total%20Downloads&amp;color=brightgreen" alt="Total npm downloads (all time)" /></a>
+  <a href="https://github.com/theihtishaam"><img src="https://img.shields.io/github/followers/theihtishaam?label=Follow%20%40theihtishaam&amp;style=social" alt="Follow @theihtishaam on GitHub" /></a>
+  <a href="https://www.npmjs.com/package/@theihtisham/agent-shadow-brain"><img alt="npm latest version" src="https://img.shields.io/npm/v/@theihtisham/agent-shadow-brain/latest?label=npm&amp;color=0f766e"></a>
+  <a href="https://github.com/theihtishaam/agents-brain/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/theihtishaam/agents-brain/actions/workflows/ci.yml/badge.svg?branch=main"></a>
+  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/github/license/theihtishaam/agents-brain?color=475569"></a>
+  <a href="https://github.com/theihtishaam/agents-brain"><img src="https://img.shields.io/github/stars/theihtishaam/agents-brain?label=Star%20on%20GitHub&amp;style=social" alt="Star agents-brain on GitHub" /></a>
+</p>
+
+<!-- NPM_TOTAL_START -->
+**Total npm downloads: 6,229** · Through **2026-11-13**. [npm data](https://github.com/theihtishaam/agents-brain/blob/main/docs/npm-metrics.json).
+
+GitHub refreshes this number every two days. The npm README records the total when this version was published. Downloads include automated installs; they are not unique users.
+<!-- NPM_TOTAL_END -->
+
+<p align="center"><a href="#try-it">Try it</a> · <a href="#inside-the-brain-hub">Visual tour</a> · <a href="#connect-your-agent">Connect your agent</a> · <a href="docs/README.md">Documentation</a></p>
+
+![Running Brain Hub with stored synthetic project records and measured MCP calls](https://raw.githubusercontent.com/theihtishaam/agents-brain/main/docs/assets/7.22.0-hub-exchanges.gif)
+
+[What works and its limits](docs/FEATURES_AND_LIMITS.md)
+
+The Brain Hub brings reviewed notes, cited documents, shared work, and recorded tool activity into one local workspace. This recording uses an isolated synthetic test project: 580 stored memories, a bounded graph view, and real MCP calls from scripted clients. It does not show a model's private thoughts or a customer's activity. [Visual guide](docs/VISUAL_GUIDE_v7.22.0.md) · [Research and release plan](docs/launch/RESEARCH_AND_PLAN_v7.22.0.md)
+
+## Try it
+
+Use **Node.js 22.13+ in the 22.x line, 24.x, or 26+**. From your project directory, one command installs the requested version in npm's cache and starts its local portal:
+
+```bash
+npx --yes --package @theihtisham/agent-shadow-brain@7.22.1 shadow-brain project workspace . --port 62595
+```
+
+For a reusable global command:
+
+```bash
+npm install -g @theihtisham/agent-shadow-brain@latest
+shadow-brain --version
+cd your-project
+shadow-brain project workspace . --port 62595
+```
+
+Keep the launcher running and open [the project Brain Hub](http://127.0.0.1:62595/hub). Start with **Knowledge → Add to memory**, then **Context → Find useful context**. Connect your chosen tool through **Setup** when you want it to retrieve that memory. Use the same project directory and port when restarting. Port `0` lets the OS assign a free port; open the URL printed by that launch.
+
+To build from this checkout while preparing a release, use `npm ci`, `npm run build`, then `node dist/cli.js project workspace . --port 62595`. The command’s directory argument selects which project store to open. [Quickstart](docs/QUICKSTART.md) · [Troubleshooting](docs/TROUBLESHOOTING.md)
+
+## Inside the Brain Hub
+
+![Running Brain Hub with tool icons, selectable reported workers, model details and a stored memory graph in an isolated test workspace](https://raw.githubusercontent.com/theihtishaam/agents-brain/main/docs/assets/7.22.0-agent-dock.png)
+
+| View | What you can do |
+| --- | --- |
+| **Brain overview** | Recognize your tools by their icons, inspect reported agents and models, follow stored memory relationships, and seek through recorded activity. An empty store has zero graph nodes and edges. |
+| **Knowledge** | Paste ordinary text and click Add to memory. Review longer notes, inspect original sources, or optionally import a document. Generate a project-specific skill. |
+| **Sessions** | Inspect reported work, original conversation snapshots, saved checkpoints and linked continuations. Connect the supported Codex history API explicitly or select an export from another tool. |
+| **Collaboration** | Open a project room, post a proposal or critique, claim a task, attach a project file, accept evidence, and record the outcome. |
+| **Context** | Assemble a scoped pack, inspect selected passages and sources, compare retrieval profiles, and copy the rendered Markdown. |
+| **Models and Usage** | Inspect client readiness, retained exchanges and optional host-reported model/token receipts. Unknown counts remain unknown; costs are not invented. |
+| **Learning** | Rate memories for a task, pause or remove retrieval feedback, and create a lesson from a recorded outcome. Record a paired evaluation, promote an eligible lesson, or roll back its retrieval influence. |
+| **Setup** | Choose tool participation, chat sharing, context limits and coordination roles. Manage features and verified Project Kit skills. |
+
+### See which tool reported the work
+
+![Actual event-driven indicator and tool details in the running test workspace](https://raw.githubusercontent.com/theihtishaam/agents-brain/main/docs/assets/7.22.0-agent-dock.gif)
+
+The tool activity panel uses local Codex/OpenAI, Claude, DeepSeek and OpenCode icons. Hover, focus or select a tool to inspect its project, recorded conversations, coordination role, latest observed action and optional model receipts. Separate conversations stay identifiable when one tool has several workers.
+
+Model, provider, effort and token counts come from explicit host reports. Missing values say **Not reported**. Activity indicators respond to new recorded events, respect **Pause motion** and reduced-motion preferences, and do not animate old history as new work. The icon identifies the tool, not the model it may be running.
+
+**Reporting MCP connections** counts initialized project connections with a current heartbeat. Connections renew every ten seconds and expire after thirty seconds without renewal. This reports the memory transport; a connected tool may be idle. It does not count native apps that have not connected to this project.
+
+The panel captures use four scripted MCP clients and synthetic model receipts. They demonstrate the working interface and transport, not four native applications or model inference.
+
+[Activity and session guide](docs/SESSIONS.md) · [Icon sources and license](docs/BRAND_ASSETS.md)
+
+### Start with ordinary words
+
+![Working Teach the brain screen with reviewed project notes](https://raw.githubusercontent.com/theihtishaam/agents-brain/main/docs/assets/7.22.0-teach-brain.png)
+
+1. Open **Knowledge** and type: **“The cupboard is black. Keep its brass handles.”**
+2. Click **Add to memory**. The note and its original wording are saved in this project.
+3. Open **Context** and ask: **“What colour is the cupboard?”** Inspect the returned note and its source. A connected agent can request the same context through MCP.
+4. For longer notes or edits before saving, choose **Review first**, then save the useful parts. Pending and skipped parts stay outside shared retrieval.
+5. Use **Learning** to mark a memory useful, irrelevant or incorrect for a task, then inspect the effect on the next retrieval.
+
+Direct notes support up to 6,000 characters and 20 paragraphs. No PDF, JSON or special format is required. The brain stores reference knowledge; your agent handles reasoning and answers from the context it requests. [Notes and conversation import guide](docs/SOURCE_INTAKE.md)
+
+```mermaid
+flowchart LR
+  Note[Your plain-language note] --> Save[Add to project memory]
+  Save --> Recall[Relevant context with sources]
+  Recall --> Codex[Codex]
+  Recall --> Claude[Claude Code]
+  Recall --> Other[OpenCode / Harness / MCP host]
+  Other --> Feedback[Task feedback and reviewed outcomes]
+  Feedback --> Recall
+```
+
+### Continue where another agent stopped
+
+![Running Sessions view with reported history and an immutable handoff](https://raw.githubusercontent.com/theihtishaam/agents-brain/main/docs/assets/7.22.0-sessions.png)
+
+An agent records meaningful progress and saves a checkpoint: what is done, decisions, evidence and next steps. Another connected agent calls `session_resume` with that checkpoint's ID and digest. It receives the exact saved handoff in a new linked session; the original remains available. This transfers recorded work, not hidden model state or an application's native running process.
+
+**Original tool history** preserves names and conversation IDs supplied by supported sources. Codex has an explicit read-only connection to its installed app-server's project index; Claude Code, OpenCode and DeepSeek Harness support selected native exports. Missing original names remain unavailable. A saved history page is a bounded snapshot, and an operator adds a checkpoint before handing it to another agent. [Sessions and native formats](docs/SESSIONS.md)
+
+```mermaid
+flowchart LR
+  A[Agent A in this project] --> Report[Progress and evidence]
+  Report --> Checkpoint[Immutable checkpoint]
+  Checkpoint --> B[Agent B resumes shared work]
+  Checkpoint --> Audit[Original history retained]
+  Control[Your sharing controls] --> Checkpoint
+```
+
+### Follow evidence from a PDF to a context pack
+
+![Working PDF intake with extracted text, a page locator, and approved project memory](https://raw.githubusercontent.com/theihtishaam/agents-brain/main/docs/assets/7.1.4-hub-knowledge.png)
+
+```mermaid
+flowchart LR
+  PDF[Local PDF] --> Parse[Extract page text]
+  Parse --> Review[Review cited page]
+  Review -->|Approve| Memory[Project memory]
+  Memory --> Pack[Scoped context pack]
+  Pack --> Host[Copy or retrieve through MCP]
+```
+
+The project store records the document fingerprint and the approved page citation. An image-only page shows that OCR is needed. Context budget figures estimate rendered pack tokens, and profile comparisons use the same scoped request. Optional host-reported token receipts appear separately in Usage. Context estimates do not prove a billing reduction. [Context guide](docs/CONTEXT_LAB.md)
+
+### Coordinate work and record a lesson
+
+```mermaid
+flowchart LR
+  Goal[Project room] --> Msg[Proposal or critique]
+  Msg --> Claim[Task claim and lease]
+  Claim --> Artifact[Versioned file and digest]
+  Artifact --> Outcome[Recorded outcome]
+  Outcome --> Candidate[Lesson candidate]
+  Candidate --> Evaluate[Operator records evaluation]
+  Evaluate --> Promote[Explicit promotion]
+  Promote --> Rollback[Rollback archives retrieval influence]
+```
+
+Browser and compatible project-local MCP clients share the same room records. Task claims carry revisions and expire. A recipient acknowledgement references the specific message or artifact. Learning changes project memory and retrieval. The workspace does not run models, train them, or assign work to hosts by itself. [Workspace guide](docs/WORKSPACE.md) · [Workflow integration](docs/WORKFLOW_INTEGRATION.md)
+
+![Actual learning view with a recorded comparison and rolled-back lesson](https://raw.githubusercontent.com/theihtishaam/agents-brain/main/docs/assets/7.1.4-hub-learning.png)
+
+### Browse the original evidence tools
+
+The classic workspace offers memory curation, typed relationships, retrieval feedback, and the full Context Lab. The detailed activity view adds filters and playback controls for the loaded journal.
+
+![Classic Context Lab with selected and excluded evidence](https://raw.githubusercontent.com/theihtishaam/agents-brain/main/docs/assets/7.1.4-context-lab.png)
+
+![Memory review with recorded sources and typed links](https://raw.githubusercontent.com/theihtishaam/agents-brain/main/docs/assets/7.1.4-memory-review.png)
+
+![Activity diagnostics showing a recorded tool timeline](https://raw.githubusercontent.com/theihtishaam/agents-brain/main/docs/assets/7.1.4-live.png)
+
+## Connect your agent
+
+Generate a recipe from the same directory used to start the project workspace. The recipe identifies the project store and launches the local stdio service.
+
+```bash
+shadow-brain project config . --target codex
+shadow-brain skills install . --target codex
+```
+
+Preview the skill installation before adding `--apply`. Merge the printed recipe in the selected host, reconnect, and confirm it can list and call a tool such as `project_inspect` or `context_pack`. A recorded exchange will appear when activity recording and display are enabled. [Integration guide](docs/INTEGRATIONS.md)
+
+| Target | Recipe |
+| --- | --- |
+| Codex | `shadow-brain project config . --target codex` |
+| Claude Code | `shadow-brain project config . --target claude-code` |
+| OpenCode | `shadow-brain project config . --target opencode` |
+| DeepSeek Harness | `shadow-brain project config . --target deepseek-harness` |
+| Other compatible host | `shadow-brain project config . --target portable` |
+
+The Setup page distinguishes installed files, configuration recipes, observed calls and host-reported usage. Tools must connect and request context; installing a package cannot make every application use it automatically. The Codex history adapter completed a real 0.145.0 handshake and an empty-project indexed list. History paging and imports were verified against controlled process fixtures; no personal native history was read for release testing.
+
+![Actual Setup view with project sharing, context limits and feature controls](https://raw.githubusercontent.com/theihtishaam/agents-brain/main/docs/assets/7.22.0-project-controls.png)
+
+### Keep the workspace under your control
+
+Set context token and entry ceilings, turn features on or off, and choose which conversations can be delivered to connected agents. Explicit source links carry those exclusions into retrieval and inherited handoffs. Tool switches use the client label supplied by a cooperating host; they are not authenticated access control. Already delivered context cannot be withdrawn from another application.
+
+Enable **project file activity** only when you want file-change metadata. The live stream sends bounded change notifications; it does not repeatedly reload the whole dashboard. File events identify paths and times, while agent attribution requires an actual report. [Measured local performance and limits](docs/WORKSPACE.md)
+
+The dashboard separates **reported model tokens**, **estimated context reduction**, and **measured tool duration**. It never converts a smaller context pack into a claimed billing or speed saving.
+
+## Documentation
+
+- [Quickstart](docs/QUICKSTART.md) · [Workspace guide](docs/WORKSPACE.md) · [Visual guide](docs/VISUAL_GUIDE_v7.22.0.md) · [Features and limits](docs/FEATURES_AND_LIMITS.md)
+- [Project Kit](docs/PROJECT_KIT.md) · [Context Lab](docs/CONTEXT_LAB.md) · [Workflow skills](docs/WORKFLOW_INTEGRATION.md)
+- [Integrations](docs/INTEGRATIONS.md) · [Sessions](docs/SESSIONS.md) · [Troubleshooting](docs/TROUBLESHOOTING.md) · [Release notes](docs/launch/RELEASE_NOTES_v7.22.0.md)
+
+MIT license. [Changelog](CHANGELOG.md)

package/dist/activity-cli.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function registerActivityCommands(program: Command): void;
+//# sourceMappingURL=activity-cli.d.ts.map

package/dist/activity-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-cli.d.ts","sourceRoot":"","sources":["../src/activity-cli.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAyDpC,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA2C/D"}

package/dist/activity-cli.js

@@ -0,0 +1,78 @@
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { Command } from 'commander';
+import { activityJournalFor } from './brain/activity-journal.js';
+import { reportAgentActivity } from './brain/activity-reporting.js';
+import { FEATURE_SETTINGS_FILENAME, FeatureSettingsStore } from './brain/feature-settings.js';
+function stores(opts) {
+    const dbPath = path.resolve(opts.db ?? path.join(os.homedir(), '.shadow-brain', 'global.json'));
+    const settings = new FeatureSettingsStore({
+        filePath: opts.settings ?? (opts.db ? path.join(path.dirname(dbPath), FEATURE_SETTINGS_FILENAME) : undefined),
+    });
+    return { brain: { dbPath }, settings };
+}
+function storeOptions(command) {
+    return command.option('--db <path>', 'Use the activity journal adjacent to this memory store')
+        .option('--settings <path>', 'Explicit feature-settings file');
+}
+function cursorNumber(input) {
+    if (input === undefined)
+        return undefined;
+    if (!/^\d+$/.test(input) || !Number.isSafeInteger(Number(input))) {
+        throw new TypeError('Activity cursor must be a nonnegative integer.');
+    }
+    return Number(input);
+}
+function durationNumber(input) {
+    if (input === undefined)
+        return undefined;
+    const value = Number(input);
+    if (!/^\d+(?:\.\d+)?$/.test(input) || !Number.isFinite(value) || value > Number.MAX_SAFE_INTEGER) {
+        throw new TypeError('Activity duration must be a nonnegative number of milliseconds.');
+    }
+    return value;
+}
+export function registerActivityCommands(program) {
+    const activity = new Command('activity').description('Report or read bounded local activity metadata');
+    storeOptions(activity.command('report').description('Record an explicitly reported session, phase, or tool event'))
+        .argument('<kind>', 'session-start, phase, tool-start, tool-end, or session-end')
+        .requiredOption('--project-id <id>', 'Project label')
+        .requiredOption('--session <id>', 'Host session label')
+        .requiredOption('--agent <id>', 'Agent label')
+        .option('--phase <phase>', 'understand, plan, work, or verify')
+        .option('--tool <name>', 'Tool label')
+        .option('--correlation <id>', 'Shared ID for the tool start and end')
+        .option('--outcome <outcome>', 'success, error, or cancelled')
+        .option('--duration-ms <number>', 'Host-reported tool duration in milliseconds')
+        .action(async (kind, opts) => {
+        const durationMs = durationNumber(opts.durationMs);
+        const { brain, settings } = stores(opts);
+        const result = await reportAgentActivity(brain, settings, {
+            kind, projectId: opts.projectId, sessionId: opts.session, agent: opts.agent,
+            phase: opts.phase, tool: opts.tool, correlationId: opts.correlation, outcome: opts.outcome, durationMs,
+        });
+        console.log(JSON.stringify(result, null, 2));
+    });
+    storeOptions(activity.command('tail').description('Read a page of recent activity or continue from a cursor'))
+        .option('--project-id <id>', 'Filter by recorded project label')
+        .option('--cursor <number>', 'Continue after this event sequence')
+        .option('--journal-id <id>', 'Journal ID paired with a previous cursor')
+        .action((opts) => {
+        const { brain, settings } = stores(opts);
+        const flags = settings.get().features;
+        const enabled = { liveEnabled: flags.liveActivity, recordingEnabled: flags.activityRecording };
+        if (!flags.liveActivity) {
+            console.log(JSON.stringify({
+                ...enabled, events: [], journalId: null, revision: 0, oldestSequence: null, latestSequence: 0,
+                nextAfterSequence: 0, cursor: 0, hasMore: false, gap: false, reset: false, retainedCount: 0, droppedCount: 0,
+            }, null, 2));
+            return;
+        }
+        const page = activityJournalFor(brain).read({
+            projectId: opts.projectId, afterSequence: cursorNumber(opts.cursor), journalId: opts.journalId, limit: 200,
+        });
+        console.log(JSON.stringify({ ...enabled, ...page, cursor: page.nextAfterSequence }, null, 2));
+    });
+    program.addCommand(activity);
+}
+//# sourceMappingURL=activity-cli.js.map

package/dist/activity-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-cli.js","sourceRoot":"","sources":["../src/activity-cli.ts"],"names":[],"mappings":"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"}

package/dist/adapters/index.d.ts

@@ -9,7 +9,8 @@ import { AiderAdapter } from './aider.js';
 import { CursorAdapter } from './cursor.js';
 import { WindsurfAdapter } from './windsurf.js';
 import { CopilotAdapter } from './copilot.js';
-export declare const ALL_ADAPTERS: Record<AgentTool, () => AgentAdapter>;
+/** File adapters are distinct from clients that connect through MCP and skills. */
+export declare const ALL_ADAPTERS: Record<Exclude<AgentTool, 'deepseek-harness' | 'user'>, () => AgentAdapter>;
 export declare function createAdapter(tool: AgentTool): AgentAdapter;
 export declare function detectRunningAgents(projectDir: string): Promise<AgentAdapter[]>;
 export { ClaudeCodeAdapter, KiloCodeAdapter, ClineAdapter, OpenCodeAdapter, CodexAdapter, RooCodeAdapter, AiderAdapter, CursorAdapter, WindsurfAdapter, CopilotAdapter, };

package/dist/adapters/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,YAAY,CAW9D,CAAC;AAEF,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,YAAY,CAI3D;AAED,wBAAsB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAcrF;AAED,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,aAAa,EACb,eAAe,EACf,cAAc,GACf,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,mFAAmF;AACnF,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,kBAAkB,GAAG,MAAM,CAAC,EAAE,MAAM,YAAY,CAWpG,CAAC;AAEF,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,YAAY,CAI3D;AAED,wBAAsB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAcrF;AAED,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,aAAa,EACb,eAAe,EACf,cAAc,GACf,CAAC"}

package/dist/adapters/index.js

@@ -9,6 +9,7 @@ import { AiderAdapter } from './aider.js';
 import { CursorAdapter } from './cursor.js';
 import { WindsurfAdapter } from './windsurf.js';
 import { CopilotAdapter } from './copilot.js';
+/** File adapters are distinct from clients that connect through MCP and skills. */
 export const ALL_ADAPTERS = {
     'claude-code': () => new ClaudeCodeAdapter(),
     'kilo-code': () => new KiloCodeAdapter(),
@@ -22,9 +23,9 @@ export const ALL_ADAPTERS = {
     'copilot': () => new CopilotAdapter(),
 };
 export function createAdapter(tool) {
+    if (!Object.hasOwn(ALL_ADAPTERS, tool))
+        throw new Error(`No native file adapter for ${tool}. Use its MCP or project-skill integration.`);
     const factory = ALL_ADAPTERS[tool];
-    if (!factory)
-        throw new Error(`Unknown agent tool: ${tool}`);
     return factory();
 }
 export async function detectRunningAgents(projectDir) {

package/dist/adapters/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA,wDAAwD;AAGxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,CAAC,MAAM,YAAY,GAA0C;IACjE,aAAa,EAAE,GAAG,EAAE,CAAC,IAAI,iBAAiB,EAAE;IAC5C,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI,eAAe,EAAE;IACxC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,YAAY,EAAE;IACjC,UAAU,EAAE,GAAG,EAAE,CAAC,IAAI,eAAe,EAAE;IACvC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,YAAY,EAAE;IACjC,UAAU,EAAE,GAAG,EAAE,CAAC,IAAI,cAAc,EAAE;IACtC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,YAAY,EAAE;IACjC,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,aAAa,EAAE;IACnC,UAAU,EAAE,GAAG,EAAE,CAAC,IAAI,eAAe,EAAE;IACvC,SAAS,EAAE,GAAG,EAAE,CAAC,IAAI,cAAc,EAAE;CACtC,CAAC;AAEF,MAAM,UAAU,aAAa,CAAC,IAAe;IAC3C,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,IAAI,EAAE,CAAC,CAAC;IAC7D,OAAO,OAAO,EAAE,CAAC;AACnB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,UAAkB;IAC1D,MAAM,QAAQ,GAAmB,EAAE,CAAC;IAEpC,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;QAC3D,MAAM,OAAO,GAAG,OAAO,EAAE,CAAC;QACzB,OAAe,CAAC,UAAU,GAAG,UAAU,CAAC;QACzC,IAAI,CAAC;YACH,IAAI,MAAM,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;gBAC3B,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC,CAAC,mBAAmB,CAAC,CAAC;IACjC,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,aAAa,EACb,eAAe,EACf,cAAc,GACf,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA,wDAAwD;AAGxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,mFAAmF;AACnF,MAAM,CAAC,MAAM,YAAY,GAAgF;IACvG,aAAa,EAAE,GAAG,EAAE,CAAC,IAAI,iBAAiB,EAAE;IAC5C,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI,eAAe,EAAE;IACxC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,YAAY,EAAE;IACjC,UAAU,EAAE,GAAG,EAAE,CAAC,IAAI,eAAe,EAAE;IACvC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,YAAY,EAAE;IACjC,UAAU,EAAE,GAAG,EAAE,CAAC,IAAI,cAAc,EAAE;IACtC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,YAAY,EAAE;IACjC,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,aAAa,EAAE;IACnC,UAAU,EAAE,GAAG,EAAE,CAAC,IAAI,eAAe,EAAE;IACvC,SAAS,EAAE,GAAG,EAAE,CAAC,IAAI,cAAc,EAAE;CACtC,CAAC;AAEF,MAAM,UAAU,aAAa,CAAC,IAAe;IAC3C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,IAAI,6CAA6C,CAAC,CAAC;IACzI,MAAM,OAAO,GAAG,YAAY,CAAC,IAAiC,CAAC,CAAC;IAChE,OAAO,OAAO,EAAE,CAAC;AACnB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,UAAkB;IAC1D,MAAM,QAAQ,GAAmB,EAAE,CAAC;IAEpC,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;QAC3D,MAAM,OAAO,GAAG,OAAO,EAAE,CAAC;QACzB,OAAe,CAAC,UAAU,GAAG,UAAU,CAAC;QACzC,IAAI,CAAC;YACH,IAAI,MAAM,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;gBAC3B,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC,CAAC,mBAAmB,CAAC,CAAC;IACjC,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,aAAa,EACb,eAAe,EACf,cAAc,GACf,CAAC"}

package/dist/brain/activity-journal.d.ts

@@ -0,0 +1,82 @@
+export declare const ACTIVITY_JOURNAL_FILENAME = "activity-journal.json";
+export declare const ACTIVITY_JOURNAL_LIMITS: Readonly<{
+    retained: 500;
+    page: 200;
+    bytes: number;
+}>;
+declare const KINDS: readonly ["session-start", "phase", "tool-start", "tool-end", "session-end"];
+declare const SOURCES: readonly ["measured", "reported"];
+declare const TRANSPORTS: readonly ["mcp", "cli", "host"];
+declare const PHASES: readonly ["understand", "plan", "work", "verify"];
+declare const OUTCOMES: readonly ["success", "error", "cancelled"];
+export interface ActivityEventInput {
+    kind: typeof KINDS[number];
+    source: typeof SOURCES[number];
+    transport: typeof TRANSPORTS[number];
+    projectId?: string;
+    sessionId?: string;
+    agent?: string;
+    phase?: typeof PHASES[number];
+    tool?: string;
+    correlationId?: string;
+    outcome?: typeof OUTCOMES[number];
+    durationMs?: number;
+}
+export interface ActivityJournalEvent extends ActivityEventInput {
+    id: string;
+    sequence: number;
+    timestamp: string;
+}
+export interface ActivityJournalSnapshot {
+    schemaVersion: 1;
+    journalId: string | null;
+    revision: number;
+    nextSequence: number;
+    events: ActivityJournalEvent[];
+}
+export interface ActivityJournalReadOptions {
+    afterSequence?: number;
+    journalId?: string;
+    limit?: number;
+    projectId?: string;
+}
+export interface ActivityJournalPage {
+    journalId: string | null;
+    revision: number;
+    oldestSequence: number | null;
+    latestSequence: number;
+    nextAfterSequence: number;
+    hasMore: boolean;
+    gap: boolean;
+    reset: boolean;
+    /** Retention counts describe the journal, including when the page filters by project. */
+    retainedCount: number;
+    droppedCount: number;
+    events: ActivityJournalEvent[];
+}
+export interface ActivityJournalOptions {
+    filePath?: string;
+    lockTimeoutMs?: number;
+}
+export declare class ActivityJournalError extends Error {
+    readonly code: 'ACTIVITY_JOURNAL_INVALID_EVENT' | 'ACTIVITY_JOURNAL_INVALID_CURSOR' | 'ACTIVITY_JOURNAL_INVALID_STORE' | 'ACTIVITY_JOURNAL_READ_FAILED' | 'ACTIVITY_JOURNAL_LOCK_TIMEOUT' | 'ACTIVITY_JOURNAL_LOCK_FAILED' | 'ACTIVITY_JOURNAL_WRITE_FAILED';
+    constructor(code: 'ACTIVITY_JOURNAL_INVALID_EVENT' | 'ACTIVITY_JOURNAL_INVALID_CURSOR' | 'ACTIVITY_JOURNAL_INVALID_STORE' | 'ACTIVITY_JOURNAL_READ_FAILED' | 'ACTIVITY_JOURNAL_LOCK_TIMEOUT' | 'ACTIVITY_JOURNAL_LOCK_FAILED' | 'ACTIVITY_JOURNAL_WRITE_FAILED', message: string);
+}
+/** Local metadata journal shared by cooperating service processes. */
+export declare class ActivityJournal {
+    readonly filePath: string;
+    private readonly lockTimeoutMs;
+    constructor(options?: ActivityJournalOptions);
+    get(): ActivityJournalSnapshot;
+    read(options?: ActivityJournalReadOptions): ActivityJournalPage;
+    append(raw: unknown): Promise<ActivityJournalEvent>;
+    private checkFile;
+    private acquireLock;
+    private releaseLock;
+    private replace;
+}
+export declare function activityJournalFor(brain: {
+    dbPath: string;
+}): ActivityJournal;
+export {};
+//# sourceMappingURL=activity-journal.d.ts.map

package/dist/brain/activity-journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-journal.d.ts","sourceRoot":"","sources":["../../src/brain/activity-journal.ts"],"names":[],"mappings":"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"}