total-recall-brain 3.41.6 → 3.42.0

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 (86) hide show
  1. package/package.json +1 -1
  2. package/scaffold/.agent/skills/total-recall/plugins/auth/package-lock.json +3118 -17
  3. package/scaffold/.agent/skills/total-recall/plugins/auth/package.json +7 -2
  4. package/scaffold/.agent/skills/total-recall/plugins/auth/src/cli-secret.mjs +84 -40
  5. package/scaffold/.agent/skills/total-recall/plugins/auth/src/exit-after-flush.mjs +22 -0
  6. package/scaffold/.agent/skills/total-recall/plugins/auth/src/provider-api-rotation.mjs +61 -6
  7. package/scaffold/.agent/skills/total-recall/plugins/auth/src/provider-catalog.mjs +1 -0
  8. package/scaffold/.agent/skills/total-recall/plugins/auth/src/secrets-remote-deploy.mjs +8 -0
  9. package/scaffold/.agent/skills/total-recall/plugins/auth/src/secrets-rotate.mjs +20 -1
  10. package/scaffold/.agent/skills/total-recall/plugins/auth/src/secrets-store.mjs +3 -0
  11. package/scaffold/.agent/skills/total-recall/plugins/code-quality/core/state.mjs +15 -7
  12. package/scaffold/.agent/skills/total-recall/plugins/code-quality/package-lock.json +4 -4
  13. package/scaffold/.agent/skills/total-recall/plugins/composable-cli/package-lock.json +4 -4
  14. package/scaffold/.agent/skills/total-recall/plugins/embeddings/package-lock.json +4 -4
  15. package/scaffold/.agent/skills/total-recall/plugins/git-sentinel/package-lock.json +4 -4
  16. package/scaffold/.agent/skills/total-recall/plugins/mesh/package-lock.json +4 -4
  17. package/scaffold/.agent/skills/total-recall/plugins/meta-harness/README.md +51 -7
  18. package/scaffold/.agent/skills/total-recall/plugins/meta-harness/cli.mjs +67 -25
  19. package/scaffold/.agent/skills/total-recall/plugins/meta-harness/package-lock.json +4 -4
  20. package/scaffold/.agent/skills/total-recall/plugins/meta-harness/plugin.json +52 -6
  21. package/scaffold/.agent/skills/total-recall/plugins/meta-harness/skills/meta-harness/SKILL.md +1 -1
  22. package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/cascade.mjs +21 -8
  23. package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/compat-harness.mjs +110 -0
  24. package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/coordinator.mjs +48 -22
  25. package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/dispatch.mjs +9 -4
  26. package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/documentation.mjs +21 -9
  27. package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/executor.mjs +9 -5
  28. package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/gate.mjs +10 -4
  29. package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/learner.mjs +30 -3
  30. package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/paths.mjs +6 -1
  31. package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/pool.mjs +19 -3
  32. package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/process-manager.mjs +222 -0
  33. package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/process-worker.mjs +18 -0
  34. package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/reasoning.mjs +94 -0
  35. package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/remote-operation.mjs +70 -0
  36. package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/review.mjs +60 -19
  37. package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/router.mjs +32 -7
  38. package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/termination.mjs +24 -0
  39. package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/threads.mjs +88 -125
  40. package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/worker.mjs +110 -29
  41. package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/worktree.mjs +35 -0
  42. package/scaffold/.agent/skills/total-recall/plugins/meta-harness/ui/card.js +95 -5
  43. package/scaffold/.agent/skills/total-recall/plugins/openwiki/cli.mjs +13 -1
  44. package/scaffold/.agent/skills/total-recall/plugins/openwiki/package-lock.json +5 -5
  45. package/scaffold/.agent/skills/total-recall/plugins/openwiki/plugin.json +78 -0
  46. package/scaffold/.agent/skills/total-recall/plugins/openwiki/src/context-provider.mjs +113 -0
  47. package/scaffold/.agent/skills/total-recall/plugins/security/package-lock.json +4 -4
  48. package/src/cli/agent.mjs +11 -6
  49. package/src/cli/compact.mjs +3 -3
  50. package/src/cli/context.mjs +52 -19
  51. package/src/cli/harness.mjs +65 -147
  52. package/src/cli/init.mjs +4 -2
  53. package/src/cli/preflight.mjs +56 -13
  54. package/src/core/agent-manager.mjs +23 -329
  55. package/src/core/context-compactor.mjs +2 -1
  56. package/src/core/context-compiler.mjs +16 -25
  57. package/src/core/context-providers.mjs +69 -0
  58. package/src/core/meta-harness.mjs +27 -749
  59. package/src/core/plugin-runner.mjs +12 -5
  60. package/src/core/plugin-runtime.mjs +4 -2
  61. package/src/core/runtime.mjs +30 -604
  62. package/src/core/task-context.mjs +122 -0
  63. package/src/server/routes/context.mjs +4 -1
  64. package/scaffold/.agent/skills/decision/SKILL.md +0 -20
  65. package/scaffold/.agent/skills/decision/references/integration.md +0 -25
  66. package/scaffold/.agent/skills/decision/references/use-cases.md +0 -20
  67. package/scaffold/.agent/skills/meta-harness/SKILL.md +0 -15
  68. package/scaffold/.agent/skills/meta-harness/references/optimized/index.md +0 -20
  69. package/scaffold/.agent/skills/meta-harness/references/optimized/manifest.json +0 -79
  70. package/scaffold/.agent/skills/meta-harness/references/optimized/original.md +0 -135
  71. package/scaffold/.agent/skills/meta-harness/references/optimized/section-01.md +0 -5
  72. package/scaffold/.agent/skills/meta-harness/references/optimized/section-02.md +0 -17
  73. package/scaffold/.agent/skills/meta-harness/references/optimized/section-03.md +0 -8
  74. package/scaffold/.agent/skills/meta-harness/references/optimized/section-04.md +0 -2
  75. package/scaffold/.agent/skills/meta-harness/references/optimized/section-05.md +0 -6
  76. package/scaffold/.agent/skills/meta-harness/references/optimized/section-06.md +0 -14
  77. package/scaffold/.agent/skills/meta-harness/references/optimized/section-07.md +0 -8
  78. package/scaffold/.agent/skills/meta-harness/references/optimized/section-08.md +0 -4
  79. package/scaffold/.agent/skills/meta-harness/references/optimized/section-09.md +0 -20
  80. package/scaffold/.agent/skills/meta-harness/references/optimized/section-10.md +0 -6
  81. package/scaffold/.agent/skills/meta-harness/references/optimized/section-11.md +0 -5
  82. package/scaffold/.agent/skills/meta-harness/references/optimized/section-12.md +0 -7
  83. package/scaffold/.agent/skills/meta-harness/references/optimized/section-13.md +0 -4
  84. package/scaffold/.agent/skills/meta-harness/references/optimized/section-14.md +0 -7
  85. package/scaffold/.agent/skills/meta-harness/references/optimized/section-15.md +0 -9
  86. package/scaffold/.agent/skills/meta-harness/references/optimized/section-16.md +0 -5
@@ -12,7 +12,7 @@
12
12
  "@gregiteen/ssss-cli": "0.14.4"
13
13
  },
14
14
  "devDependencies": {
15
- "total-recall-brain": "3.41.4"
15
+ "total-recall-brain": "3.41.6"
16
16
  }
17
17
  },
18
18
  "node_modules/@alcalzone/ansi-tokenize": {
@@ -5529,9 +5529,9 @@
5529
5529
  }
5530
5530
  },
5531
5531
  "node_modules/total-recall-brain": {
5532
- "version": "3.41.4",
5533
- "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.41.4.tgz",
5534
- "integrity": "sha512-xn6Ye5R/fHT7JP/ZjNJwmpteG/jcD9dzErbYwE46ZGThVaGsP1H81avSn0ZOAuLdUFRSgsoEijiAEHSaUA/4uQ==",
5532
+ "version": "3.41.6",
5533
+ "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.41.6.tgz",
5534
+ "integrity": "sha512-ibJulU7/jxO9BwEzOaW54z9eBEQzanDfEFy8FS1yNnz/3QDhl9mqLFikLAXAlp34i5Ev4UC5KvjhNJa/sC49Rg==",
5535
5535
  "dev": true,
5536
5536
  "license": "MIT",
5537
5537
  "workspaces": [
@@ -5539,7 +5539,7 @@
5539
5539
  ],
5540
5540
  "dependencies": {
5541
5541
  "@simplewebauthn/server": "^13.3.2",
5542
- "@ssss/cli": "npm:@gregiteen/ssss-cli@0.14.3",
5542
+ "@ssss/cli": "npm:@gregiteen/ssss-cli@0.14.4",
5543
5543
  "bcrypt": "^6.0.0",
5544
5544
  "better-sqlite3": "^12.11.1",
5545
5545
  "cookie-parser": "^1.4.7",
@@ -5,6 +5,11 @@
5
5
  "version": "0.1.7",
6
6
  "description": "Multi-repo knowledge graph and documentation wiki engine for Total Recall.",
7
7
  "license": "MIT",
8
+ "runtime": {
9
+ "modules": {
10
+ "context-provider": "src/context-provider.mjs"
11
+ }
12
+ },
8
13
  "tasks": [
9
14
  {
10
15
  "intent": "Watch upstream OpenWiki repository and announce/propagate updates",
@@ -92,6 +97,79 @@
92
97
  "command": "openwiki",
93
98
  "handler": "./cli.mjs",
94
99
  "subcommands": [
100
+ {
101
+ "name": "context",
102
+ "description": "Retrieve task-relevant wiki and explicitly linked source evidence with provenance and freshness",
103
+ "effect": "read",
104
+ "output": "json",
105
+ "args": [
106
+ { "name": "task", "label": "Task description", "type": "string", "positional": true, "required": true },
107
+ { "name": "json", "label": "JSON output", "type": "boolean", "flag": "--json" }
108
+ ]
109
+ },
110
+ {
111
+ "name": "search",
112
+ "description": "Search evidence passages in workspace, registered-vault or mesh documentation hubs",
113
+ "effect": "read",
114
+ "output": "json",
115
+ "args": [
116
+ { "name": "query", "label": "Search terms", "type": "string", "positional": true, "required": true },
117
+ { "name": "allVaults", "label": "Search all registered vaults", "type": "boolean", "flag": "--all-vaults" },
118
+ { "name": "node", "label": "Mesh node", "type": "string", "flag": "--node" },
119
+ { "name": "limit", "label": "Maximum results", "type": "number", "flag": "--limit" },
120
+ { "name": "json", "label": "JSON output", "type": "boolean", "flag": "--json" }
121
+ ]
122
+ },
123
+ {
124
+ "name": "graph",
125
+ "description": "Extract documentation link topology as JSON, Mermaid or DOT",
126
+ "effect": "read",
127
+ "output": "json",
128
+ "args": [
129
+ { "name": "allVaults", "label": "Inspect all registered vaults", "type": "boolean", "flag": "--all-vaults" },
130
+ { "name": "node", "label": "Mesh node", "type": "string", "flag": "--node" },
131
+ { "name": "format", "label": "Graph format", "type": "choice", "options": ["json", "mermaid", "dot"], "flag": "--format" },
132
+ { "name": "json", "label": "JSON output", "type": "boolean", "flag": "--json" }
133
+ ]
134
+ },
135
+ {
136
+ "name": "generate",
137
+ "description": "Generate documentation for the selected registered repository or current workspace",
138
+ "effect": "write",
139
+ "output": "json",
140
+ "timeout_ms": 600000,
141
+ "args": [
142
+ { "name": "repo", "label": "Registered repository", "type": "string", "flag": "--repo" },
143
+ { "name": "node", "label": "Mesh node", "type": "string", "flag": "--node" },
144
+ { "name": "force", "label": "Regenerate existing pages", "type": "boolean", "flag": "--force" },
145
+ { "name": "dryRun", "label": "Describe generation without writing", "type": "boolean", "flag": "--dry-run" },
146
+ { "name": "json", "label": "JSON output", "type": "boolean", "flag": "--json" }
147
+ ]
148
+ },
149
+ {
150
+ "name": "token",
151
+ "description": "Inspect provider credential status or save a provider key through the shared auth owner",
152
+ "effect": "write",
153
+ "output": "json",
154
+ "args": [
155
+ { "name": "action", "label": "Credential action", "type": "choice", "options": ["status", "set"], "positional": true },
156
+ { "name": "provider", "label": "Credential provider", "type": "choice", "options": ["openrouter", "google"], "positional": true },
157
+ { "name": "value", "label": "Secret value through stdin", "type": "string", "secret": true },
158
+ { "name": "stdin", "label": "Read secret from stdin", "type": "boolean", "flag": "--stdin" },
159
+ { "name": "json", "label": "JSON output", "type": "boolean", "flag": "--json" }
160
+ ]
161
+ },
162
+ {
163
+ "name": "lint",
164
+ "description": "Inspect documentation links and orphaned hubs without rewriting files",
165
+ "effect": "read",
166
+ "output": "json",
167
+ "args": [
168
+ { "name": "allVaults", "label": "Inspect all registered vaults", "type": "boolean", "flag": "--all-vaults" },
169
+ { "name": "node", "label": "Mesh node", "type": "string", "flag": "--node" },
170
+ { "name": "json", "label": "JSON output", "type": "boolean", "flag": "--json" }
171
+ ]
172
+ },
95
173
  {
96
174
  "name": "status",
97
175
  "description": "Show which OpenWiki subcommands are implemented",
@@ -0,0 +1,113 @@
1
+ /** OpenWiki's native task evidence provider. Reads projections and explicit source vicinity; never generates. */
2
+ import fs from 'node:fs';
3
+ import path from 'node:path';
4
+ import crypto from 'node:crypto';
5
+ import { spawnSync } from 'node:child_process';
6
+ import { searchWikiHubs } from './search.mjs';
7
+ import { staleness } from './refresh.mjs';
8
+
9
+ const hash = text => crypto.createHash('sha256').update(text).digest('hex');
10
+ const STOP = new Set('the and for from with this that task implement should into through using before after all can how what does'.split(' '));
11
+ const termsOf = text => [...new Set((String(text).toLowerCase().match(/[\p{L}\p{N}_-]{3,}/gu) || []).filter(term => !STOP.has(term)))];
12
+ const within = (root, target) => { const relative = path.relative(root, target); return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative)); };
13
+ const sensitive = relative => relative.split(path.sep).some(part => ['.git', '.agent', '.agents', 'node_modules', 'dist', 'build', 'coverage', 'vault', 'memory-vault', 'memory-derived'].includes(part) || /^\.env(?:\.|$)|^secrets\.enc$|\.(?:pem|key|p12|pfx)$/i.test(part));
14
+ const TEXT_EXTENSIONS = new Set(['.md', '.mdx', '.mjs', '.cjs', '.js', '.ts', '.tsx', '.jsx', '.py', '.go', '.rs', '.sh', '.sql', '.json', '.yaml', '.yml', '.toml', '.css', '.html']);
15
+
16
+ function readSource(root, target) {
17
+ const file = fs.realpathSync(target), relative = path.relative(root, file);
18
+ if (!within(root, file) || sensitive(relative) || !TEXT_EXTENSIONS.has(path.extname(file).toLowerCase())) throw new Error(`reference is outside permitted workspace text: ${path.basename(target)}`);
19
+ if (fs.statSync(file).size > 512 * 1024) throw new Error(`reference exceeds the 512 KiB read limit: ${relative}`);
20
+ const text = fs.readFileSync(file, 'utf8');
21
+ if (text.includes('\0')) throw new Error(`binary reference skipped: ${relative}`);
22
+ return { file, relative, text, hash: hash(text) };
23
+ }
24
+
25
+ function excerpt(source, task, maxChars, anchorLine) {
26
+ const lines = source.text.split('\n'), terms = termsOf(task);
27
+ let anchor = Number.isInteger(anchorLine) ? Math.max(0, Math.min(lines.length - 1, anchorLine - 1)) : 0;
28
+ if (!Number.isInteger(anchorLine)) {
29
+ let best = -1;
30
+ lines.forEach((line, index) => {
31
+ const score = terms.filter(term => line.toLowerCase().includes(term)).length;
32
+ if (score > best) { anchor = index; best = score; }
33
+ });
34
+ }
35
+ let start = Math.max(0, anchor - 2), end = Math.min(lines.length, anchor + 3);
36
+ while (lines.slice(start, end).join('\n').length > maxChars && (start < anchor || end > anchor + 1)) {
37
+ if (anchor - start >= end - anchor - 1 && start < anchor) start++;
38
+ else end--;
39
+ }
40
+ let text = lines.slice(start, end).join('\n');
41
+ if (text.length > maxChars) {
42
+ const hits = terms.map(term => text.toLowerCase().indexOf(term)).filter(index => index >= 0);
43
+ const focus = hits.length ? Math.min(...hits) : 0;
44
+ const offset = Math.max(0, Math.min(text.length - maxChars, focus - Math.floor(maxChars / 3)));
45
+ text = text.slice(offset, offset + maxChars);
46
+ }
47
+ return { text: text.trim(), startLine: start + 1, endLine: end };
48
+ }
49
+
50
+ function references(passage, source, root) {
51
+ const found = [];
52
+ for (const match of passage.matchAll(/\[[^\]]*\]\(([^\s)]+)\)/g)) {
53
+ const raw = match[1];
54
+ if (/^[a-z][a-z\d+.-]*:/i.test(raw) || raw.startsWith('#')) continue;
55
+ const [file, anchor] = raw.split('#');
56
+ let decoded; try { decoded = decodeURIComponent(file); } catch { continue; }
57
+ found.push({ target: path.resolve(path.dirname(source.file), decoded), line: Number(anchor?.match(/^L(\d+)/i)?.[1]) || undefined });
58
+ }
59
+ for (const match of passage.matchAll(/\[\[([^\]|]+)(?:\|[^\]]+)?\]\]/g)) {
60
+ const file = match[1].endsWith('.md') ? match[1] : `${match[1]}.md`;
61
+ found.push({ target: path.resolve(root, 'openwiki', file) });
62
+ }
63
+ for (const match of passage.matchAll(/`((?:src|lib|test|tests|docs|scripts)\/[\w./-]+)(?::(\d+)(?:-\d+)?)?`/g)) {
64
+ found.push({ target: path.resolve(root, match[1]), line: Number(match[2]) || undefined });
65
+ }
66
+ return found;
67
+ }
68
+
69
+ export async function retrieveContext({ task, projectRoot = process.cwd(), limit = 6, maxChars = 1000, signal,
70
+ search = searchWikiHubs, inspectFreshness = staleness, git = spawnSync } = {}) {
71
+ const root = fs.realpathSync(projectRoot), terms = termsOf(task), diagnostics = [], candidates = [];
72
+ const cap = Math.min(6, Math.max(0, Number(limit) || 0)), chars = Math.min(1400, Math.max(1, Number(maxChars) || 1000));
73
+ if (!terms.length || !cap) return { candidates, diagnostics, coverage: { scope: 'workspace-hubs-and-explicit-source', ranking: 'lexical', repositoryFilesIndexed: false } };
74
+ signal?.throwIfAborted();
75
+ const boundedGit = (binary, args, options) => git(binary, args, { ...options, timeout: 1500 });
76
+ const fresh = inspectFreshness(root, { git: boundedGit });
77
+ const dirty = boundedGit('git', ['-C', root, 'status', '--porcelain', '--untracked-files=no'], { encoding: 'utf8' });
78
+ const workspaceChanged = dirty.status === 0 && String(dirty.stdout || '').split('\n').some(line => line.trim() && !line.slice(3).startsWith('openwiki/'));
79
+ const freshness = fresh.stale ? true : !fresh.generatedAt || workspaceChanged || dirty.status !== 0 ? 'unknown' : false;
80
+ if (freshness !== false) diagnostics.push(`wiki freshness ${freshness === true ? 'stale' : 'unverified'}${fresh.commitsSince ? ` (${fresh.commitsSince} commits since generation)` : ''}${workspaceChanged ? '; workspace has uncommitted changes' : ''}`);
81
+ const result = await search(terms.join(' '), { cwd: root, allVaults: false, limit: cap * 2 });
82
+ const seen = new Set();
83
+ const add = (source, passage, score, kind, relatedTo) => {
84
+ const id = `${source.relative}:${passage.startLine}`;
85
+ if (seen.has(id) || !passage.text || candidates.length >= cap) return;
86
+ seen.add(id);
87
+ candidates.push({ id, title: source.relative, text: passage.text, score,
88
+ source: { path: source.file, hash: source.hash, kind, startLine: passage.startLine, endLine: passage.endLine, stale: kind === 'source' ? false : freshness },
89
+ ...(relatedTo ? { relatedTo } : {}) });
90
+ };
91
+ for (const hit of (result.results || []).slice(0, 3)) {
92
+ if (candidates.length >= cap) break;
93
+ signal?.throwIfAborted();
94
+ try {
95
+ const source = readSource(root, hit.path), passage = excerpt(source, task, chars, hit.line);
96
+ const id = `${source.relative}:${passage.startLine}`;
97
+ add(source, passage, Math.min(.9, Math.max(.2, hit.score / 100)), 'wiki');
98
+ // Expand only links present in this selected passage, never the page's unrelated navigation graph.
99
+ for (const ref of references(passage.text, source, root).slice(0, 2)) {
100
+ if (candidates.length >= cap) break;
101
+ try {
102
+ const target = readSource(root, ref.target), kind = target.relative.startsWith(`openwiki${path.sep}`) ? 'wiki' : 'source';
103
+ add(target, excerpt(target, task, chars, ref.line), .35, kind, id);
104
+ } catch (error) { diagnostics.push(String(error.message).slice(0, 160)); }
105
+ }
106
+ } catch (error) { diagnostics.push(String(error.message).slice(0, 160)); }
107
+ }
108
+ return { candidates, diagnostics: [...new Set(diagnostics)].slice(0, 5), coverage: {
109
+ scope: 'workspace-hubs-and-explicit-source', ranking: 'lexical', repositoryFilesIndexed: false,
110
+ hubsScanned: result.totalHubsScanned || 0, sourceExcerpts: candidates.filter(row => row.source.kind === 'source').length,
111
+ generatedAt: fresh.generatedAt, wikiFreshness: freshness,
112
+ } };
113
+ }
@@ -13,7 +13,7 @@
13
13
  },
14
14
  "devDependencies": {
15
15
  "jsdom": "^26.1.0",
16
- "total-recall-brain": "3.41.5"
16
+ "total-recall-brain": "3.41.6"
17
17
  }
18
18
  },
19
19
  "node_modules/@alcalzone/ansi-tokenize": {
@@ -5698,9 +5698,9 @@
5698
5698
  }
5699
5699
  },
5700
5700
  "node_modules/total-recall-brain": {
5701
- "version": "3.41.5",
5702
- "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.41.5.tgz",
5703
- "integrity": "sha512-gaW46xAtnFf+zfkv8LHYQLMzt27JjelyFggc8zAZafCnCJRbNSP8D02cbbcx49f3a70t/hkgA9RhJOY8HTqRFg==",
5701
+ "version": "3.41.6",
5702
+ "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.41.6.tgz",
5703
+ "integrity": "sha512-ibJulU7/jxO9BwEzOaW54z9eBEQzanDfEFy8FS1yNnz/3QDhl9mqLFikLAXAlp34i5Ev4UC5KvjhNJa/sC49Rg==",
5704
5704
  "dev": true,
5705
5705
  "license": "MIT",
5706
5706
  "workspaces": [
package/src/cli/agent.mjs CHANGED
@@ -1,7 +1,6 @@
1
1
  #!/usr/bin/env node
2
2
 
3
3
  import { listAgents, spawnAgent, killAgent, getAgentLogs } from '../core/agent-manager.mjs';
4
- import { detectHarnesses } from '../core/meta-harness.mjs';
5
4
  import { checkReceipt, findRoot, ACK_COMMAND } from '../core/preflight-receipt.mjs';
6
5
 
7
6
  function printHelp() {
@@ -28,10 +27,11 @@ Options:
28
27
  --tools <list> Built-in tools for the harness: default (all), none, or e.g. "Bash,Read,WebFetch"
29
28
  (alias --allow-tools; --no-tools = none). Spawns default to all tools.
30
29
  --setting-sources <list> Settings layers the harness loads (e.g. local, or user,project)
30
+ --read-only Run without persistent changes
31
+ --allow-unknown-auth Explicitly permit a harness without a verified login probe
31
32
 
32
33
  Auth:
33
- Claude Code reads CLAUDE_CODE_OAUTH_TOKEN (from \`claude setup-token\`) from the environment,
34
- else from the Total Recall secret store, so SSH/launchd sessions without a login keychain work.
34
+ The Meta Harness owner probes login and resolves only adapter-declared credentials through auth.
35
35
 
36
36
  Available Harnesses:
37
37
  agy, claude, codex, dsh, hermes, openclaw
@@ -54,6 +54,7 @@ const SPAWN_VALUE_FLAGS = {
54
54
  '--tools': 'tools',
55
55
  '--allow-tools': 'tools',
56
56
  '--setting-sources': 'settingSources',
57
+ '--model': 'model',
57
58
  };
58
59
 
59
60
  /**
@@ -61,7 +62,7 @@ const SPAWN_VALUE_FLAGS = {
61
62
  * they never leak into the task text; `--tools ""` is a real (empty) value.
62
63
  */
63
64
  export function parseSpawnArgs(rest) {
64
- const out = { detach: true, isJson: false, name: null, targetNode: null, cwd: undefined, tools: undefined, settingSources: undefined };
65
+ const out = { detach: true, isJson: false, name: null, targetNode: null, cwd: undefined, tools: undefined, settingSources: undefined, write: true, allowUnknownAuth: false };
65
66
  const positional = [];
66
67
  for (let i = 0; i < rest.length; i++) {
67
68
  const arg = rest[i];
@@ -79,6 +80,9 @@ export function parseSpawnArgs(rest) {
79
80
  else if (arg === '--no-detach') out.detach = false;
80
81
  else if (arg === '--detach') out.detach = true;
81
82
  else if (arg === '--no-tools') out.tools = 'none';
83
+ else if (arg === '--read-only') out.write = false;
84
+ else if (arg === '--write') out.write = true;
85
+ else if (arg === '--allow-unknown-auth') out.allowUnknownAuth = true;
82
86
  else if (arg.startsWith('--')) throw new Error(`Unknown option for agent spawn: ${arg}`);
83
87
  else positional.push(arg);
84
88
  }
@@ -137,7 +141,7 @@ export async function run(argv) {
137
141
  console.error(`Error: ${err.message}`);
138
142
  process.exit(1);
139
143
  }
140
- const { harness, task, detach, isJson, name, targetNode, cwd, tools, settingSources } = parsed;
144
+ const { harness, task, detach, isJson, name, targetNode, cwd, tools, settingSources, model, write, allowUnknownAuth } = parsed;
141
145
 
142
146
  if (!harness || !task) {
143
147
  console.error('Error: Please specify harness ID and task prompt.');
@@ -158,7 +162,8 @@ export async function run(argv) {
158
162
  const nodeStr = targetNode ? ` on mesh node \x1b[1;33m${targetNode}\x1b[0m` : '';
159
163
  if (!isJson) console.log(`\n🚀 Spawning agent on harness: \x1b[1;36m${harness}\x1b[0m${nodeStr}...`);
160
164
  try {
161
- const record = await spawnAgent(harness, task, { detach, name, node: targetNode, cwd, tools, settingSources });
165
+ const record = await spawnAgent(harness, task, { detach, name, node: targetNode, cwd, tools, settingSources, model, write, allowUnknownAuth });
166
+ if (record.status === 'failed') process.exitCode = 1;
162
167
  if (isJson) {
163
168
  console.log(JSON.stringify(record, null, 2));
164
169
  return;
@@ -55,10 +55,10 @@ function lexicalScore(terms, text) {
55
55
  }
56
56
 
57
57
  /** Rank the applicable rules against the task and fit them into `budget`. Shared by `compact` and `context`. */
58
- export async function compactNodes({ task, actions = [], budget, expand = [], complete = false, rank = true, nodes, skillsDir, derivedDirs, header }) {
58
+ export async function compactNodes({ task, actions = [], budget, expand = [], complete = false, rank = true, nodes, skillsDir, derivedDirs, header, supplemental = [], taskVector: suppliedVector }) {
59
59
  const rules = selectRules(curatedRules(nodes), { actions, projectRoot: process.cwd() });
60
60
  const vectors = loadVectors(derivedDirs);
61
- const taskVector = rank ? await embedTask(task) : null;
61
+ const taskVector = suppliedVector !== undefined ? suppliedVector : rank ? await embedTask(task) : null;
62
62
  const terms = String(task).toLowerCase().match(/[\p{L}\p{N}_-]{3,}/gu) || [];
63
63
  const semantic = Boolean(taskVector);
64
64
 
@@ -76,7 +76,7 @@ export async function compactNodes({ task, actions = [], budget, expand = [], co
76
76
  }
77
77
 
78
78
  const ranking = semantic ? 'semantic' : 'lexical';
79
- return { ranking, ...compactRules(items, { budget, expand, complete, header: (counts, tokens) => header(counts, tokens, ranking) }) };
79
+ return { ranking, ...compactRules(items, { budget, expand, complete, supplemental, header: (counts, tokens) => header(counts, tokens, ranking) }) };
80
80
  }
81
81
 
82
82
  export default async function compact(args = []) {
@@ -7,11 +7,11 @@ import { isBrainEnabled } from '../core/brain-registry.mjs';
7
7
  import { surfaceInputsHash } from '../core/command-surface.mjs';
8
8
  import { readConfigValue } from './config.mjs';
9
9
  import { recordCapsule } from '../core/context-telemetry.mjs';
10
+ import { estimateTokens } from '../core/context-policy.mjs';
11
+ import { summarizeRetrieval } from '../core/task-context.mjs';
10
12
 
11
13
  /** About 28 KB: harnesses save output over about 30 KB to a file instead of showing it, which agents then cannot read (audit C-005, F-019). */
12
14
  export const CAPSULE_LIMIT = 7000;
13
- const JSON_ESCAPE_SHARE = 0.97;
14
- const JSON_WRAPPER_TOKENS = 128;
15
15
 
16
16
  /** The merged rule nodes a capsule draws from, for the selected layer. */
17
17
  export function loadContextNodes(layer) {
@@ -22,7 +22,9 @@ export function loadContextNodes(layer) {
22
22
  const nodes = own ? mergeGlobalRuleNodes(getNodes(path.join(own, 'memory-vault')), global ? getNodes(path.join(global, 'memory-vault')) : []) :
23
23
  getNodes(path.join(global, 'memory-vault')).map(n => ({ ...n, _layer: 'global' }));
24
24
  return { nodes, skillsDir: path.dirname(own || global),
25
- derivedDirs: [own, global].filter(Boolean).map(dir => path.join(dir, 'memory-derived')) };
25
+ derivedDirs: [own, global].filter(Boolean).map(dir => path.join(dir, 'memory-derived')),
26
+ indexScopes: [own && { layer: 'project', derivedDir: path.join(own, 'memory-derived') },
27
+ global && { layer: 'global', derivedDir: path.join(global, 'memory-derived') }].filter(Boolean) };
26
28
  }
27
29
 
28
30
  /** The first lines of an automatically compacted capsule. `rules verify` measures with it too, so both agree on what fits. */
@@ -33,33 +35,64 @@ export const compactedHeader = (version, budget) => (counts, tokens, ranking) =>
33
35
  ].join('\n');
34
36
 
35
37
  /** Compact the over-budget capsule, or explain the budget it needs. `fullRequired` is what the uncompacted capsule would take. */
36
- async function printCompacted({ query, actions, budget, format, version, fullRequired, nodes, skillsDir, derivedDirs }) {
38
+ async function printCompacted({ query, actions, budget, format, version, nodes, skillsDir, derivedDirs, knowledge }) {
37
39
  const { compactNodes } = await import('./compact.mjs');
38
- // JSON escaping and its wrapper count against the budget too.
39
- const target = format === 'json' ? Math.floor(budget * JSON_ESCAPE_SHARE) - JSON_WRAPPER_TOKENS : budget;
40
40
  const header = compactedHeader(version, budget);
41
- let result;
41
+ const compact = target => compactNodes({ task: query, actions, budget: target, complete: true, nodes, skillsDir, derivedDirs, header,
42
+ supplemental: knowledge?.contributions || [], taskVector: knowledge?.queryVector });
43
+ const output = result => {
44
+ if (format !== 'json') return result.context;
45
+ const payload = { ready: true, compacted: true, ranking: result.ranking, context: result.context, counts: result.counts,
46
+ stats: { version, budget, retrieval: summarizeRetrieval(knowledge?.summary), token_measurement: 'estimated_chars_divided_by_four' } };
47
+ for (let index = 0; index < 10; index++) {
48
+ const tokens = estimateTokens(`${JSON.stringify(payload)}\n`);
49
+ if (tokens === payload.stats.total_tokens) break;
50
+ payload.stats.total_tokens = tokens;
51
+ }
52
+ return JSON.stringify(payload);
53
+ };
42
54
  try {
43
- result = await compactNodes({ task: query, actions, budget: Math.max(target, 1), complete: true, nodes, skillsDir, derivedDirs, header });
55
+ // Encoding inflates the capsule by a varying share, so search for the compaction target that fits.
56
+ let target = budget, low = 1, high = budget, best = null, floor = null;
57
+ for (let attempt = 0; attempt < 12 && low <= high; attempt++) {
58
+ let result;
59
+ try { result = await compact(target); }
60
+ catch (error) {
61
+ if (!error.requiredBudget) throw error;
62
+ floor = error;
63
+ low = Math.max(target, error.requiredBudget > target ? error.requiredBudget : target + 1);
64
+ target = low;
65
+ continue;
66
+ }
67
+ const text = output(result), measured = estimateTokens(`${text}\n`);
68
+ if (measured <= budget) {
69
+ best = text;
70
+ if (budget - measured <= Math.max(16, budget * 0.02)) break;
71
+ low = target + 1;
72
+ // Any target above the text it actually produced yields the same text, so step below that.
73
+ } else high = Math.min(target, result.tokens ?? target) - 1;
74
+ const projected = Math.floor(target * budget / measured);
75
+ target = projected >= low && projected <= high ? projected : Math.floor((low + high) / 2);
76
+ }
77
+ if (best !== null) { console.log(best); return; }
78
+ if (floor) throw floor;
79
+ throw new Error('Context wire accounting did not converge');
44
80
  } catch (error) {
45
81
  if (!error.requiredBudget) throw error;
46
- const floor = format === 'json' ? Math.ceil((error.requiredBudget + JSON_WRAPPER_TOKENS) / JSON_ESCAPE_SHARE) : error.requiredBudget;
47
- const requiredBudget = Math.min(fullRequired, floor);
82
+ // Measure the actual floor through the same encoder; leave room for the changed budget digits on retry.
83
+ const floor = await compact(error.requiredBudget);
84
+ const requiredBudget = estimateTokens(`${output(floor)}\n`) + 16;
48
85
  console.log(format === 'json'
49
86
  ? JSON.stringify({ ready: false, reason: 'budget-overflow', context: '', stats: { version, budget, required_budget: requiredBudget, overage: requiredBudget - budget, rules: error.ruleCount, token_measurement: 'estimated_chars_divided_by_four' } })
50
87
  : `ready:false reason:budget-overflow budget:${budget} required_budget:${requiredBudget} overage:${requiredBudget - budget} rules:${error.ruleCount} version:${version}\nThis budget cannot hold all ${error.ruleCount} applicable rules even compacted; \`total-recall rules audit\` lists them by size. Retry with --budget ${requiredBudget}; do not act until ready:true.`);
51
88
  process.exitCode = 2;
52
89
  return;
53
90
  }
54
- console.log(format === 'json'
55
- ? JSON.stringify({ ready: true, compacted: true, ranking: result.ranking, context: result.context, counts: result.counts,
56
- stats: { version, budget, total_tokens: result.tokens, token_measurement: 'estimated_chars_divided_by_four' } })
57
- : result.context);
58
91
  }
59
92
 
60
93
  export default async function context(args = []) {
61
94
  if (!args.length || args.includes('--help')) {
62
- console.log(`Usage: total-recall context "task" [--action edit,test,publish] [--budget ${CAPSULE_LIMIT}] [--format text|json] [--knowledge] [--debug] [--project|--global]\nLocal rules only by default. Unknown applicability is required. Over budget, the capsule compacts automatically: absolute rules keep at least a summary and every other rule keeps at least its slug. Configured budgets are capped at ${CAPSULE_LIMIT}; pass a larger --budget to print the full capsule. Exit 2 means the budget cannot hold every rule; do not act until ready:true. --knowledge adds supporting documents; --debug exposes inventories within the same budget. Refresh on task/action/project or policy changes.`);
95
+ console.log(`Usage: total-recall context "task" [--action edit,test,publish] [--budget ${CAPSULE_LIMIT}] [--format text|json] [--knowledge] [--debug] [--project|--global]\nApplicable rules plus semantically retrieved task memory and active plugin evidence by default; unavailable vectors use a labelled lexical fallback. Unknown rule applicability is required. Over budget, compaction preserves selected task evidence and accounts for every rule: absolute rules keep at least a summary and every other rule keeps at least its slug. Configured budgets are capped at ${CAPSULE_LIMIT}; pass a larger --budget to print the full capsule. Exit 2 means the complete capsule cannot fit; do not act until ready:true. --knowledge remains accepted; --debug exposes retrieval inventories within the same budget. Refresh on task/action/project or policy changes.`);
63
96
  return;
64
97
  }
65
98
  const { layer, remainingArgs } = parseLayerFlag(args);
@@ -73,7 +106,7 @@ export default async function context(args = []) {
73
106
  }
74
107
  return undefined;
75
108
  })();
76
- let actions = [], budget = Math.min(configuredBudget ?? CAPSULE_LIMIT, CAPSULE_LIMIT), format = 'text', includeKnowledge = false, debug = false;
109
+ let actions = [], budget = Math.min(configuredBudget ?? CAPSULE_LIMIT, CAPSULE_LIMIT), format = 'text', includeKnowledge = true, debug = false;
77
110
  for (let i = 1; i < remainingArgs.length; i++) {
78
111
  const flag = remainingArgs[i];
79
112
  if (flag === '--knowledge') { includeKnowledge = true; continue; }
@@ -84,10 +117,10 @@ export default async function context(args = []) {
84
117
  else if (flag === '--format' && ['json', 'text'].includes(value)) format = value;
85
118
  else throw new Error(`Unknown context option: ${flag}`);
86
119
  }
87
- const { nodes, skillsDir, derivedDirs } = loadContextNodes(layer);
120
+ const { nodes, skillsDir, derivedDirs, indexScopes } = loadContextNodes(layer);
88
121
  const derivedDir = derivedDirs[0];
89
122
  const result = await compileContext({ query, actions, nodes, includeKnowledge, budget: { total: budget }, projectRoot: process.cwd(),
90
- derivedDir, contributions: legacyRuleContributions(skillsDir), versionInputs: surfaceInputsHash({ skillsDir }) });
123
+ derivedDir, indexScopes, contributions: legacyRuleContributions(skillsDir), versionInputs: surfaceInputsHash({ skillsDir }) });
91
124
  if (debug && format === 'text') throw new Error('--debug requires --format json');
92
125
  const response = capsuleResponse(result, { total: budget, debug, format });
93
126
  // Measured before the admission branch, so a capsule that failed to fit is
@@ -98,7 +131,7 @@ export default async function context(args = []) {
98
131
  derivedDir, action: actions, query, consumer: 'cli',
99
132
  });
100
133
  if (!response.ready && !debug) {
101
- await printCompacted({ query, actions, budget, format, version: response.stats.version, fullRequired: response.stats.total_tokens + 32, nodes, skillsDir, derivedDirs });
134
+ await printCompacted({ query, actions, budget, format, version: response.stats.version, nodes, skillsDir, derivedDirs, knowledge: result.taskKnowledge });
102
135
  return;
103
136
  }
104
137
  console.log(renderCapsule(response, format));