@theihtisham/agent-shadow-brain 7.1.4 → 7.22.0

package/docs/WORKSPACE.md

@@ -1,37 +1,63 @@
-# Workspace guide
-
-Start a project-local Brain Hub from your project directory.
-
-```bash
-shadow-brain project workspace . --port 62595
-```
-
-Open [the project Hub](http://127.0.0.1:62595/hub). Keep the process running and reuse the same directory and port after restarting. `/workspace` opens the classic memory workspace; `/live` opens detailed activity diagnostics. The shared-store `shadow-brain dash . --no-analysis` opens an all-project view. Project-local PDF review, rooms, skills, and lesson promotion require the project workspace.
-
-![Running Brain Hub with a replayed event](assets/7.1.4-hub-control-room.png)
-
-## Inspect records and activity
-
-Select a project, agent, or memory node. For keyboard navigation, open **Node list**. The inspector shows record content, recorded source references, and explicit links. **Trace** shows the retained journal. Seek an event to inspect it and copy the event receipt. **Latest** returns to incoming records. **Pause motion** and reduced-motion settings suppress moving packets.
-
-Every graph node and relationship comes from the stored project, memory and author records. Cyan moving highlights mark fresh measured events and amber marks fresh reports when both recorded endpoints are present. Events without matching graph endpoints remain in the journal. The local workspace status, client file presence, observed tool activity, and model data each have independent evidence.
-
-## Review and use knowledge
-
-Use **Knowledge** to upload a PDF and inspect extracted pages. Approving a page writes a source-backed project memory. Image-only pages require OCR. You can also save explicit text and a reference, inspect project markers, or preview and apply a project skill. [Project Kit](PROJECT_KIT.md)
-
-Use **Context** to enter a task, set a budget, compare profiles, and copy a pack. Review selected passages, reasons, and citations. The pack size is estimated. Tool timings and model token receipts are separate, and unavailable receipts stay visibly unavailable. [Context Lab](CONTEXT_LAB.md)
-
-## Share a task and its evidence
-
-Create or open a **Collaboration** room. Post a proposal, critique, question, decision, or handoff. Add a task and claim it before attaching a project-relative file. The task’s lease and revision control ownership. Accept the current submitted artifact and record the result with its check and evidence. A participant can acknowledge another participant’s message or artifact. These operations are shared with project-local MCP clients. [Workflow integration](WORKFLOW_INTEGRATION.md)
-
-In **Learning**, propose a lesson from a recorded outcome. Record the baseline, candidate, controls, and evidence. Promotion is an explicit operator action. Rollback archives the promoted memory so it no longer influences normal retrieval. Use the classic workspace to manage separate task-scoped retrieval feedback. [Learning guide](LEARNING.md)
-
-## Change runtime controls
-
-In **Setup**, manage context packs, activity display, and activity recording. The project portal stays pinned to its project, so cross-project context is unavailable here. Automatic briefing requires a legacy analysis session. Feature changes are revisioned and persist when the local process restarts. Disabling the activity display hides journal records in the Hub. Disabling recording stops new optional telemetry. Work-room records remain available.
-
-Setup can print native client recipes and diagnostic text. Recipes point to the selected local installation and store. To confirm the host actually uses the same project, call one of its project tools and inspect the journal. [Integrations](INTEGRATIONS.md)
-
-[Visual guide](VISUAL_GUIDE_v7.1.4.md) · [Troubleshooting](TROUBLESHOOTING.md)
+# Workspace guide
+
+Start a project-local Brain Hub from your project directory.
+
+```bash
+shadow-brain project workspace . --port 62595
+```
+
+Open [the project Hub](http://127.0.0.1:62595/hub). Keep the process running and reuse the same directory and port after restarting. `/workspace` opens the classic memory workspace; `/live` opens detailed activity diagnostics. The shared-store `shadow-brain dash . --no-analysis` opens an all-project view. Project-local PDF review, rooms, skills, and lesson promotion require the project workspace.
+
+![Running Brain Hub with stored memories and observed tool exchanges](assets/7.22.0-hub-graph.png)
+
+## Inspect records and activity
+
+Select a project, agent, or memory node. **Find node** lists the displayed graph records and searches stored memories in the selected scope. Selecting a search result brings the exact record into the graph even when it falls outside the current sample. Use **+**, **−**, and **Fit** to adjust the view, or drag the zoomed canvas with a pointer. The relationship filters show project membership, recorded authors, or explicit memory links. The inspector shows the record, its recorded sources, and its links.
+
+**MCP exchanges** shows recent measured client sessions even in a project with no stored memories. The request arrow points from client to workspace. The result arrow points from workspace to client when a handler completes, with the outcome shown on the receipt. A result-ready event records tool completion. Model consumption is unobserved. Select a lane, or open **Trace** and choose a journal record. The inspector links an exact matching request or result when both are retained in the loaded history. **Latest** returns to incoming activity. **Pause motion** and reduced-motion settings keep the display still.
+
+## Review and use knowledge
+
+Use **Knowledge** to write an ordinary fact, paragraph or plan and click **Add to memory**. For longer notes or corrections, choose **Review first**. Optional PDFs provide extracted pages with source citations; image-only pages require OCR. You can also inspect project markers or preview and apply a project skill. [Plain-text guide](SOURCE_INTAKE.md) · [Project Kit](PROJECT_KIT.md)
+
+Use **Context** to enter a task, set a budget, compare profiles, and copy a pack. Review selected passages, reasons, and citations. The pack size is estimated. Tool timings and model token receipts are separate, and unavailable receipts stay visibly unavailable. [Context Lab](CONTEXT_LAB.md)
+
+## Report optional model usage
+
+A cooperating host can call `usage_report` with counters and metadata it already knows. For example, replace the project and session identifiers with the host's actual labels:
+
+```json
+{
+  "operationId": "example-operation-1",
+  "projectId": "0123456789abcdef",
+  "sessionId": "example-host-session",
+  "agent": "codex",
+  "requestModel": "example-model",
+  "reasoningEffort": "high",
+  "inputTokens": 1200
+}
+```
+
+`reasoningEffort` is an optional short plain label reported by the host, not a value inferred from a model name. Omit it and any unknown counters when they are unavailable; zero means a reported zero. Receipts remain labelled **host-reported**, do not include prompts or credentials, and are not billing records. A receipt can be associated with a project session only when project ID, the host session ID and the agent label match exactly. Reuse the same operation ID for an identical retry.
+
+## Share a task and its evidence
+
+Create or open a **Collaboration** room. Post a proposal, critique, question, decision, or handoff. Add a task and claim it before attaching a project-relative file. The task’s lease and revision control ownership. Accept the current submitted artifact and record the result with its check and evidence. A participant can acknowledge another participant’s message or artifact. These operations are shared with project-local MCP clients. [Workflow integration](WORKFLOW_INTEGRATION.md)
+
+In **Learning**, propose a lesson from a recorded outcome. Record the baseline, candidate, controls, and evidence. Promotion is an explicit operator action. Rollback archives the promoted memory so it no longer influences normal retrieval. Use the classic workspace to manage separate task-scoped retrieval feedback. [Learning guide](LEARNING.md)
+
+## Change runtime controls
+
+In **Setup**, manage context packs, activity display, and activity recording. The project portal stays pinned to its project, so cross-project context is unavailable here. Automatic briefing requires a legacy analysis session. Feature changes are revisioned and persist when the local process restarts. Disabling the activity display hides journal records in the Hub. Disabling recording stops new optional telemetry. Work-room records remain available.
+
+**Project sharing** lets you set context ceilings, control tool participation, and turn off delivery for a conversation. An unshared chat and its inherited handoffs remain available for operator audit. Memories with explicit provenance linking them to that conversation are removed before retrieval ranks or merges candidates. Older memories without that linkage cannot be associated automatically. Tool limits follow the MCP client label; roles are coordination labels. **Context** previews the same limits, including its reference comparison.
+
+Setup can print native client recipes and diagnostic text. Recipes point to the selected local installation and store. To confirm the host actually uses the same project, call one of its project tools and inspect the journal. [Integrations](INTEGRATIONS.md)
+
+The project Hub uses a local event stream for store changes while the tab is visible. **Polling fallback** appears if the stream disconnects. A reconnect can replay retained notices or refresh the current snapshot when the replay window has expired. Earlier records do not start fresh activity animations.
+
+Turn on **Project file activity** in Setup to see eligible relative paths and grouped filesystem notifications in **Sessions**. Watching runs while there is an open live subscription and both live display and recording are enabled. The watcher skips hidden, private, configuration, dependency, and build paths, and does not open file contents. It caps directory watches at 64 and shows at most 180 project paths and the 24 latest groups in the panel. File changes have an unknown actor. A grouped notification only establishes that the filesystem reported a change.
+
+A local Windows fixture measured 30 writes through to the visible Chrome page. Ten independent MCP memory writes, ten session API writes, and ten allowed file creates delivered in 241 ms median and 386 ms p95, with an 888 ms maximum. Over 60 seconds idle on the same fixture and Node 24.15.0, workspace RSS moved from 82.33 to 82.21 MiB, average server CPU was 0.365% of one core, and the open Sessions page made no workspace API refetches.
+
+[Visual guide](VISUAL_GUIDE_v7.22.0.md) · [Troubleshooting](TROUBLESHOOTING.md)

package/docs/launch/RELEASE_ACCEPTANCE_v7.22.0.md

@@ -0,0 +1,48 @@
+# 7.22.0 verification record
+
+Checked on 2026-11-14 against the release candidate. The checks below describe observed behavior and its limits. The [CI workflow](https://github.com/theihtishaam/agents-brain/actions/workflows/ci.yml) separately runs the build, tests, type checks, retrieval diagnostics, dependency audit and fresh-package checks on Ubuntu and Windows with Node 22, 24 and 26.
+
+The final local full-suite run passed **452 tests in 64 files**. Four public-metrics validation tests also passed. The matching commit's CI remains the authority for the complete current revision and its supported-platform package checks.
+
+The fresh-consumer package check passed: archive allowlist and integrity, isolated installation, public exports, CLI, all four skill layouts, MCP resources/prompts, PDF extraction, plaintext memory with evidence and retry identity, checkpoint continuation, context ceilings and byte-exact skill restoration. It also verifies that README images are included in the package.
+
+## Practical outcomes
+
+| User action | Evidence | Result |
+| --- | --- | --- |
+| Save “The cupboard is black” | Real portal HTTP, browser and two already-running independent MCP processes | Both clients retrieve the saved fact for a cupboard question; original line evidence resolves; another project cannot retrieve it. |
+| Retry a note or preserve a correction | Source-intake regressions | Identical notes keep their memory IDs; an earlier approved edit is preserved. |
+| Add PDF, JSON and transcript evidence | Real portal and independent MCP processes | Pending and rejected items stay out of retrieval. Approved records retain page/item locators and original versus edited text. |
+| Continue another agent's work | Real MCP subprocess and portal session tests | A digest-verified checkpoint opens a new linked session; original history and ownership remain intact. |
+| Hide a conversation | Warm-client policy tests | Tools, resources, prompts, direct evidence and inherited handoffs respect exclusions. Explicitly linked memories are filtered before ranking and duplicate collapse. |
+| Change context ceilings | Portal, MCP and project CLI tests | Token and entry ceilings also constrain the reference comparison. Corrupt policy storage fails agent delivery closed. |
+| Disable or remove a generated skill | Store tests and actual browser controls | Verified Project Kit files can be moved, restored or removed; edited and unowned files stay intact. Interrupted operations and abandoned locks are covered. |
+| Inspect live work | Browser and real MCP requests | The graph follows observed exchanges; empty memory stays empty. Hidden/reduced-motion behavior, replay expiry and node search are checked. |
+| Inspect models and usage | Real MCP and HTTP receipts | Missing counters remain unknown. Cache/reasoning subsets are not added twice; retries do not double-count. |
+| Inspect tool and worker details | Browser plus exact-identity regressions | Local logos, separate worker models and effort, shared-host ambiguity, custom client identity, keyboard/touch access, and reduced motion are covered. |
+| Count reporting MCP connections | Two independent owned stdio child processes and store/stream tests | No lease before readiness; clean closure removes it. A hard-killed child's retained lease expires under the tested clock. Disabling tool participation blocks recall while preserving the transport count. Recording off is unavailable. |
+
+## Browser and native integration evidence
+
+- The final graph fixture contains **580 synthetic stored memories**, with **504 displayed nodes and 1,925 recorded relationships** in the captured desktop view. Its three client labels come from scripted MCP clients. Eleven graph browser checks passed with no page errors or external requests.
+- Seven project-control browser checks passed, including keyboard-operated sliders, sharing, roles, tool participation and filtered context. Six managed-skill browser checks passed, including preserving an unrelated file.
+- Eleven additional tool-panel browser checks passed with four initialized scripted MCP stream clients, five registered sessions and two synthetic model receipts. These exercised local logos, hover/focus/click details, distinct worker models and effort, source attribution, event-driven motion, reduced motion, narrow layout and session navigation. No page errors or external requests occurred. Expiry/offline counts and custom-client joins also have focused regressions.
+- The plain-text, source-evidence, session paging and checkpoint paths were exercised in the running app. Native navigation and delayed disconnect responses were tested with controlled browser responses; server protocol tests use a separate owned process fixture.
+- Installed **Codex CLI 0.145.0** completed a real initialize/list/disconnect cycle scoped to a newly created empty test workspace. It returned zero conversations. No personal history was read, created or resumed and no model request was sent. This verifies the handshake and empty indexed list, not personal-history paging or every installed-client variant.
+- Claude Code, OpenCode and DeepSeek Harness imports are tested with supported native export fixtures. These do not establish automatic capture or native-client reconnection. MCP project memory and checkpoints are a separate shared interface.
+
+## Measured local cost
+
+One Windows/Node 24.15.0 fixture measured 30 writes reaching the visible browser: ten MCP memory writes, ten session API writes and ten allowed file changes. Median latency was **241 ms**, p95 **386 ms**, maximum **888 ms**. Over a 60-second idle sample, workspace RSS moved from **82.33 to 82.21 MiB**, server CPU averaged **0.365% of one core**, and the page made **zero workspace API refetches**.
+
+These figures describe a small local fixture on an i5-12450H, not a service-level guarantee, large-corpus benchmark or measurement of the optional native connector. Native metadata refreshes every ten seconds while its view is open; it is separate from local pushed activity.
+
+The added MCP presence lease renews every ten seconds, with a thirty-second expiry. An 11.2-second browser observation containing actual fixture tool exchanges and heartbeats produced four telemetry reads and two presence reads, with zero graph, usage, session or overview reads. Heartbeats update presence independently and do not animate work. This is a targeted request-routing check, not a large-team capacity benchmark.
+
+The 14 author-generated retrieval diagnostics passed for adaptive retrieval with no scoped-data leaks or budget violations. They test named retrieval behaviors, not model answer quality or superiority over other tools. The dependency audit reported no known vulnerabilities at the time of checking.
+
+## Boundaries that remain explicit
+
+This is a local project service. Client labels and coordination roles are not authenticated enterprise identities. The service does not inspect hidden reasoning, train model weights, reopen native application tabs, guarantee every host will request memory, or prove reported outcomes true. Context reduction is estimated; provider billing and model execution time are not inferred from it. Previously delivered information cannot be withdrawn from another application.
+
+Source code, installed-package behavior and UI captures are checked separately. Use the matching commit's CI result when assessing a published release.

package/docs/launch/RELEASE_NOTES_v7.22.0.md

@@ -0,0 +1,53 @@
+# Agent Shadow Brain 7.22.0
+
+Release date: 2026-11-14. See the [verification record](RELEASE_ACCEPTANCE_v7.22.0.md) for tested behavior and integration boundaries.
+
+This release makes project knowledge easier to add, trace, share and correct. Save ordinary notes directly with **Add to memory**, or review longer notes and optional document imports before sharing them. Pending and rejected review items remain outside shared retrieval.
+
+## Knowledge and learning
+
+- Paste a short fact or paragraph and save it with one click, retaining its original evidence and retry identity. Longer notes offer section review, correction and selective approval.
+- Import text PDFs, knowledge JSON and simple transcript JSON. The source review keeps speaker attribution, original text, exact page or item locator, fingerprint and approved corrections.
+- Inspect source evidence through the portal or the read-only `memory_evidence` MCP tool.
+- Rate a retrieved memory for a task. Bounded feedback affects matching future queries; users can pause or remove this influence.
+- Follow a lesson back to its recorded outcome and reported comparison. Promotion and rollback remain explicit.
+
+## Shared memory and handoffs
+
+- Already-running independent project MCP servers refresh their read view before ordinary recall.
+- Archived, contested and superseded records are excluded before project recall ranking. Audit views retain the historical record.
+- `hub_artifact_read` retrieves the saved immutable UTF-8 artifact by room, artifact ID and SHA-256. It does not reread a changed workspace file.
+- Duplicate collapse preserves conservative feedback attribution, and a supplied query without searchable terms no longer falls back to unrelated recent memories.
+
+## Portal and usage
+
+- A tool activity panel uses locally bundled integration icons and accessible detail controls for reported sessions, models, coordination roles and latest observed actions. Fresh event indicators respect pause and reduced-motion settings.
+- Initialized project MCP transports report bounded presence leases, with ten-second renewals, thirty-second expiry and clean-disconnect removal. Presence refreshes independently of the graph and never substitutes for evidence of model execution.
+- Optional usage receipts accept a bounded `reasoningEffort` label. It remains host-reported, with unknown effort omitted; existing receipts keep their retry identity.
+- The brain-shaped graph lays out actual stored records, with depth cues, quieter membership links, recorded relationship filters, search, pan, zoom and reduced motion.
+- Observed client exchanges remain visible even when the memory graph is empty. Replay does not silently switch to a newer event after the selected record expires.
+- Context shows candidates, selection reasons, exclusions, source navigation and the actual added/removed/shared records in a comparison.
+- Cooperating hosts can send optional `usage_report` receipts. Input and output totals remain distinct from cached and reasoning subsets. Missing counts remain unknown and receipts stay labelled host-reported.
+- Legacy model routes no longer discover host configuration files automatically, expose saved credential fields in JSON, or claim a successful provider test without testing it.
+
+## Compatibility and limits
+
+Existing project memory and ActivityJournal v1 remain compatible. New source and usage records live in separate project-local SQLite stores. No external database service or model download is required. Feature data is bounded and project scoped.
+
+Text organization is deterministic; it is not a separate model interpreting every paragraph. The connected agent reasons over the reviewed context it requests. Learning adapts stored memory and retrieval; it does not train model weights. Scanned PDFs need OCR, which is not included. Model reports do not establish billing or independently prove a proxy's upstream model. Native application connectivity requires that application's configuration and active use of the tools.
+
+## Conversation continuity
+
+Connected tools can register project sessions, report progress, save immutable checkpoints and continue another tool's checkpoint in a new agent-owned session. History is paged and bounded; old checkpoints keep their exact digest. Imported conversation snapshots preserve original IDs, available titles, workspace identity and source locators. A changed export becomes a linked snapshot rather than overwriting the original.
+
+The optional Codex history connection starts only after **Connect**. It uses the installed app-server's read interface, scopes the list to the current project, supports archived conversations and reads selected history in pages. Other supported tools use selected native exports. These interfaces do not reopen another application's native tab or transfer hidden model state.
+
+## Live updates and control
+
+The portal receives bounded pushed invalidations from local stores, with reconnect and polling fallback. Optional file activity reports safe project-relative file metadata; a filesystem event alone cannot identify the editing agent. Graph motion follows observed activity and can be paused.
+
+Project controls set tool participation, conversation sharing, coordination roles and context ceilings. Excluded conversations and their explicitly linked evidence are withheld from subsequent agent delivery, including inherited handoffs. Client labels are cooperative controls, not authenticated enterprise access control. Information already received by another process cannot be recalled.
+
+Project Kit skills with intact ownership receipts can be disabled, restored or removed through an exact preview. Edited and unmanaged files remain protected. Disabling a skill changes future file discovery; a host may need to reload to discard instructions already in its context.
+
+See the [research and acceptance plan](RESEARCH_AND_PLAN_v7.22.0.md), [source intake guide](../SOURCE_INTAKE.md), [sessions guide](../SESSIONS.md), and [visual guide](../VISUAL_GUIDE_v7.22.0.md).