@technomoron/agent-brain 0.1.0 → 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.
Files changed (48) hide show
  1. package/CHANGES.md +25 -0
  2. package/README.md +22 -15
  3. package/dist/brain/built-in-skills.js +2 -0
  4. package/dist/brain/cli.js +8 -0
  5. package/dist/brain/config.js +7 -0
  6. package/dist/brain/connectors.js +2 -0
  7. package/dist/brain/consolidation.js +4 -0
  8. package/dist/brain/git.js +9 -2
  9. package/dist/brain/github-reviews.js +13 -0
  10. package/dist/brain/projects.js +4 -6
  11. package/dist/brain/remote-policy.js +12 -3
  12. package/dist/brain/remote-server.js +54 -12
  13. package/dist/brain/repositories.js +3 -0
  14. package/dist/brain/repository-discovery.js +4 -1
  15. package/dist/brain/server.js +14 -2
  16. package/dist/brain/skills.js +11 -0
  17. package/dist/brain/store.js +36 -1
  18. package/dist/brain/todos.js +10 -1
  19. package/dist/brain/windows-pipe.js +2 -1
  20. package/dist/version.js +1 -4
  21. package/examples/remote.jsonc +1 -1
  22. package/ops/brain-pipe-security.ps1 +40 -0
  23. package/ops/config-deploy-root.cjs +6 -0
  24. package/ops/config-deploy.cjs +11 -4
  25. package/ops/config-policy.cjs +18 -2
  26. package/ops/config-sync.cjs +34 -1
  27. package/package.json +2 -2
  28. package/skills/brain-consolidate/README.md +5 -0
  29. package/skills/brain-import/README.md +5 -0
  30. package/skills/brain-memory/README.md +5 -0
  31. package/skills/brain-memory/SKILL.md +7 -3
  32. package/skills/code-review/README.md +7 -0
  33. package/skills/code-review/SKILL.md +26 -0
  34. package/skills/git-workflow/README.md +5 -0
  35. package/skills/git-workflow/SKILL.md +14 -0
  36. package/skills/node-cleanup/README.md +5 -0
  37. package/skills/node-cleanup/SKILL.md +239 -0
  38. package/skills/node-cleanup/agents/openai.yaml +4 -0
  39. package/skills/package-integrity-check/README.md +5 -0
  40. package/skills/package-integrity-check/SKILL.md +27 -0
  41. package/skills/todo-manager/README.md +5 -0
  42. package/skills/todo-manager/SKILL.md +9 -3
  43. package/skills/unslop/README.md +5 -0
  44. package/skills/unslop/SKILL.md +177 -0
  45. package/skills/unslop/agents/openai.yaml +4 -0
  46. package/skills/brain-review/SKILL.md +0 -38
  47. package/skills/code-review-organizer/SKILL.md +0 -150
  48. package/skills/review-items/SKILL.md +0 -43
package/CHANGES.md CHANGED
@@ -1,3 +1,28 @@
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
+
22
+ Version 0.1.1 (2026-10-22)
23
+ --------------------------
24
+ * Allow independent repositories without a pool in configuration deployment and Git sync.
25
+
1
26
  Version 0.1.0 (2026-10-22)
2
27
  --------------------------
3
28
  * Extract the project knowledge and skills MCP server from agent-run.
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 owns the Markdown sources under `skills/`: `brain-consolidate`, `brain-import`, `brain-memory`, `brain-review`, `code-review-organizer`, `review-items`, and `todo-manager`. These were extracted from the current external shared skill set on 2026-10-16. The project-specific consolidation copy was identical and is represented once.
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
- Initialization reads these packaged sources and installs missing skills into the external global skill directory. Existing customized installations are preserved. Consolidation’s CLI fallback also reads its packaged Markdown source; there is no separate embedded copy of that workflow. The existing ordinary-conversation retrieval and task-authorization guards are retained in the packaged memory and task skills.
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
- Keep MCP-owned skills and tools with this implementation. Independent reusable skills belong in the private catalog. The live configuration is unchanged by the source extraction; use initialization explicitly when installing missing packaged skills.
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`. Human passwords are bcrypt hashes supplied through the
85
- configured environment variables; optional TOTP secrets are base32 values enrolled
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. Packaged review skills
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/ # knowledge and skills shared by all repositories
215
- pools/documentmedia/ # knowledge and skills shared by this pool
216
- projects/documentmedia/doc-api/ # repository knowledge, reviews and tasks
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: documentmedia` in each member's `projects/<owner>/<repo>/config.yaml`.
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`.
@@ -226,6 +229,9 @@ does not replace an explicit user constraint.
226
229
  For a remote server, set `dataRoot` to this shared configuration root and use
227
230
  that same `configRoot` for its groups and repositories. The existing `group`
228
231
  registration identifies the pool and must match the project's `pool` field.
232
+ For independent repositories, omit `pool` from both the project and deployment
233
+ manifest, and omit `group` from the remote registration. They receive global
234
+ and project context without sharing a pool.
229
235
  Legacy separate group roots remain supported when `dataRoot` is absent.
230
236
  Global writes require a wildcard token and current wildcard write permission.
231
237
  Pool writes require write permission for every registered member. Reading a
@@ -646,9 +652,7 @@ including template. Nunjucks variables remain available. Symlinks are rejected,
646
652
  and each file is limited to 1 MiB. Move snippets and skill overrides stored
647
653
  elsewhere into these directories before rendering or loading those skills.
648
654
 
649
- The installed `brain-memory`, `brain-consolidate`, `brain-review`, and `todo-manager`
650
- skills describe retrieval, persistence, consolidation, review learning, and task workflows. Review records use
651
- 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`.
652
656
 
653
657
  ### Tasks and connectors
654
658
 
@@ -743,6 +747,7 @@ not identify Brain as the target. Agents still need a user request or standing
743
747
  authorization to sync.
744
748
 
745
749
  Saving includes Markdown knowledge, skills, tasks, project metadata, and `.gitignore`.
750
+ Skill support files and tracked skill/task deletions are included.
746
751
  It also includes all regular files under each scope's `templates/` directory,
747
752
  including nested Nunjucks templates and supporting files. Template additions,
748
753
  edits, and deletions are synced; symlinks are rejected.
@@ -851,3 +856,5 @@ Transport and connector implementations follow the
851
856
  [Node MCP SDK server documentation](https://ts.sdk.modelcontextprotocol.io/server),
852
857
  [GitHub Issues REST API](https://docs.github.com/en/rest/issues/issues), and
853
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;
@@ -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)))
@@ -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', 'notes', ...Object.values(store_1.knowledgeDirectories)].map((folder) => path.relative(store.configRoot, path.join(root, folder))));
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))
@@ -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
- const built_in_skills_1 = require("./built-in-skills");
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 (!user.disabled && user.kind === 'human' && !user.passwordHashEnv)
47
- throw new Error('Human users require passwordHashEnv');
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';