@technomoron/agent-brain 0.1.1 → 0.1.3
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 +21 -0
- package/README.md +19 -15
- package/dist/brain/built-in-skills.js +2 -0
- package/dist/brain/cli.js +8 -0
- package/dist/brain/config.js +7 -0
- package/dist/brain/connectors.js +2 -0
- package/dist/brain/consolidation.js +4 -0
- package/dist/brain/git.js +9 -2
- package/dist/brain/github-reviews.js +13 -0
- package/dist/brain/projects.js +4 -6
- package/dist/brain/remote-policy.js +12 -3
- package/dist/brain/remote-server.js +54 -12
- package/dist/brain/repositories.js +3 -0
- package/dist/brain/repository-discovery.js +4 -1
- package/dist/brain/server.js +14 -2
- package/dist/brain/skills.js +11 -0
- package/dist/brain/store.js +36 -1
- package/dist/brain/todos.js +10 -1
- package/dist/brain/windows-pipe.js +2 -1
- package/dist/version.js +1 -4
- package/examples/remote.jsonc +1 -1
- package/ops/brain-pipe-security.ps1 +40 -0
- package/ops/config-deploy-root.cjs +6 -0
- package/ops/config-deploy.cjs +11 -4
- package/ops/config-policy.cjs +16 -0
- package/ops/config-sync.cjs +34 -1
- package/package.json +1 -1
- package/skills/brain-consolidate/README.md +5 -0
- package/skills/brain-import/README.md +5 -0
- package/skills/brain-memory/README.md +5 -0
- package/skills/brain-memory/SKILL.md +7 -3
- package/skills/code-review/README.md +7 -0
- package/skills/code-review/SKILL.md +26 -0
- package/skills/git-workflow/README.md +5 -0
- package/skills/git-workflow/SKILL.md +14 -0
- package/skills/node-cleanup/README.md +5 -0
- package/skills/node-cleanup/SKILL.md +239 -0
- package/skills/node-cleanup/agents/openai.yaml +4 -0
- package/skills/package-integrity-check/README.md +5 -0
- package/skills/package-integrity-check/SKILL.md +27 -0
- package/skills/todo-manager/README.md +5 -0
- package/skills/todo-manager/SKILL.md +9 -3
- package/skills/unslop/README.md +5 -0
- package/skills/unslop/SKILL.md +177 -0
- package/skills/unslop/agents/openai.yaml +4 -0
- package/skills/brain-review/SKILL.md +0 -38
- package/skills/code-review-organizer/SKILL.md +0 -150
- package/skills/review-items/SKILL.md +0 -43
package/CHANGES.md
CHANGED
|
@@ -1,3 +1,24 @@
|
|
|
1
|
+
Version 0.1.3 (2026-10-23)
|
|
2
|
+
--------------------------
|
|
3
|
+
* Simplify internal helpers and add concise function and method comments.
|
|
4
|
+
|
|
5
|
+
Version 0.1.2 (2026-10-23)
|
|
6
|
+
--------------------------
|
|
7
|
+
* Preserve repeated sync exports, reversals and deletions before deployment.
|
|
8
|
+
* Sync skill support files and tracked skill/task deletions.
|
|
9
|
+
* Enforce shared-scope write permissions for legacy repository groups.
|
|
10
|
+
* Include the Windows pipe ACL helper in the package.
|
|
11
|
+
* Create severity labels when the GitHub Severity field is unavailable.
|
|
12
|
+
* Use fictional organization examples.
|
|
13
|
+
* Bundle unslop and merge personal-memory guidance into brain-memory.
|
|
14
|
+
* Serve node-cleanup from the agent-brain bundle and remove the pnmp typo rule.
|
|
15
|
+
* Bundle package-integrity-check in place of release-package-check.
|
|
16
|
+
* Bundle Git operations and commit policy in git-workflow.
|
|
17
|
+
* Load all Brain workflows directly from the package instead of installing configuration copies.
|
|
18
|
+
* Track reviews and tasks with GitHub issue types and structured severity.
|
|
19
|
+
* Serve one bundled code-review workflow using ordinary GitHub issues, with optional local overrides.
|
|
20
|
+
* Support plaintext or hashed remote login passwords.
|
|
21
|
+
|
|
1
22
|
Version 0.1.1 (2026-10-22)
|
|
2
23
|
--------------------------
|
|
3
24
|
* Allow independent repositories without a pool in configuration deployment and Git sync.
|
package/README.md
CHANGED
|
@@ -49,11 +49,13 @@ Operational systemd and Windows installation scripts remain in agent-run, which
|
|
|
49
49
|
|
|
50
50
|
## MCP-owned skills
|
|
51
51
|
|
|
52
|
-
The server
|
|
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/`.
|
|
53
53
|
|
|
54
|
-
|
|
54
|
+
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
55
|
|
|
56
|
-
|
|
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.
|
|
57
|
+
|
|
58
|
+
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.
|
|
57
59
|
|
|
58
60
|
## Shared skill catalog
|
|
59
61
|
|
|
@@ -81,8 +83,11 @@ Create each repository's separate configuration root using `agent-brain init
|
|
|
81
83
|
--configdir <root> --cwd <checkout>`. Run the server as a dedicated OS user with a
|
|
82
84
|
private runtime directory (0700). Supply two different random signing secrets of
|
|
83
85
|
at least 32 characters through `MCP_OAUTH_ACCESS_SECRET` and
|
|
84
|
-
`MCP_OAUTH_REFRESH_SECRET`.
|
|
85
|
-
|
|
86
|
+
`MCP_OAUTH_REFRESH_SECRET`. Set each human user's `passwordEnv` to a plaintext
|
|
87
|
+
password environment variable, or `passwordHashEnv` to a bcrypt hash variable;
|
|
88
|
+
choose one. Plaintext passwords are hashed in memory at startup. Keep the
|
|
89
|
+
environment file private and restart after password changes.
|
|
90
|
+
Optional TOTP secrets are base32 values enrolled
|
|
86
91
|
in the user's authenticator. Enrolment and password management are administrator
|
|
87
92
|
operations. Service accounts use confidential client secrets from the environment.
|
|
88
93
|
Never put credentials in source control or client command arguments.
|
|
@@ -151,9 +156,7 @@ GitHub offers no atomic issue-create idempotency or conditional PATCH here: a
|
|
|
151
156
|
crash between creation and saving the key, or separate MCP instances creating the
|
|
152
157
|
same finding simultaneously, can still require manual reconciliation. Re-read
|
|
153
158
|
before writes; revision checks cannot eliminate races with concurrent GitHub edits.
|
|
154
|
-
Old internal findings are not migrated automatically.
|
|
155
|
-
select their backend through `brain_status`; existing customized installations
|
|
156
|
-
must adopt that backend-selection section before using GitHub reviews.
|
|
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.
|
|
157
160
|
|
|
158
161
|
The reusable private skill repository is separate from MCP-owned workflows.
|
|
159
162
|
Automatic catalog cloning/polling and OAuth login in the local stdio bridge are
|
|
@@ -211,12 +214,12 @@ catalog; local access follows the existing OS-user trust model.
|
|
|
211
214
|
Use one configuration root with three parallel directories:
|
|
212
215
|
|
|
213
216
|
```text
|
|
214
|
-
global/
|
|
215
|
-
pools/
|
|
216
|
-
projects/
|
|
217
|
+
global/ # knowledge and skills shared by all repositories
|
|
218
|
+
pools/acme/ # knowledge and skills shared by this pool
|
|
219
|
+
projects/acme/catalog-api/ # repository knowledge, reviews and tasks
|
|
217
220
|
```
|
|
218
221
|
|
|
219
|
-
Set `pool:
|
|
222
|
+
Set `pool: acme` in each member's `projects/<owner>/<repo>/config.yaml`.
|
|
220
223
|
The MCP reads only global, the active repository's pool, and that repository.
|
|
221
224
|
Skills with the same name resolve in repository, pool, global order. A skill can
|
|
222
225
|
extend an ancestor with `extends: global:name` or `extends: pool:name`.
|
|
@@ -649,9 +652,7 @@ including template. Nunjucks variables remain available. Symlinks are rejected,
|
|
|
649
652
|
and each file is limited to 1 MiB. Move snippets and skill overrides stored
|
|
650
653
|
elsewhere into these directories before rendering or loading those skills.
|
|
651
654
|
|
|
652
|
-
The
|
|
653
|
-
skills describe retrieval, persistence, consolidation, review learning, and task workflows. Review records use
|
|
654
|
-
the knowledge tools and remain inferred unless confirmed by the user.
|
|
655
|
+
The packaged memory, consolidation, review and task skills document their workflows. New review findings belong in GitHub Issues through `code-review`.
|
|
655
656
|
|
|
656
657
|
### Tasks and connectors
|
|
657
658
|
|
|
@@ -746,6 +747,7 @@ not identify Brain as the target. Agents still need a user request or standing
|
|
|
746
747
|
authorization to sync.
|
|
747
748
|
|
|
748
749
|
Saving includes Markdown knowledge, skills, tasks, project metadata, and `.gitignore`.
|
|
750
|
+
Skill support files and tracked skill/task deletions are included.
|
|
749
751
|
It also includes all regular files under each scope's `templates/` directory,
|
|
750
752
|
including nested Nunjucks templates and supporting files. Template additions,
|
|
751
753
|
edits, and deletions are synced; symlinks are rejected.
|
|
@@ -854,3 +856,5 @@ Transport and connector implementations follow the
|
|
|
854
856
|
[Node MCP SDK server documentation](https://ts.sdk.modelcontextprotocol.io/server),
|
|
855
857
|
[GitHub Issues REST API](https://docs.github.com/en/rest/issues/issues), and
|
|
856
858
|
[Trello board API](https://developer.atlassian.com/cloud/trello/rest/api-group-boards/).
|
|
859
|
+
|
|
860
|
+
Personal preferences and context retrieval are covered by bundled `brain-memory`; the separate `personal-memory` skill is retired.
|
|
@@ -8,6 +8,7 @@ const zod_1 = require("zod");
|
|
|
8
8
|
const store_1 = require("./store");
|
|
9
9
|
const directory = path.resolve(__dirname, '..', '..', 'skills');
|
|
10
10
|
const metadata = zod_1.z.object({ name: zod_1.z.string(), description: zod_1.z.string().min(1) });
|
|
11
|
+
// Read and validate a bundled skill by name.
|
|
11
12
|
function readBuiltInSkill(name) {
|
|
12
13
|
if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name))
|
|
13
14
|
throw new Error(`Invalid built-in skill name: ${name}`);
|
|
@@ -17,6 +18,7 @@ function readBuiltInSkill(name) {
|
|
|
17
18
|
throw new Error(`Built-in skill name must match directory: ${name}`);
|
|
18
19
|
return { description: parsed.description, content: document.content };
|
|
19
20
|
}
|
|
21
|
+
// Load all bundled skills in name order.
|
|
20
22
|
function readBuiltInSkills() {
|
|
21
23
|
return Object.fromEntries(fs.readdirSync(directory, { withFileTypes: true })
|
|
22
24
|
.filter((entry) => entry.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))
|
package/dist/brain/cli.js
CHANGED
|
@@ -17,6 +17,7 @@ const todos_1 = require("./todos");
|
|
|
17
17
|
const connectors_1 = require("./connectors");
|
|
18
18
|
const git_1 = require("./git");
|
|
19
19
|
const github_reviews_1 = require("./github-reviews");
|
|
20
|
+
// Parse CLI arguments and run the requested Brain command.
|
|
20
21
|
async function brainMain(argv, wrapperCommand) {
|
|
21
22
|
const { values, positionals } = (0, node_util_1.parseArgs)({ args: argv, allowPositionals: true, strict: true, options: {
|
|
22
23
|
configdir: { type: 'string' }, cwd: { type: 'string' }, socket: { type: 'string' },
|
|
@@ -43,6 +44,7 @@ async function brainMain(argv, wrapperCommand) {
|
|
|
43
44
|
}
|
|
44
45
|
if (values.pull && command !== 'serve')
|
|
45
46
|
throw new Error('--pull is only supported by serve');
|
|
47
|
+
// Print a JSON result to standard output.
|
|
46
48
|
const print = (value) => { process.stdout.write(`${JSON.stringify(value, null, 2)}\n`); };
|
|
47
49
|
if (values.help || command === 'help') {
|
|
48
50
|
process.stdout.write([
|
|
@@ -102,6 +104,7 @@ async function brainMain(argv, wrapperCommand) {
|
|
|
102
104
|
const service = await serveApiCore(root, socket);
|
|
103
105
|
process.stderr.write(`agent-brain listening on ${socket}\n`);
|
|
104
106
|
let closing = false;
|
|
107
|
+
// Close the local service once and report shutdown failures.
|
|
105
108
|
const close = () => { if (!closing) {
|
|
106
109
|
closing = true;
|
|
107
110
|
void service.close().catch((error) => { process.stderr.write(`${String(error)}\n`); process.exitCode = 1; });
|
|
@@ -115,12 +118,16 @@ async function brainMain(argv, wrapperCommand) {
|
|
|
115
118
|
return;
|
|
116
119
|
}
|
|
117
120
|
const store = new store_1.BrainStore(root, cwd);
|
|
121
|
+
// Require an item ID at the requested argument position.
|
|
118
122
|
const requireId = (index = 0) => { const id = positionals[index]; if (!id)
|
|
119
123
|
throw new Error('An item id is required'); return id; };
|
|
124
|
+
// Require the revision supplied for an update.
|
|
120
125
|
const requireRevision = () => { if (!values.revision)
|
|
121
126
|
throw new Error('--revision is required; read the item first'); return values.revision; };
|
|
127
|
+
// Parse the required JSON command argument.
|
|
122
128
|
const json = () => { if (!values.json)
|
|
123
129
|
throw new Error('--json is required'); return JSON.parse(values.json); };
|
|
130
|
+
// Print a result with any broken-file diagnostics.
|
|
124
131
|
const report = (value) => print(store.withDiagnostics(value));
|
|
125
132
|
try {
|
|
126
133
|
switch (command) {
|
|
@@ -259,6 +266,7 @@ async function brainMain(argv, wrapperCommand) {
|
|
|
259
266
|
store.close();
|
|
260
267
|
}
|
|
261
268
|
}
|
|
269
|
+
// Print a command failure and set the process exit status.
|
|
262
270
|
function reportBrainError(error) {
|
|
263
271
|
process.stderr.write(`agent-brain: ${error instanceof Error ? error.message : String(error)}\n`);
|
|
264
272
|
process.exitCode = 1;
|
package/dist/brain/config.js
CHANGED
|
@@ -15,6 +15,7 @@ const jsonc_parser_1 = require("jsonc-parser");
|
|
|
15
15
|
const yaml_1 = require("yaml");
|
|
16
16
|
const zod_1 = require("zod");
|
|
17
17
|
const utils_1 = require("@technomoron/agent-run/dist/utils");
|
|
18
|
+
// Choose a local socket or user-specific Windows pipe for this configuration.
|
|
18
19
|
function defaultSocketPath(configRoot) {
|
|
19
20
|
if (process.platform === 'win32') {
|
|
20
21
|
const identity = `${os.homedir().toLowerCase()}\0${path.resolve(configRoot).toLowerCase()}`;
|
|
@@ -36,6 +37,7 @@ exports.brainConfigSchema = zod_1.z.object({
|
|
|
36
37
|
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()
|
|
37
38
|
])).default({})
|
|
38
39
|
}).strict();
|
|
40
|
+
// Read and validate optional Brain JSONC configuration.
|
|
39
41
|
function readBrainConfig(root) {
|
|
40
42
|
const file = path.join(root, 'brain.jsonc');
|
|
41
43
|
if (!fs.existsSync(file))
|
|
@@ -55,10 +57,12 @@ exports.projectConfigSchema = zod_1.z.object({
|
|
|
55
57
|
repository: zod_1.z.object({ url: zod_1.z.string() }).optional(),
|
|
56
58
|
agent: zod_1.z.object({ default: zod_1.z.enum(['codex', 'claude', 'gemini', 'grok']).default('codex') }).default({ default: 'codex' })
|
|
57
59
|
}).strict();
|
|
60
|
+
// Read registered projects from the configuration tree.
|
|
58
61
|
function listBrainProjects(configRoot) {
|
|
59
62
|
const directory = path.join(configRoot, 'projects');
|
|
60
63
|
if (!fs.existsSync(directory))
|
|
61
64
|
return [];
|
|
65
|
+
// Find project configurations beneath this directory.
|
|
62
66
|
function scan(parent) {
|
|
63
67
|
return fs.readdirSync(parent, { withFileTypes: true }).filter((entry) => entry.isDirectory()).sort((a, b) => a.name.localeCompare(b.name)).flatMap((entry) => {
|
|
64
68
|
const child = path.join(parent, entry.name);
|
|
@@ -75,12 +79,15 @@ function listBrainProjects(configRoot) {
|
|
|
75
79
|
}
|
|
76
80
|
return scan(directory);
|
|
77
81
|
}
|
|
82
|
+
// Find the profile registered under a project name.
|
|
78
83
|
function namedBrainProfile(configRoot, name) {
|
|
79
84
|
return listBrainProjects(configRoot).find((project) => project.name === name || project.profile === name)?.profile ?? null;
|
|
80
85
|
}
|
|
86
|
+
// Find the profile containing the current source directory.
|
|
81
87
|
function registeredBrainProfile(configRoot, cwd) {
|
|
82
88
|
return registeredBrainProject(configRoot, cwd)?.profile ?? null;
|
|
83
89
|
}
|
|
90
|
+
// Select the most specific registered source root and reject ties.
|
|
84
91
|
function registeredBrainProject(configRoot, cwd) {
|
|
85
92
|
const matches = listBrainProjects(configRoot).flatMap((project) => project.roots
|
|
86
93
|
.filter((root) => (0, utils_1.isSamePathOrDescendant)(path.resolve(cwd), path.resolve(root)))
|
package/dist/brain/connectors.js
CHANGED
|
@@ -8,6 +8,7 @@ const githubIssue = zod_1.z.object({ number: zod_1.z.number().int(), title: zod_
|
|
|
8
8
|
html_url: zod_1.z.url(), pull_request: zod_1.z.unknown().optional(), labels: zod_1.z.array(zod_1.z.union([zod_1.z.string(), zod_1.z.object({ name: zod_1.z.string() })])) });
|
|
9
9
|
const trelloCard = zod_1.z.object({ id: zod_1.z.string(), name: zod_1.z.string(), desc: zod_1.z.string(), closed: zod_1.z.boolean(), dueComplete: zod_1.z.boolean(), due: zod_1.z.string().nullable(),
|
|
10
10
|
url: zod_1.z.url(), labels: zod_1.z.array(zod_1.z.object({ name: zod_1.z.string() })) });
|
|
11
|
+
// Fetch connector JSON with bounded requests and sanitized network errors.
|
|
11
12
|
async function readRemote(url, headers) {
|
|
12
13
|
let response;
|
|
13
14
|
try {
|
|
@@ -20,6 +21,7 @@ async function readRemote(url, headers) {
|
|
|
20
21
|
throw new Error(`Connector ${url.hostname} returned HTTP ${response.status}`);
|
|
21
22
|
return response.json();
|
|
22
23
|
}
|
|
24
|
+
// Import configured GitHub issues or Trello cards as local tasks.
|
|
23
25
|
async function syncConnector(store, name, scope) {
|
|
24
26
|
store.scopeDirectory(scope);
|
|
25
27
|
const connector = (0, config_1.readBrainConfig)(store.configRoot)?.connectors[name];
|
|
@@ -22,6 +22,7 @@ exports.inventoryOptions = zod_1.z.object({
|
|
|
22
22
|
scope: store_1.scopeSchema.optional(), types: zod_1.z.array(store_1.typeSchema).optional(), includeDeprecated: zod_1.z.boolean().optional(),
|
|
23
23
|
offset: zod_1.z.number().int().min(0).default(0), limit: zod_1.z.number().int().min(1).max(100).default(50)
|
|
24
24
|
}).strict();
|
|
25
|
+
// List filtered knowledge metadata with pagination and the context budget.
|
|
25
26
|
function listKnowledge(store, input = {}) {
|
|
26
27
|
const options = exports.inventoryOptions.parse(input);
|
|
27
28
|
if (options.scope)
|
|
@@ -31,9 +32,11 @@ function listKnowledge(store, input = {}) {
|
|
|
31
32
|
.sort((a, b) => a.source.localeCompare(b.source));
|
|
32
33
|
return { total: items.length, contextBudget: store.budget, items: items.slice(options.offset, options.offset + options.limit).map(({ content, ...item }) => ({ ...item, characters: content.length })) };
|
|
33
34
|
}
|
|
35
|
+
// Locate the archive history for an available scope.
|
|
34
36
|
function historyFile(store, scope) {
|
|
35
37
|
return store.safePath(store.scopeDirectory(scope), 'knowledge-history.jsonl');
|
|
36
38
|
}
|
|
39
|
+
// Read archive records and verify their scope, IDs and content hashes.
|
|
37
40
|
function readHistory(store, scope) {
|
|
38
41
|
const file = historyFile(store, scope);
|
|
39
42
|
if (!fs.existsSync(file))
|
|
@@ -52,6 +55,7 @@ exports.historyOptions = zod_1.z.object({
|
|
|
52
55
|
scope: store_1.scopeSchema.optional(), id: reference.shape.id.optional(), query: zod_1.z.string().max(1000).optional(),
|
|
53
56
|
offset: zod_1.z.number().int().min(0).default(0), limit: zod_1.z.number().int().min(1).max(100).default(50)
|
|
54
57
|
}).strict();
|
|
58
|
+
// Search archived records and include original text when an ID is requested.
|
|
55
59
|
function knowledgeHistory(store, input = {}) {
|
|
56
60
|
const options = exports.historyOptions.parse(input);
|
|
57
61
|
if (options.scope)
|
package/dist/brain/git.js
CHANGED
|
@@ -9,6 +9,7 @@ const path = require("node:path");
|
|
|
9
9
|
const node_child_process_1 = require("node:child_process");
|
|
10
10
|
const store_1 = require("./store");
|
|
11
11
|
const config_1 = require("./config");
|
|
12
|
+
// Run noninteractive Git commands and report failures.
|
|
12
13
|
function git(root, args) {
|
|
13
14
|
const result = (0, node_child_process_1.spawnSync)('git', ['-C', root, ...args], { encoding: 'utf8', shell: false, timeout: 60000,
|
|
14
15
|
env: { ...process.env, PATH: process.env.AGENT_RUN_REAL_PATH ?? process.env.PATH, GIT_TERMINAL_PROMPT: '0' }, maxBuffer: 16 * 1024 * 1024 });
|
|
@@ -16,11 +17,13 @@ function git(root, args) {
|
|
|
16
17
|
throw new Error(`git ${args[0]} failed: ${result.error?.message ?? result.stderr.trim()}`);
|
|
17
18
|
return result.stdout.trimEnd();
|
|
18
19
|
}
|
|
20
|
+
// Require the configuration directory to be the Git repository root.
|
|
19
21
|
function requireRepository(store) {
|
|
20
22
|
if (fs.realpathSync(git(store.configRoot, ['rev-parse', '--show-toplevel'])) !== fs.realpathSync(store.configRoot)) {
|
|
21
23
|
throw new Error('Git sync requires the configuration directory itself to be the repository root.');
|
|
22
24
|
}
|
|
23
25
|
}
|
|
26
|
+
// Report configuration Git state, conflicts and branch.
|
|
24
27
|
function gitStatus(store) {
|
|
25
28
|
if (!fs.existsSync(path.join(store.configRoot, '.git')))
|
|
26
29
|
return { state: 'uninitialized', files: [], conflicts: [], branch: '' };
|
|
@@ -30,6 +33,7 @@ function gitStatus(store) {
|
|
|
30
33
|
return { state: conflicts.length ? 'conflicted' : files.length ? 'dirty' : 'clean', files, conflicts,
|
|
31
34
|
branch: git(store.configRoot, ['branch', '--show-current']) };
|
|
32
35
|
}
|
|
36
|
+
// Collect canonical files and tracked removals eligible for local Git sync.
|
|
33
37
|
function syncableFiles(store) {
|
|
34
38
|
const folders = new Set([...Object.values(store_1.knowledgeDirectories), 'skills', 'todo', 'notes']);
|
|
35
39
|
const roots = [path.join(store.configRoot, 'global'), path.join(store.configRoot, 'default')];
|
|
@@ -39,7 +43,7 @@ function syncableFiles(store) {
|
|
|
39
43
|
const files = [];
|
|
40
44
|
for (const root of roots) {
|
|
41
45
|
for (const folder of folders)
|
|
42
|
-
files.push(...store.files(path.join(root, folder)));
|
|
46
|
+
files.push(...store.files(path.join(root, folder), { includeAllFiles: folder === 'skills' }));
|
|
43
47
|
files.push(...store.files(path.join(root, 'templates'), { includeAllFiles: true }));
|
|
44
48
|
for (const name of ['config.yaml', 'project.md', 'review-history.jsonl', 'review-counters.json', 'knowledge-history.jsonl']) {
|
|
45
49
|
const file = store.safePath(root, name);
|
|
@@ -48,7 +52,7 @@ function syncableFiles(store) {
|
|
|
48
52
|
}
|
|
49
53
|
}
|
|
50
54
|
if (fs.existsSync(path.join(store.configRoot, '.git'))) {
|
|
51
|
-
const removable = roots.flatMap((root) => ['templates',
|
|
55
|
+
const removable = roots.flatMap((root) => ['templates', ...folders].map((folder) => path.relative(store.configRoot, path.join(root, folder))));
|
|
52
56
|
const deleted = git(store.configRoot, ['ls-files', '--deleted', '-z', '--', ...removable]).split('\0').filter(Boolean);
|
|
53
57
|
files.push(...deleted.map((file) => store.safePath(file)));
|
|
54
58
|
}
|
|
@@ -57,6 +61,7 @@ function syncableFiles(store) {
|
|
|
57
61
|
files.push(ignore);
|
|
58
62
|
return [...new Set(files.map((file) => path.relative(store.configRoot, file)))].sort();
|
|
59
63
|
}
|
|
64
|
+
// Save, pull or push canonical configuration under the Brain write lock.
|
|
60
65
|
function syncGit(store, action, message) {
|
|
61
66
|
return store.writeLocked(() => {
|
|
62
67
|
const steps = [];
|
|
@@ -112,9 +117,11 @@ function syncGit(store, action, message) {
|
|
|
112
117
|
}
|
|
113
118
|
});
|
|
114
119
|
}
|
|
120
|
+
// Show Git state and canonical files eligible for synchronization.
|
|
115
121
|
function gitPreview(store) {
|
|
116
122
|
return { status: gitStatus(store), files: syncableFiles(store) };
|
|
117
123
|
}
|
|
124
|
+
// Fast-forward clean configuration at startup without blocking service availability.
|
|
118
125
|
function pullOnStart(store) {
|
|
119
126
|
try {
|
|
120
127
|
return store.writeLocked(() => {
|
|
@@ -18,15 +18,18 @@ const metadata = zod_1.z.object({ key: zod_1.z.string(), severity: store_1.sever
|
|
|
18
18
|
const issueSchema = zod_1.z.object({ number: zod_1.z.number().int().positive(), title: zod_1.z.string(), body: zod_1.z.string().nullable(),
|
|
19
19
|
state: zod_1.z.enum(['open', 'closed']), state_reason: zod_1.z.string().nullable().optional(), html_url: zod_1.z.string().url(),
|
|
20
20
|
updated_at: zod_1.z.string(), pull_request: zod_1.z.unknown().optional() });
|
|
21
|
+
// Hash review content for revisions and repository-specific retry files.
|
|
21
22
|
const hash = (value) => (0, node_crypto_1.createHash)('sha256').update(value).digest('hex');
|
|
22
23
|
const start = '<!-- agent-mcp-review:start -->';
|
|
23
24
|
const end = '<!-- agent-mcp-review:end -->';
|
|
24
25
|
class GithubReviews {
|
|
26
|
+
// Bind the review backend to its store, configuration and GitHub repository.
|
|
25
27
|
constructor(store, config, repository) {
|
|
26
28
|
this.store = store;
|
|
27
29
|
this.config = config;
|
|
28
30
|
this.repository = repository;
|
|
29
31
|
}
|
|
32
|
+
// Send an authenticated GitHub issue request with time and size limits.
|
|
30
33
|
async request(route, method = 'GET', body) {
|
|
31
34
|
const token = process.env[this.config.tokenEnv];
|
|
32
35
|
if (!token)
|
|
@@ -43,6 +46,7 @@ class GithubReviews {
|
|
|
43
46
|
throw new Error('GitHub response exceeds 4 MiB');
|
|
44
47
|
return JSON.parse(text);
|
|
45
48
|
}
|
|
49
|
+
// Extract managed review metadata from an ordinary GitHub issue.
|
|
46
50
|
data(issue) {
|
|
47
51
|
if (issue.pull_request)
|
|
48
52
|
return null;
|
|
@@ -64,6 +68,7 @@ class GithubReviews {
|
|
|
64
68
|
title: issue.title, content: body, state: issue.state === 'open' ? 'open' : issue.state_reason === 'not_planned' ? 'wontfix' : 'fixed',
|
|
65
69
|
url: issue.html_url, revision: hash(JSON.stringify(issue)), backend: 'github' };
|
|
66
70
|
}
|
|
71
|
+
// Page through managed findings and sort them by severity.
|
|
67
72
|
async list(state = 'open') {
|
|
68
73
|
const found = [];
|
|
69
74
|
for (let page = 1; page <= 100; page++) {
|
|
@@ -78,6 +83,7 @@ class GithubReviews {
|
|
|
78
83
|
}
|
|
79
84
|
throw new Error('GitHub review listing exceeds 100 pages; narrow the repository backlog before retrying');
|
|
80
85
|
}
|
|
86
|
+
// Extract an issue number belonging to the configured repository.
|
|
81
87
|
number(id) {
|
|
82
88
|
const prefix = 'github:' + this.repository + '#';
|
|
83
89
|
const number = id.startsWith(prefix) ? id.slice(prefix.length) : id.replace(/^#/, '');
|
|
@@ -85,12 +91,14 @@ class GithubReviews {
|
|
|
85
91
|
throw new Error('Issue must belong to the configured repository');
|
|
86
92
|
return number;
|
|
87
93
|
}
|
|
94
|
+
// Read a managed GitHub finding by its issue identity.
|
|
88
95
|
async get(id) {
|
|
89
96
|
const item = this.data(issueSchema.parse(await this.request('/' + this.number(id))));
|
|
90
97
|
if (!item)
|
|
91
98
|
throw new Error('Issue is not an agent-mcp review finding');
|
|
92
99
|
return item;
|
|
93
100
|
}
|
|
101
|
+
// Serialize GitHub writes and enforce the explicit write gate.
|
|
94
102
|
async locked(work) {
|
|
95
103
|
if (!this.config.writesEnabled)
|
|
96
104
|
throw new Error('GitHub review writes are disabled; configure writesEnabled explicitly');
|
|
@@ -104,12 +112,14 @@ class GithubReviews {
|
|
|
104
112
|
fs.unlinkSync(lock);
|
|
105
113
|
}
|
|
106
114
|
}
|
|
115
|
+
// Encode a finding inside the reserved GitHub review markers.
|
|
107
116
|
block(input) {
|
|
108
117
|
if (input.content.includes('<!-- agent-mcp-'))
|
|
109
118
|
throw new Error('Finding content contains a reserved marker');
|
|
110
119
|
const encoded = Buffer.from(JSON.stringify({ key: input.key, severity: input.severity, applies_to: input.applies_to })).toString('base64url');
|
|
111
120
|
return start + '\n<!-- agent-mcp-meta:' + encoded + ' -->\nSeverity: ' + input.severity + '\n\n' + input.content + '\n' + end;
|
|
112
121
|
}
|
|
122
|
+
// Create a finding or return the issue already associated with its retry key.
|
|
113
123
|
async create(input) {
|
|
114
124
|
input = exports.reviewInput.parse(input);
|
|
115
125
|
return this.locked(async () => {
|
|
@@ -133,6 +143,7 @@ class GithubReviews {
|
|
|
133
143
|
return { ...item, created: true };
|
|
134
144
|
});
|
|
135
145
|
}
|
|
146
|
+
// Revise the managed finding while preserving unrelated issue content.
|
|
136
147
|
async update(id, revision, changes) {
|
|
137
148
|
return this.locked(async () => {
|
|
138
149
|
const current = await this.get(id);
|
|
@@ -145,6 +156,7 @@ class GithubReviews {
|
|
|
145
156
|
return this.data(issue);
|
|
146
157
|
});
|
|
147
158
|
}
|
|
159
|
+
// Close a current finding with its resolution reason.
|
|
148
160
|
async resolve(id, revision, state, reason) {
|
|
149
161
|
return this.locked(async () => {
|
|
150
162
|
const current = await this.get(id);
|
|
@@ -158,6 +170,7 @@ class GithubReviews {
|
|
|
158
170
|
}
|
|
159
171
|
}
|
|
160
172
|
exports.GithubReviews = GithubReviews;
|
|
173
|
+
// Load the optional GitHub review backend for the active profile.
|
|
161
174
|
function githubReviews(store) {
|
|
162
175
|
const file = store.safePath(store.profile ?? 'default', 'review.jsonc');
|
|
163
176
|
if (!fs.existsSync(file))
|
package/dist/brain/projects.js
CHANGED
|
@@ -14,7 +14,7 @@ const project_1 = require("@technomoron/agent-run/dist/project");
|
|
|
14
14
|
const utils_1 = require("@technomoron/agent-run/dist/utils");
|
|
15
15
|
const config_1 = require("./config");
|
|
16
16
|
const store_1 = require("./store");
|
|
17
|
-
|
|
17
|
+
// Initialize external Brain storage, templates and profile directories.
|
|
18
18
|
function initializeBrain(configRoot, cwd) {
|
|
19
19
|
if ((0, utils_1.isSamePathOrDescendant)(path.resolve(configRoot), (0, project_1.findProjectRoot)(cwd)))
|
|
20
20
|
throw new Error('Brain configuration must live outside the source repository.');
|
|
@@ -40,21 +40,18 @@ function initializeBrain(configRoot, cwd) {
|
|
|
40
40
|
for (const directory of directories)
|
|
41
41
|
initializeScopeDirectories(store, directory);
|
|
42
42
|
});
|
|
43
|
-
for (const [name, skill] of Object.entries((0, built_in_skills_1.readBuiltInSkills)())) {
|
|
44
|
-
const destination = store.safePath('global', 'skills', name, 'SKILL.md');
|
|
45
|
-
if (!fs.existsSync(destination))
|
|
46
|
-
store.atomicWrite(destination, `---\n${(0, yaml_1.stringify)({ name, description: skill.description })}---\n\n${skill.content}\n`);
|
|
47
|
-
}
|
|
48
43
|
}
|
|
49
44
|
finally {
|
|
50
45
|
store.close();
|
|
51
46
|
}
|
|
52
47
|
}
|
|
48
|
+
// Create the knowledge, skill, task and template directories for a scope.
|
|
53
49
|
function initializeScopeDirectories(store, directory) {
|
|
54
50
|
for (const folder of [...Object.values(store_1.knowledgeDirectories), 'skills', 'todo', 'templates']) {
|
|
55
51
|
store.directory(directory, folder);
|
|
56
52
|
}
|
|
57
53
|
}
|
|
54
|
+
// Detect source languages, package scripts and the Git origin.
|
|
58
55
|
function inspectProject(cwd) {
|
|
59
56
|
const root = (0, project_1.findProjectRoot)(cwd);
|
|
60
57
|
const git = (0, node_child_process_1.spawnSync)('git', ['-C', root, 'config', '--get', 'remote.origin.url'], { encoding: 'utf8', shell: false });
|
|
@@ -68,6 +65,7 @@ function inspectProject(cwd) {
|
|
|
68
65
|
packageManager: fs.existsSync(path.join(root, 'pnpm-lock.yaml')) ? 'pnpm' : fs.existsSync(pkg) ? 'npm' : undefined,
|
|
69
66
|
documents: ['README.md', 'AGENTS.md', 'CLAUDE.md'].filter((file) => fs.existsSync(path.join(root, file))), scripts };
|
|
70
67
|
}
|
|
68
|
+
// Register a source project using detected or interactively supplied settings.
|
|
71
69
|
async function createBrainProject(configRoot, cwd, name, mode) {
|
|
72
70
|
config_1.projectConfigSchema.shape.name.parse(name);
|
|
73
71
|
const detected = inspectProject(cwd);
|
|
@@ -22,7 +22,7 @@ exports.remoteConfigSchema = zod_1.z.object({
|
|
|
22
22
|
accessSecretEnv: envName.default('MCP_OAUTH_ACCESS_SECRET'), refreshSecretEnv: envName.default('MCP_OAUTH_REFRESH_SECRET'),
|
|
23
23
|
listen: zod_1.z.object({ host: zod_1.z.literal('127.0.0.1').default('127.0.0.1'), port: zod_1.z.number().int().min(1).max(65535).default(3000), socket: absolute.optional() }).strict().default({ host: '127.0.0.1', port: 3000 }),
|
|
24
24
|
users: zod_1.z.array(zod_1.z.object({ subject: zod_1.z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/), login: zod_1.z.string().min(1).max(200),
|
|
25
|
-
kind: zod_1.z.enum(['human', 'service']).default('human'), passwordHashEnv: envName.optional(), totpSecretEnv: envName.optional(), disabled: zod_1.z.boolean().default(false) }).strict()),
|
|
25
|
+
kind: zod_1.z.enum(['human', 'service']).default('human'), passwordEnv: envName.optional(), passwordHashEnv: envName.optional(), totpSecretEnv: envName.optional(), disabled: zod_1.z.boolean().default(false) }).strict()),
|
|
26
26
|
clients: zod_1.z.array(zod_1.z.object({ id: zod_1.z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/), kind: zod_1.z.enum(['public', 'confidential', 'service']).default('public'),
|
|
27
27
|
secretEnv: envName.optional(), subject: zod_1.z.string().optional(), redirectUris: zod_1.z.array(zod_1.z.string().url()).default([]),
|
|
28
28
|
repos: zod_1.z.array(repositories_1.repositoryPattern).min(1), permissions: zod_1.z.array(exports.permission).min(1) }).strict()),
|
|
@@ -30,6 +30,7 @@ exports.remoteConfigSchema = zod_1.z.object({
|
|
|
30
30
|
groups: zod_1.z.array(zod_1.z.object({ id: zod_1.z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/), configRoot: absolute }).strict()).default([]),
|
|
31
31
|
repositories: zod_1.z.array(zod_1.z.object({ id: repositories_1.repositoryId, configRoot: absolute, cwd: absolute, group: zod_1.z.string().optional() }).strict())
|
|
32
32
|
}).strict();
|
|
33
|
+
// Validate remote configuration and its identity and repository relationships.
|
|
33
34
|
function readRemoteConfig(file) {
|
|
34
35
|
const errors = [];
|
|
35
36
|
const value = (0, jsonc_parser_1.parse)(fs.readFileSync(file, 'utf8'), errors, { allowTrailingComma: true });
|
|
@@ -43,8 +44,10 @@ function readRemoteConfig(file) {
|
|
|
43
44
|
for (const user of config.users) {
|
|
44
45
|
if (config.users.some((other) => other.subject !== user.subject && other.subject === user.login))
|
|
45
46
|
throw new Error('Logins must not alias another subject');
|
|
46
|
-
if (
|
|
47
|
-
throw new Error('
|
|
47
|
+
if (user.passwordEnv && user.passwordHashEnv)
|
|
48
|
+
throw new Error('Choose passwordEnv or passwordHashEnv, not both');
|
|
49
|
+
if (!user.disabled && user.kind === 'human' && !user.passwordHashEnv && !user.passwordEnv)
|
|
50
|
+
throw new Error('Human users require passwordEnv or passwordHashEnv');
|
|
48
51
|
}
|
|
49
52
|
for (const client of config.clients) {
|
|
50
53
|
if (client.kind !== 'public' && !client.secretEnv)
|
|
@@ -64,6 +67,7 @@ function readRemoteConfig(file) {
|
|
|
64
67
|
/** A declared group may share a root; unrelated groups and repositories must remain isolated. */
|
|
65
68
|
function validateRepositoryRoots(config, canonical = false) {
|
|
66
69
|
if (config.dataRoot) {
|
|
70
|
+
// Resolve a configured root, following symlinks only for canonical validation.
|
|
67
71
|
const resolve = (value) => canonical ? fs.realpathSync(value) : path.resolve(value);
|
|
68
72
|
if (config.repositories.some((repo) => resolve(repo.configRoot) !== resolve(config.dataRoot)) || config.groups.some((group) => resolve(group.configRoot) !== resolve(config.dataRoot)))
|
|
69
73
|
throw new Error('All repositories and pools must use the central dataRoot');
|
|
@@ -73,6 +77,7 @@ function validateRepositoryRoots(config, canonical = false) {
|
|
|
73
77
|
}
|
|
74
78
|
if (new Set(config.groups.map((g) => g.id)).size !== config.groups.length)
|
|
75
79
|
throw new Error('Group IDs must be unique');
|
|
80
|
+
// Resolve a configured root, following symlinks only for canonical validation.
|
|
76
81
|
const resolve = (value) => canonical ? fs.realpathSync(value) : path.resolve(value);
|
|
77
82
|
for (const repo of config.repositories)
|
|
78
83
|
if (repo.group !== undefined) {
|
|
@@ -85,11 +90,13 @@ function validateRepositoryRoots(config, canonical = false) {
|
|
|
85
90
|
for (let i = 0; i < roots.length; i++)
|
|
86
91
|
for (let j = i + 1; j < roots.length; j++) {
|
|
87
92
|
const a = roots[i].root, b = roots[j].root;
|
|
93
|
+
// Check whether one storage root contains another.
|
|
88
94
|
const overlaps = (from, to) => { const relative = path.relative(from, to); return !relative || (relative !== '..' && !relative.startsWith('..' + path.sep) && !path.isAbsolute(relative)); };
|
|
89
95
|
if (overlaps(a, b) || overlaps(b, a))
|
|
90
96
|
throw new Error('Repository and group data roots must be separate and non-overlapping');
|
|
91
97
|
}
|
|
92
98
|
}
|
|
99
|
+
// Check requested OAuth scopes against the current user and client grants.
|
|
93
100
|
function allowedGrant(config, subject, clientId, scopes) {
|
|
94
101
|
const user = config.users.find((u) => u.subject === subject && !u.disabled);
|
|
95
102
|
const client = config.clients.find((c) => c.id === clientId);
|
|
@@ -103,6 +110,7 @@ function allowedGrant(config, subject, clientId, scopes) {
|
|
|
103
110
|
operations.every((operation) => client.permissions.includes(operation) && config.access.some((rule) => rule.subject === subject &&
|
|
104
111
|
rule.permissions.includes(operation) && rule.repos.some((pattern) => (0, repositories_1.coversPattern)(pattern, repo)))));
|
|
105
112
|
}
|
|
113
|
+
// Intersect current user, client and token permissions for one repository.
|
|
106
114
|
function repositoryPermissions(config, subject, clientId, scopes, repo) {
|
|
107
115
|
const client = config.clients.find((c) => c.id === clientId);
|
|
108
116
|
const user = config.users.find((u) => u.subject === subject && !u.disabled);
|
|
@@ -115,6 +123,7 @@ function repositoryPermissions(config, subject, clientId, scopes, repo) {
|
|
|
115
123
|
}
|
|
116
124
|
const readTools = new Set(['list_repositories', 'list_repository_groups', 'brain_status', 'get_context', 'search_knowledge', 'list_knowledge', 'knowledge_history', 'get_knowledge', 'list_skills', 'get_skill', 'review_context', 'review_list', 'review_get', 'review_history', 'todo_list', 'todo_get']);
|
|
117
125
|
const reviewTools = new Set(['review_create', 'review_update', 'resolve_review']);
|
|
126
|
+
// Classify a tool by required permission and reject unsupported remote tools.
|
|
118
127
|
function toolPermission(name) {
|
|
119
128
|
if (readTools.has(name))
|
|
120
129
|
return 'read';
|