@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 +15 -0
- package/README.md +141 -136
- package/dist/brain/cli.js +12 -43
- package/dist/brain/config.js +1 -0
- package/dist/brain/github-client.js +78 -0
- package/dist/brain/github-issues.js +332 -0
- package/dist/brain/issue-configuration-tools.js +29 -0
- package/dist/brain/issue-configuration.js +398 -0
- package/dist/brain/issue-tools.js +61 -0
- package/dist/brain/remote-policy.js +7 -6
- package/dist/brain/remote-server.js +108 -19
- package/dist/brain/repository-discovery.js +36 -2
- package/dist/brain/server.js +11 -63
- package/dist/brain/skills.js +18 -5
- package/dist/brain/todos.js +3 -99
- package/ops/config-deploy-entry.sh +1 -1
- package/ops/config-deploy-root.cjs +8 -6
- package/ops/config-deploy.cjs +7 -6
- package/ops/config-policy.cjs +23 -1
- package/ops/layout.cjs +13 -0
- package/package.json +9 -6
- package/skills/brain-memory/SKILL.md +5 -5
- package/skills/changelog/SKILL.md +25 -0
- package/skills/code-review/README.md +2 -2
- package/skills/code-review/SKILL.md +48 -12
- package/skills/git-workflow/SKILL.md +12 -2
- package/skills/github-issue-cleanup/SKILL.md +20 -0
- package/skills/github-release/SKILL.md +14 -0
- package/skills/package-integrity-check/SKILL.md +3 -2
- package/skills/todo-manager/README.md +2 -2
- package/skills/todo-manager/SKILL.md +11 -5
- package/skills/unslop/SKILL.md +4 -1
- package/dist/brain/connectors.js +0 -65
- package/dist/brain/github-reviews.js +0 -187
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
|
-
|
|
19
|
-
|
|
20
|
-
|
|
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
|
|
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
|
-
|
|
67
|
-
|
|
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
|
-
|
|
143
|
-
|
|
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
|
-
`
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
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":"/
|
|
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`.
|
|
205
|
-
|
|
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
|
-
|
|
261
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
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
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
701
|
-
|
|
702
|
-
GitHub
|
|
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
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
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
|
-
|
|
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
|
|
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)
|
|
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
|
|
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
|
-
|
|
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('
|
|
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('
|
|
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': {
|
package/dist/brain/config.js
CHANGED
|
@@ -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
|
+
}
|