@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.
Files changed (268) hide show
  1. package/README.md +49 -4
  2. package/dist/agents/backlog-groomer.md +5 -0
  3. package/dist/agents/ci-watcher.md +5 -0
  4. package/dist/agents/deployer.md +20 -2
  5. package/dist/agents/doer.md +38 -2
  6. package/dist/agents/harvester.md +12 -9
  7. package/dist/agents/integ-test-runner.md +5 -0
  8. package/dist/agents/kb-reconciler.md +6 -0
  9. package/dist/agents/plan-reviewer.md +5 -0
  10. package/dist/agents/planner.md +5 -0
  11. package/dist/agents/regression-test-runner.md +5 -0
  12. package/dist/agents/reviewer.md +67 -15
  13. package/dist/agents/schemas/deployer-output.json +5 -0
  14. package/dist/agents/schemas/doer-output.json +78 -2
  15. package/dist/agents/schemas/reviewer-output.json +104 -2
  16. package/dist/cli/auth.js +5 -1
  17. package/dist/cli/beads-pin.js +6 -7
  18. package/dist/cli/claude-mod.d.ts +75 -0
  19. package/dist/cli/claude-mod.js +288 -0
  20. package/dist/cli/dolt-install.d.ts +1 -1
  21. package/dist/cli/dolt-install.js +5 -1
  22. package/dist/cli/fleet-se-guard.d.ts +8 -0
  23. package/dist/cli/fleet-se-guard.js +19 -3
  24. package/dist/cli/install-guard.d.ts +9 -0
  25. package/dist/cli/install-guard.js +24 -0
  26. package/dist/cli/install.d.ts +12 -0
  27. package/dist/cli/install.js +180 -20
  28. package/dist/cli/kb-profile.d.ts +16 -0
  29. package/dist/cli/kb-profile.js +81 -0
  30. package/dist/cli/start.js +3 -0
  31. package/dist/cli/uninstall.js +13 -3
  32. package/dist/cli/update.d.ts +4 -0
  33. package/dist/cli/update.js +19 -3
  34. package/dist/commands/kb-server.d.ts +10 -1
  35. package/dist/commands/kb-server.js +285 -11
  36. package/dist/index.js +22 -1
  37. package/dist/os/git-executable.d.ts +57 -0
  38. package/dist/os/git-executable.js +85 -0
  39. package/dist/os/go-concurrency.d.ts +44 -0
  40. package/dist/os/go-concurrency.js +53 -0
  41. package/dist/os/index.d.ts +1 -0
  42. package/dist/os/index.js +1 -0
  43. package/dist/os/linux.d.ts +2 -0
  44. package/dist/os/linux.js +10 -1
  45. package/dist/os/os-commands.d.ts +25 -0
  46. package/dist/os/os-commands.js +2 -0
  47. package/dist/os/windows-executable.d.ts +53 -0
  48. package/dist/os/windows-executable.js +185 -0
  49. package/dist/os/windows-gitbash.d.ts +23 -14
  50. package/dist/os/windows-gitbash.js +40 -16
  51. package/dist/os/windows.d.ts +2 -0
  52. package/dist/os/windows.js +37 -6
  53. package/dist/paths.d.ts +10 -1
  54. package/dist/paths.js +19 -2
  55. package/dist/services/agy-project.d.ts +7 -1
  56. package/dist/services/agy-project.js +7 -2
  57. package/dist/services/auth-socket.d.ts +18 -0
  58. package/dist/services/auth-socket.js +30 -4
  59. package/dist/services/credential-store.d.ts +33 -0
  60. package/dist/services/credential-store.js +79 -2
  61. package/dist/services/http-transport.d.ts +29 -0
  62. package/dist/services/http-transport.js +166 -37
  63. package/dist/services/kb-tool-profile.d.ts +36 -0
  64. package/dist/services/kb-tool-profile.js +88 -0
  65. package/dist/services/knowledge/bible-blob-id.js +10 -1
  66. package/dist/services/knowledge/bible-import.d.ts +108 -0
  67. package/dist/services/knowledge/bible-import.js +137 -4
  68. package/dist/services/knowledge/file-hash.js +6 -5
  69. package/dist/services/knowledge/http-provider.d.ts +303 -20
  70. package/dist/services/knowledge/http-provider.js +795 -125
  71. package/dist/services/knowledge/kb-config.d.ts +65 -1
  72. package/dist/services/knowledge/kb-config.js +143 -3
  73. package/dist/services/knowledge/kb-http-auth-state.d.ts +26 -0
  74. package/dist/services/knowledge/kb-http-auth-state.js +40 -0
  75. package/dist/services/knowledge/kb-providers.d.ts +9 -2
  76. package/dist/services/knowledge/kb-providers.js +67 -37
  77. package/dist/services/knowledge/kb-removed-scope-keys.js +1 -1
  78. package/dist/services/knowledge/kb-self.d.ts +122 -9
  79. package/dist/services/knowledge/kb-self.js +196 -36
  80. package/dist/services/knowledge/member-bible-view.js +16 -3
  81. package/dist/services/knowledge/path-validation.d.ts +7 -0
  82. package/dist/services/knowledge/path-validation.js +11 -0
  83. package/dist/services/knowledge/project-slug.js +3 -2
  84. package/dist/services/knowledge/repository-header.d.ts +77 -0
  85. package/dist/services/knowledge/repository-header.js +233 -0
  86. package/dist/services/knowledge/require-sqlite-project.d.ts +1 -1
  87. package/dist/services/knowledge/require-sqlite-project.js +1 -1
  88. package/dist/services/knowledge/sqlite-provider.d.ts +169 -0
  89. package/dist/services/knowledge/sqlite-provider.js +416 -4
  90. package/dist/services/knowledge/types.d.ts +15 -2
  91. package/dist/services/member-busy.d.ts +12 -0
  92. package/dist/services/member-busy.js +20 -0
  93. package/dist/services/member-config-io.d.ts +3 -2
  94. package/dist/services/member-config-io.js +7 -4
  95. package/dist/services/member-fleet-install.js +1 -0
  96. package/dist/services/member-tool-allowlist.d.ts +1 -1
  97. package/dist/services/member-tool-allowlist.js +8 -4
  98. package/dist/services/port-holder.js +2 -1
  99. package/dist/services/service-manager/types.d.ts +17 -1
  100. package/dist/services/service-manager/windows.d.ts +7 -2
  101. package/dist/services/service-manager/windows.js +28 -11
  102. package/dist/services/service-notice.d.ts +7 -0
  103. package/dist/services/service-notice.js +19 -0
  104. package/dist/services/session-registry.d.ts +13 -0
  105. package/dist/services/session-registry.js +13 -0
  106. package/dist/services/session-roots.d.ts +67 -0
  107. package/dist/services/session-roots.js +126 -0
  108. package/dist/services/statusline.d.ts +21 -0
  109. package/dist/services/statusline.js +97 -1
  110. package/dist/services/supervisor-service-cleanup.js +2 -1
  111. package/dist/services/tool-registry.js +108 -20
  112. package/dist/services/tool-scope.d.ts +34 -1
  113. package/dist/services/tool-scope.js +27 -2
  114. package/dist/services/vcs/azure-devops.js +10 -0
  115. package/dist/services/vcs/bitbucket.d.ts +22 -1
  116. package/dist/services/vcs/bitbucket.js +163 -17
  117. package/dist/services/vcs/types.d.ts +25 -2
  118. package/dist/services/watch/project-resolver.js +2 -1
  119. package/dist/skills/pm/cost.md +5 -1
  120. package/dist/skills/pm/index.md +9 -9
  121. package/dist/skills/pm/sprint.md +2 -1
  122. package/dist/tools/check-status.d.ts +51 -0
  123. package/dist/tools/check-status.js +124 -12
  124. package/dist/tools/code-intelligence-freshness.js +1 -1
  125. package/dist/tools/code-intelligence-gitnexus.d.ts +19 -0
  126. package/dist/tools/code-intelligence-gitnexus.js +166 -9
  127. package/dist/tools/code-intelligence-readiness.d.ts +58 -1
  128. package/dist/tools/code-intelligence-readiness.js +93 -8
  129. package/dist/tools/code-intelligence-reindex.d.ts +25 -1
  130. package/dist/tools/code-intelligence-reindex.js +76 -4
  131. package/dist/tools/code-intelligence.d.ts +1 -1
  132. package/dist/tools/code-intelligence.js +1 -1
  133. package/dist/tools/execute-command.js +14 -8
  134. package/dist/tools/execute-prompt.js +6 -2
  135. package/dist/tools/fleet-snapshot.d.ts +21 -0
  136. package/dist/tools/fleet-snapshot.js +78 -0
  137. package/dist/tools/kb-bible-commit.d.ts +25 -11
  138. package/dist/tools/kb-bible-commit.js +142 -33
  139. package/dist/tools/kb-capture.d.ts +2 -2
  140. package/dist/tools/kb-context.js +47 -27
  141. package/dist/tools/kb-demote.d.ts +27 -0
  142. package/dist/tools/kb-demote.js +37 -0
  143. package/dist/tools/kb-export.d.ts +35 -3
  144. package/dist/tools/kb-export.js +56 -13
  145. package/dist/tools/kb-feedback.d.ts +2 -0
  146. package/dist/tools/kb-feedback.js +17 -7
  147. package/dist/tools/kb-harvest.js +28 -9
  148. package/dist/tools/kb-import.d.ts +18 -2
  149. package/dist/tools/kb-import.js +24 -9
  150. package/dist/tools/kb-invalidate.d.ts +11 -3
  151. package/dist/tools/kb-invalidate.js +80 -7
  152. package/dist/tools/kb-list.js +38 -10
  153. package/dist/tools/kb-promote.js +6 -4
  154. package/dist/tools/kb-query.d.ts +3 -0
  155. package/dist/tools/kb-query.js +181 -37
  156. package/dist/tools/kb-session-prime.d.ts +4 -4
  157. package/dist/tools/kb-session-prime.js +89 -9
  158. package/dist/tools/kb-setup.d.ts +20 -0
  159. package/dist/tools/kb-setup.js +149 -11
  160. package/dist/tools/list-members.js +1 -1
  161. package/dist/tools/member-detail.js +7 -3
  162. package/dist/tools/provision-vcs-auth.d.ts +28 -3
  163. package/dist/tools/provision-vcs-auth.js +53 -7
  164. package/dist/tools/receive-files.js +7 -4
  165. package/dist/tools/send-files.js +5 -4
  166. package/dist/tools/send-message.d.ts +3 -0
  167. package/dist/tools/send-message.js +15 -2
  168. package/dist/tools/stop-prompt.js +3 -1
  169. package/dist/tools/vcs-credential-exec.d.ts +45 -3
  170. package/dist/tools/vcs-credential-exec.js +90 -11
  171. package/dist/utils/process-utils.js +5 -1
  172. package/dist/utils/redact-known-secrets.d.ts +17 -0
  173. package/dist/utils/redact-known-secrets.js +70 -0
  174. package/dist/utils/skill-matrix.js +1 -1
  175. package/dist/utils/vcs-provider-detect.js +2 -2
  176. package/dist/workflows/auto-sprint.js +245 -9
  177. package/package.json +10 -7
  178. package/packages/apra-fleet-client/package.json +1 -1
  179. package/packages/apra-fleet-client/src/client/api.mjs +172 -19
  180. package/packages/apra-fleet-client/src/client/reconnecting-transport.mjs +35 -2
  181. package/packages/apra-fleet-client/src/client/transport.mjs +6 -0
  182. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +5 -0
  183. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +5 -0
  184. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +20 -2
  185. package/packages/apra-fleet-se/apra-pm/agents/doer.md +38 -2
  186. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +12 -9
  187. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +5 -0
  188. package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +6 -0
  189. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +5 -0
  190. package/packages/apra-fleet-se/apra-pm/agents/planner.md +5 -0
  191. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +5 -0
  192. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +67 -15
  193. package/packages/apra-fleet-se/apra-pm/agents/schemas/deployer-output.json +5 -0
  194. package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-output.json +78 -2
  195. package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json +104 -2
  196. package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +5 -1
  197. package/packages/apra-fleet-se/apra-pm/skills/pm/index.md +9 -9
  198. package/packages/apra-fleet-se/apra-pm/skills/pm/sprint.md +2 -1
  199. package/packages/apra-fleet-se/bin/cli.mjs +104 -31
  200. package/packages/apra-fleet-se/bin/serve.mjs +46 -8
  201. package/packages/apra-fleet-se/fleet-sprint/abort.mjs +184 -32
  202. package/packages/apra-fleet-se/fleet-sprint/bd-sync-command.mjs +69 -0
  203. package/packages/apra-fleet-se/fleet-sprint/beads-children.mjs +21 -0
  204. package/packages/apra-fleet-se/fleet-sprint/beads-lock-probe.mjs +176 -0
  205. package/packages/apra-fleet-se/fleet-sprint/beads-reachability.mjs +126 -0
  206. package/packages/apra-fleet-se/fleet-sprint/beads-scope.mjs +158 -1
  207. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +82 -2
  208. package/packages/apra-fleet-se/fleet-sprint/coordination.mjs +23 -6
  209. package/packages/apra-fleet-se/fleet-sprint/decision-notify.mjs +338 -0
  210. package/packages/apra-fleet-se/fleet-sprint/decision-wait.mjs +731 -0
  211. package/packages/apra-fleet-se/fleet-sprint/decisions.mjs +372 -0
  212. package/packages/apra-fleet-se/fleet-sprint/dispatch-role.mjs +44 -11
  213. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +4 -1
  214. package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +9 -3
  215. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +314 -19
  216. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +72 -4
  217. package/packages/apra-fleet-se/fleet-sprint/git-sync.mjs +7 -1
  218. package/packages/apra-fleet-se/fleet-sprint/git-topology.mjs +112 -1
  219. package/packages/apra-fleet-se/fleet-sprint/guarded-modules.mjs +36 -2
  220. package/packages/apra-fleet-se/fleet-sprint/kb.mjs +736 -101
  221. package/packages/apra-fleet-se/fleet-sprint/member-init-probe.mjs +1 -1
  222. package/packages/apra-fleet-se/fleet-sprint/member-provisioning.mjs +7 -1
  223. package/packages/apra-fleet-se/fleet-sprint/phases/deploy.mjs +49 -2
  224. package/packages/apra-fleet-se/fleet-sprint/phases/develop.mjs +206 -3
  225. package/packages/apra-fleet-se/fleet-sprint/phases/final-review.mjs +61 -3
  226. package/packages/apra-fleet-se/fleet-sprint/phases/harvest.mjs +81 -31
  227. package/packages/apra-fleet-se/fleet-sprint/phases/plan.mjs +7 -3
  228. package/packages/apra-fleet-se/fleet-sprint/phases/publish-pr.mjs +39 -14
  229. package/packages/apra-fleet-se/fleet-sprint/phases/re-review.mjs +17 -1
  230. package/packages/apra-fleet-se/fleet-sprint/phases/review.mjs +18 -3
  231. package/packages/apra-fleet-se/fleet-sprint/pr-body.mjs +14 -1
  232. package/packages/apra-fleet-se/fleet-sprint/prompts.mjs +32 -5
  233. package/packages/apra-fleet-se/fleet-sprint/runner.js +824 -98
  234. package/packages/apra-fleet-se/fleet-sprint/se-os-commands.mjs +4 -2
  235. package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +54 -1
  236. package/packages/apra-fleet-se/fleet-sprint/se-windows.mjs +29 -2
  237. package/packages/apra-fleet-se/fleet-sprint/set-aside.mjs +288 -0
  238. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +3 -2
  239. package/packages/apra-fleet-se/fleet-sprint/sprint-args.mjs +20 -0
  240. package/packages/apra-fleet-se/fleet-sprint/sprint-report.mjs +21 -0
  241. package/packages/apra-fleet-se/fleet-sprint/sprint-state.mjs +9 -0
  242. package/packages/apra-fleet-se/fleet-sprint/vcs-auth.mjs +605 -32
  243. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +811 -17
  244. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +89 -1
  245. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +225 -2
  246. package/packages/apra-fleet-se/fleet-sprint/worklists.mjs +59 -3
  247. package/packages/apra-fleet-se/src/supervisor/api.mjs +148 -8
  248. package/packages/apra-fleet-se/src/supervisor/dashboard.mjs +6 -3
  249. package/packages/apra-fleet-se/src/supervisor/dolt-mutex.mjs +30 -10
  250. package/packages/apra-fleet-se/src/supervisor/fleet-members.mjs +17 -4
  251. package/packages/apra-fleet-se/src/supervisor/history.mjs +8 -1
  252. package/packages/apra-fleet-se/src/supervisor/id-allocator.mjs +92 -2
  253. package/packages/apra-fleet-se/src/supervisor/proxy.mjs +26 -1
  254. package/packages/apra-fleet-se/src/supervisor/server.mjs +151 -8
  255. package/packages/apra-fleet-se/src/supervisor/spawner.mjs +11 -9
  256. package/packages/apra-fleet-se/src/supervisor/watchdog.mjs +7 -1
  257. package/packages/apra-fleet-workflow/package.json +2 -1
  258. package/packages/apra-fleet-workflow/src/viewer/index.mjs +86 -5
  259. package/packages/apra-fleet-workflow/src/viewer/request-guard.mjs +222 -0
  260. package/packages/apra-fleet-workflow/src/workflow/index.mjs +34 -2
  261. package/plugins/claude-code/fleet-status/.claude-plugin/plugin.json +7 -0
  262. package/plugins/claude-code/fleet-status/hooks/hooks.json +1 -0
  263. package/plugins/claude-code/fleet-status/hooks/register.tsx +906 -0
  264. package/plugins/claude-code/fleet-status/types/index.d.ts +88 -0
  265. package/skills/fleet/auth-bitbucket.md +47 -20
  266. package/skills/fleet/onboarding.md +1 -1
  267. package/skills/fleet/skill-matrix.md +3 -3
  268. package/version.json +1 -1
@@ -5,7 +5,7 @@ import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/
5
5
  import { fleetEvents } from './event-bus.js';
6
6
  import { getOrCreateKey } from './jwt.js';
7
7
  import { getTokenIssuer, localWorkspaceId } from './token-issuer.js';
8
- import { sessionRegistry } from './session-registry.js';
8
+ import { sessionRegistry, ORCHESTRATOR_SESSION_ID } from './session-registry.js';
9
9
  import { FULL_TOOL_SCOPE, memberToolScope } from './tool-scope.js';
10
10
  import { getAgent, findAgentByName } from './registry.js';
11
11
  import { DEFAULT_HOST, resolveServerPort } from '../paths.js';
@@ -13,6 +13,21 @@ import { serverVersion } from '../version.js';
13
13
  import { logLine, shortSid } from '../utils/log-helpers.js';
14
14
  import { recordShutdown } from './server-lifecycle.js';
15
15
  import { getOrCreateMemberAccessSecret, memberAccessSecretMatches, memberAccessSecretPath, readMemberAccessSecret, MEMBER_SECRET_HEADER } from './member-access-secret.js';
16
+ /** Idle bound after which a session with no open request is evicted. */
17
+ export const DEFAULT_SESSION_IDLE_MS = 30 * 60 * 1000;
18
+ const DEFAULT_IDLE_SWEEP_INTERVAL_MS = 60 * 1000;
19
+ /** Open-session count that triggers a one-time WARNING log line. */
20
+ export const DEFAULT_SESSION_COUNT_WARN = 500;
21
+ function positiveIntFromEnv(name, fallback) {
22
+ const raw = process.env[name];
23
+ if (raw === undefined || raw === '')
24
+ return fallback;
25
+ const n = Number(raw);
26
+ if (Number.isFinite(n) && n > 0)
27
+ return Math.floor(n);
28
+ logLine('session', `WARNING: ignoring ${name}=${JSON.stringify(raw)} (not a positive number); using ${fallback}`);
29
+ return fallback;
30
+ }
16
31
  /** Why `caller` may not address a session owned by `owner`, or null when it may. */
17
32
  export function sessionOwnerMismatch(owner, caller) {
18
33
  if (owner.kind === 'jwt') {
@@ -128,13 +143,70 @@ function extractBearer(req) {
128
143
  export async function createHttpTransport(options) {
129
144
  const { registerTools, preferredPort } = options;
130
145
  const sessions = new Map();
146
+ const now = options.now ?? Date.now;
147
+ const sessionIdleMs = options.sessionIdleMs ?? positiveIntFromEnv('APRA_FLEET_SESSION_IDLE_MS', DEFAULT_SESSION_IDLE_MS);
148
+ const sessionCountWarn = options.sessionCountWarn ?? positiveIntFromEnv('APRA_FLEET_SESSION_COUNT_WARN', DEFAULT_SESSION_COUNT_WARN);
149
+ let sessionsEvicted = 0;
150
+ let sessionCountWarned = false;
131
151
  // Every install has its member access secret from the first server start
132
152
  // (install creates it too): a `?member=` request must present it.
133
153
  const memberSecretPath = options.memberSecretPath ?? memberAccessSecretPath();
134
154
  getOrCreateMemberAccessSecret(memberSecretPath);
135
155
  const startedAt = Date.now();
156
+ // Open channel-capable FULL-scope sessions (the operator's own orchestrating
157
+ // sessions), oldest first. The newest holds ORCHESTRATOR_SESSION_ID in the
158
+ // session registry; when it closes, the id moves to the newest still open.
159
+ const orchestratorSessions = [];
160
+ function registerOrchestrator(entry) {
161
+ sessionRegistry.register({
162
+ member_id: ORCHESTRATOR_SESSION_ID,
163
+ workspace_id: entry.workspaceId,
164
+ role: 'orchestrator',
165
+ work_folder: '',
166
+ server: entry.server,
167
+ sessionId: entry.sid,
168
+ status: 'online',
169
+ channelCapable: true,
170
+ });
171
+ logLine('session', `registered orchestrator session as member_id=${ORCHESTRATOR_SESSION_ID} workspace_id=${entry.workspaceId} sid=${shortSid(entry.sid)}`);
172
+ }
136
173
  // LOW-1: Track event listener references for cleanup in close()
137
174
  const eventCleanups = [];
175
+ /** Counts `res` as an open request on `session` until its response closes. */
176
+ function trackRequest(session, res) {
177
+ session.openRequests += 1;
178
+ session.lastActivity = now();
179
+ res.once('close', () => {
180
+ session.openRequests = Math.max(0, session.openRequests - 1);
181
+ session.lastActivity = now();
182
+ });
183
+ }
184
+ /**
185
+ * Evicts every session that has had no open request for longer than
186
+ * sessionIdleMs. Such a session belongs to a client that went away without
187
+ * an HTTP DELETE (a crash, or a transport stopped without close()): nothing
188
+ * can reach it again, and it would otherwise keep its McpServer forever.
189
+ * A client that comes back gets 404 and opens a new session, as the MCP
190
+ * spec requires.
191
+ */
192
+ function sweepIdleSessions() {
193
+ const t = now();
194
+ let evicted = 0;
195
+ for (const [sid, s] of [...sessions]) {
196
+ if (s.openRequests > 0 || t - s.lastActivity <= sessionIdleMs)
197
+ continue;
198
+ logLine('session', `evicted idle sid=${shortSid(sid)} client=${s.client} idle_s=${Math.round((t - s.lastActivity) / 1000)} (no open request; the client never closed it)`);
199
+ s.release('idle');
200
+ s.transport.close().catch(() => { });
201
+ evicted += 1;
202
+ }
203
+ sessionsEvicted += evicted;
204
+ if (sessionCountWarned && sessions.size < sessionCountWarn)
205
+ sessionCountWarned = false;
206
+ return evicted;
207
+ }
208
+ const idleSweepTimer = setInterval(sweepIdleSessions, options.idleSweepIntervalMs ?? DEFAULT_IDLE_SWEEP_INTERVAL_MS);
209
+ idleSweepTimer.unref?.();
138
210
  async function handleSessionRequest(req, res) {
139
211
  const sessionId = req.headers['mcp-session-id'];
140
212
  if (!sessionId) {
@@ -150,6 +222,7 @@ export async function createHttpTransport(options) {
150
222
  }
151
223
  if (refuseForeignCaller(req, res, sessionId, session))
152
224
  return;
225
+ trackRequest(session, res);
153
226
  await session.transport.handleRequest(req, res);
154
227
  }
155
228
  /** The identity this request carries. Called only past the pre-route gate,
@@ -192,6 +265,8 @@ export async function createHttpTransport(options) {
192
265
  pid: process.pid,
193
266
  uptime: Math.floor((Date.now() - startedAt) / 1000),
194
267
  sessions: sessions.size,
268
+ sessionsEvicted,
269
+ sessionIdleMs,
195
270
  });
196
271
  res.writeHead(200, { 'Content-Type': 'application/json' });
197
272
  res.end(body);
@@ -361,10 +436,80 @@ export async function createHttpTransport(options) {
361
436
  ? { kind: 'jwt', memberId: postClaims.member_id, workspaceId: postClaims.workspace_id }
362
437
  : { kind: 'secret', member: fallbackMemberId, engineOrigin, kbMaintainer: kbMaintainerParam };
363
438
  const sessionServer = new McpServer({ name: `apra fleet server ${serverVersion}`, version: serverVersion }, { capabilities: { logging: {}, experimental: { 'claude/channel': {} } } });
439
+ // Everything this session holds, released exactly once: by an HTTP
440
+ // DELETE (onsessionclosed) or by idle eviction (sweepIdleSessions).
441
+ let released = false;
442
+ const releaseSession = (sid, reason) => {
443
+ if (released)
444
+ return;
445
+ released = true;
446
+ if (reason === 'closed')
447
+ logLine('session', `closed sid=${shortSid(sid)}`);
448
+ // LOW-2: Close the McpServer when its session closes
449
+ sessionServer.server?.close().catch(() => { });
450
+ sessions.delete(sid);
451
+ // Unregister interactive member session -- but only if the registry
452
+ // entry still points at THIS session. If the member reconnected
453
+ // (new sid) before this stale session's close event fired, the
454
+ // registry now holds the NEW session's sessionId and must not be
455
+ // clobbered by the old one closing late (apra-fleet-2xs.10).
456
+ if (postClaims) {
457
+ const current = sessionRegistry.get(postClaims.workspace_id, postClaims.member_id);
458
+ if (current?.sessionId === sid) {
459
+ sessionRegistry.unregister(postClaims.workspace_id, postClaims.member_id);
460
+ logLine('session', `unregistered member member_id=${postClaims.member_id} sid=${shortSid(sid)}`);
461
+ }
462
+ else {
463
+ logLine('session', `skipped stale unregister member_id=${postClaims.member_id} sid=${shortSid(sid)} (superseded by sid=${shortSid(current?.sessionId)})`);
464
+ }
465
+ }
466
+ else if (fallbackMemberId && channelCapable) {
467
+ // A tool-only ?member= session never registered (see
468
+ // onsessioninitialized), so it never unregisters either.
469
+ const current = sessionRegistry.get(sessionWorkspaceId, fallbackMemberId);
470
+ if (current?.sessionId === sid) {
471
+ sessionRegistry.unregister(sessionWorkspaceId, fallbackMemberId);
472
+ logLine('session', `unregistered member member_id=${fallbackMemberId} sid=${shortSid(sid)}`);
473
+ }
474
+ else {
475
+ logLine('session', `skipped stale unregister member_id=${fallbackMemberId} sid=${shortSid(sid)} (superseded by sid=${shortSid(current?.sessionId)})`);
476
+ }
477
+ }
478
+ else if (channelCapable) {
479
+ const idx = orchestratorSessions.findIndex((o) => o.sid === sid);
480
+ if (idx !== -1)
481
+ orchestratorSessions.splice(idx, 1);
482
+ const current = sessionRegistry.get(sessionWorkspaceId, ORCHESTRATOR_SESSION_ID);
483
+ if (current?.sessionId === sid) {
484
+ // Hand the id to the newest orchestrating session still open
485
+ // in this workspace, else drop it.
486
+ const next = [...orchestratorSessions].reverse().find((o) => o.workspaceId === sessionWorkspaceId);
487
+ if (next)
488
+ registerOrchestrator(next);
489
+ else {
490
+ sessionRegistry.unregister(sessionWorkspaceId, ORCHESTRATOR_SESSION_ID);
491
+ logLine('session', `unregistered orchestrator session sid=${shortSid(sid)}`);
492
+ }
493
+ }
494
+ }
495
+ };
364
496
  const sessionTransport = new StreamableHTTPServerTransport({
365
497
  sessionIdGenerator: () => crypto.randomUUID(),
366
498
  onsessioninitialized: (sid) => {
367
- sessions.set(sid, { server: sessionServer, transport: sessionTransport, workspaceId: sessionWorkspaceId, owner: sessionOwner });
499
+ sessions.set(sid, {
500
+ server: sessionServer,
501
+ transport: sessionTransport,
502
+ workspaceId: sessionWorkspaceId,
503
+ owner: sessionOwner,
504
+ client: `${clientInfo.name ?? 'unknown'}/${clientInfo.version ?? 'unknown'}`,
505
+ lastActivity: now(),
506
+ openRequests: 0,
507
+ release: (reason) => releaseSession(sid, reason),
508
+ });
509
+ if (!sessionCountWarned && sessions.size >= sessionCountWarn) {
510
+ sessionCountWarned = true;
511
+ logLine('session', `WARNING: ${sessions.size} open MCP sessions (threshold ${sessionCountWarn}). A client is likely opening sessions without closing them (HTTP DELETE); sessions idle over ${Math.round(sessionIdleMs / 1000)}s are evicted. GET /health shows sessions and sessionsEvicted.`);
512
+ }
368
513
  const hasMember = !!(postClaims || fallbackMemberId);
369
514
  logLine('session', `new sid=${shortSid(sid)} client=${clientInfo.name ?? 'unknown'}/${clientInfo.version ?? 'unknown'} caps=${capKeys || 'none'} member=${hasMember} scope=${toolScope.kind}`);
370
515
  // Register interactive member session when JWT claims are present.
@@ -431,43 +576,17 @@ export async function createHttpTransport(options) {
431
576
  });
432
577
  logLine('session', `registered member member_id=${fallbackMemberId} workspace_id=${sessionWorkspaceId} via URL param sid=${shortSid(sid)} channelCapable=${channelCapable}`);
433
578
  }
434
- },
435
- onsessionclosed: (sid) => {
436
- logLine('session', `closed sid=${shortSid(sid)}`);
437
- // LOW-2: Close the McpServer when its session closes
438
- const s = sessions.get(sid);
439
- if (s) {
440
- s.server.server?.close().catch(() => { });
441
- }
442
- sessions.delete(sid);
443
- // Unregister interactive member session -- but only if the registry
444
- // entry still points at THIS session. If the member reconnected
445
- // (new sid) before this stale session's close event fired, the
446
- // registry now holds the NEW session's sessionId and must not be
447
- // clobbered by the old one closing late (apra-fleet-2xs.10).
448
- if (postClaims) {
449
- const current = sessionRegistry.get(postClaims.workspace_id, postClaims.member_id);
450
- if (current?.sessionId === sid) {
451
- sessionRegistry.unregister(postClaims.workspace_id, postClaims.member_id);
452
- logLine('session', `unregistered member member_id=${postClaims.member_id} sid=${shortSid(sid)}`);
453
- }
454
- else {
455
- logLine('session', `skipped stale unregister member_id=${postClaims.member_id} sid=${shortSid(sid)} (superseded by sid=${shortSid(current?.sessionId)})`);
456
- }
457
- }
458
- else if (fallbackMemberId && channelCapable) {
459
- // A tool-only ?member= session never registered (see
460
- // onsessioninitialized), so it never unregisters either.
461
- const current = sessionRegistry.get(sessionWorkspaceId, fallbackMemberId);
462
- if (current?.sessionId === sid) {
463
- sessionRegistry.unregister(sessionWorkspaceId, fallbackMemberId);
464
- logLine('session', `unregistered member member_id=${fallbackMemberId} sid=${shortSid(sid)}`);
465
- }
466
- else {
467
- logLine('session', `skipped stale unregister member_id=${fallbackMemberId} sid=${shortSid(sid)} (superseded by sid=${shortSid(current?.sessionId)})`);
468
- }
579
+ else if (channelCapable) {
580
+ // No member identity + claude/channel declared: the operator's
581
+ // own orchestrating session. Make it addressable by send_message
582
+ // under the stable ORCHESTRATOR_SESSION_ID (newest wins), so a
583
+ // sprint's needs-decision message can reach it.
584
+ const entry = { sid, workspaceId: sessionWorkspaceId, server: sessionServer };
585
+ orchestratorSessions.push(entry);
586
+ registerOrchestrator(entry);
469
587
  }
470
588
  },
589
+ onsessionclosed: (sid) => releaseSession(sid, 'closed'),
471
590
  });
472
591
  await registerTools(sessionServer, toolScope);
473
592
  await sessionServer.connect(sessionTransport);
@@ -488,6 +607,7 @@ export async function createHttpTransport(options) {
488
607
  }
489
608
  if (refuseForeignCaller(req, res, sessionId, session))
490
609
  return;
610
+ trackRequest(session, res);
491
611
  await session.transport.handleRequest(req, res, parsedBody);
492
612
  return;
493
613
  }
@@ -566,7 +686,9 @@ export async function createHttpTransport(options) {
566
686
  port,
567
687
  url,
568
688
  sessions,
689
+ sweepIdleSessions,
569
690
  close() {
691
+ clearInterval(idleSweepTimer);
570
692
  // LOW-1: Unsubscribe all fleet event listeners
571
693
  for (const cleanup of eventCleanups)
572
694
  cleanup();
@@ -575,6 +697,13 @@ export async function createHttpTransport(options) {
575
697
  session.server.server?.close().catch(() => { });
576
698
  }
577
699
  sessions.clear();
700
+ // Drop an orchestrator registry entry that points at one of this
701
+ // transport's sessions: its server is closed and can never answer.
702
+ for (const o of orchestratorSessions.splice(0)) {
703
+ if (sessionRegistry.get(o.workspaceId, ORCHESTRATOR_SESSION_ID)?.sessionId === o.sid) {
704
+ sessionRegistry.unregister(o.workspaceId, ORCHESTRATOR_SESSION_ID);
705
+ }
706
+ }
578
707
  return new Promise((resolve, reject) => {
579
708
  httpServer.close((err) => (err ? reject(err) : resolve()));
580
709
  });
@@ -0,0 +1,36 @@
1
+ export type KbToolProfileName = 'full' | 'developer' | 'custom';
2
+ export declare const KB_TOOL_PROFILE_NAMES: readonly KbToolProfileName[];
3
+ /** The resolved install-wide profile. `tools` is set only for custom. */
4
+ export type KbToolProfile = {
5
+ name: 'full';
6
+ } | {
7
+ name: 'developer';
8
+ } | {
9
+ name: 'custom';
10
+ tools: readonly string[];
11
+ };
12
+ export declare const FULL_KB_TOOL_PROFILE: KbToolProfile;
13
+ /** The kb_* tools the developer profile serves. */
14
+ export declare const DEVELOPER_KB_TOOLS: readonly string[];
15
+ /** Every registered kb_* tool name (the only names a custom list may hold). */
16
+ export declare function registeredKbToolNames(): string[];
17
+ export declare function isKbToolName(name: string): boolean;
18
+ /**
19
+ * Validate a custom tool list: non-empty, and every entry a registered kb_*
20
+ * tool name. Throws an Error naming the unknown entries and the valid ones.
21
+ * Returns the list de-duplicated, in the caller's order.
22
+ */
23
+ export declare function validateCustomKbTools(tools: readonly unknown[]): string[];
24
+ /**
25
+ * Build a profile from its name and (for custom) its list, validating both.
26
+ * Throws a clear Error on an unknown profile name or an invalid custom list.
27
+ */
28
+ export declare function makeKbToolProfile(name: unknown, tools?: readonly unknown[]): KbToolProfile;
29
+ /**
30
+ * True when `name` may be registered on a FULL session under `profile`.
31
+ * Non-kb tools are always allowed.
32
+ */
33
+ export declare function kbToolAllowedByProfile(name: string, profile: KbToolProfile): boolean;
34
+ /** One-line human description, e.g. for the CLI. */
35
+ export declare function describeKbToolProfile(profile: KbToolProfile): string;
36
+ //# sourceMappingURL=kb-tool-profile.d.ts.map
@@ -0,0 +1,88 @@
1
+ // KB tool profiles (GitHub #759): which kb_* tools a FULL (interactive,
2
+ // non-member) MCP session is served.
3
+ //
4
+ // full -- every kb_* tool (the default; also what an absent setting means).
5
+ // developer -- the everyday set: DEVELOPER_KB_TOOLS below.
6
+ // custom -- an explicit list of registered kb_* tool names.
7
+ //
8
+ // The profile is install-wide (stored in FLEET_DIR/knowledge/config.json as
9
+ // tool_profile / tool_profile_tools, see src/services/knowledge/kb-config.ts)
10
+ // and is applied only to FULL sessions when they register their tools
11
+ // (src/services/tool-registry.ts). Member sessions -- including the engine's
12
+ // kb_maintainer session -- keep their own allowlists regardless of profile.
13
+ // Non-kb tools (code_* included) are never filtered.
14
+ //
15
+ // This is a usability control that trims the tool list, NOT a security
16
+ // boundary: a hidden tool is just not listed, and the profile can be changed
17
+ // back with `apra-fleet kb profile full`.
18
+ import { REGISTERED_TOOL_NAMES } from './member-tool-allowlist.js';
19
+ export const KB_TOOL_PROFILE_NAMES = Object.freeze(['full', 'developer', 'custom']);
20
+ export const FULL_KB_TOOL_PROFILE = Object.freeze({ name: 'full' });
21
+ /** The kb_* tools the developer profile serves. */
22
+ export const DEVELOPER_KB_TOOLS = Object.freeze([
23
+ 'kb_session_prime', 'kb_query', 'kb_context', 'kb_capture', 'kb_feedback',
24
+ ]);
25
+ /** Every registered kb_* tool name (the only names a custom list may hold). */
26
+ export function registeredKbToolNames() {
27
+ return REGISTERED_TOOL_NAMES.filter(isKbToolName);
28
+ }
29
+ export function isKbToolName(name) {
30
+ return name.startsWith('kb_');
31
+ }
32
+ /**
33
+ * Validate a custom tool list: non-empty, and every entry a registered kb_*
34
+ * tool name. Throws an Error naming the unknown entries and the valid ones.
35
+ * Returns the list de-duplicated, in the caller's order.
36
+ */
37
+ export function validateCustomKbTools(tools) {
38
+ const valid = registeredKbToolNames();
39
+ const names = tools.map(t => (typeof t === 'string' ? t.trim() : String(t))).filter(t => t.length > 0);
40
+ if (names.length === 0) {
41
+ throw new Error(`KB tool profile "custom" needs at least one kb_* tool name. Valid names: ${valid.join(', ')}`);
42
+ }
43
+ const unknown = names.filter(n => !valid.includes(n));
44
+ if (unknown.length > 0) {
45
+ throw new Error(`KB tool profile "custom" has unknown kb tool name(s): ${[...new Set(unknown)].join(', ')}. ` +
46
+ `Valid names: ${valid.join(', ')}`);
47
+ }
48
+ return [...new Set(names)];
49
+ }
50
+ /**
51
+ * Build a profile from its name and (for custom) its list, validating both.
52
+ * Throws a clear Error on an unknown profile name or an invalid custom list.
53
+ */
54
+ export function makeKbToolProfile(name, tools) {
55
+ if (name === 'full')
56
+ return FULL_KB_TOOL_PROFILE;
57
+ if (name === 'developer')
58
+ return { name: 'developer' };
59
+ if (name === 'custom') {
60
+ if (!Array.isArray(tools)) {
61
+ throw new Error(`KB tool profile "custom" needs a tool list. Valid names: ${registeredKbToolNames().join(', ')}`);
62
+ }
63
+ return { name: 'custom', tools: validateCustomKbTools(tools) };
64
+ }
65
+ throw new Error(`Unknown KB tool profile ${JSON.stringify(name)}; expected one of: ${KB_TOOL_PROFILE_NAMES.join(', ')}`);
66
+ }
67
+ /**
68
+ * True when `name` may be registered on a FULL session under `profile`.
69
+ * Non-kb tools are always allowed.
70
+ */
71
+ export function kbToolAllowedByProfile(name, profile) {
72
+ if (!isKbToolName(name))
73
+ return true;
74
+ switch (profile.name) {
75
+ case 'full': return true;
76
+ case 'developer': return DEVELOPER_KB_TOOLS.includes(name);
77
+ case 'custom': return profile.tools.includes(name);
78
+ }
79
+ }
80
+ /** One-line human description, e.g. for the CLI. */
81
+ export function describeKbToolProfile(profile) {
82
+ switch (profile.name) {
83
+ case 'full': return 'full (every kb_* tool)';
84
+ case 'developer': return `developer (${DEVELOPER_KB_TOOLS.join(', ')})`;
85
+ case 'custom': return `custom (${profile.tools.join(', ')})`;
86
+ }
87
+ }
88
+ //# sourceMappingURL=kb-tool-profile.js.map
@@ -27,10 +27,19 @@
27
27
  // returns null rather than throwing when git cannot answer.
28
28
  import { execFile } from 'node:child_process';
29
29
  import { createHash } from 'node:crypto';
30
+ import { gitExecutable } from '../../os/git-executable.js';
30
31
  export const OWN_BIBLE_REL = '.fleet/kb-canonical.json';
31
32
  function gitBuffer(args, cwd) {
32
33
  return new Promise((resolve) => {
33
- execFile('git', ['--no-replace-objects', ...args], {
34
+ let gitBin;
35
+ try {
36
+ gitBin = gitExecutable();
37
+ }
38
+ catch {
39
+ resolve(null);
40
+ return;
41
+ }
42
+ execFile(gitBin, ['--no-replace-objects', ...args], {
34
43
  cwd, windowsHide: true, timeout: 30_000, maxBuffer: 256 * 1024 * 1024, encoding: 'buffer',
35
44
  }, (err, stdout) => resolve(err ? null : stdout));
36
45
  });
@@ -11,6 +11,92 @@ export declare class KbBibleError extends Error {
11
11
  readonly remediation: string;
12
12
  constructor(message: string, biblePath: string);
13
13
  }
14
+ /**
15
+ * An EXPLICIT tombstone in the committed bible: this id was removed from the
16
+ * bible at `at`, for `reason`. Only `reason: 'demoted'` (TOMBSTONE_DEMOTED)
17
+ * lowers a local row on import; every reason keeps the entry out of a bible view
18
+ * and stops kb_export re-adding it. Readers tolerate reason strings they do not
19
+ * know, so new removal reasons can be added without breaking older readers.
20
+ *
21
+ * A removal is NEVER inferred from an entry merely being absent from the bible
22
+ * -- a clone legitimately holds CONFIRMED rows that were never exported
23
+ * (local-only promotions, basis_mismatch refusals), and those must never be
24
+ * demoted by an import.
25
+ */
26
+ export interface BibleTombstone {
27
+ id: string;
28
+ at: string;
29
+ reason: string;
30
+ }
31
+ /** The tombstone reason a kb_demote produces; the only one that demotes on import. */
32
+ export declare const TOMBSTONE_DEMOTED = "demoted";
33
+ /**
34
+ * A parsed bible: its entries AND its tombstones. The two readers that return
35
+ * entries only (readBibleEntries/parseBibleText here, readBibleEntries in
36
+ * src/tools/kb-export.ts) keep their existing signature and are implemented on
37
+ * top of the document readers, so no existing caller changes shape.
38
+ */
39
+ export interface BibleDocument {
40
+ entries: unknown[];
41
+ demotions: BibleTombstone[];
42
+ }
43
+ /**
44
+ * The tombstones of an already-parsed bible value, in id order and deduped
45
+ * (last wins). Only a v3 envelope may carry them: a legacy bare array or a v2
46
+ * envelope yields none, whatever it holds. Tolerant otherwise: the field is
47
+ * OPTIONAL, and a malformed tombstone is dropped individually rather than
48
+ * failing the whole bible -- exactly how a malformed ENTRY is treated by
49
+ * importBibleEntries below. kb-export.ts's reader calls this too.
50
+ *
51
+ * Each `at` is clamped to `now` (clampBibleTimeToNow): a future-dated tombstone
52
+ * would otherwise become a future demoted_at on import, and every later
53
+ * re-promotion would count as withdrawn against it.
54
+ */
55
+ export declare function extractBibleDemotions(parsed: unknown, now?: Date): BibleTombstone[];
56
+ /**
57
+ * A bible-carried updated_at, clamped to `now`. A future-dated entry would
58
+ * otherwise outrank every later tombstone under standingAgainstTombstone. An
59
+ * unparseable value is returned unchanged (the standing rule reports it as
60
+ * 'unknown').
61
+ */
62
+ export declare function clampBibleTimeToNow(time: string, now?: Date): string;
63
+ /**
64
+ * How a local row stands against a tombstone for the same id. The ONE rule both
65
+ * directions use -- kb_import demotes only on 'withdrawn', kb_export re-adds
66
+ * only on 'repromoted', and 'unknown' makes neither act.
67
+ *
68
+ * `trustTime` is the time this clone's trust in the row dates from, AS A BIBLE
69
+ * RECORDS IT (SqliteProvider.getBibleTrustTimes): the local promotion time, else
70
+ * the `updated_at` the bible carried when the row was imported -- never the
71
+ * local import time, which says nothing about when the entry was promoted.
72
+ * - null (a row imported before that time was kept) -> 'withdrawn': its trust
73
+ * came from a bible, and a later bible withdrew it.
74
+ * - strictly after `at` -> 'repromoted': newer evidence than the tombstone.
75
+ * - at or before `at` -> 'withdrawn'.
76
+ * - either time unparseable -> 'unknown'.
77
+ */
78
+ export type TombstoneStanding = 'repromoted' | 'withdrawn' | 'unknown';
79
+ export declare function standingAgainstTombstone(trustTime: string | null, at: string): TombstoneStanding;
80
+ /** The tombstoned ids of a parsed bible, as a set for membership tests. */
81
+ export declare function tombstonedIds(demotions: BibleTombstone[]): Set<string>;
82
+ /**
83
+ * Drop every entry a tombstone names from a raw bible entry array.
84
+ *
85
+ * For the READ paths that build a view of the bible rather than merging it into
86
+ * an existing KB -- the member bible view, which imports into a FRESH empty
87
+ * in-memory provider. There is no local row there for a tombstone to demote, so
88
+ * the demotion can only be honoured by not listing the entry at all.
89
+ *
90
+ * Normally a committed bible holds no entry for a tombstoned id (kb_bible_commit
91
+ * removes it when it records the tombstone), so this is belt-and-braces against
92
+ * a hand-edited or partially merged bible -- the one place where "the file says
93
+ * both" must resolve to the demotion, because a view that lists a demoted entry
94
+ * is exactly the staleness the tombstone exists to stop.
95
+ *
96
+ * Entries too malformed to carry an id are left alone; importBibleEntries
97
+ * already tolerates and skips those.
98
+ */
99
+ export declare function excludeTombstonedEntries(entries: unknown[], demotions: BibleTombstone[]): unknown[];
14
100
  /**
15
101
  * Read and parse a bible file into its raw entry array. Throws KbBibleError
16
102
  * when the file is not valid JSON or not a bible shape. `label` prefixes the
@@ -27,6 +113,10 @@ export declare class KbBibleError extends Error {
27
113
  export declare function readBibleEntries(biblePath: string, label: string): unknown[];
28
114
  /** Parse bible text already in memory (e.g. fetched from a remote member). */
29
115
  export declare function parseBibleText(raw: string, biblePath: string, label: string): unknown[];
116
+ /** Entries AND tombstones of a bible file. Same parse, same refusals. */
117
+ export declare function readBibleDocument(biblePath: string, label: string): BibleDocument;
118
+ /** Entries AND tombstones of bible text already in memory. */
119
+ export declare function parseBibleDocument(raw: string, biblePath: string, label: string): BibleDocument;
30
120
  /**
31
121
  * The basis a v3 bible entry carries, or null when it carries none or an
32
122
  * invalid one. Valid means: a plain object, at least one key, every key
@@ -45,6 +135,13 @@ export interface BibleImportCounts {
45
135
  linked: number;
46
136
  flagged: number;
47
137
  rejected: number;
138
+ /**
139
+ * Local rows actually taken CONFIRMED -> INFERRED by an explicit demotion
140
+ * tombstone in this bible. A tombstone that named no local row, or one whose
141
+ * row was re-promoted after the demotion, is NOT counted: this is how many
142
+ * rows changed, not how many tombstones were read.
143
+ */
144
+ demoted: number;
48
145
  }
49
146
  /**
50
147
  * Import raw bible entries into a SqliteProvider through capture()'s INTERNAL
@@ -60,6 +157,17 @@ export interface BibleImportOptions {
60
157
  * which must reproduce the reviewed bible rather than re-curate it.
61
158
  */
62
159
  verbatim?: boolean;
160
+ /**
161
+ * The EXPLICIT demotion tombstones of the same bible (parseBibleDocument /
162
+ * readBibleDocument return them alongside the entries). Applied AFTER the
163
+ * entry loop, against rows that already existed locally.
164
+ *
165
+ * Omitted (or empty) means "this bible carries no tombstones" -- NOT "demote
166
+ * whatever is missing". Absence is never evidence of demotion: a clone
167
+ * legitimately holds CONFIRMED rows that were never exported, and an import
168
+ * must leave those byte-unchanged.
169
+ */
170
+ demotions?: BibleTombstone[];
63
171
  }
64
172
  export declare function importBibleEntries(provider: SqliteProvider, bibleEntries: unknown[], options?: BibleImportOptions): Promise<BibleImportCounts>;
65
173
  //# sourceMappingURL=bible-import.d.ts.map