@technomoron/agent-brain 0.1.3 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGES.md CHANGED
@@ -1,3 +1,18 @@
1
+ Version 0.1.6 (2026-11-16)
2
+ --------------------------
3
+ * Support console password login, MFA challenges and session revocation.
4
+ * Use agent-run 0.99.49.
5
+
6
+ Version 0.1.5 (2026-10-28)
7
+ --------------------------
8
+ * Bundle shared changelog and release skills for project and default sessions.
9
+ * Expose authorized global skills in authenticated default sessions.
10
+
11
+ Version 0.1.4 (2026-10-26)
12
+ --------------------------
13
+ * Move to the shared monorepo with independent package releases.
14
+ * Use agent-run 0.99.48.
15
+
1
16
  Version 0.1.3 (2026-10-23)
2
17
  --------------------------
3
18
  * Simplify internal helpers and add concise function and method comments.
package/README.md CHANGED
@@ -15,21 +15,9 @@ their own access controls. Node.js 24 or newer is required.
15
15
 
16
16
  ## Development
17
17
 
18
- Keep the agent-run and agent-brain checkouts next to each other. Build agent-run first, then install this package’s dependencies and link the local agent-run checkout:
19
-
20
- ```sh
21
- cd ../agent-run
22
- pnpm install
23
- pnpm build
24
- cd ../agent-brain
25
- pnpm install
26
- node scripts/link-agent-run.cjs
27
- pnpm build
28
- ```
29
-
30
- Run `pnpm test` for the server and agent-run integration suite. The test harness supplies this checkout’s executables through an isolated temporary PATH. Run `npm run build` to check the npm build path.
31
-
32
- The server currently depends on `@technomoron/agent-run` for profile resolution, initialization and Nunjucks skill rendering. This preserves existing behavior while moving server ownership into this repository; it does not yet make the server independent of the launcher’s profile format. Link the sibling launcher checkout when developing changes to those libraries; normal installations use the published dependency.
18
+ From the repository root, run `pnpm install`, `pnpm build`, and `pnpm test`.
19
+ The workspace links agent-run locally. Run `npm run build` inside this package
20
+ for the npm build path.
33
21
 
34
22
  ## Running
35
23
 
@@ -49,11 +37,13 @@ Operational systemd and Windows installation scripts remain in agent-run, which
49
37
 
50
38
  ## MCP-owned skills
51
39
 
52
- The server bundles `brain-consolidate`, `brain-import`, `brain-memory`, `code-review`, `todo-manager`, `git-workflow`, `package-integrity-check`, `node-cleanup`, and `unslop` under `skills/`.
40
+ The server bundles `brain-consolidate`, `brain-import`, `brain-memory`, `code-review`, `todo-manager`, `git-workflow`, `changelog`, `github-release`, `package-integrity-check`, `node-cleanup`, and `unslop` under `skills/`.
41
+
42
+ Use `changelog` for CHANGES formatting and entries. `github-release` and `package-integrity-check` load the same rules. These bundled skills are also available in default sessions without repository selection. Remove old configured `github-release` copies to use the bundled version; intentional overrides remain supported.
53
43
 
54
44
  All bundled skills are served directly by `list_skills` and `get_skill`; no configuration copy is required. Explicit global, pool, or project overrides remain supported. Legacy `brain-review`, `code-review-organizer`, `review-items`, `commit-workflow`, `release-package-check`, and `personal-memory` copies are excluded from MCP discovery. Remove these copies from configurations. Route review callers to `code-review`, Git callers to `git-workflow`, and package checks to `package-integrity-check`.
55
45
 
56
- The review workflow uses ordinary GitHub Issues through GitHub tools or `gh`. Brain supplies project context; GitHub owns issue identity, metadata, discussion and history. Existing `review_*` tools remain a compatibility API for earlier installations, not a requirement of the bundled skill.
46
+ The task and review workflows use Brain MCP `issue_*` tools for ordinary GitHub Issues. Direct GitHub tools or `gh` are explicit fallbacks only when the Brain backend or a required capability is unavailable. Brain supplies project context; GitHub owns issue identity, metadata, discussion and history. Review tracking uses only `issue_*`; `review_context` retrieves review guidance. The `code-review` skill retains reporting, severity mapping, attribution and resolution instructions.
57
47
 
58
48
  Initialization does not copy bundled skills into configuration directories. Remove old bundled-skill copies to use the package versions; intentional overrides remain supported. Consolidation's CLI fallback reads the same packaged source.
59
49
 
@@ -63,19 +53,15 @@ Initialization does not copy bundled skills into configuration directories. Remo
63
53
 
64
54
  ## Releases
65
55
 
66
- The release workflow publishes `@technomoron/agent-brain` on npm with public
67
- access. Tags use `@technomoron/agent-brain@<version>` and must match the package
68
- version. Run `pnpm release:preflight` before committing and tagging a release.
69
- The workflow checks the tag, runs the integration suite, and attaches the package
70
- tarball to its GitHub release. Configure `NPM_TOKEN` in the source repository for
71
- npm publishing; private source repositories publish without provenance.
56
+ See [publishing](../../docs/publishing.md). This package uses
57
+ `agent-brain-v<version>` tags and publishes independently of agent-run.
72
58
 
73
59
  ## Remote OAuth endpoint
74
60
 
75
61
  The remote endpoint uses the generic OAuth APIs in
76
62
  `@technomoron/apicore-server` 1.1.0 or newer. Normal npm installations include
77
63
  that dependency. When developing changes to apicore locally, build the sibling
78
- `../apicore` checkout and run `node scripts/link-apicore.cjs`; reinstalling
64
+ `../apicore` checkout next to the monorepo and run `node scripts/link-apicore.cjs`; reinstalling
79
65
  dependencies replaces this development link.
80
66
 
81
67
  Copy `examples/remote.jsonc` outside the source tree and customize absolute paths.
@@ -139,8 +125,86 @@ and unfinished login forms are deliberately lost on restart.
139
125
 
140
126
  ## Reviews as GitHub Issues
141
127
 
142
- Create `<active-profile>/review.jsonc` (or `default/review.jsonc`) inside the
143
- repository's private configuration root:
128
+ ### Ordinary issue tools
129
+
130
+ `issue_list`, `issue_get`, `issue_create`, `issue_update`, `issue_comments`,
131
+ `issue_comment` and `issue_comment_update` manage ordinary issues, including ones
132
+ created outside Brain. They use the repository, token and write gate in
133
+ `review.jsonc` below. Remote reads require `read`; writes require both `write`
134
+ and `review`, since ordinary issues can include review findings. PRs are excluded.
135
+
136
+ Lists and comments use `page`/`per_page` and return `next_page`. `issue_get`
137
+ returns the full body and metadata; comments are read separately. Creation requires
138
+ one origin, work type and Priority; organisation definitions must already exist.
139
+ Updates can change classification, assignees and milestone, or close/reopen using
140
+ `state` and `state_reason`. Unspecified fields and unrelated labels are preserved.
141
+
142
+ Writes require `confirmed: true`; edits require the last-read `revision`.
143
+ Creation and comment retries reuse `key` and the original content. Retry state
144
+ blocks uncertain writes instead of posting duplicates; reconcile those outcomes
145
+ on GitHub. Multi-step classification failures report partial success and the issue
146
+ URL. Revisions detect stale reads but cannot prevent concurrent external edits.
147
+
148
+ `issue_search` adds literal text and structured state/origin/type/Priority,
149
+ assignee and milestone filters. It stays within the configured repository and
150
+ reports incomplete results and GitHub's 1000-result search limit. `issue_metadata`
151
+ discovers labels, types, fields, assignees and milestones. `issue_relations` reads
152
+ parents, sub-issues and dependencies; `issue_relation_update` adds/removes
153
+ sub-issues and blocking dependencies. Both ends require Brain access; mutations
154
+ require write/review access to both repositories. Unsupported GitHub endpoints
155
+ and missing permissions are reported explicitly.
156
+
157
+ ### Issue configuration reconciliation
158
+
159
+ Call `issue_config_preview(settings)` to inspect definition changes, affected
160
+ issues, legacy-value migrations and blockers. Then pass the same settings and
161
+ returned `revision` to `issue_config_reconcile`, with `confirmed: true`. A stale
162
+ preview or any blocker prevents writes. No LLM or client-side GitHub login is used.
163
+
164
+ The standard contains the five origin labels, seven work types and four Priority
165
+ options documented by the bundled skills. Optional `<active-profile>/issue-standard.jsonc`
166
+ can configure complete `labels`/`types` metadata records (description and color)
167
+ and `priority_description`; it cannot introduce additional taxonomy values.
168
+
169
+ Settings support `defaults`, per-number `issue_overrides`, `label_migrations`,
170
+ `type_migrations`, `priority_migrations`, `remove_fields` (default: `Severity`),
171
+ `field_migrations` and `prune_types` (default: true). Unknown or ambiguous values
172
+ block apply until mapped. Legacy Severity critical/high/medium/low maps to
173
+ Urgent/High/Medium/Low. An explicit null field mapping acknowledges discarding
174
+ that value. Unrelated fields such as Effort and dates remain unchanged.
175
+
176
+ ```json
177
+ {"label_migrations":{"enhancement":"Feature Request"},"type_migrations":{"Improvement":"Feature"},"defaults":{"priority":"Medium"}}
178
+ ```
179
+
180
+ Reconciliation creates/updates definitions, migrates and verifies issue values,
181
+ then removes obsolete definitions. Priority option IDs are retained. Label cleanup
182
+ also previews and migrates PR labels. Organisation-wide changes require an active
183
+ GitHub organisation owner token, complete repository visibility, and remote Brain
184
+ `read write review repo:OWNER/*` (or `repo:*`) grants. All organisation repositories
185
+ are checked; outside use blocks destructive changes. Disable `prune_types` to
186
+ retain unrelated types while migrating individual repositories first.
187
+
188
+ Apply returns the read-back configuration and completed actions. On a partial or
189
+ uncertain failure, preview again; changes already present are not recreated.
190
+ GitHub offers no cross-resource transaction, so concurrent external changes can
191
+ still interrupt reconciliation. Capability failures and inventory limits fail
192
+ closed rather than authorizing deletion from an incomplete view.
193
+
194
+ ### Backend configuration
195
+
196
+ Configure the shared connection once in `global/review.jsonc` inside the private
197
+ configuration root:
198
+
199
+ ```json
200
+ {"backend":"github","tokenEnv":"GITHUB_TOKEN","writesEnabled":true}
201
+ ```
202
+
203
+ The global configuration has no fixed repository: remote requests use the selected
204
+ Brain repository; local requests use the registered GitHub remote or owner/repo
205
+ project name. Brain grants and GitHub token permissions still apply. A repository
206
+ must be selected before using issue tools. Existing `<active-profile>/review.jsonc`
207
+ (or `default/review.jsonc`) takes precedence when present:
144
208
 
145
209
  ```json
146
210
  {"backend":"github","repository":"technomoron/agent-run","tokenEnv":"MCP_GITHUB_TOKEN","writesEnabled":true}
@@ -149,14 +213,11 @@ repository's private configuration root:
149
213
  The token needs issue access to that private repository. Prefer a narrowly scoped
150
214
  GitHub App installation token or fine-grained token; token rotation is managed by
151
215
  the operator. Without `writesEnabled: true`, GitHub writes fail closed. The
152
- `review_*` tools use repository issue IDs and revision checks, preserve discussion
153
- outside their managed block, and deduplicate creation by a stable finding `key`.
154
- Retry keys are persisted locally to handle GitHub's delayed issue listings.
155
- GitHub offers no atomic issue-create idempotency or conditional PATCH here: a
156
- crash between creation and saving the key, or separate MCP instances creating the
157
- same finding simultaneously, can still require manual reconciliation. Re-read
158
- before writes; revision checks cannot eliminate races with concurrent GitHub edits.
159
- Old internal findings are not migrated automatically. This compatibility adapter uses its own managed metadata format; the bundled `code-review` skill instead uses ordinary GitHub issues directly.
216
+ `issue_*` tools use revision checks and persistent retry keys. Re-read before
217
+ writes; GitHub offers no atomic conditional PATCH, so concurrent edits can still
218
+ race. Existing GitHub finding bodies and discussion remain readable through
219
+ `issue_get` and `issue_comments`, including legacy managed blocks. No issues or
220
+ local historical records are migrated or deleted automatically.
160
221
 
161
222
  The reusable private skill repository is separate from MCP-owned workflows.
162
223
  Automatic catalog cloning/polling and OAuth login in the local stdio bridge are
@@ -165,7 +226,7 @@ not implemented by this change.
165
226
  ## Repository groups
166
227
 
167
228
  A remote configuration can declare `groups: [{"id":"agent-tools",
168
- "configRoot":"/var/lib/agent-mcp/groups/agent-tools"}]`. Set `group: "agent-tools"`
229
+ "configRoot":"/usr/local/agent-brain/groups/agent-tools"}]`. Set `group: "agent-tools"`
169
230
  and that same `configRoot` on each member of `repositories`. Each member keeps
170
231
  its own repository ID and working directory. Register its project at
171
232
  `<configRoot>/projects/<owner>/<repo>/config.yaml` with `name: owner/repo` and
@@ -201,8 +262,11 @@ projects, hidden members, empty groups, credentials and internal paths are omitt
201
262
  Changes to access rules apply to subsequent requests.
202
263
 
203
264
  An authenticated client can call these tools at `/mcp` without
204
- `X-Agent-Repository`. Only the discovery tools are available until a repository
205
- is selected. Send `X-Agent-Repository: owner/repo` for knowledge, skill, task and
265
+ `X-Agent-Repository`. `list_skills` and `get_skill` expose bundled skills and
266
+ configured global skills from roots containing repositories the caller can read.
267
+ Default, pool and project skill overrides require repository selection. Conflicting
268
+ global skills across accessible roots require selecting a repository.
269
+ Send `X-Agent-Repository: owner/repo` for knowledge, scoped skills, task and
206
270
  review tools. Discovery remains available after selection. Request a token with
207
271
  `read` and the desired repository scopes, such as `repo:*`; a token narrowed to
208
272
  one repository will only discover that repository, even if the user can access
@@ -257,8 +321,14 @@ compatibility; the application and package are named agent-brain.
257
321
 
258
322
  ### Export Brain changes to Git
259
323
 
260
- Configure `gitSync: {"catalog":"/var/lib/agent-mcp/catalogs/agent-brain-config",
261
- "state":"/var/lib/agent-mcp/config-deploy"}` alongside `dataRoot` in the remote
324
+ The server base is `/usr/local/agent-brain`. Keep service settings and credentials
325
+ in `conf/` (`remote.jsonc`, `.env`, and `ssh/`), the configuration Git checkout in
326
+ `brain-config/`, live knowledge in `data/live/`, authentication state in `runtime/`,
327
+ packages in `releases/` with a `current` link, and deployment state in `deploy/`.
328
+ Keep the existing service account and keep user launcher state separate.
329
+
330
+ Configure `gitSync: {"catalog":"/usr/local/agent-brain/brain-config",
331
+ "state":"/usr/local/agent-brain/deploy"}` alongside `dataRoot` in the remote
262
332
  server configuration. The catalog origin must grant SSH write access, and its
263
333
  local `user.name` and `user.email` must identify the configured human author.
264
334
  The deployment state must contain its successful deployment baseline.
@@ -292,7 +362,7 @@ New clients and instructions use `brain_sync` and `brain_flush`. Bare chat
292
362
  ## Local service and knowledge guide
293
363
 
294
364
  Agent-brain owns canonical knowledge, specifications, skills, reviews, tasks,
295
- connectors, retrieval and configuration synchronization. Its project profile is
365
+ retrieval and configuration synchronization. Its project profile is
296
366
  `projects/technomoron/agent-brain` under the external configuration root;
297
367
  agent-run owns launcher configuration, native adapters and the client connection.
298
368
  Both projects remain members of the `agent-tools` pool. Source registrations and
@@ -455,15 +525,15 @@ the file into the corresponding directory. User preferences belong in
455
525
  `decisions/`. Code-derived facts remain inferred `observations/`; source
456
526
  references and history belong in `memory/`, with planned features labeled as
457
527
  plans. An import request does not make inferred content authoritative.
458
- Use the todo tools for tasks. Reusable workflows are `skills/<name>/SKILL.md`
528
+ Use `issue_*` and the `todo-manager` skill for tasks. Reusable workflows are `skills/<name>/SKILL.md`
459
529
  files, and reusable templates belong in `templates/`; `remember` does not
460
530
  install either. Global skills remain available without copying them into each
461
531
  project. The brain-memory skill explains these choices to native agents.
462
532
 
463
533
  Available MCP tools include `get_context`, `search_knowledge`, `get_knowledge`,
464
534
  `remember`, `amend_knowledge`, `list_knowledge`, `archive_knowledge`,
465
- `knowledge_history`, `promote`, `deprecate_knowledge`, `review_context`,
466
- `review_list`, `resolve_review`, `review_history`, and `review_archive`.
535
+ `knowledge_history`, `promote`, `deprecate_knowledge`, `review_context`, and
536
+ the `issue_*` tools.
467
537
  Writes use atomic file replacement and a shared lock; concurrent writes either
468
538
  complete or report that the caller should retry. After a crashed writer, stop
469
539
  the service, verify the PID in `runtime/brain-write.lock` is no longer running,
@@ -594,46 +664,20 @@ by id afterwards.
594
664
 
595
665
  #### Review findings
596
666
 
597
- Review knowledge is a numbered, prioritized list. `remember` requires a
598
- `severity` of `critical`, `high`, `medium`, or `low` when the type is `review`,
599
- and rejects `severity` for every other type. The store assigns the finding
600
- label itself: `C1`, `H1`, `M1`, `L1`, counting up per severity within the scope.
601
- Resolved numbers are never handed out again, so a label always refers to the
602
- same finding.
603
-
604
- Each finding also carries a `state` of `open`, `fixed`, or `wontfix`, separate
605
- from the `active` and `deprecated` status that controls recall. New findings
606
- start `open`.
607
-
608
- ```sh
609
- agent-brain review list
610
- agent-brain review list --severity high --state open
611
- agent-brain review resolve ITEM_ID --revision REVISION --state fixed "Fixed by using a stable command name"
612
- ```
667
+ Use the `code-review` skill and `issue_*` tools for findings, discussion and
668
+ history. `review_context` retrieves constraints and decisions for a review.
669
+ Close completed fixes only after validation and a linked fix comment; deferred
670
+ findings stay open. The skill retains severity mapping and reporting attribution.
613
671
 
614
- `review_list` returns findings in severity then number order, open ones only
615
- unless states are given, each with the revision needed to resolve it.
616
- `resolve_review` records the state and reason and takes the finding out of active
617
- recall. It writes a short record (label, title, outcome, date, reason, and original
618
- file/revision) to the scope's `review-history.jsonl`, then deletes the full finding
619
- file. `review-counters.json` preserves numbering. These files participate in brain
620
- Git sync but are excluded from normal knowledge retrieval.
621
-
622
- Use MCP `review_history` to recall old fixes, with optional `query`, `scope`, `state`,
623
- `offset`, and `limit` (default 100). The CLI equivalent is
624
- `agent-brain review history [query]`. Git retains full details only when the original
625
- files were committed before cleanup; the MCP history is sufficient for the short fix list.
626
- Use `review_archive` with a scope, or `agent-brain review archive --scope project`,
627
- to compact existing files already marked `fixed` or `wontfix`. Deferred findings
628
- remain open. Mark a finding `wontfix` only when the user explicitly drops it or
629
- confirms it is intentional. A request to postpone an issue does not close it.
630
-
631
- Finding labels are indexed, so `search_knowledge` for `H2` finds that finding.
632
- Review files written before these fields existed keep parsing; they simply carry
633
- no label and stay out of the finding list.
672
+ The legacy review tracking MCP tools and GitHub adapter have been removed.
673
+ `remember` rejects new review records. Existing local records remain readable
674
+ through knowledge tools and `agent-brain review list`; archived closures remain
675
+ available through `agent-brain review history [query]`. These CLI commands read
676
+ local history only; they do not query GitHub. Historical files and counters are
677
+ preserved, without automatic migration or deletion.
634
678
 
635
679
  Remembered deductions default to inferred authority and must remain observations,
636
- memories, or review records. Global writes require explicit user authority.
680
+ or memories. Global writes require explicit user authority.
637
681
  Promotion copies an item, records its origin, preserves the original, and requires
638
682
  confirmation. Deprecation and promotion require the last-read revision so stale
639
683
  requests cannot overwrite newer work. An agent's authority claim is an instruction
@@ -654,60 +698,17 @@ elsewhere into these directories before rendering or loading those skills.
654
698
 
655
699
  The packaged memory, consolidation, review and task skills document their workflows. New review findings belong in GitHub Issues through `code-review`.
656
700
 
657
- ### Tasks and connectors
658
-
659
- Tasks are separate from knowledge and stored in `todo/<id>.md`. Supported states
660
- are `todo`, `doing`, `blocked`, `done`, and `cancelled`. Tasks have titles,
661
- descriptions, priorities, owners, due dates, labels, notes, and optional external
662
- source identities.
663
-
664
- ```sh
665
- agent-brain todo add --json '{"scope":"project","title":"Check refresh handling","priority":"high"}'
666
- agent-brain todo list
667
- agent-brain todo get ITEM_ID
668
- agent-brain todo complete ITEM_ID --revision REVISION
669
- ```
670
-
671
- MCP exposes `todo_list`, `todo_get`, `todo_add`, `todo_update`, `todo_complete`,
672
- `todo_import`, and `todo_sync`. Update requests require the current revision.
673
-
674
- Configure optional connectors in `brain.jsonc`:
675
-
676
- ```jsonc
677
- {
678
- "enabled": true,
679
- "connectors": {
680
- "issues": {
681
- "type": "github",
682
- "repository": "my-org/my-project",
683
- "tokenEnv": "GITHUB_TOKEN"
684
- },
685
- "board": {
686
- "type": "trello",
687
- "board": "BOARD_ID",
688
- "keyEnv": "TRELLO_API_KEY",
689
- "tokenEnv": "TRELLO_TOKEN"
690
- }
691
- }
692
- }
693
- ```
694
-
695
- ```sh
696
- agent-brain todo import issues --scope project
697
- agent-brain todo sync issues --scope project
698
- ```
701
+ ### Tasks
699
702
 
700
- Credentials are read from the process environment and never written to task files.
701
- Set credentials in the service's environment.
702
- GitHub imports paginate and exclude pull requests. Trello maps due-complete cards
703
- to done, archived cards to cancelled, and other cards to todo; it does not guess
704
- workflow states from list names.
703
+ Manage todos through `issue_*` and the bundled `todo-manager` skill. Manual tasks
704
+ use origin label `ToDo`, normally work type `Task`, and the existing `Priority`
705
+ field. GitHub owns task identity, discussion, state and history.
705
706
 
706
- Imports deduplicate by source identity and scope. Synchronization compares local
707
- and remote fields against the last imported version, preserves local-only edits,
708
- and reports conflicting task IDs without replacing those tasks. Deleted remote
709
- items are retained locally. These connectors only read remote systems; completing
710
- a local task does not close a GitHub issue or modify a Trello card.
707
+ The legacy `todo_*` MCP tools, local task writes and GitHub/Trello imports are
708
+ retired. Existing `todo/<id>.md` files remain untouched and readable through
709
+ `agent-brain todo list` and `agent-brain todo get ITEM_ID`. These commands read
710
+ local history only. Old `brain.jsonc` connector settings are accepted but unused.
711
+ No automatic migration or deletion is performed.
711
712
 
712
713
  ### Git portability
713
714
 
@@ -849,12 +850,16 @@ or a separate authoritative cache.
849
850
 
850
851
  The initial implementation uses lexical retrieval and path matching. Embeddings,
851
852
  vector ranking, background watchers, debounced automatic Git synchronization,
852
- remote task writes, and additional connectors remain future work. No model
853
+ and additional retrieval methods remain future work. No model
853
854
  provider or external account is required for the local features.
854
855
 
855
- Transport and connector implementations follow the
856
+ Transport and issue implementations follow the
856
857
  [Node MCP SDK server documentation](https://ts.sdk.modelcontextprotocol.io/server),
857
- [GitHub Issues REST API](https://docs.github.com/en/rest/issues/issues), and
858
- [Trello board API](https://developer.atlassian.com/cloud/trello/rest/api-group-boards/).
858
+ [GitHub Issues REST API](https://docs.github.com/en/rest/issues/issues).
859
859
 
860
860
  Personal preferences and context retrieval are covered by bundled `brain-memory`; the separate `personal-memory` skill is retired.
861
+
862
+ Console login: `agent-run brain-login --user USER --password PASSWORD` prompts
863
+ for MFA when required. `agent-run brain-logout` revokes the session. Public
864
+ clients use the issuer’s `/console/login` and `/console/logout` endpoints; login
865
+ returns a PKCE-bound authorization code for the standard token exchange.
package/dist/brain/cli.js CHANGED
@@ -14,9 +14,7 @@ const consolidation_1 = require("./consolidation");
14
14
  const consolidation_skill_1 = require("./consolidation-skill");
15
15
  const skills_1 = require("./skills");
16
16
  const todos_1 = require("./todos");
17
- const connectors_1 = require("./connectors");
18
17
  const git_1 = require("./git");
19
- const github_reviews_1 = require("./github-reviews");
20
18
  // Parse CLI arguments and run the requested Brain command.
21
19
  async function brainMain(argv, wrapperCommand) {
22
20
  const { values, positionals } = (0, node_util_1.parseArgs)({ args: argv, allowPositionals: true, strict: true, options: {
@@ -59,12 +57,7 @@ async function brainMain(argv, wrapperCommand) {
59
57
  'agent-brain skills [name]',
60
58
  'agent-brain review list [--severity <level>] [--state <state>]',
61
59
  'agent-brain review history [query] [--scope <scope>] [--state fixed|wontfix]',
62
- 'agent-brain review archive --scope <scope>',
63
- 'agent-brain review resolve <id> --revision <hash> --state fixed|wontfix [reason]',
64
- 'agent-brain todo list | get <id> | add --json <task-object>',
65
- 'agent-brain todo update <id> --revision <hash> --json <changes>',
66
- 'agent-brain todo complete <id> --revision <hash>',
67
- 'agent-brain todo import|sync <connector> --scope <scope>',
60
+ 'agent-brain todo list | get <id> (local history only)',
68
61
  'agent-brain pull | push | save | sync [--message <commit-message>]',
69
62
  'agent-brain sync status | init',
70
63
  'agent-brain serve [--pull] [--socket <path>] | mcp [--socket <path>]',
@@ -130,6 +123,9 @@ async function brainMain(argv, wrapperCommand) {
130
123
  // Print a result with any broken-file diagnostics.
131
124
  const report = (value) => print(store.withDiagnostics(value));
132
125
  try {
126
+ if (['amend', 'promote', 'deprecate'].includes(command) && store.get(requireId()).type === 'review') {
127
+ throw new Error('Historical local findings are read-only; use MCP issue_* tools for review tracking');
128
+ }
133
129
  switch (command) {
134
130
  case 'status':
135
131
  report({ configRoot: root, enabled: (0, config_1.readBrainConfig)(root)?.enabled ?? false, profile: store.profile, scopes: store.scopes, knowledge: store.allKnowledge().length, todos: (0, todos_1.listTodos)(store).length });
@@ -143,9 +139,13 @@ async function brainMain(argv, wrapperCommand) {
143
139
  case 'get':
144
140
  report(store.get(requireId()));
145
141
  break;
146
- case 'remember':
147
- report(store.remember(store_1.knowledgeInput.parse(json())));
142
+ case 'remember': {
143
+ const input = store_1.knowledgeInput.parse(json());
144
+ if (input.type === 'review')
145
+ throw new Error('Use MCP issue_create and the code-review skill for findings');
146
+ report(store.remember(input));
148
147
  break;
148
+ }
149
149
  case 'promote':
150
150
  if (!values.confirmed)
151
151
  throw new Error('Promotion requires --confirmed after explicit user approval');
@@ -174,22 +174,6 @@ async function brainMain(argv, wrapperCommand) {
174
174
  break;
175
175
  case 'review': {
176
176
  const operation = positionals.shift() ?? 'list';
177
- const github = (0, github_reviews_1.githubReviews)(store);
178
- if (github) {
179
- if (operation === 'list' || operation === 'history') {
180
- const items = await github.list(operation === 'history' ? 'closed' : values.state && values.state !== 'open' ? 'closed' : 'open');
181
- report(items.filter((item) => (!values.severity || item.severity === values.severity) && (!values.state || item.state === values.state)));
182
- }
183
- else if (operation === 'get')
184
- report(await github.get(requireId()));
185
- else if (operation === 'create')
186
- report(await github.create(github_reviews_1.reviewInput.parse(json())));
187
- else if (operation === 'resolve')
188
- report(await github.resolve(requireId(), requireRevision(), zod_1.z.enum(['fixed', 'wontfix']).parse(values.state), positionals.slice(1).join(' ') || 'Resolved after verification'));
189
- else
190
- throw new Error('GitHub reviews support list, history, get, create and resolve; use review_update over MCP for edits');
191
- break;
192
- }
193
177
  if (operation === 'list') {
194
178
  report(store.reviews({
195
179
  ...(values.severity ? { severity: [store_1.severitySchema.parse(values.severity)] } : {}),
@@ -199,15 +183,8 @@ async function brainMain(argv, wrapperCommand) {
199
183
  else if (operation === 'history') {
200
184
  report(store.reviewHistory({ query: positionals.join(' '), ...(values.scope ? { scope: store_1.scopeSchema.parse(values.scope) } : {}), ...(values.state ? { state: zod_1.z.enum(['fixed', 'wontfix']).parse(values.state) } : {}), limit: Number.MAX_SAFE_INTEGER }));
201
185
  }
202
- else if (operation === 'archive') {
203
- report(store.archiveReviews(store_1.scopeSchema.parse(values.scope)));
204
- }
205
- else if (operation === 'resolve') {
206
- const state = zod_1.z.enum(['fixed', 'wontfix']).parse(values.state);
207
- report(store.resolveReview(requireId(), requireRevision(), state, positionals.slice(1).join(' ') || undefined));
208
- }
209
186
  else
210
- throw new Error('Usage: agent-brain review list | resolve <id> --revision <hash> --state fixed|wontfix');
187
+ throw new Error('Legacy review tracking is retired; use MCP issue_* tools. Local history: agent-brain review list | history');
211
188
  break;
212
189
  }
213
190
  case 'pull':
@@ -235,16 +212,8 @@ async function brainMain(argv, wrapperCommand) {
235
212
  report((0, todos_1.listTodos)(store));
236
213
  else if (operation === 'get')
237
214
  report((0, todos_1.getTodo)(store, requireId()));
238
- else if (operation === 'add')
239
- report((0, todos_1.addTodo)(store, todos_1.todoInput.parse(json())));
240
- else if (operation === 'update')
241
- report((0, todos_1.updateTodo)(store, requireId(), requireRevision(), todos_1.todoChanges.parse(json())));
242
- else if (operation === 'complete')
243
- report((0, todos_1.updateTodo)(store, requireId(), requireRevision(), { status: 'done' }));
244
- else if (operation === 'import' || operation === 'sync')
245
- report(await (0, connectors_1.syncConnector)(store, requireId(), store_1.scopeSchema.parse(values.scope)));
246
215
  else
247
- throw new Error('Unknown todo command; use agent-brain --help');
216
+ throw new Error('Legacy todo tracking is retired; use MCP issue_* tools and the todo-manager skill. Local history: agent-brain todo list | get <id>');
248
217
  break;
249
218
  }
250
219
  case 'project': {
@@ -32,6 +32,7 @@ exports.brainConfigSchema = zod_1.z.object({
32
32
  scope: zod_1.z.string().default('read write review repo:*')
33
33
  }).strict().optional(),
34
34
  contextBudget: zod_1.z.number().int().min(1000).max(100000).default(16000),
35
+ // Accept old connector settings without importing tasks into a parallel store.
35
36
  connectors: zod_1.z.record(zod_1.z.string().regex(/^[a-zA-Z0-9_-]+$/), zod_1.z.discriminatedUnion('type', [
36
37
  zod_1.z.object({ type: zod_1.z.literal('github'), repository: zod_1.z.string().regex(/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/), tokenEnv: zod_1.z.string().regex(/^[A-Z_][A-Z0-9_]*$/).default('GITHUB_TOKEN') }).strict(),
37
38
  zod_1.z.object({ type: zod_1.z.literal('trello'), board: zod_1.z.string().regex(/^[a-zA-Z0-9]+$/), keyEnv: zod_1.z.string().regex(/^[A-Z_][A-Z0-9_]*$/).default('TRELLO_API_KEY'), tokenEnv: zod_1.z.string().regex(/^[A-Z_][A-Z0-9_]*$/).default('TRELLO_TOKEN') }).strict()
@@ -0,0 +1,78 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.GithubClient = void 0;
4
+ exports.githubIssueConfig = githubIssueConfig;
5
+ const fs = require("node:fs");
6
+ const jsonc_parser_1 = require("jsonc-parser");
7
+ const zod_1 = require("zod");
8
+ const repositories_1 = require("./repositories");
9
+ const config_1 = require("./config");
10
+ const configSchema = zod_1.z.object({ backend: zod_1.z.literal('github'), repository: repositories_1.repositoryId.optional(),
11
+ tokenEnv: zod_1.z.string().regex(/^[A-Z_][A-Z0-9_]*$/).default('GITHUB_TOKEN'), writesEnabled: zod_1.z.boolean().default(false) }).strict();
12
+ class GithubClient {
13
+ // Bind the issue client to its store, configuration and GitHub repository.
14
+ constructor(store, config, repository) {
15
+ this.store = store;
16
+ this.config = config;
17
+ this.repository = repository;
18
+ }
19
+ // Send an authenticated GitHub issue request with time and size limits.
20
+ async request(route, method = 'GET', body) {
21
+ return this.requestApi('/repos/' + this.repository + '/issues' + route, method, body);
22
+ }
23
+ // Send a bounded request to a fixed GitHub API path.
24
+ async requestApi(route, method = 'GET', body) {
25
+ const token = process.env[this.config.tokenEnv];
26
+ if (!token)
27
+ throw new Error('Set ' + this.config.tokenEnv + ' for GitHub issues');
28
+ const response = await fetch('https://api.github.com' + route, {
29
+ method, redirect: 'error', signal: AbortSignal.timeout(30000), headers: { accept: 'application/vnd.github+json',
30
+ 'content-type': 'application/json', 'user-agent': 'agent-brain', authorization: 'Bearer ' + token,
31
+ 'X-GitHub-Api-Version': '2026-03-10' }, ...(body ? { body: JSON.stringify(body) } : {})
32
+ });
33
+ if (!response.ok)
34
+ throw new Error('GitHub request failed with HTTP ' + response.status + (response.status === 403 ? '; check token permissions, organisation policy and rate limits' : ''));
35
+ if (response.status === 204)
36
+ return null;
37
+ const text = await response.text();
38
+ if (text.length > 4 * 1024 * 1024)
39
+ throw new Error('GitHub response exceeds 4 MiB');
40
+ return JSON.parse(text);
41
+ }
42
+ // Serialize GitHub writes and enforce the explicit write gate.
43
+ async locked(work) {
44
+ if (!this.config.writesEnabled)
45
+ throw new Error('GitHub issue writes are disabled; configure writesEnabled explicitly');
46
+ const lock = this.store.safePath('runtime', 'github-review.lock');
47
+ const descriptor = fs.openSync(lock, 'wx', 0o600);
48
+ try {
49
+ return await work();
50
+ }
51
+ finally {
52
+ fs.closeSync(descriptor);
53
+ fs.unlinkSync(lock);
54
+ }
55
+ }
56
+ }
57
+ exports.GithubClient = GithubClient;
58
+ // Resolve the repository-bound GitHub configuration used by issue tools.
59
+ function githubIssueConfig(store, selectedRepository) {
60
+ const local = store.safePath(store.profile ?? 'default', 'review.jsonc');
61
+ const global = !fs.existsSync(local);
62
+ const file = global ? store.safePath('global', 'review.jsonc') : local;
63
+ if (!fs.existsSync(file))
64
+ return null;
65
+ const errors = [];
66
+ const document = (0, jsonc_parser_1.parse)(store.read(file), errors);
67
+ if (errors.length)
68
+ throw new Error('Invalid review.jsonc');
69
+ const config = global ? configSchema.omit({ repository: true }).parse(document) : configSchema.parse(document);
70
+ const project = (0, config_1.listBrainProjects)(store.configRoot).find((item) => item.profile === store.profile);
71
+ const registered = project?.repository?.url ? (0, repositories_1.githubRepository)(project.repository.url) : null;
72
+ const repository = global
73
+ ? selectedRepository ?? registered ?? (repositories_1.repositoryId.safeParse(project?.name).success ? project.name : null)
74
+ : ('repository' in config ? config.repository : undefined) ?? registered;
75
+ if (!repository)
76
+ throw new Error('GitHub issues need an explicit repository or a registered GitHub remote');
77
+ return { config, repository: repositories_1.repositoryId.parse(repository) };
78
+ }