@apralabs/apra-fleet 0.4.4 → 0.4.5
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/README.md +49 -4
- package/dist/agents/backlog-groomer.md +5 -0
- package/dist/agents/ci-watcher.md +5 -0
- package/dist/agents/deployer.md +20 -2
- package/dist/agents/doer.md +38 -2
- package/dist/agents/harvester.md +12 -9
- package/dist/agents/integ-test-runner.md +5 -0
- package/dist/agents/kb-reconciler.md +6 -0
- package/dist/agents/plan-reviewer.md +5 -0
- package/dist/agents/planner.md +5 -0
- package/dist/agents/regression-test-runner.md +5 -0
- package/dist/agents/reviewer.md +67 -15
- package/dist/agents/schemas/deployer-output.json +5 -0
- package/dist/agents/schemas/doer-output.json +78 -2
- package/dist/agents/schemas/reviewer-output.json +104 -2
- package/dist/cli/auth.js +5 -1
- package/dist/cli/beads-pin.js +6 -7
- package/dist/cli/claude-mod.d.ts +75 -0
- package/dist/cli/claude-mod.js +288 -0
- package/dist/cli/dolt-install.d.ts +1 -1
- package/dist/cli/dolt-install.js +5 -1
- package/dist/cli/fleet-se-guard.d.ts +8 -0
- package/dist/cli/fleet-se-guard.js +19 -3
- package/dist/cli/install-guard.d.ts +9 -0
- package/dist/cli/install-guard.js +24 -0
- package/dist/cli/install.d.ts +12 -0
- package/dist/cli/install.js +180 -20
- package/dist/cli/kb-profile.d.ts +16 -0
- package/dist/cli/kb-profile.js +81 -0
- package/dist/cli/start.js +3 -0
- package/dist/cli/uninstall.js +13 -3
- package/dist/cli/update.d.ts +4 -0
- package/dist/cli/update.js +19 -3
- package/dist/commands/kb-server.d.ts +10 -1
- package/dist/commands/kb-server.js +285 -11
- package/dist/index.js +22 -1
- package/dist/os/git-executable.d.ts +57 -0
- package/dist/os/git-executable.js +85 -0
- package/dist/os/go-concurrency.d.ts +44 -0
- package/dist/os/go-concurrency.js +53 -0
- package/dist/os/index.d.ts +1 -0
- package/dist/os/index.js +1 -0
- package/dist/os/linux.d.ts +2 -0
- package/dist/os/linux.js +10 -1
- package/dist/os/os-commands.d.ts +25 -0
- package/dist/os/os-commands.js +2 -0
- package/dist/os/windows-executable.d.ts +53 -0
- package/dist/os/windows-executable.js +185 -0
- package/dist/os/windows-gitbash.d.ts +23 -14
- package/dist/os/windows-gitbash.js +40 -16
- package/dist/os/windows.d.ts +2 -0
- package/dist/os/windows.js +37 -6
- package/dist/paths.d.ts +10 -1
- package/dist/paths.js +19 -2
- package/dist/services/agy-project.d.ts +7 -1
- package/dist/services/agy-project.js +7 -2
- package/dist/services/auth-socket.d.ts +18 -0
- package/dist/services/auth-socket.js +30 -4
- package/dist/services/credential-store.d.ts +33 -0
- package/dist/services/credential-store.js +79 -2
- package/dist/services/http-transport.d.ts +29 -0
- package/dist/services/http-transport.js +166 -37
- package/dist/services/kb-tool-profile.d.ts +36 -0
- package/dist/services/kb-tool-profile.js +88 -0
- package/dist/services/knowledge/bible-blob-id.js +10 -1
- package/dist/services/knowledge/bible-import.d.ts +108 -0
- package/dist/services/knowledge/bible-import.js +137 -4
- package/dist/services/knowledge/file-hash.js +6 -5
- package/dist/services/knowledge/http-provider.d.ts +303 -20
- package/dist/services/knowledge/http-provider.js +795 -125
- package/dist/services/knowledge/kb-config.d.ts +65 -1
- package/dist/services/knowledge/kb-config.js +143 -3
- package/dist/services/knowledge/kb-http-auth-state.d.ts +26 -0
- package/dist/services/knowledge/kb-http-auth-state.js +40 -0
- package/dist/services/knowledge/kb-providers.d.ts +9 -2
- package/dist/services/knowledge/kb-providers.js +67 -37
- package/dist/services/knowledge/kb-removed-scope-keys.js +1 -1
- package/dist/services/knowledge/kb-self.d.ts +122 -9
- package/dist/services/knowledge/kb-self.js +196 -36
- package/dist/services/knowledge/member-bible-view.js +16 -3
- package/dist/services/knowledge/path-validation.d.ts +7 -0
- package/dist/services/knowledge/path-validation.js +11 -0
- package/dist/services/knowledge/project-slug.js +3 -2
- package/dist/services/knowledge/repository-header.d.ts +77 -0
- package/dist/services/knowledge/repository-header.js +233 -0
- package/dist/services/knowledge/require-sqlite-project.d.ts +1 -1
- package/dist/services/knowledge/require-sqlite-project.js +1 -1
- package/dist/services/knowledge/sqlite-provider.d.ts +169 -0
- package/dist/services/knowledge/sqlite-provider.js +416 -4
- package/dist/services/knowledge/types.d.ts +15 -2
- package/dist/services/member-busy.d.ts +12 -0
- package/dist/services/member-busy.js +20 -0
- package/dist/services/member-config-io.d.ts +3 -2
- package/dist/services/member-config-io.js +7 -4
- package/dist/services/member-fleet-install.js +1 -0
- package/dist/services/member-tool-allowlist.d.ts +1 -1
- package/dist/services/member-tool-allowlist.js +8 -4
- package/dist/services/port-holder.js +2 -1
- package/dist/services/service-manager/types.d.ts +17 -1
- package/dist/services/service-manager/windows.d.ts +7 -2
- package/dist/services/service-manager/windows.js +28 -11
- package/dist/services/service-notice.d.ts +7 -0
- package/dist/services/service-notice.js +19 -0
- package/dist/services/session-registry.d.ts +13 -0
- package/dist/services/session-registry.js +13 -0
- package/dist/services/session-roots.d.ts +67 -0
- package/dist/services/session-roots.js +126 -0
- package/dist/services/statusline.d.ts +21 -0
- package/dist/services/statusline.js +97 -1
- package/dist/services/supervisor-service-cleanup.js +2 -1
- package/dist/services/tool-registry.js +108 -20
- package/dist/services/tool-scope.d.ts +34 -1
- package/dist/services/tool-scope.js +27 -2
- package/dist/services/vcs/azure-devops.js +10 -0
- package/dist/services/vcs/bitbucket.d.ts +22 -1
- package/dist/services/vcs/bitbucket.js +163 -17
- package/dist/services/vcs/types.d.ts +25 -2
- package/dist/services/watch/project-resolver.js +2 -1
- package/dist/skills/pm/cost.md +5 -1
- package/dist/skills/pm/index.md +9 -9
- package/dist/skills/pm/sprint.md +2 -1
- package/dist/tools/check-status.d.ts +51 -0
- package/dist/tools/check-status.js +124 -12
- package/dist/tools/code-intelligence-freshness.js +1 -1
- package/dist/tools/code-intelligence-gitnexus.d.ts +19 -0
- package/dist/tools/code-intelligence-gitnexus.js +166 -9
- package/dist/tools/code-intelligence-readiness.d.ts +58 -1
- package/dist/tools/code-intelligence-readiness.js +93 -8
- package/dist/tools/code-intelligence-reindex.d.ts +25 -1
- package/dist/tools/code-intelligence-reindex.js +76 -4
- package/dist/tools/code-intelligence.d.ts +1 -1
- package/dist/tools/code-intelligence.js +1 -1
- package/dist/tools/execute-command.js +14 -8
- package/dist/tools/execute-prompt.js +6 -2
- package/dist/tools/fleet-snapshot.d.ts +21 -0
- package/dist/tools/fleet-snapshot.js +78 -0
- package/dist/tools/kb-bible-commit.d.ts +25 -11
- package/dist/tools/kb-bible-commit.js +142 -33
- package/dist/tools/kb-capture.d.ts +2 -2
- package/dist/tools/kb-context.js +47 -27
- package/dist/tools/kb-demote.d.ts +27 -0
- package/dist/tools/kb-demote.js +37 -0
- package/dist/tools/kb-export.d.ts +35 -3
- package/dist/tools/kb-export.js +56 -13
- package/dist/tools/kb-feedback.d.ts +2 -0
- package/dist/tools/kb-feedback.js +17 -7
- package/dist/tools/kb-harvest.js +28 -9
- package/dist/tools/kb-import.d.ts +18 -2
- package/dist/tools/kb-import.js +24 -9
- package/dist/tools/kb-invalidate.d.ts +11 -3
- package/dist/tools/kb-invalidate.js +80 -7
- package/dist/tools/kb-list.js +38 -10
- package/dist/tools/kb-promote.js +6 -4
- package/dist/tools/kb-query.d.ts +3 -0
- package/dist/tools/kb-query.js +181 -37
- package/dist/tools/kb-session-prime.d.ts +4 -4
- package/dist/tools/kb-session-prime.js +89 -9
- package/dist/tools/kb-setup.d.ts +20 -0
- package/dist/tools/kb-setup.js +149 -11
- package/dist/tools/list-members.js +1 -1
- package/dist/tools/member-detail.js +7 -3
- package/dist/tools/provision-vcs-auth.d.ts +28 -3
- package/dist/tools/provision-vcs-auth.js +53 -7
- package/dist/tools/receive-files.js +7 -4
- package/dist/tools/send-files.js +5 -4
- package/dist/tools/send-message.d.ts +3 -0
- package/dist/tools/send-message.js +15 -2
- package/dist/tools/stop-prompt.js +3 -1
- package/dist/tools/vcs-credential-exec.d.ts +45 -3
- package/dist/tools/vcs-credential-exec.js +90 -11
- package/dist/utils/process-utils.js +5 -1
- package/dist/utils/redact-known-secrets.d.ts +17 -0
- package/dist/utils/redact-known-secrets.js +70 -0
- package/dist/utils/skill-matrix.js +1 -1
- package/dist/utils/vcs-provider-detect.js +2 -2
- package/dist/workflows/auto-sprint.js +245 -9
- package/package.json +10 -7
- package/packages/apra-fleet-client/package.json +1 -1
- package/packages/apra-fleet-client/src/client/api.mjs +172 -19
- package/packages/apra-fleet-client/src/client/reconnecting-transport.mjs +35 -2
- package/packages/apra-fleet-client/src/client/transport.mjs +6 -0
- package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/deployer.md +20 -2
- package/packages/apra-fleet-se/apra-pm/agents/doer.md +38 -2
- package/packages/apra-fleet-se/apra-pm/agents/harvester.md +12 -9
- package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +6 -0
- package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/planner.md +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +67 -15
- package/packages/apra-fleet-se/apra-pm/agents/schemas/deployer-output.json +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-output.json +78 -2
- package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json +104 -2
- package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +5 -1
- package/packages/apra-fleet-se/apra-pm/skills/pm/index.md +9 -9
- package/packages/apra-fleet-se/apra-pm/skills/pm/sprint.md +2 -1
- package/packages/apra-fleet-se/bin/cli.mjs +104 -31
- package/packages/apra-fleet-se/bin/serve.mjs +46 -8
- package/packages/apra-fleet-se/fleet-sprint/abort.mjs +184 -32
- package/packages/apra-fleet-se/fleet-sprint/bd-sync-command.mjs +69 -0
- package/packages/apra-fleet-se/fleet-sprint/beads-children.mjs +21 -0
- package/packages/apra-fleet-se/fleet-sprint/beads-lock-probe.mjs +176 -0
- package/packages/apra-fleet-se/fleet-sprint/beads-reachability.mjs +126 -0
- package/packages/apra-fleet-se/fleet-sprint/beads-scope.mjs +158 -1
- package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +82 -2
- package/packages/apra-fleet-se/fleet-sprint/coordination.mjs +23 -6
- package/packages/apra-fleet-se/fleet-sprint/decision-notify.mjs +338 -0
- package/packages/apra-fleet-se/fleet-sprint/decision-wait.mjs +731 -0
- package/packages/apra-fleet-se/fleet-sprint/decisions.mjs +372 -0
- package/packages/apra-fleet-se/fleet-sprint/dispatch-role.mjs +44 -11
- package/packages/apra-fleet-se/fleet-sprint/docs/README.md +4 -1
- package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +9 -3
- package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +314 -19
- package/packages/apra-fleet-se/fleet-sprint/errors.mjs +72 -4
- package/packages/apra-fleet-se/fleet-sprint/git-sync.mjs +7 -1
- package/packages/apra-fleet-se/fleet-sprint/git-topology.mjs +112 -1
- package/packages/apra-fleet-se/fleet-sprint/guarded-modules.mjs +36 -2
- package/packages/apra-fleet-se/fleet-sprint/kb.mjs +736 -101
- package/packages/apra-fleet-se/fleet-sprint/member-init-probe.mjs +1 -1
- package/packages/apra-fleet-se/fleet-sprint/member-provisioning.mjs +7 -1
- package/packages/apra-fleet-se/fleet-sprint/phases/deploy.mjs +49 -2
- package/packages/apra-fleet-se/fleet-sprint/phases/develop.mjs +206 -3
- package/packages/apra-fleet-se/fleet-sprint/phases/final-review.mjs +61 -3
- package/packages/apra-fleet-se/fleet-sprint/phases/harvest.mjs +81 -31
- package/packages/apra-fleet-se/fleet-sprint/phases/plan.mjs +7 -3
- package/packages/apra-fleet-se/fleet-sprint/phases/publish-pr.mjs +39 -14
- package/packages/apra-fleet-se/fleet-sprint/phases/re-review.mjs +17 -1
- package/packages/apra-fleet-se/fleet-sprint/phases/review.mjs +18 -3
- package/packages/apra-fleet-se/fleet-sprint/pr-body.mjs +14 -1
- package/packages/apra-fleet-se/fleet-sprint/prompts.mjs +32 -5
- package/packages/apra-fleet-se/fleet-sprint/runner.js +824 -98
- package/packages/apra-fleet-se/fleet-sprint/se-os-commands.mjs +4 -2
- package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +54 -1
- package/packages/apra-fleet-se/fleet-sprint/se-windows.mjs +29 -2
- package/packages/apra-fleet-se/fleet-sprint/set-aside.mjs +288 -0
- package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +3 -2
- package/packages/apra-fleet-se/fleet-sprint/sprint-args.mjs +20 -0
- package/packages/apra-fleet-se/fleet-sprint/sprint-report.mjs +21 -0
- package/packages/apra-fleet-se/fleet-sprint/sprint-state.mjs +9 -0
- package/packages/apra-fleet-se/fleet-sprint/vcs-auth.mjs +605 -32
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +811 -17
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +89 -1
- package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +225 -2
- package/packages/apra-fleet-se/fleet-sprint/worklists.mjs +59 -3
- package/packages/apra-fleet-se/src/supervisor/api.mjs +148 -8
- package/packages/apra-fleet-se/src/supervisor/dashboard.mjs +6 -3
- package/packages/apra-fleet-se/src/supervisor/dolt-mutex.mjs +30 -10
- package/packages/apra-fleet-se/src/supervisor/fleet-members.mjs +17 -4
- package/packages/apra-fleet-se/src/supervisor/history.mjs +8 -1
- package/packages/apra-fleet-se/src/supervisor/id-allocator.mjs +92 -2
- package/packages/apra-fleet-se/src/supervisor/proxy.mjs +26 -1
- package/packages/apra-fleet-se/src/supervisor/server.mjs +151 -8
- package/packages/apra-fleet-se/src/supervisor/spawner.mjs +11 -9
- package/packages/apra-fleet-se/src/supervisor/watchdog.mjs +7 -1
- package/packages/apra-fleet-workflow/package.json +2 -1
- package/packages/apra-fleet-workflow/src/viewer/index.mjs +86 -5
- package/packages/apra-fleet-workflow/src/viewer/request-guard.mjs +222 -0
- package/packages/apra-fleet-workflow/src/workflow/index.mjs +34 -2
- package/plugins/claude-code/fleet-status/.claude-plugin/plugin.json +7 -0
- package/plugins/claude-code/fleet-status/hooks/hooks.json +1 -0
- package/plugins/claude-code/fleet-status/hooks/register.tsx +906 -0
- package/plugins/claude-code/fleet-status/types/index.d.ts +88 -0
- package/skills/fleet/auth-bitbucket.md +47 -20
- package/skills/fleet/onboarding.md +1 -1
- package/skills/fleet/skill-matrix.md +3 -3
- package/version.json +1 -1
|
@@ -1,27 +1,46 @@
|
|
|
1
|
+
import { RootsListChangedNotificationSchema } from '@modelcontextprotocol/sdk/types.js';
|
|
1
2
|
import { FULL_TOOL_SCOPE, isToolInScope, runWithSessionMember, scopeHasKbMaintainer, scopeIsEngineOrigin, scopeMemberId } from './tool-scope.js';
|
|
2
3
|
import { recordMemberToolCall } from './member-call-counts.js';
|
|
3
4
|
import { assertNoRemovedKbScopeKeys } from './knowledge/kb-removed-scope-keys.js';
|
|
5
|
+
import { SessionRootsCache } from './session-roots.js';
|
|
6
|
+
import { readKbToolProfileFromDisk } from './knowledge/kb-config.js';
|
|
7
|
+
import { FULL_KB_TOOL_PROFILE, kbToolAllowedByProfile } from './kb-tool-profile.js';
|
|
8
|
+
import { logWarn } from '../utils/log-helpers.js';
|
|
4
9
|
/**
|
|
5
10
|
* Wrap a session's McpServer so every server.tool(...)/registerTool(...) registration below goes
|
|
6
11
|
* through the scope gate: an out-of-scope tool is simply never registered
|
|
7
12
|
* (deny by omission -- absent from tools/list, unknown when called). Every
|
|
8
13
|
* other property is forwarded to the real server unchanged.
|
|
14
|
+
*
|
|
15
|
+
* MEMBER scope: the member allowlists (isToolInScope); the KB tool profile is
|
|
16
|
+
* never consulted. FULL scope: every tool, except that kb_* tools outside the
|
|
17
|
+
* install-wide KB tool profile (src/services/kb-tool-profile.ts) are not
|
|
18
|
+
* registered. With the full profile (the default) the base server is returned
|
|
19
|
+
* unchanged.
|
|
9
20
|
*/
|
|
10
21
|
function scopeGatedServer(base, scope) {
|
|
11
|
-
|
|
12
|
-
|
|
22
|
+
let allowed;
|
|
23
|
+
if (scope.kind === 'full') {
|
|
24
|
+
const profile = fullSessionKbToolProfile();
|
|
25
|
+
if (profile.name === 'full')
|
|
26
|
+
return base;
|
|
27
|
+
allowed = (name) => kbToolAllowedByProfile(name, profile);
|
|
28
|
+
}
|
|
29
|
+
else {
|
|
30
|
+
allowed = (name) => isToolInScope(name, scope);
|
|
31
|
+
}
|
|
13
32
|
return new Proxy(base, {
|
|
14
33
|
get(target, prop, receiver) {
|
|
15
34
|
if (prop === 'tool') {
|
|
16
35
|
return (name, ...rest) => {
|
|
17
|
-
if (!
|
|
36
|
+
if (!allowed(name))
|
|
18
37
|
return undefined;
|
|
19
38
|
return target.tool.call(target, name, ...rest);
|
|
20
39
|
};
|
|
21
40
|
}
|
|
22
41
|
if (prop === 'registerTool') {
|
|
23
42
|
return (name, ...rest) => {
|
|
24
|
-
if (!
|
|
43
|
+
if (!allowed(name))
|
|
25
44
|
return undefined;
|
|
26
45
|
return target.registerTool.call(target, name, ...rest);
|
|
27
46
|
};
|
|
@@ -30,6 +49,47 @@ function scopeGatedServer(base, scope) {
|
|
|
30
49
|
},
|
|
31
50
|
});
|
|
32
51
|
}
|
|
52
|
+
/**
|
|
53
|
+
* The KB tool profile a FULL session registers under, read when the session
|
|
54
|
+
* registers its tools (so a change takes effect on reconnect). An unreadable
|
|
55
|
+
* or invalid profile setting falls back to full with a logged warning rather
|
|
56
|
+
* than breaking every session, and fleet_status names the problem
|
|
57
|
+
* (kbToolProfileWarning): kb_setup and `apra-fleet kb profile` refuse an invalid
|
|
58
|
+
* profile on write, so only a hand edit can get here.
|
|
59
|
+
*/
|
|
60
|
+
function fullSessionKbToolProfile() {
|
|
61
|
+
try {
|
|
62
|
+
return readKbToolProfileFromDisk();
|
|
63
|
+
}
|
|
64
|
+
catch (err) {
|
|
65
|
+
logWarn('kb_tool_profile', `${err.message}; serving every kb_* tool (profile full)`);
|
|
66
|
+
return FULL_KB_TOOL_PROFILE;
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
/**
|
|
70
|
+
* The per-session client-roots cache for a FULL session: asks for roots only
|
|
71
|
+
* when the client declared the roots capability, and drops the cache on
|
|
72
|
+
* notifications/roots/list_changed. Minimal test doubles without an
|
|
73
|
+
* underlying Server get a cache that never reports roots.
|
|
74
|
+
*/
|
|
75
|
+
function createRootsCache(baseServer) {
|
|
76
|
+
const inner = baseServer.server;
|
|
77
|
+
const cache = new SessionRootsCache(() => {
|
|
78
|
+
try {
|
|
79
|
+
return !!inner?.getClientCapabilities?.()?.roots;
|
|
80
|
+
}
|
|
81
|
+
catch {
|
|
82
|
+
return false;
|
|
83
|
+
}
|
|
84
|
+
});
|
|
85
|
+
try {
|
|
86
|
+
inner?.setNotificationHandler?.(RootsListChangedNotificationSchema, async () => { cache.invalidate(); });
|
|
87
|
+
}
|
|
88
|
+
catch {
|
|
89
|
+
// a double without notification support: roots are fetched once per session
|
|
90
|
+
}
|
|
91
|
+
return cache;
|
|
92
|
+
}
|
|
33
93
|
/**
|
|
34
94
|
* Register the fleet tool surface on ONE session's McpServer. `scope` is
|
|
35
95
|
* derived from the session's identity by the HTTP transport; it defaults to
|
|
@@ -42,6 +102,10 @@ export async function registerAllTools(baseServer, scope = FULL_TOOL_SCOPE) {
|
|
|
42
102
|
// Whether this member session carries the engine's kb_maintainer grant;
|
|
43
103
|
// handlers read it via getSessionKbMaintainer() (src/services/tool-scope.ts).
|
|
44
104
|
const kbMaintainer = scopeHasKbMaintainer(scope);
|
|
105
|
+
// FULL session: kb_*/code_* scope comes from the client's MCP roots
|
|
106
|
+
// (src/services/session-roots.ts, src/services/knowledge/kb-self.ts). A
|
|
107
|
+
// MEMBER session never reads roots -- its scope is its registered work folder.
|
|
108
|
+
const rootsCache = sessionMemberId === undefined ? createRootsCache(baseServer) : undefined;
|
|
45
109
|
// Load onboarding functions
|
|
46
110
|
const { getFirstRunPreamble, isJsonResponse, isActiveTool, getOnboardingNudge, getWelcomeBackPreamble } = await import('./onboarding.js');
|
|
47
111
|
// Tool schemas and handlers
|
|
@@ -64,6 +128,7 @@ export async function registerAllTools(baseServer, scope = FULL_TOOL_SCOPE) {
|
|
|
64
128
|
const { revokeVcsAuthSchema, revokeVcsAuth } = await import('../tools/revoke-vcs-auth.js');
|
|
65
129
|
const { vcsCredentialExecSchema, vcsCredentialExec } = await import('../tools/vcs-credential-exec.js');
|
|
66
130
|
const { fleetStatusSchema, fleetStatus } = await import('../tools/check-status.js');
|
|
131
|
+
const { fleetSnapshotSchema, fleetSnapshot } = await import('../tools/fleet-snapshot.js');
|
|
67
132
|
const { memberDetailSchema, memberDetail } = await import('../tools/member-detail.js');
|
|
68
133
|
const { updateAgentCliSchema, updateAgentCli } = await import('../tools/update-agent-cli.js');
|
|
69
134
|
const { shutdownServerSchema, shutdownServer } = await import('../tools/shutdown-server.js');
|
|
@@ -96,6 +161,7 @@ export async function registerAllTools(baseServer, scope = FULL_TOOL_SCOPE) {
|
|
|
96
161
|
const { kbFeedbackSchema, kbFeedback } = await import('../tools/kb-feedback.js');
|
|
97
162
|
const { kbHarvestSchema, kbHarvest } = await import('../tools/kb-harvest.js');
|
|
98
163
|
const { kbPromoteSchema, kbPromote } = await import('../tools/kb-promote.js');
|
|
164
|
+
const { kbDemoteSchema, kbDemote } = await import('../tools/kb-demote.js');
|
|
99
165
|
const { kbFreshnessSweepSchema, kbFreshnessSweep } = await import('../tools/kb-freshness-sweep.js');
|
|
100
166
|
const { kbImportSchema, kbImport } = await import('../tools/kb-import.js');
|
|
101
167
|
const { kbResolveContradictionSchema, kbResolveContradiction } = await import('../tools/kb-resolve-contradiction.js');
|
|
@@ -155,7 +221,27 @@ export async function registerAllTools(baseServer, scope = FULL_TOOL_SCOPE) {
|
|
|
155
221
|
const scopedExtra = extra === undefined && sessionMemberId === undefined
|
|
156
222
|
? undefined
|
|
157
223
|
: { ...(extra ?? {}), sessionMemberId };
|
|
158
|
-
const
|
|
224
|
+
const roots = rootsCache && (toolName.startsWith('kb_') || toolName.startsWith('code_'))
|
|
225
|
+
? await rootsCache.get(extra?.sendRequest?.bind(extra))
|
|
226
|
+
: undefined;
|
|
227
|
+
let raw;
|
|
228
|
+
try {
|
|
229
|
+
raw = await runWithSessionMember(sessionMemberId, () => handler(input, scopedExtra), { kbMaintainer, roots });
|
|
230
|
+
}
|
|
231
|
+
catch (err) {
|
|
232
|
+
// A thrown error carrying machine-readable detail (structuredContent,
|
|
233
|
+
// e.g. E-CODE-INDEX-NOT-READY's retry_after_ms and build progress)
|
|
234
|
+
// becomes a one-line isError text that repeats it (toolText: a client
|
|
235
|
+
// may pass its model only the text of an error result), plus that
|
|
236
|
+
// detail as the result's structuredContent. Any other error is left to
|
|
237
|
+
// the SDK unchanged.
|
|
238
|
+
const sc = err instanceof Error ? err.structuredContent : undefined;
|
|
239
|
+
if (err instanceof Error && sc && typeof sc === 'object' && !Array.isArray(sc)) {
|
|
240
|
+
const toolText = err.toolText;
|
|
241
|
+
return { content: [{ type: 'text', text: typeof toolText === 'string' ? toolText : err.message }], isError: true, structuredContent: sc };
|
|
242
|
+
}
|
|
243
|
+
throw err;
|
|
244
|
+
}
|
|
159
245
|
const result = typeof raw === 'string' ? raw : raw.text;
|
|
160
246
|
const structuredContent = typeof raw === 'string' ? undefined : raw.structuredContent;
|
|
161
247
|
const isJson = isJsonResponse(result);
|
|
@@ -210,11 +296,12 @@ export async function registerAllTools(baseServer, scope = FULL_TOOL_SCOPE) {
|
|
|
210
296
|
server.tool('provision_llm_auth', "Authenticate a fleet member so it can run prompts. With api_key, deploys that API key or Claude Code OAuth token (routed by prefix). Without api_key, re-deploys a credential already stored for the member, else copies your current login session; force_oauth_copy: true copies your login anyway and clears the stored credential. Run this before execute_prompt if the member reports no authentication. Note: a copied OAuth session is shared and its refresh token is rotated across every holder, so a refresh on one machine can invalidate the copies elsewhere; prefer an API key for unattended members.", provisionAuthSchema.shape, wrapTool('provision_llm_auth', (input) => provisionAuth(input)));
|
|
211
297
|
server.tool('setup_ssh_key', 'Generate an SSH key pair and migrate a member from password to key-based authentication.', setupSSHKeySchema.shape, wrapTool('setup_ssh_key', (input) => setupSSHKey(input)));
|
|
212
298
|
server.tool('setup_git_app', "One-time setup: register a GitHub App for git token minting. Requires a GitHub App ID, private key (.pem) file path, and installation ID. The app must already be created and installed, with the repository permissions each git_access level needs (see docs/github-app-setup.md; push+pr needs Metadata, Contents, Workflows, Pull requests, Actions) -- a mint requesting a permission the App lacks fails.", setupGitAppSchema.shape, wrapTool('setup_git_app', (input) => setupGitApp(input)));
|
|
213
|
-
server.tool('provision_vcs_auth', 'Set up git access credentials on a member. Supports GitHub, Bitbucket, and Azure DevOps. Tests connectivity after setup.', provisionVcsAuthSchema.shape, wrapTool('provision_vcs_auth', (input) => provisionVcsAuth(input)));
|
|
299
|
+
server.tool('provision_vcs_auth', 'Set up git access credentials on a member so it can clone, push, create pull requests, dispatch workflows and re-run CI jobs. Supports GitHub, Bitbucket, and Azure DevOps. On GitHub with a GitHub App, git_access decides which of these the member may do: push+pr covers create pull requests and dispatch workflows. Tests connectivity after setup.', provisionVcsAuthSchema.shape, wrapTool('provision_vcs_auth', (input) => provisionVcsAuth(input)));
|
|
214
300
|
server.tool('revoke_vcs_auth', 'Remove VCS credentials from a member. Specify the provider (github, bitbucket, or azure-devops) to revoke.', revokeVcsAuthSchema.shape, wrapTool('revoke_vcs_auth', (input) => revokeVcsAuth(input)));
|
|
215
|
-
server.tool('vcs_credential_exec', 'Run a credential-requiring git/VCS command on a member WITHOUT ever learning the credential. Put one of two literal placeholders where the token belongs: {{vcs_token}}, referenced BARE (never inside your own quotes) -- the server substitutes it already escaped AND quoted for that member\'s shell; or {{vcs_token_inline}}, referenced INSIDE your own single quotes (e.g. an Authorization header value) -- the server substitutes it escaped for the interior of a single-quoted string, with no quotes of its own. Using {{vcs_token}} inside your own quotes double-escapes it; use {{vcs_token_inline}} there instead. Both may appear in the same command. The server dispatches the command and redacts
|
|
301
|
+
server.tool('vcs_credential_exec', 'Run a credential-requiring git/VCS command on a member WITHOUT ever learning the credential. Put one of two literal placeholders where the token belongs: {{vcs_token}}, referenced BARE (never inside your own quotes) -- the server substitutes it already escaped AND quoted for that member\'s shell; or {{vcs_token_inline}}, referenced INSIDE your own single quotes (e.g. an Authorization header value) -- the server substitutes it escaped for the interior of a single-quoted string, with no quotes of its own. Using {{vcs_token}} inside your own quotes double-escapes it; use {{vcs_token_inline}} there instead. Both may appear in the same command. Bitbucket REST uses the token as a Bearer value (-H \'Authorization: Bearer {{vcs_token_inline}}\'), with no username and no email. The optional {{vcs_username}} and {{vcs_username_inline}} placeholders substitute the credential helper\'s git username under the same two dialects (for Bitbucket always x-bitbucket-api-token-auth, a git-only username, never a REST login) -- never on their own: a token placeholder is still required. The server dispatches the command and redacts both values from the returned stdout/stderr. Use this instead of reading a token back out of a credential helper.', vcsCredentialExecSchema.shape, wrapTool('vcs_credential_exec', (input) => vcsCredentialExec(input)));
|
|
216
302
|
// Status & Monitoring
|
|
217
303
|
server.tool('fleet_status', 'Get status of all fleet members. Use json format for structured data.', fleetStatusSchema.shape, wrapTool('fleet_status', (input) => fleetStatus(input)));
|
|
304
|
+
server.tool('fleet_snapshot', 'Cheap read-only fleet view for status displays: every member with its last-known status (busy/idle/offline/unknown), icon, category and holder, as JSON. Reads only local state -- no SSH probes, no writes. Use fleet_status for a live check.', fleetSnapshotSchema.shape, wrapTool('fleet_snapshot', () => fleetSnapshot()));
|
|
218
305
|
server.tool('member_detail', 'Get detailed status for one member: connectivity, AI version, authentication, active session, resources, and git branch.', memberDetailSchema.shape, wrapTool('member_detail', (input) => memberDetail(input)));
|
|
219
306
|
// Maintenance
|
|
220
307
|
server.tool('update_llm_cli', "Update or install the AI provider CLI on members. Omit member to update all online members at once. Use install_if_missing to install on members that don't have it yet.", updateAgentCliSchema.shape, wrapTool('update_llm_cli', (input) => updateAgentCli(input)));
|
|
@@ -236,7 +323,7 @@ export async function registerAllTools(baseServer, scope = FULL_TOOL_SCOPE) {
|
|
|
236
323
|
// Email
|
|
237
324
|
server.tool('send_email', 'Send an email. Pass provider config inline (provider, from, and for SMTP: host, port, user, secure). Secrets (API keys, passwords) are resolved from the credential store -- store them first with credential_store_set (names: "sendgrid_api_key" for SendGrid, "smtp_password" for SMTP). Returns JSON with messageId on success or error on failure.', sendEmailSchema.shape, wrapTool('send_email', (input, extra) => sendEmail(input, extra)));
|
|
238
325
|
// Interactive Session Messaging
|
|
239
|
-
server.tool('send_message', 'Send a task message to a connected interactive member session via SSE. Returns the message ID.', sendMessageSchema.shape, wrapTool('send_message', (input) => sendMessage(input)));
|
|
326
|
+
server.tool('send_message', 'Send a task message to a connected interactive member session via SSE. Returns the message ID. With probe: true, sends nothing and only reports whether a session holds the target and can receive channel messages (connected, channel_capable).', sendMessageSchema.shape, wrapTool('send_message', (input) => sendMessage(input)));
|
|
240
327
|
server.tool('report_status', 'Called by a connected interactive member session (not the orchestrator) to report it is done responding to a send_message notification and available again ("online") or still connected but not actively engaged ("idle"). Closes the busy->online/idle status loop send_message opens.', reportStatusSchema.shape, wrapTool('report_status', (input, extra) => reportStatus(input, extra)));
|
|
241
328
|
server.tool('respond_to_message', 'Called by a connected interactive member session to respond to a prompt delivered via execute_prompt or send_message. Pass reply_to as the msgid from the original notification\'s meta. If execute_prompt is waiting on this reply_to, its call resolves with this content; otherwise this is a no-op response with a clear "no pending call" result.', respondToMessageSchema.shape, wrapTool('respond_to_message', (input) => respondToMessage(input)));
|
|
242
329
|
// --- Code Intelligence ---
|
|
@@ -308,21 +395,22 @@ export async function registerAllTools(baseServer, scope = FULL_TOOL_SCOPE) {
|
|
|
308
395
|
}));
|
|
309
396
|
// --- Knowledge Bank ---
|
|
310
397
|
server.tool('kb_capture', 'Capture a learning, fact, or file summary into the knowledge bank. Confidence is capped at INFERRED: any CONFIRMED passed here is downgraded to INFERRED, and a user-directive is stored UNVERIFIED as a pending proposal until a human approves it; confidence_clamped:true whenever the stored confidence differs from the requested one (default INFERRED). CONFIRMED is minted ONLY via kb_promote. Returns {id, audn_decision, confidence_clamped}. audn_decision: add=new entry, none=duplicate skipped, update=same-topic predecessor linked (refines; both entries stay live), flagged=contradiction flagged for review. Pass supersedes:<id> to retire that entry instead (only takes effect if AUDN independently matched it). In a MEMBER session the entry is stored in the per-repo DB tagged member:<caller uuid>. A MEMBER session without the kb_maintainer grant never retires a CONFIRMED entry through supersedes (a retired entry leaves the bible at the next kb_bible_commit): the capture links to it instead (refines, both stay live) and the response adds refused, the CONFIRMED ids left live; refused is present exactly when such a session passed supersedes.' + KB_SELF_NOTE, kbCaptureSchema.shape, wrapTool('kb_capture', (input) => kbCapture(input)));
|
|
311
|
-
server.tool('kb_invalidate', 'Mark context-cache entries stale for the given file paths (pass files), or discard entries by id (pass ids): discarding sets superseded_at so the entry drops out of every read. Exactly one of files or ids. ids returns {discarded, not_found, already_discarded}. In a MEMBER session both forms act only on entries tagged member:<caller uuid>: files leaves other entries for those files untouched, and with ids any other id is reported in not_found and changes nothing. A MEMBER session without the kb_maintainer grant cannot retire a CONFIRMED entry by either form (a retired entry leaves the bible at the next kb_bible_commit): such ids are left untouched and listed in refused, which the response carries exactly for such a session. Call after modifying files to ensure the KB reflects the current state.' + KB_SELF_NOTE, kbInvalidateSchema.shape, wrapTool('kb_invalidate', (input) => kbInvalidate(input)));
|
|
312
|
-
server.tool('kb_context', 'Check freshness of files against the knowledge bank. Returns {fresh, stale, missing} -- fresh files can be skipped, stale/missing files must be re-read. With no confidence filter the default is confidence ["CONFIRMED","INFERRED"] plus exclude_disputed (a context-cache entry is verified by its content hash); UNVERIFIED only when listed explicitly. In a MEMBER session the default read merges the member\'s checkout bible (CONFIRMED) with the member\'s own CONFIRMED/INFERRED captures (tagged member:<caller uuid>).' + KB_SELF_NOTE, kbContextSchema.shape, wrapTool('kb_context', (input) => kbContext(input)));
|
|
313
|
-
server.tool('kb_session_prime', 'Prime a session with KB context. Returns session_warm status, stale files needing re-read, top KB entries, and recommended GitNexus calls. In a MEMBER session the
|
|
314
|
-
server.tool('kb_query', 'Two-level knowledge bank search. L1: FTS5 on title+summary (up to 20 results). L2: full content for top 5 hits (max 800 tokens each). Excludes stale/superseded by default. Optional tag filter (exact match) ANDs alongside other filters without touching FTS/OR-join logic, and may be used alone (no query) to list all entries carrying the tag. Pass flagged_only: true to list all contradiction-flagged entry pairs for resolution. Pass expand_related: true to also receive related_claims -- entries joined to the top hits by a refines or contradiction_of edge. Those record the KB own judgements about its contents (there is a newer framing of this; something disputes this) and cannot be reached by a text match. shares_file/shares_symbol edges are deliberately not traversed, since FTS over those same fields already surfaces them. Default false, in which case related_claims is absent and the result shape is unchanged. With no confidence filter the default is confidence ["CONFIRMED"] plus exclude_disputed: true, so only CONFIRMED entries outside any unresolved contradiction are returned (related_claims included). Pass an explicit confidence list (e.g. ["CONFIRMED","INFERRED","UNVERIFIED"]) to opt into other tiers; exclude_disputed then defaults off unless set true. flagged_only is exempt. In a MEMBER session
|
|
315
|
-
server.tool('kb_list', 'List KB entries by confidence/type/module/symbol/tag -- audit the KB. With no confidence filter, returns only CONFIRMED, undisputed entries; pass an explicit confidence list (e.g. ["INFERRED","UNVERIFIED"]; a single tier string such as "INFERRED" is accepted as a one-element list) to see other tiers without touching FTS ranking or use_count telemetry. Excludes superseded/stale entries. Returns {results, total} with each entry as {id, type, confidence, title, summary, symbols, source_files}. In a MEMBER session the
|
|
398
|
+
server.tool('kb_invalidate', 'Mark context-cache entries stale for the given file paths (pass files), or discard entries by id (pass ids): discarding sets superseded_at so the entry drops out of every read. Exactly one of files or ids. ids returns {discarded, not_found, already_discarded}. In a MEMBER session both forms act only on entries tagged member:<caller uuid>: files leaves other entries for those files untouched, and with ids any other id is reported in not_found and changes nothing. A MEMBER session without the kb_maintainer grant cannot retire a CONFIRMED entry by either form (a retired entry leaves the bible at the next kb_bible_commit): such ids are left untouched and listed in refused, which the response carries exactly for such a session. Under an http KB provider the ids form, and the files form in a MEMBER session (the KB server has no own-scope invalidate), are refused with E-KB-HTTP-UNSUPPORTED and nothing is changed. Call after modifying files to ensure the KB reflects the current state.' + KB_SELF_NOTE, kbInvalidateSchema.shape, wrapTool('kb_invalidate', (input) => kbInvalidate(input)));
|
|
399
|
+
server.tool('kb_context', 'Check freshness of files against the knowledge bank. Returns {fresh, stale, missing} -- fresh files can be skipped, stale/missing files must be re-read. With no confidence filter the default is confidence ["CONFIRMED","INFERRED"] plus exclude_disputed (a context-cache entry is verified by its content hash); UNVERIFIED only when listed explicitly. In a MEMBER session over a SQLite project KB the default read merges the member\'s checkout bible (CONFIRMED) with the member\'s own CONFIRMED/INFERRED captures (tagged member:<caller uuid>). An explicit confidence list is split the same way: CONFIRMED is read from the member checkout bible and INFERRED/UNVERIFIED only from the member\'s own captures (tagged member:<caller uuid>), merged for a mixed request, which also returns captures of the member promoted to CONFIRMED in the per-repo DB (the bible copy wins on a shared id). Under an http KB provider a MEMBER read is answered by the server for every tier, with no bible merge; member own-scope still holds (checked by fleet on the entry tags the server returns): the default read merges every CONFIRMED summary with the member\'s own CONFIRMED/INFERRED ones.' + KB_SELF_NOTE, kbContextSchema.shape, wrapTool('kb_context', (input) => kbContext(input)));
|
|
400
|
+
server.tool('kb_session_prime', 'Prime a session with KB context. Returns session_warm status, stale files needing re-read, top KB entries, and recommended GitNexus calls. In a MEMBER session over a SQLite project KB CONFIRMED is read from the member checkout bible and INFERRED/UNVERIFIED only from the member\'s own captures (tagged member:<caller uuid>), merged for a mixed request, which also returns captures of the member promoted to CONFIRMED in the per-repo DB (the bible copy wins on a shared id). Under an http KB provider a MEMBER prime is answered by the server for every tier; a prime naming INFERRED/UNVERIFIED keeps only entries tagged member:<caller uuid> (checked by fleet on the entry tags the server returns).' + KB_SELF_NOTE, kbSessionPrimeSchema.shape, wrapTool('kb_session_prime', (input) => kbSessionPrime(input)));
|
|
401
|
+
server.tool('kb_query', 'Two-level knowledge bank search. L1: FTS5 on title+summary (up to 20 results). L2: full content for top 5 hits (max 800 tokens each). Excludes stale/superseded by default. Optional tag filter (exact match) ANDs alongside other filters without touching FTS/OR-join logic, and may be used alone (no query) to list all entries carrying the tag. Pass flagged_only: true to list all contradiction-flagged entry pairs for resolution. Pass expand_related: true to also receive related_claims -- entries joined to the top hits by a refines or contradiction_of edge. Those record the KB own judgements about its contents (there is a newer framing of this; something disputes this) and cannot be reached by a text match. shares_file/shares_symbol edges are deliberately not traversed, since FTS over those same fields already surfaces them. Default false, in which case related_claims is absent and the result shape is unchanged. With no confidence filter the default is confidence ["CONFIRMED"] plus exclude_disputed: true, so only CONFIRMED entries outside any unresolved contradiction are returned (related_claims included). Pass an explicit confidence list (e.g. ["CONFIRMED","INFERRED","UNVERIFIED"]) to opt into other tiers; exclude_disputed then defaults off unless set true. flagged_only is exempt. In a MEMBER session over a SQLite project KB CONFIRMED is read from the member checkout bible and INFERRED/UNVERIFIED only from the member\'s own captures (tagged member:<caller uuid>), merged for a mixed request, which also returns captures of the member promoted to CONFIRMED in the per-repo DB (the bible copy wins on a shared id). Under an http KB provider every MEMBER read, CONFIRMED included, is answered by the server; a read naming INFERRED/UNVERIFIED keeps only entries tagged member:<caller uuid> (checked by fleet on the entry tags the server returns). A MEMBER flagged_only read is the exception: over SQLite it is answered from the member checkout bible plus the global KB; under an http KB provider it is refused with E-KB-HTTP-UNSUPPORTED (the bible is not used there, and the server\'s flagged listing carries no owner tag). Under an http KB provider a server that cannot be reached fails with E-KB-HTTP-UNREACHABLE; no read is answered from the checkout bible or a local store. own_scope: true returns only the own half of that read -- the member\'s own captures (tagged member:<caller uuid>) at every requested tier, CONFIRMED included, from the per-repo KB (the KB server under an http provider), with no bible rows -- which is how a member reads back a CONFIRMED row it promoted itself (every checkout-bible row is untagged); ignored when flagged_only is set. Under an http KB provider a MEMBER own_scope read is refused with E-KB-HTTP-UNSUPPORTED when the KB server does not list the demote route in GET /api/kb/capabilities (own_scope exists to find what may be demoted). own_scope changes only WHICH store answers: to span everything kb_demote accepts, pass own_scope: true with confidence: ["CONFIRMED"] and include_stale: true, then drop the superseded rows that widening also returns.' + KB_SELF_NOTE, kbQuerySchema.shape, wrapTool('kb_query', (input) => kbQuery(input)));
|
|
402
|
+
server.tool('kb_list', 'List KB entries by confidence/type/module/symbol/tag -- audit the KB. With no confidence filter, returns only CONFIRMED, undisputed entries; pass an explicit confidence list (e.g. ["INFERRED","UNVERIFIED"]; a single tier string such as "INFERRED" is accepted as a one-element list) to see other tiers without touching FTS ranking or use_count telemetry. Excludes superseded/stale entries. Returns {results, total} with each entry as {id, type, confidence, title, summary, symbols, source_files}. In a MEMBER session CONFIRMED is read from the member checkout bible and INFERRED/UNVERIFIED only from the member\'s own captures (tagged member:<caller uuid>), merged for a mixed request, which also returns captures of the member promoted to CONFIRMED in the per-repo DB (the bible copy wins on a shared id). Under an http KB provider every MEMBER list, CONFIRMED included, is answered by the server\'s list route, never the checkout bible; a server that does not list that route fails with E-KB-HTTP-UNSUPPORTED.' + KB_SELF_NOTE, kbListSchema.shape, wrapTool('kb_list', (input) => kbList(input)));
|
|
316
403
|
server.tool('kb_harvest', 'Scan a session transcript for learnings and capture them into the KB. Returns {entries_captured, entries_updated, entries_skipped}. Extracted entries are UNVERIFIED and author=harvest, source=harvest.' + KB_SELF_NOTE, kbHarvestSchema.shape, wrapTool('kb_harvest', (input) => kbHarvest(input)));
|
|
317
|
-
server.tool('kb_promote', 'Upgrade KB entry confidence: UNVERIFIED -> INFERRED -> CONFIRMED. Appends promotion note to content as evidence trail. CONFIRMED entries are no-op. In a MEMBER session only entries tagged member:<caller uuid> can be promoted; any other id returns not-found and changes nothing.' + KB_SELF_NOTE, kbPromoteSchema.shape, wrapTool('kb_promote', (input) => kbPromote(input)));
|
|
404
|
+
server.tool('kb_promote', 'Upgrade KB entry confidence: UNVERIFIED -> INFERRED -> CONFIRMED. Appends promotion note to content as evidence trail. CONFIRMED entries are no-op. In a MEMBER session over a SQLite project KB only entries tagged member:<caller uuid> can be promoted; any other id returns not-found and changes nothing. Under an http project KB the promote is sent by id with no lookup first: the KB server refuses an unknown, superseded or out-of-scope id itself (a 404 is reported as Entry not found: <id> followed by the server\'s answer, any other refusal with its HTTP status and the server\'s title/code/detail), and fleet does not check the member tag.' + KB_SELF_NOTE, kbPromoteSchema.shape, wrapTool('kb_promote', (input) => kbPromote(input)));
|
|
405
|
+
server.tool('kb_demote', 'Lower a CONFIRMED KB entry back to INFERRED: { id, reason, evidence_files }. Returns {id, previous_confidence, new_confidence}. Appends a "[Demoted: <reason> | evidence: <files> -- <author>]" note to content as the audit trail; promoted_at and source are left untouched, and a stale entry may be demoted. WHEN TO USE WHICH: the entry is still broadly right but you are LESS CERTAIN than CONFIRMED claims (it did not hold in a case you checked, its evidence turned out thinner than the promotion note implies) -> kb_demote. The entry is PROVEN WRONG in practice -> kb_feedback (flags it stale for human review, never touches confidence). Two entries make opposing claims and you know which wins -> kb_resolve_contradiction. You are discarding an unconfirmed capture outright -> kb_invalidate {ids}. REFUSALS, all checked before any write, nothing changes: a non-CONFIRMED entry is refused with E-DEMOTE-NOT-CONFIRMED (never a silent no-op); a superseded entry E-DEMOTE-SUPERSEDED; a user-directive E-DEMOTE-REFUSED-DIRECTIVE (directive state is human-terminal in both directions); a reason under 20 characters after collapsing newlines and trimming E-DEMOTE-REASON-REQUIRED; an evidence path that does not resolve, is not a file, or traverses out of the repo E-DEMOTE-EVIDENCE-UNRESOLVED. evidence_files is required (at least one): an absent or empty list is an input-validation error, raised before the tool runs. In a MEMBER session only entries tagged member:<caller uuid> can be demoted; any other id returns not-found and changes nothing. Under an http KB provider the demote is sent to the KB server by id (the server enforces which ids the caller may demote) only when GET /api/kb/capabilities lists the optional demote route; otherwise it fails with E-KB-HTTP-UNSUPPORTED naming the route and nothing is changed.' + KB_SELF_NOTE, kbDemoteSchema.shape, wrapTool('kb_demote', (input) => kbDemote(input)));
|
|
318
406
|
server.tool('kb_freshness_sweep', 'Bounded full-KB bidirectional freshness sweep: re-hash every entry that has a stored per-file basis against the CURRENT worktree, mark mismatches stale, and revive stale entries whose full basis matches again (superseded, feedback-downvoted, and invalidated entries stay retired). This is the branch-switch revival surface kb_session_prime cannot be (prime excludes stale entries). Returns {checked, staled, unstaled}.' + KB_SELF_NOTE, kbFreshnessSweepSchema.shape, wrapTool('kb_freshness_sweep', (input) => kbFreshnessSweep(input)));
|
|
319
|
-
server.tool('kb_import', 'Import a merged bible (.fleet/kb-canonical.json) into the warm local KB -- the post-merge write path (the prime-time cold-seed is output-only). Reads the repo-resolved bible, or an explicit --path file. Each entry routes through the AUDN choke point (duplicate -> skipped, refinement -> linked, contradiction -> flagged); non-directive entries KEEP their bible confidence (the bible is a git-reviewed, human-merged artifact), stamped source="import"; type="user-directive" entries are FORCED to pending proposals (never active -- a bible cannot smuggle an active directive). Idempotent (re-import of the same bible adds nothing). Runs a freshness sweep after import so entries whose basis does not match this worktree are staled. Accepts every bible shape: a legacy bare JSON array and the v2/v3 {version, provenance:{commit, branch, entry_count}, entries} envelope. A v3 entry\'s source_file_hashes (repo-relative path -> hash, covering every cited file) is stored as its basis exactly -- local files are never re-hashed for it; an entry without a valid carried map (any v1/v2 entry) gets a LOCAL freshness-only basis hashed from this worktree, so it still goes stale when a cited file changes; that local basis is never exported and never admits the entry to kb_export or kb_bible_commit, so neither re-publishes it until it is recaptured. Entries with no source_files, or citing files absent from this worktree, are REJECTED (an entry with no checkable basis can never be staled, so nothing could falsify it) -- re-importing a legacy bible deliberately drops those. Returns {imported, skipped, linked, flagged, rejected, sweep:{checked, staled, unstaled}}. Pass skip_sweep: true to skip the post-import freshness sweep -- the sweep re-judges EVERY entry against the given worktree, which is right for a deliberate audit but wrong for a routine warm-the-KB import (it mass-stales entries merely because unrelated files moved on, which in turn empties the promotion candidates kb_list returns). `path` names only the bible file to read, never which KB is written. TRUST BOUNDARY: importing the repo-resolved bible as committed is the git-reviewed trusted channel; an explicit --path bible is caller-asserted trust, equivalent in power to kb_promote, so a MEMBER session without the kb_maintainer grant is refused an explicit path (other than its own .fleet/kb-canonical.json) with E-KB-MAINTAINER-REQUIRED and nothing is imported; without path (or naming its own bible) it imports the COMMITTED .fleet/kb-canonical.json at HEAD, never the member-writable work-tree file, and the response adds bible_source:"HEAD" and worktree_ignored (true when uncommitted work-tree content was not imported); with no committed copy, or when that committed bible was never written or imported by the maintainer side, it fails with E-KB-MAINTAINER-REQUIRED and nothing is imported. Pass ref (a plain git ref name, e.g. refs/remotes/origin/main) to read the bible as committed at that ref instead of the file on disk, in any session: the bytes are verified against the git blob id in-process, bible_source reports the ref, a ref without the bible fails with E-BIBLE-NOT-FOUND, and a kb_maintainer or FULL session records that verified blob as trusted (the engine seeds trust this way from the base branch, never from a work tree). Directives are quarantined either way; activation stays CLI-only.' + KB_SELF_NOTE, kbImportSchema.shape, wrapTool('kb_import', (input) => kbImport(input)));
|
|
407
|
+
server.tool('kb_import', 'Import a merged bible (.fleet/kb-canonical.json) into the warm local KB -- the post-merge write path (the prime-time cold-seed is output-only). Reads the repo-resolved bible, or an explicit --path file. Each entry routes through the AUDN choke point (duplicate -> skipped, refinement -> linked, contradiction -> flagged); non-directive entries KEEP their bible confidence (the bible is a git-reviewed, human-merged artifact), stamped source="import"; type="user-directive" entries are FORCED to pending proposals (never active -- a bible cannot smuggle an active directive). Idempotent (re-import of the same bible adds nothing). Runs a freshness sweep after import so entries whose basis does not match this worktree are staled. Accepts every bible shape: a legacy bare JSON array and the v2/v3 {version, provenance:{commit, branch, entry_count}, entries} envelope. A v3 entry\'s source_file_hashes (repo-relative path -> hash, covering every cited file) is stored as its basis exactly -- local files are never re-hashed for it; an entry without a valid carried map (any v1/v2 entry) gets a LOCAL freshness-only basis hashed from this worktree, so it still goes stale when a cited file changes; that local basis is never exported and never admits the entry to kb_export or kb_bible_commit, so neither re-publishes it until it is recaptured. Entries with no source_files, or citing files absent from this worktree, are REJECTED (an entry with no checkable basis can never be staled, so nothing could falsify it) -- re-importing a legacy bible deliberately drops those. Returns {imported, skipped, linked, flagged, rejected, sweep:{checked, staled, unstaled}}. Under an http project KB nothing is read or imported: every count is 0 and the result carries bible_skipped: true with a reason (the KB server is the source of truth). Pass skip_sweep: true to skip the post-import freshness sweep -- the sweep re-judges EVERY entry against the given worktree, which is right for a deliberate audit but wrong for a routine warm-the-KB import (it mass-stales entries merely because unrelated files moved on, which in turn empties the promotion candidates kb_list returns). `path` names only the bible file to read, never which KB is written. TRUST BOUNDARY: importing the repo-resolved bible as committed is the git-reviewed trusted channel; an explicit --path bible is caller-asserted trust, equivalent in power to kb_promote, so a MEMBER session without the kb_maintainer grant is refused an explicit path (other than its own .fleet/kb-canonical.json) with E-KB-MAINTAINER-REQUIRED and nothing is imported; without path (or naming its own bible) it imports the COMMITTED .fleet/kb-canonical.json at HEAD, never the member-writable work-tree file, and the response adds bible_source:"HEAD" and worktree_ignored (true when uncommitted work-tree content was not imported); with no committed copy, or when that committed bible was never written or imported by the maintainer side, it fails with E-KB-MAINTAINER-REQUIRED and nothing is imported. Pass ref (a plain git ref name, e.g. refs/remotes/origin/main) to read the bible as committed at that ref instead of the file on disk, in any session: the bytes are verified against the git blob id in-process, bible_source reports the ref, a ref without the bible fails with E-BIBLE-NOT-FOUND, and a kb_maintainer or FULL session records that verified blob as trusted (the engine seeds trust this way from the base branch, never from a work tree). Directives are quarantined either way; activation stays CLI-only.' + KB_SELF_NOTE, kbImportSchema.shape, wrapTool('kb_import', (input) => kbImport(input)));
|
|
320
408
|
server.tool('kb_resolve_contradiction', 'Resolve a KB contradiction pair: {winnerId, loserId, evidence}. The SINGLE write path for reconcile resolutions (used by kb_reconcile_prefilter and the reconciler agent alike). Winner ends confidence=CONFIRMED with the evidence note appended and both flag fields cleared (flagged_for_review + contradiction_of); stale is cleared ONLY if the D2 un-stale predicate holds on the post-flag-clear row (so a downvoted or invalidated winner still stays retired -- it wins the contradiction, not its reputation). Loser ends superseded_at=now + stale=1 + flag cleared, never deleted. REFUSES (throws, writes nothing) when either id is missing, either entry is already superseded, the ids do not form a genuinely linked contradiction pair, or the pair involves an ACTIVE user-directive.' + KB_SELF_NOTE, kbResolveContradictionSchema.shape, wrapTool('kb_resolve_contradiction', (input) => kbResolveContradiction(input)));
|
|
321
409
|
server.tool('kb_reconcile_prefilter', 'Mechanical hash-basis prefilter over all flagged contradiction pairs (including stale members -- see flaggedPairs liveness contract). Re-hashes both sides of each pair against the CURRENT worktree: exactly one side fully matching wins mechanically via kb_resolve_contradiction (evidence "hash-basis match on merged worktree"); both match, both mismatch, or an empty/missing basis on either side leaves the pair for the reconciler agent. Pairs involving an ACTIVE user-directive are never touched. Returns {pairs, resolved, left_for_agent, skipped_directive}. Run after kb_import + kb_freshness_sweep, before dispatching the reconciler agent. It mints CONFIRMED, so a MEMBER session is served it only with the kb_maintainer grant (like kb_resolve_contradiction).' + KB_SELF_NOTE, kbReconcilePrefilterSchema.shape, wrapTool('kb_reconcile_prefilter', (input) => kbReconcilePrefilter(input)));
|
|
322
|
-
server.tool('kb_setup', 'Set up KB: install git post-commit hook, write provider config, store remote credentials encrypted. Run once per repo.' + KB_SELF_NOTE, kbSetupSchema.shape, wrapTool('kb_setup', (input) => kbSetup(input)));
|
|
323
|
-
server.tool('kb_export', 'Export CONFIRMED, non-superseded, non-stale KB entries to a canonical bible file (stable field set, deterministic id order, ASCII-safe). scope="project" (default): reads the project KB and ADDITIVELY merges into <repo>/.fleet/kb-canonical.json. Only entries whose cited source_files each have a recorded per-file hash that matches the file at the repo\'s HEAD commit qualify (an empty or missing basis, or a cited file absent at HEAD, excludes the entry; uncommitted edits never change the verdict; a folder that is not a git work tree is refused, never hashed from disk). Entries already in the bible are never removed or rewritten (the existing bible entry wins on an id clash); only qualifying new ids are added, and when none qualify the file is left untouched and nothing is committed. exported is the entry count of the resulting bible. scope="global" is unchanged: it exports the full GLOBAL set with no basis filter. scope="global": reads the GLOBAL KB, writes <repo>/.fleet/kb-canonical-global.json (in practice the apra-fleet platform repo, committed there so the installer can distribute it to every project on the machine -- D8/F9). Run after kb_promote so the canonical set stays current. F6a: the tool itself auto-commits the bible file (pathspec-only, identity pm-kb) when the repo is a git repo and the content changed -- this is code, not agent discretion, so no manual git step is needed, and this applies to the global file too. Non-fatal on any git failure; push is not automatic. Writes the v3 format: {version:3, provenance:{commit, branch, entry_count}, entries:[...]}; each project entry it adds carries source_file_hashes, its stored per-file hash basis (repo-relative path -> hash; never re-hashed at write time). Refuses (throws, file untouched) to write a bible holding a duplicate id. provenance.branch is the target base branch (the branch the entries merge into) and provenance.commit the base commit the entries were verified against (a commit, not a timestamp, so re-exports stay diff-free when nothing changed): pass baseBranch and baseCommit to state them explicitly; when omitted they default to the export folder HEAD branch and commit. An export whose entry set is unchanged rewrites nothing. Auto-commit defaults to ON (USER DIRECTIVE 2026-08-11 -- an export left uncommitted is knowledge nobody else ever sees): set FLEET_DIR/knowledge/config.json { bible: { autoCommit: false } } to opt out. A malformed config disables it.' + KB_SELF_NOTE, kbExportSchema.shape, wrapTool('kb_export', (input) => kbExport(input)));
|
|
324
|
-
server.tool('kb_bible_commit', 'Commit one round of confirmed entries to the bible: { ids, baseBranch, baseCommit }. Merges exactly the given ids from this repository\'s KB into <repo>/.fleet/kb-canonical.json at ENTRY level -- only the given ids are added or replaced; every entry already in the file is kept unless this KB holds it as superseded or invalidated, and an entry in the file but not in the KB (or CONFIRMED and current, or merely stale) is never dropped -- in kb_export\'s stable serialization (v3 envelope, id order, ASCII-safe; each merged entry carries its stored source_file_hashes basis). provenance.branch is baseBranch (the sprint\'s target base branch) and provenance.commit is baseCommit (the base commit the entries were verified against), never the working folder HEAD. Then makes a local commit scoped to that one path (identity pm-kb). It NEVER pushes. Re-running with the same ids after resetting to a newer HEAD re-merges at entry level, so a rejected push can be retried with no manual merge. Ids that are unknown, stale, superseded, or not CONFIRMED are SKIPPED (never an error) and reported in skipped with reason not_confirmed_or_unknown. A CONFIRMED id is admitted only if it passes the same basis rule kb_export (scope=project) applies: every cited source file has a recorded per-file hash that matches that file\'s content at the repo\'s HEAD commit (an empty or missing basis, a cited file with no basis key, a file absent or changed at HEAD, or a path that is not repo-relative excludes it; uncommitted edits never change the verdict; a folder that is not a git work tree is refused, never hashed from disk); such an id is SKIPPED with reason basis_mismatch, logged, and any entry already in the bible for it is left unchanged. A CONFIRMED id that cites no source file has no checkable basis and is SKIPPED with its own reason no_source_files (never basis_mismatch), also leaving any existing bible entry unchanged. At every call (also with no ids) each bible entry this KB holds as superseded or invalidated is REMOVED and reported in removed as {id, reason} (reason superseded or invalidated); the commit message lists each removal. kb_export never removes entries. Also at every call, each bible entry with no source_file_hashes (carried over from a v1/v2 bible) that this KB holds under the same id, citing the same source files, with a stored basis that passes the same basis rule at HEAD gains that stored basis as its source_file_hashes (only that field changes; an entry that does not qualify is kept unchanged, never dropped); backfilled reports how many, and the commit message names the count. Nothing merged, nothing removed and nothing backfilled, or an unchanged entry set: no write and no commit. Refuses (throws, file untouched) when the existing bible file is unreadable or holds a duplicate id, or when the local commit fails. Returns {path, merged, skipped, removed, entry_count, backfilled, committed}.' + KB_SELF_NOTE, kbBibleCommitSchema.shape, wrapTool('kb_bible_commit', (input) => kbBibleCommit(input)));
|
|
325
|
-
server.tool('kb_stats', 'Read-only KB health aggregation: totals by confidence/type, stale/flagged/superseded counts, retrieval hit_rate, promote_ratio, canonical-bible presence/drift, and optional per-symbol coverage. Never bumps use_count/last_accessed (kb_list pattern). Bible drift is visibility for the machine that owns the KB -- CI cannot see the local kb.sqlite, so there is no CI gate on it. In a MEMBER session the counts describe the member\'s checkout bible.' + KB_SELF_NOTE, kbStatsSchema.shape, wrapTool('kb_stats', (input) => kbStats(input)));
|
|
326
|
-
server.tool('kb_feedback', 'Downvote a KB entry that proved wrong in practice: { id, reason, role? }. Marks the entry stale=1 + flagged_for_review=1 and appends an ASCII feedback note "[feedback <ISO>] <validated-role>: <reason>" (CONTENT_CAP respected). NEVER deletes and NEVER touches confidence -- a downvoted CONFIRMED entry stays CONFIRMED-but-stale-flagged; the human resolves it in kb-review, this tool only flags it for that review. Exception: an ACTIVE user-directive is flagged for review but NOT staled (directives outrank agent experience -- the human decides); a pending directive proposal stales normally. Not available in a MEMBER session: it returns E-MEMBER-VIEW-READ-ONLY and changes nothing.' + KB_SELF_NOTE, kbFeedbackSchema.shape, wrapTool('kb_feedback', (input) => kbFeedback(input)));
|
|
410
|
+
server.tool('kb_setup', 'Set up KB: install git post-commit hook, write provider config, store remote credentials encrypted. Run once per repo. Also sets the install-wide KB tool profile (tool_profile: full, developer or custom) that decides which kb_* tools interactive non-member sessions list; member sessions are unaffected and a change takes effect on reconnect.' + KB_SELF_NOTE, kbSetupSchema.shape, wrapTool('kb_setup', (input) => kbSetup(input)));
|
|
411
|
+
server.tool('kb_export', 'Export CONFIRMED, non-superseded, non-stale KB entries to a canonical bible file (stable field set, deterministic id order, ASCII-safe). scope="project" (default): reads the project KB and ADDITIVELY merges into <repo>/.fleet/kb-canonical.json. Only entries whose cited source_files each have a recorded per-file hash that matches the file at the repo\'s HEAD commit qualify (an empty or missing basis, or a cited file absent at HEAD, excludes the entry; uncommitted edits never change the verdict; a folder that is not a git work tree is refused, never hashed from disk). Entries already in the bible are never removed or rewritten (the existing bible entry wins on an id clash); only qualifying new ids are added, and when none qualify the file is left untouched and nothing is committed. exported is the entry count of the resulting bible. scope="global" is unchanged: it exports the full GLOBAL set with no basis filter. scope="global": reads the GLOBAL KB, writes <repo>/.fleet/kb-canonical-global.json (in practice the apra-fleet platform repo, committed there so the installer can distribute it to every project on the machine -- D8/F9). Run after kb_promote so the canonical set stays current. F6a: the tool itself auto-commits the bible file (pathspec-only, identity pm-kb) when the repo is a git repo and the content changed -- this is code, not agent discretion, so no manual git step is needed, and this applies to the global file too. Non-fatal on any git failure; push is not automatic. Writes the v3 format: {version:3, provenance:{commit, branch, entry_count}, entries:[...]} plus, when the bible carries any, an optional top-level demotions:[{id, at, reason}] of tombstones; each project entry it adds carries source_file_hashes, its stored per-file hash basis (repo-relative path -> hash; never re-hashed at write time). Refuses (throws, file untouched) to write a bible holding a duplicate id. scope="project" HONOURS those tombstones: a tombstoned id is NOT re-added, unless the local row was promoted AFTER the tombstone at -- judged on when it was promoted, as its bible recorded it, never on the local import time (the same rule kb_import applies), in which case the entry is re-added and its tombstone cleared in the same write. provenance.branch is the target base branch (the branch the entries merge into) and provenance.commit the base commit the entries were verified against (a commit, not a timestamp, so re-exports stay diff-free when nothing changed): pass baseBranch and baseCommit to state them explicitly; when omitted they default to the export folder HEAD branch and commit. An export whose entry set is unchanged rewrites nothing. Auto-commit defaults to ON (USER DIRECTIVE 2026-08-11 -- an export left uncommitted is knowledge nobody else ever sees): set FLEET_DIR/knowledge/config.json { bible: { autoCommit: false } } to opt out. A malformed config disables it.' + KB_SELF_NOTE, kbExportSchema.shape, wrapTool('kb_export', (input) => kbExport(input)));
|
|
412
|
+
server.tool('kb_bible_commit', 'Commit one round of confirmed entries to the bible: { ids, baseBranch, baseCommit, demoted_ids? }. Merges exactly the given ids from this repository\'s KB into <repo>/.fleet/kb-canonical.json at ENTRY level -- only the given ids are added or replaced; every entry already in the file is kept unless this KB holds it as superseded or invalidated, and an entry in the file but not in the KB (or CONFIRMED and current, or merely stale) is never dropped -- in kb_export\'s stable serialization (v3 envelope, id order, ASCII-safe; each merged entry carries its stored source_file_hashes basis). provenance.branch is baseBranch (the sprint\'s target base branch) and provenance.commit is baseCommit (the base commit the entries were verified against), never the working folder HEAD. Then makes a local commit scoped to that one path (identity pm-kb). It NEVER pushes. Re-running with the same ids after resetting to a newer HEAD re-merges at entry level, so a rejected push can be retried with no manual merge. Ids that are unknown, stale, superseded, or not CONFIRMED are SKIPPED (never an error) and reported in skipped with reason not_confirmed_or_unknown. A CONFIRMED id is admitted only if it passes the same basis rule kb_export (scope=project) applies: every cited source file has a recorded per-file hash that matches that file\'s content at the repo\'s HEAD commit (an empty or missing basis, a cited file with no basis key, a file absent or changed at HEAD, or a path that is not repo-relative excludes it; uncommitted edits never change the verdict; a folder that is not a git work tree is refused, never hashed from disk); such an id is SKIPPED with reason basis_mismatch, logged, and any entry already in the bible for it is left unchanged. A CONFIRMED id that cites no source file has no checkable basis and is SKIPPED with its own reason no_source_files (never basis_mismatch), also leaving any existing bible entry unchanged. demoted_ids (optional) records DEMOTIONS EXPLICITLY: each id must name a local entry that carries a demoted_at and is now below CONFIRMED (i.e. kb_demote ran on it); any other id -- unknown, never demoted, or since re-promoted to CONFIRMED -- is SKIPPED with reason not_demoted_or_unknown and nothing changes for it. An admitted id is REMOVED from entries and upserted into the bible\'s OPTIONAL top-level demotions array as a tombstone {id, at, reason} carrying the LOCAL row\'s demoted_at as at and reason "demoted" (and does the same, every call, for each bible entry this KB holds as demoted, unless that entry was promoted after the local demotion), so another clone applies the demotion explicitly instead of inferring it from an absence (a clone legitimately holds CONFIRMED entries that were never exported). Tombstones already in the file are PRESERVED by a later commit carrying unrelated ids, and re-committing a tombstoned id through ids after a re-promotion restores its entry and CLEARS its tombstone. provenance.entry_count counts entries only -- a tombstone is not an entry. At every call (also with no ids) each bible entry this KB holds as superseded or invalidated is REMOVED and reported in removed as {id, reason} (reason superseded or invalidated); the commit message lists each removal. kb_export never removes entries. Also at every call, each bible entry with no source_file_hashes (carried over from a v1/v2 bible) that this KB holds under the same id, citing the same source files, with a stored basis that passes the same basis rule at HEAD gains that stored basis as its source_file_hashes (only that field changes; an entry that does not qualify is kept unchanged, never dropped); backfilled reports how many, and the commit message names the count. Nothing merged, nothing removed, nothing demotable and nothing backfilled, or an unchanged entry and tombstone set: no write and no commit. Refuses (throws, file untouched) when the existing bible file is unreadable or holds a duplicate id, or when the local commit fails. Under an http KB provider the call is skipped with bible_skipped:true and a reason, never an error (the KB is not read and nothing is written or committed). Returns {path, merged, demoted, skipped, removed, entry_count, backfilled, committed}.' + KB_SELF_NOTE, kbBibleCommitSchema.shape, wrapTool('kb_bible_commit', (input) => kbBibleCommit(input)));
|
|
413
|
+
server.tool('kb_stats', 'Read-only KB health aggregation: totals by confidence/type, stale/flagged/superseded counts, retrieval hit_rate, promote_ratio, canonical-bible presence/drift, and optional per-symbol coverage. Never bumps use_count/last_accessed (kb_list pattern). Bible drift is visibility for the machine that owns the KB -- CI cannot see the local kb.sqlite, so there is no CI gate on it. In a MEMBER session over a SQLite project KB the counts describe the member\'s checkout bible; under an http KB provider stats are reported as unsupported (the bible is not used).' + KB_SELF_NOTE, kbStatsSchema.shape, wrapTool('kb_stats', (input) => kbStats(input)));
|
|
414
|
+
server.tool('kb_feedback', 'Downvote a KB entry that proved wrong in practice: { id, reason, role? }. Marks the entry stale=1 + flagged_for_review=1 and appends an ASCII feedback note "[feedback <ISO>] <validated-role>: <reason>" (CONTENT_CAP respected). NEVER deletes and NEVER touches confidence -- a downvoted CONFIRMED entry stays CONFIRMED-but-stale-flagged; the human resolves it in kb-review, this tool only flags it for that review. Exception: an ACTIVE user-directive is flagged for review but NOT staled (directives outrank agent experience -- the human decides); a pending directive proposal stales normally. Not available in a MEMBER session, under a SQLite or an http KB provider: it returns E-MEMBER-VIEW-READ-ONLY and changes nothing.' + KB_SELF_NOTE, kbFeedbackSchema.shape, wrapTool('kb_feedback', (input) => kbFeedback(input)));
|
|
327
415
|
}
|
|
328
416
|
//# sourceMappingURL=tool-registry.js.map
|
|
@@ -36,13 +36,46 @@ export declare function scopeMemberId(scope: ToolScope): string | undefined;
|
|
|
36
36
|
* FULL session is not a member session and is not gated by the grant at all.
|
|
37
37
|
*/
|
|
38
38
|
export declare function scopeHasKbMaintainer(scope: ToolScope): boolean;
|
|
39
|
+
/**
|
|
40
|
+
* The MCP client roots (roots/list) a FULL session's client offered, as last
|
|
41
|
+
* fetched for that session (src/services/session-roots.ts).
|
|
42
|
+
*
|
|
43
|
+
* `offered` is every root URI the client returned, in client order.
|
|
44
|
+
* `folders` is the subset that is a file:// URI naming an existing directory
|
|
45
|
+
* on THIS host, converted to a local path, in the same order (a remote HTTP
|
|
46
|
+
* client's roots are paths on its own machine and are skipped).
|
|
47
|
+
* `fetchError` is set, with both lists empty, when asking the client failed: the
|
|
48
|
+
* roots are unknown, which is not the same as "no roots offered".
|
|
49
|
+
*/
|
|
50
|
+
export interface SessionRoots {
|
|
51
|
+
offered: string[];
|
|
52
|
+
folders: string[];
|
|
53
|
+
fetchError?: string;
|
|
54
|
+
}
|
|
39
55
|
/**
|
|
40
56
|
* Run a tool handler with the calling session's member id (and whether that
|
|
41
|
-
* member session carries the kb_maintainer grant) in context.
|
|
57
|
+
* member session carries the kb_maintainer grant) in context. `roots` carries
|
|
58
|
+
* the client roots of a FULL session (ignored for a MEMBER session, whose
|
|
59
|
+
* scope is always its registered work folder).
|
|
42
60
|
*/
|
|
43
61
|
export declare function runWithSessionMember<T>(sessionMemberId: string | undefined, fn: () => T, opts?: {
|
|
44
62
|
kbMaintainer?: boolean;
|
|
63
|
+
roots?: SessionRoots;
|
|
45
64
|
}): T;
|
|
65
|
+
/**
|
|
66
|
+
* The client roots of the FULL session whose tool call is currently
|
|
67
|
+
* executing; undefined for a MEMBER session, a client that offered no roots
|
|
68
|
+
* (or lacks the roots capability), and outside any tool call.
|
|
69
|
+
*/
|
|
70
|
+
export declare function getSessionRoots(): SessionRoots | undefined;
|
|
71
|
+
/**
|
|
72
|
+
* The per-call memo slot for (self) resolution, or undefined outside a tool
|
|
73
|
+
* call (no memo: every resolution probes afresh).
|
|
74
|
+
*/
|
|
75
|
+
export declare function getSelfMemoSlot(): {
|
|
76
|
+
value?: unknown;
|
|
77
|
+
error?: unknown;
|
|
78
|
+
} | undefined;
|
|
46
79
|
/**
|
|
47
80
|
* The member id of the MCP session whose tool call is currently executing,
|
|
48
81
|
* or undefined for a FULL (non-member) session or outside any tool call.
|
|
@@ -75,10 +75,35 @@ export function scopeHasKbMaintainer(scope) {
|
|
|
75
75
|
const toolCallContext = new AsyncLocalStorage();
|
|
76
76
|
/**
|
|
77
77
|
* Run a tool handler with the calling session's member id (and whether that
|
|
78
|
-
* member session carries the kb_maintainer grant) in context.
|
|
78
|
+
* member session carries the kb_maintainer grant) in context. `roots` carries
|
|
79
|
+
* the client roots of a FULL session (ignored for a MEMBER session, whose
|
|
80
|
+
* scope is always its registered work folder).
|
|
79
81
|
*/
|
|
80
82
|
export function runWithSessionMember(sessionMemberId, fn, opts = {}) {
|
|
81
|
-
|
|
83
|
+
const ctx = { sessionMemberId, kbMaintainer: opts.kbMaintainer === true };
|
|
84
|
+
if (sessionMemberId === undefined && opts.roots !== undefined)
|
|
85
|
+
ctx.roots = opts.roots;
|
|
86
|
+
return toolCallContext.run(ctx, fn);
|
|
87
|
+
}
|
|
88
|
+
/**
|
|
89
|
+
* The client roots of the FULL session whose tool call is currently
|
|
90
|
+
* executing; undefined for a MEMBER session, a client that offered no roots
|
|
91
|
+
* (or lacks the roots capability), and outside any tool call.
|
|
92
|
+
*/
|
|
93
|
+
export function getSessionRoots() {
|
|
94
|
+
return toolCallContext.getStore()?.roots;
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* The per-call memo slot for (self) resolution, or undefined outside a tool
|
|
98
|
+
* call (no memo: every resolution probes afresh).
|
|
99
|
+
*/
|
|
100
|
+
export function getSelfMemoSlot() {
|
|
101
|
+
const store = toolCallContext.getStore();
|
|
102
|
+
if (!store)
|
|
103
|
+
return undefined;
|
|
104
|
+
if (!store.selfMemo)
|
|
105
|
+
store.selfMemo = {};
|
|
106
|
+
return store.selfMemo;
|
|
82
107
|
}
|
|
83
108
|
/**
|
|
84
109
|
* The member id of the MCP session whose tool call is currently executing,
|
|
@@ -225,6 +225,16 @@ export const azureDevOpsProvider = {
|
|
|
225
225
|
}
|
|
226
226
|
return { org_url: input.org_url, pat: azPat, expires_at: input.pat_expires_at };
|
|
227
227
|
},
|
|
228
|
+
// Non-secret checks run before any OOB prompt (see VcsProviderService.
|
|
229
|
+
// validateNonSecretFields); buildCredentials repeats them afterwards.
|
|
230
|
+
validateNonSecretFields(input) {
|
|
231
|
+
if (!input.org_url)
|
|
232
|
+
return 'Azure DevOps requires the "org_url" field.';
|
|
233
|
+
if (input.pat_expires_at !== undefined && Number.isNaN(Date.parse(input.pat_expires_at))) {
|
|
234
|
+
return `Azure DevOps "pat_expires_at" is not a parseable date/time: ${input.pat_expires_at}`;
|
|
235
|
+
}
|
|
236
|
+
return null;
|
|
237
|
+
},
|
|
228
238
|
// apra-fleet-5co8.3.2: the former
|
|
229
239
|
// `if (provider === 'azure-devops' && pat === undefined && token === undefined)`
|
|
230
240
|
// block, verbatim. Either field can carry the PAT, so the credential only
|
|
@@ -1,6 +1,27 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Bitbucket VCS provider
|
|
2
|
+
* Bitbucket VCS provider -- deploys API token credentials via git credential helper.
|
|
3
|
+
*
|
|
4
|
+
* Auth model (owner decision 2026-11-02): a Bitbucket API token authenticates
|
|
5
|
+
* git over HTTPS with the FIXED username TOKEN_USERNAME, and the REST API with
|
|
6
|
+
* `Authorization: Bearer <token>`. The account email is never used for auth:
|
|
7
|
+
* Bitbucket accepts an email only for REST basic auth, and writing it as the
|
|
8
|
+
* git username (the 0.4.4 behaviour) made every git push/pull fail while the
|
|
9
|
+
* old unauthenticated REST probe still reported success.
|
|
3
10
|
*/
|
|
4
11
|
import type { VcsProviderService } from './types.js';
|
|
12
|
+
/** The git username Bitbucket requires next to an API token. A constant, not
|
|
13
|
+
* a parameter: no caller can supply a username (and so never an email). */
|
|
14
|
+
export declare const BITBUCKET_TOKEN_USERNAME = "x-bitbucket-api-token-auth";
|
|
15
|
+
export interface BitbucketRepoRef {
|
|
16
|
+
workspace: string;
|
|
17
|
+
repo: string;
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* Parse a Bitbucket Cloud git remote (https, ssh:// or scp-like) into its
|
|
21
|
+
* { workspace, repo } slugs. NEVER throws; null for anything that is not a
|
|
22
|
+
* bitbucket.org two-segment repo path with safe slugs. Any user:password in
|
|
23
|
+
* an https remote is discarded, never returned.
|
|
24
|
+
*/
|
|
25
|
+
export declare function parseBitbucketRemote(remoteUrl: unknown): BitbucketRepoRef | null;
|
|
5
26
|
export declare const bitbucketProvider: VcsProviderService;
|
|
6
27
|
//# sourceMappingURL=bitbucket.d.ts.map
|