@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
|
@@ -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, {
|
|
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
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
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
|
-
|
|
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
|