@apralabs/apra-fleet 0.4.4 → 0.4.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +49 -4
- package/dist/agents/backlog-groomer.md +5 -0
- package/dist/agents/ci-watcher.md +5 -0
- package/dist/agents/deployer.md +20 -2
- package/dist/agents/doer.md +38 -2
- package/dist/agents/harvester.md +12 -9
- package/dist/agents/integ-test-runner.md +5 -0
- package/dist/agents/kb-reconciler.md +6 -0
- package/dist/agents/plan-reviewer.md +5 -0
- package/dist/agents/planner.md +5 -0
- package/dist/agents/regression-test-runner.md +5 -0
- package/dist/agents/reviewer.md +67 -15
- package/dist/agents/schemas/deployer-output.json +5 -0
- package/dist/agents/schemas/doer-output.json +78 -2
- package/dist/agents/schemas/reviewer-output.json +104 -2
- package/dist/cli/auth.js +5 -1
- package/dist/cli/beads-pin.js +6 -7
- package/dist/cli/claude-mod.d.ts +75 -0
- package/dist/cli/claude-mod.js +288 -0
- package/dist/cli/dolt-install.d.ts +1 -1
- package/dist/cli/dolt-install.js +5 -1
- package/dist/cli/fleet-se-guard.d.ts +8 -0
- package/dist/cli/fleet-se-guard.js +19 -3
- package/dist/cli/install-guard.d.ts +9 -0
- package/dist/cli/install-guard.js +24 -0
- package/dist/cli/install.d.ts +12 -0
- package/dist/cli/install.js +180 -20
- package/dist/cli/kb-profile.d.ts +16 -0
- package/dist/cli/kb-profile.js +81 -0
- package/dist/cli/start.js +3 -0
- package/dist/cli/uninstall.js +13 -3
- package/dist/cli/update.d.ts +4 -0
- package/dist/cli/update.js +19 -3
- package/dist/commands/kb-server.d.ts +10 -1
- package/dist/commands/kb-server.js +285 -11
- package/dist/index.js +22 -1
- package/dist/os/git-executable.d.ts +57 -0
- package/dist/os/git-executable.js +85 -0
- package/dist/os/go-concurrency.d.ts +44 -0
- package/dist/os/go-concurrency.js +53 -0
- package/dist/os/index.d.ts +1 -0
- package/dist/os/index.js +1 -0
- package/dist/os/linux.d.ts +2 -0
- package/dist/os/linux.js +10 -1
- package/dist/os/os-commands.d.ts +25 -0
- package/dist/os/os-commands.js +2 -0
- package/dist/os/windows-executable.d.ts +53 -0
- package/dist/os/windows-executable.js +185 -0
- package/dist/os/windows-gitbash.d.ts +23 -14
- package/dist/os/windows-gitbash.js +40 -16
- package/dist/os/windows.d.ts +2 -0
- package/dist/os/windows.js +37 -6
- package/dist/paths.d.ts +10 -1
- package/dist/paths.js +19 -2
- package/dist/services/agy-project.d.ts +7 -1
- package/dist/services/agy-project.js +7 -2
- package/dist/services/auth-socket.d.ts +18 -0
- package/dist/services/auth-socket.js +30 -4
- package/dist/services/credential-store.d.ts +33 -0
- package/dist/services/credential-store.js +79 -2
- package/dist/services/http-transport.d.ts +29 -0
- package/dist/services/http-transport.js +166 -37
- package/dist/services/kb-tool-profile.d.ts +36 -0
- package/dist/services/kb-tool-profile.js +88 -0
- package/dist/services/knowledge/bible-blob-id.js +10 -1
- package/dist/services/knowledge/bible-import.d.ts +108 -0
- package/dist/services/knowledge/bible-import.js +137 -4
- package/dist/services/knowledge/file-hash.js +6 -5
- package/dist/services/knowledge/http-provider.d.ts +303 -20
- package/dist/services/knowledge/http-provider.js +795 -125
- package/dist/services/knowledge/kb-config.d.ts +65 -1
- package/dist/services/knowledge/kb-config.js +143 -3
- package/dist/services/knowledge/kb-http-auth-state.d.ts +26 -0
- package/dist/services/knowledge/kb-http-auth-state.js +40 -0
- package/dist/services/knowledge/kb-providers.d.ts +9 -2
- package/dist/services/knowledge/kb-providers.js +67 -37
- package/dist/services/knowledge/kb-removed-scope-keys.js +1 -1
- package/dist/services/knowledge/kb-self.d.ts +122 -9
- package/dist/services/knowledge/kb-self.js +196 -36
- package/dist/services/knowledge/member-bible-view.js +16 -3
- package/dist/services/knowledge/path-validation.d.ts +7 -0
- package/dist/services/knowledge/path-validation.js +11 -0
- package/dist/services/knowledge/project-slug.js +3 -2
- package/dist/services/knowledge/repository-header.d.ts +77 -0
- package/dist/services/knowledge/repository-header.js +233 -0
- package/dist/services/knowledge/require-sqlite-project.d.ts +1 -1
- package/dist/services/knowledge/require-sqlite-project.js +1 -1
- package/dist/services/knowledge/sqlite-provider.d.ts +169 -0
- package/dist/services/knowledge/sqlite-provider.js +416 -4
- package/dist/services/knowledge/types.d.ts +15 -2
- package/dist/services/member-busy.d.ts +12 -0
- package/dist/services/member-busy.js +20 -0
- package/dist/services/member-config-io.d.ts +3 -2
- package/dist/services/member-config-io.js +7 -4
- package/dist/services/member-fleet-install.js +1 -0
- package/dist/services/member-tool-allowlist.d.ts +1 -1
- package/dist/services/member-tool-allowlist.js +8 -4
- package/dist/services/port-holder.js +2 -1
- package/dist/services/service-manager/types.d.ts +17 -1
- package/dist/services/service-manager/windows.d.ts +7 -2
- package/dist/services/service-manager/windows.js +28 -11
- package/dist/services/service-notice.d.ts +7 -0
- package/dist/services/service-notice.js +19 -0
- package/dist/services/session-registry.d.ts +13 -0
- package/dist/services/session-registry.js +13 -0
- package/dist/services/session-roots.d.ts +67 -0
- package/dist/services/session-roots.js +126 -0
- package/dist/services/statusline.d.ts +21 -0
- package/dist/services/statusline.js +97 -1
- package/dist/services/supervisor-service-cleanup.js +2 -1
- package/dist/services/tool-registry.js +108 -20
- package/dist/services/tool-scope.d.ts +34 -1
- package/dist/services/tool-scope.js +27 -2
- package/dist/services/vcs/azure-devops.js +10 -0
- package/dist/services/vcs/bitbucket.d.ts +22 -1
- package/dist/services/vcs/bitbucket.js +163 -17
- package/dist/services/vcs/types.d.ts +25 -2
- package/dist/services/watch/project-resolver.js +2 -1
- package/dist/skills/pm/cost.md +5 -1
- package/dist/skills/pm/index.md +9 -9
- package/dist/skills/pm/sprint.md +2 -1
- package/dist/tools/check-status.d.ts +51 -0
- package/dist/tools/check-status.js +124 -12
- package/dist/tools/code-intelligence-freshness.js +1 -1
- package/dist/tools/code-intelligence-gitnexus.d.ts +19 -0
- package/dist/tools/code-intelligence-gitnexus.js +166 -9
- package/dist/tools/code-intelligence-readiness.d.ts +58 -1
- package/dist/tools/code-intelligence-readiness.js +93 -8
- package/dist/tools/code-intelligence-reindex.d.ts +25 -1
- package/dist/tools/code-intelligence-reindex.js +76 -4
- package/dist/tools/code-intelligence.d.ts +1 -1
- package/dist/tools/code-intelligence.js +1 -1
- package/dist/tools/execute-command.js +14 -8
- package/dist/tools/execute-prompt.js +6 -2
- package/dist/tools/fleet-snapshot.d.ts +21 -0
- package/dist/tools/fleet-snapshot.js +78 -0
- package/dist/tools/kb-bible-commit.d.ts +25 -11
- package/dist/tools/kb-bible-commit.js +142 -33
- package/dist/tools/kb-capture.d.ts +2 -2
- package/dist/tools/kb-context.js +47 -27
- package/dist/tools/kb-demote.d.ts +27 -0
- package/dist/tools/kb-demote.js +37 -0
- package/dist/tools/kb-export.d.ts +35 -3
- package/dist/tools/kb-export.js +56 -13
- package/dist/tools/kb-feedback.d.ts +2 -0
- package/dist/tools/kb-feedback.js +17 -7
- package/dist/tools/kb-harvest.js +28 -9
- package/dist/tools/kb-import.d.ts +18 -2
- package/dist/tools/kb-import.js +24 -9
- package/dist/tools/kb-invalidate.d.ts +11 -3
- package/dist/tools/kb-invalidate.js +80 -7
- package/dist/tools/kb-list.js +38 -10
- package/dist/tools/kb-promote.js +6 -4
- package/dist/tools/kb-query.d.ts +3 -0
- package/dist/tools/kb-query.js +181 -37
- package/dist/tools/kb-session-prime.d.ts +4 -4
- package/dist/tools/kb-session-prime.js +89 -9
- package/dist/tools/kb-setup.d.ts +20 -0
- package/dist/tools/kb-setup.js +149 -11
- package/dist/tools/list-members.js +1 -1
- package/dist/tools/member-detail.js +7 -3
- package/dist/tools/provision-vcs-auth.d.ts +28 -3
- package/dist/tools/provision-vcs-auth.js +53 -7
- package/dist/tools/receive-files.js +7 -4
- package/dist/tools/send-files.js +5 -4
- package/dist/tools/send-message.d.ts +3 -0
- package/dist/tools/send-message.js +15 -2
- package/dist/tools/stop-prompt.js +3 -1
- package/dist/tools/vcs-credential-exec.d.ts +45 -3
- package/dist/tools/vcs-credential-exec.js +90 -11
- package/dist/utils/process-utils.js +5 -1
- package/dist/utils/redact-known-secrets.d.ts +17 -0
- package/dist/utils/redact-known-secrets.js +70 -0
- package/dist/utils/skill-matrix.js +1 -1
- package/dist/utils/vcs-provider-detect.js +2 -2
- package/dist/workflows/auto-sprint.js +245 -9
- package/package.json +10 -7
- package/packages/apra-fleet-client/package.json +1 -1
- package/packages/apra-fleet-client/src/client/api.mjs +172 -19
- package/packages/apra-fleet-client/src/client/reconnecting-transport.mjs +35 -2
- package/packages/apra-fleet-client/src/client/transport.mjs +6 -0
- package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/deployer.md +20 -2
- package/packages/apra-fleet-se/apra-pm/agents/doer.md +38 -2
- package/packages/apra-fleet-se/apra-pm/agents/harvester.md +12 -9
- package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +6 -0
- package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/planner.md +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +67 -15
- package/packages/apra-fleet-se/apra-pm/agents/schemas/deployer-output.json +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-output.json +78 -2
- package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json +104 -2
- package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +5 -1
- package/packages/apra-fleet-se/apra-pm/skills/pm/index.md +9 -9
- package/packages/apra-fleet-se/apra-pm/skills/pm/sprint.md +2 -1
- package/packages/apra-fleet-se/bin/cli.mjs +104 -31
- package/packages/apra-fleet-se/bin/serve.mjs +46 -8
- package/packages/apra-fleet-se/fleet-sprint/abort.mjs +184 -32
- package/packages/apra-fleet-se/fleet-sprint/bd-sync-command.mjs +69 -0
- package/packages/apra-fleet-se/fleet-sprint/beads-children.mjs +21 -0
- package/packages/apra-fleet-se/fleet-sprint/beads-lock-probe.mjs +176 -0
- package/packages/apra-fleet-se/fleet-sprint/beads-reachability.mjs +126 -0
- package/packages/apra-fleet-se/fleet-sprint/beads-scope.mjs +158 -1
- package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +82 -2
- package/packages/apra-fleet-se/fleet-sprint/coordination.mjs +23 -6
- package/packages/apra-fleet-se/fleet-sprint/decision-notify.mjs +338 -0
- package/packages/apra-fleet-se/fleet-sprint/decision-wait.mjs +731 -0
- package/packages/apra-fleet-se/fleet-sprint/decisions.mjs +372 -0
- package/packages/apra-fleet-se/fleet-sprint/dispatch-role.mjs +44 -11
- package/packages/apra-fleet-se/fleet-sprint/docs/README.md +4 -1
- package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +9 -3
- package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +314 -19
- package/packages/apra-fleet-se/fleet-sprint/errors.mjs +72 -4
- package/packages/apra-fleet-se/fleet-sprint/git-sync.mjs +7 -1
- package/packages/apra-fleet-se/fleet-sprint/git-topology.mjs +112 -1
- package/packages/apra-fleet-se/fleet-sprint/guarded-modules.mjs +36 -2
- package/packages/apra-fleet-se/fleet-sprint/kb.mjs +736 -101
- package/packages/apra-fleet-se/fleet-sprint/member-init-probe.mjs +1 -1
- package/packages/apra-fleet-se/fleet-sprint/member-provisioning.mjs +7 -1
- package/packages/apra-fleet-se/fleet-sprint/phases/deploy.mjs +49 -2
- package/packages/apra-fleet-se/fleet-sprint/phases/develop.mjs +206 -3
- package/packages/apra-fleet-se/fleet-sprint/phases/final-review.mjs +61 -3
- package/packages/apra-fleet-se/fleet-sprint/phases/harvest.mjs +81 -31
- package/packages/apra-fleet-se/fleet-sprint/phases/plan.mjs +7 -3
- package/packages/apra-fleet-se/fleet-sprint/phases/publish-pr.mjs +39 -14
- package/packages/apra-fleet-se/fleet-sprint/phases/re-review.mjs +17 -1
- package/packages/apra-fleet-se/fleet-sprint/phases/review.mjs +18 -3
- package/packages/apra-fleet-se/fleet-sprint/pr-body.mjs +14 -1
- package/packages/apra-fleet-se/fleet-sprint/prompts.mjs +32 -5
- package/packages/apra-fleet-se/fleet-sprint/runner.js +824 -98
- package/packages/apra-fleet-se/fleet-sprint/se-os-commands.mjs +4 -2
- package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +54 -1
- package/packages/apra-fleet-se/fleet-sprint/se-windows.mjs +29 -2
- package/packages/apra-fleet-se/fleet-sprint/set-aside.mjs +288 -0
- package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +3 -2
- package/packages/apra-fleet-se/fleet-sprint/sprint-args.mjs +20 -0
- package/packages/apra-fleet-se/fleet-sprint/sprint-report.mjs +21 -0
- package/packages/apra-fleet-se/fleet-sprint/sprint-state.mjs +9 -0
- package/packages/apra-fleet-se/fleet-sprint/vcs-auth.mjs +605 -32
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +811 -17
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +89 -1
- package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +225 -2
- package/packages/apra-fleet-se/fleet-sprint/worklists.mjs +59 -3
- package/packages/apra-fleet-se/src/supervisor/api.mjs +148 -8
- package/packages/apra-fleet-se/src/supervisor/dashboard.mjs +6 -3
- package/packages/apra-fleet-se/src/supervisor/dolt-mutex.mjs +30 -10
- package/packages/apra-fleet-se/src/supervisor/fleet-members.mjs +17 -4
- package/packages/apra-fleet-se/src/supervisor/history.mjs +8 -1
- package/packages/apra-fleet-se/src/supervisor/id-allocator.mjs +92 -2
- package/packages/apra-fleet-se/src/supervisor/proxy.mjs +26 -1
- package/packages/apra-fleet-se/src/supervisor/server.mjs +151 -8
- package/packages/apra-fleet-se/src/supervisor/spawner.mjs +11 -9
- package/packages/apra-fleet-se/src/supervisor/watchdog.mjs +7 -1
- package/packages/apra-fleet-workflow/package.json +2 -1
- package/packages/apra-fleet-workflow/src/viewer/index.mjs +86 -5
- package/packages/apra-fleet-workflow/src/viewer/request-guard.mjs +222 -0
- package/packages/apra-fleet-workflow/src/workflow/index.mjs +34 -2
- package/plugins/claude-code/fleet-status/.claude-plugin/plugin.json +7 -0
- package/plugins/claude-code/fleet-status/hooks/hooks.json +1 -0
- package/plugins/claude-code/fleet-status/hooks/register.tsx +906 -0
- package/plugins/claude-code/fleet-status/types/index.d.ts +88 -0
- package/skills/fleet/auth-bitbucket.md +47 -20
- package/skills/fleet/onboarding.md +1 -1
- package/skills/fleet/skill-matrix.md +3 -3
- package/version.json +1 -1
|
@@ -1,3 +1,20 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @typedef {Object} FleetSnapshotMember
|
|
3
|
+
* @property {string} id
|
|
4
|
+
* @property {string} name
|
|
5
|
+
* @property {string} icon
|
|
6
|
+
* @property {string|null} category
|
|
7
|
+
* @property {'busy'|'idle'|'offline'|'unknown'} status
|
|
8
|
+
* @property {number} [quietForS] While busy: seconds since the task last showed activity.
|
|
9
|
+
* @property {string} [reservedBy] Holder of the member reservation, when held.
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* @typedef {Object} FleetSnapshot
|
|
14
|
+
* @property {string} version Server version.
|
|
15
|
+
* @property {FleetSnapshotMember[]} members
|
|
16
|
+
*/
|
|
17
|
+
|
|
1
18
|
/**
|
|
2
19
|
* @typedef {Object} ExecutePromptOptions
|
|
3
20
|
* @property {string} prompt - The prompt to send to the LLM on the remote member
|
|
@@ -269,6 +286,23 @@
|
|
|
269
286
|
* @property {string} [repo_path] - Absolute path to a repo checkout; adds that repo's code-intelligence index health and its KB scope's bible drift. The server's own cwd is never used. KB health itself always covers every project KB scope plus the global KB.
|
|
270
287
|
*/
|
|
271
288
|
|
|
289
|
+
/**
|
|
290
|
+
* Remote KB credential health, `kbHealth.credential` in fleet_status json
|
|
291
|
+
* output (one compact `kb credential:` line in compact output). Present only
|
|
292
|
+
* when the KB config selects the http provider; this host only. Never carries
|
|
293
|
+
* the token value, nor any JWT claim other than exp.
|
|
294
|
+
* @typedef {Object} FleetStatusKbCredential
|
|
295
|
+
* @property {"secret" | "literal"} kind - "secret": token_ref names a fleet secret looked up per request; "literal": a stored literal token
|
|
296
|
+
* @property {string} url - Remote KB URL
|
|
297
|
+
* @property {string} [secretName] - kind "secret": the fleet secret's name
|
|
298
|
+
* @property {"ok" | "missing" | "expired" | "unreadable"} [resolves] - kind "secret": metadata lookup result (an expired record is kept); "unreadable" when the credential store cannot be read or the value cannot be decrypted
|
|
299
|
+
* @property {string | null} [lastWritten] - kind "secret": the secret record's created_at; null when missing or the store is unreadable
|
|
300
|
+
* @property {string | null} [tokenExpiry] - kind "secret": JWT exp decoded locally (ISO time); null for a non-JWT or unresolved value
|
|
301
|
+
* @property {string | null} lastSuccessfulCall - Last KB call accepted by the remote server in this server process; null when none yet
|
|
302
|
+
* @property {string | null} lastRejectedCall - Last KB call rejected with HTTP 401 in this server process; null when none yet
|
|
303
|
+
* @property {string} [hint] - kind "literal": the token cannot be refreshed; how to switch to {{secret.NAME}}
|
|
304
|
+
*/
|
|
305
|
+
|
|
272
306
|
/**
|
|
273
307
|
* @typedef {Object} SendFilesOptions
|
|
274
308
|
* @property {string[]} local_paths - Array of local file paths to upload
|
|
@@ -502,6 +536,18 @@
|
|
|
502
536
|
* with the value escaped for the interior of a single-quoted string, with no quotes of its
|
|
503
537
|
* own, for interpolating the token into a larger already-quoted value (e.g. an Authorization
|
|
504
538
|
* header) where a bare, self-quoting substitution cannot compose.
|
|
539
|
+
* Bitbucket REST uses the token as a Bearer value
|
|
540
|
+
* (-H 'Authorization: Bearer {{vcs_token_inline}}'), with no username and no email.
|
|
541
|
+
* Two further OPTIONAL placeholders substitute the credential helper's git username under
|
|
542
|
+
* exactly the same two dialects (for Bitbucket always x-bitbucket-api-token-auth, a git-only
|
|
543
|
+
* username, never a REST login): {{vcs_username}}, referenced BARE -- already escaped AND
|
|
544
|
+
* quoted for that member's shell; and {{vcs_username_inline}}, referenced INSIDE your own
|
|
545
|
+
* single quotes -- escaped for the interior of a single-quoted string, with no quotes of its
|
|
546
|
+
* own. A username placeholder may not appear on
|
|
547
|
+
* its own: a token placeholder is still required, or the call is refused with
|
|
548
|
+
* reason "placeholder_missing". If the command references a username placeholder and the
|
|
549
|
+
* helper prints no username= line, the call fails with reason "username_empty" and dispatches
|
|
550
|
+
* nothing.
|
|
505
551
|
* @property {string} [label] - Credential label provision_vcs_auth deployed the helper under
|
|
506
552
|
* (it defaults to the provider name there, e.g. "github" or "azure-devops"). Omit for the
|
|
507
553
|
* unlabelled helper.
|
|
@@ -515,13 +561,15 @@
|
|
|
515
561
|
* @property {boolean} ok - True when the credential-requiring command was dispatched. Read
|
|
516
562
|
* exitCode for the command's own outcome.
|
|
517
563
|
* @property {"ok" | "member_not_found" | "placeholder_missing" | "unsupported_member_os" |
|
|
518
|
-
* "credential_read_failed" | "credential_empty" | "
|
|
564
|
+
* "credential_read_failed" | "credential_empty" | "username_empty" |
|
|
565
|
+
* "dispatch_failed"} reason - Machine-readable
|
|
519
566
|
* outcome code. Branch on this, never on the text.
|
|
520
567
|
* @property {number|null} exitCode - Exit code of the dispatched command, null if it never ran.
|
|
521
568
|
* @property {string} stdout - Command stdout, with every occurrence of the credential redacted.
|
|
522
569
|
* @property {string} stderr - Command stderr, with every occurrence of the credential redacted.
|
|
523
|
-
* @property {number} tokenRedactions - How many times
|
|
524
|
-
* stdout+stderr
|
|
570
|
+
* @property {number} tokenRedactions - How many times credential material had to be redacted out
|
|
571
|
+
* of stdout+stderr -- the token, plus the helper git username when the command substituted one.
|
|
572
|
+
* Normally 0; nonzero means the command echoed its own credential back.
|
|
525
573
|
* @property {string|null} credentialLabel - Credential label used, or null for the unlabelled helper.
|
|
526
574
|
* @property {string|null} memberId - Registry id of the resolved member, or null.
|
|
527
575
|
* @property {string|null} memberName - Friendly name of the resolved member, or null.
|
|
@@ -563,8 +611,10 @@
|
|
|
563
611
|
* @property {"ok" | "deployed_unverified" | "deployed_verification_skipped" |
|
|
564
612
|
* "member_not_found" | "member_offline" | "secret_variable_not_found" |
|
|
565
613
|
* "secret_variable_denied" | "secret_variable_expired" | "oob_cancelled" |
|
|
566
|
-
* "
|
|
567
|
-
* "deploy_failed"} reason - Machine-readable outcome code. Branch on this,
|
|
614
|
+
* "credential_missing" | "credential_assembly_unsupported" | "credential_assembly_failed" |
|
|
615
|
+
* "deploy_threw" | "deploy_failed"} reason - Machine-readable outcome code. Branch on this,
|
|
616
|
+
* never on the text. "credential_missing": non_interactive was set and the secret field is
|
|
617
|
+
* absent (message names it; nothing was prompted).
|
|
568
618
|
* @property {string} provider - The VCS provider requested.
|
|
569
619
|
* @property {string} credentialLabel - Credential label the helper was deployed under
|
|
570
620
|
* (defaults to the provider name).
|
|
@@ -574,6 +624,10 @@
|
|
|
574
624
|
* instead of scraping an "expiresAt:" line out of the summary text.
|
|
575
625
|
* @property {boolean} verified - True only when testConnectivity() actually ran AND succeeded.
|
|
576
626
|
* @property {boolean} verificationSkipped - True when the connectivity check was not performed.
|
|
627
|
+
* @property {string|null} verificationReason - The provider's machine-readable verification
|
|
628
|
+
* cause naming which channel failed, when it reports one (Bitbucket: "ok",
|
|
629
|
+
* "rest_unauthorized", "rest_failed", "git_auth_failed", "git_failed"); null when the
|
|
630
|
+
* provider reports none or the check was skipped.
|
|
577
631
|
* @property {Record<string, string>|null} metadata - The provider's own deploy metadata,
|
|
578
632
|
* filtered through a server-side key allowlist before it reaches this field (an unrecognised
|
|
579
633
|
* key is dropped, never passed through). Providers additionally mask the token value here to
|
|
@@ -597,6 +651,9 @@
|
|
|
597
651
|
* @property {string} [member_name] - Friendly name of the member
|
|
598
652
|
* @property {"github" | "bitbucket" | "azure-devops"} provider - VCS provider to configure
|
|
599
653
|
* @property {string} [label] - Credential label (slug, e.g. "work-github"). Defaults to provider name.
|
|
654
|
+
* @property {boolean} [non_interactive] - When true, never prompt out of band: a missing secret
|
|
655
|
+
* field (api_token / pat / token) returns ok=false with reason "credential_missing" naming the
|
|
656
|
+
* field. Required non-secret fields are validated before any prompt in both modes. Default false.
|
|
600
657
|
* @property {string} [scope_url] - Git credential scope URL (e.g. "https://github.com/my-org").
|
|
601
658
|
* Defaults to "https://<host>". For an Azure DevOps repo on the legacy host, pass
|
|
602
659
|
* "https://ORG.visualstudio.com" so the PAT is bound to the host the member pushes to.
|
|
@@ -604,13 +661,18 @@
|
|
|
604
661
|
* configured app) or pat (personal access token)
|
|
605
662
|
* @property {string} [token] - Personal access token (GitHub PAT or Azure DevOps PAT).
|
|
606
663
|
* Supports {{secret.NAME}} token -- resolved from the credential store server-side before use.
|
|
607
|
-
* @property {"read" | "push" | "push+pr" | "admin" | "issues" | "full"} [git_access] - GitHub App
|
|
664
|
+
* @property {"read" | "push" | "push+pr" | "admin" | "issues" | "full"} [git_access] - GitHub App mode
|
|
665
|
+
* only: what the token may do. Use "push+pr" to create pull requests and dispatch workflows (see
|
|
666
|
+
* docs/api-reference.md for every level). GitHub App access
|
|
608
667
|
* level override
|
|
609
668
|
* @property {string[]} [repos] - GitHub App repository list override
|
|
610
|
-
* @property {string} [email] - Bitbucket account email
|
|
611
|
-
*
|
|
612
|
-
*
|
|
613
|
-
* @property {string} [
|
|
669
|
+
* @property {string} [email] - OPTIONAL Bitbucket account email. Ignored for authentication
|
|
670
|
+
* (git uses the fixed token username x-bitbucket-api-token-auth, REST uses a Bearer token);
|
|
671
|
+
* kept only as metadata if given.
|
|
672
|
+
* @property {string} [api_token] - Bitbucket API token (required for bitbucket). Store it as the
|
|
673
|
+
* fleet secret bitbucket_api_token and pass {{secret.bitbucket_api_token}} -- resolved from
|
|
674
|
+
* the credential store server-side before use.
|
|
675
|
+
* @property {string} [workspace] - Bitbucket workspace slug (required for bitbucket).
|
|
614
676
|
* @property {string} [org_url] - Azure DevOps organization URL (e.g. https://dev.azure.com/myorg,
|
|
615
677
|
* or the legacy https://myorg.visualstudio.com)
|
|
616
678
|
* @property {string} [pat] - Azure DevOps personal access token. Supports {{secret.NAME}}
|
|
@@ -699,6 +761,27 @@
|
|
|
699
761
|
* @property {string} baseBranch - The target base branch, written to provenance.branch.
|
|
700
762
|
* @property {string} baseCommit - The base commit the entries were verified against,
|
|
701
763
|
* written to provenance.commit.
|
|
764
|
+
* @property {string[]} [demoted_ids] - Ids demoted this round (kb_demote). An id whose
|
|
765
|
+
* local row carries a demoted_at and is now below CONFIRMED is REMOVED from entries and
|
|
766
|
+
* recorded as an explicit tombstone {id, at, reason} in the bible's optional top-level
|
|
767
|
+
* demotions array; any other id is skipped with reason not_demoted_or_unknown. Existing
|
|
768
|
+
* tombstones are preserved, and re-committing a tombstoned id through ids (a
|
|
769
|
+
* re-promotion) restores its entry and clears its tombstone.
|
|
770
|
+
*/
|
|
771
|
+
|
|
772
|
+
/**
|
|
773
|
+
* @typedef {Object} KbDemoteOptions
|
|
774
|
+
* @property {string} id - ID of the KB entry to demote.
|
|
775
|
+
* @property {string} reason - Why trust is being withdrawn -- at least 20 characters
|
|
776
|
+
* after newlines are collapsed to spaces and the result trimmed. Appended to the
|
|
777
|
+
* entry content as the audit trail; a reason made only of whitespace or newlines
|
|
778
|
+
* is refused.
|
|
779
|
+
* @property {string[]} evidence_files - At least one repo-relative file backing the
|
|
780
|
+
* demotion; an absent or empty list is refused by input validation before the
|
|
781
|
+
* tool runs. A path that is ABSOLUTE or contains a ".." segment is refused with
|
|
782
|
+
* E-DEMOTE-EVIDENCE-UNRESOLVED and nothing is written. Over a local SQLite KB each
|
|
783
|
+
* must also resolve to a real file (not a directory) inside the calling session's
|
|
784
|
+
* repo; over a remote (http) KB the KB server validates the rest of the evidence.
|
|
702
785
|
*/
|
|
703
786
|
|
|
704
787
|
/**
|
|
@@ -863,7 +946,7 @@ export function assertNoRemovedKbScopeKeys(tool, options) {
|
|
|
863
946
|
const err = new Error(
|
|
864
947
|
`E-SCOPE-KEY-REMOVED: ${tool} no longer accepts ${present.map((k) => `'${k}'`).join(', ')} ` +
|
|
865
948
|
'(removed in the KB redesign); the call was not sent. Remediation: drop it -- every kb_* call acts on the ' +
|
|
866
|
-
"calling session's own KB (a member session's registered work folder; a FULL session's fleet server working folder).",
|
|
949
|
+
"calling session's own KB (a member session's registered work folder; a FULL session's first MCP client root inside a git repository with an origin remote, or the fleet server working folder when the client offers no roots).",
|
|
867
950
|
);
|
|
868
951
|
err.code = 'E-SCOPE-KEY-REMOVED';
|
|
869
952
|
throw err;
|
|
@@ -1035,13 +1118,26 @@ export class ApraFleet {
|
|
|
1035
1118
|
}
|
|
1036
1119
|
|
|
1037
1120
|
/**
|
|
1038
|
-
* Get status of all fleet members.
|
|
1121
|
+
* Get status of all fleet members. With format "json" the result's
|
|
1122
|
+
* kbHealth.credential is a {@link FleetStatusKbCredential} when the KB
|
|
1123
|
+
* config selects the http provider, and kbHealth.toolProfileWarning is a
|
|
1124
|
+
* string when the configured KB tool profile is invalid.
|
|
1039
1125
|
* @param {FleetStatusOptions} [options]
|
|
1040
1126
|
*/
|
|
1041
1127
|
async fleetStatus(options = {}) {
|
|
1042
1128
|
return this.mcpClient.callTool('fleet_status', options);
|
|
1043
1129
|
}
|
|
1044
1130
|
|
|
1131
|
+
/**
|
|
1132
|
+
* Cheap read-only fleet view for status displays (the Claude Code
|
|
1133
|
+
* fleet-status mod polls it). The result text is the JSON of a
|
|
1134
|
+
* {@link FleetSnapshot}: every member's last-known status from local
|
|
1135
|
+
* state only -- no SSH probes, no writes. Use fleetStatus for a live check.
|
|
1136
|
+
*/
|
|
1137
|
+
async fleetSnapshot() {
|
|
1138
|
+
return this.mcpClient.callTool('fleet_snapshot', {});
|
|
1139
|
+
}
|
|
1140
|
+
|
|
1045
1141
|
/**
|
|
1046
1142
|
* Get detailed status for one member: connectivity, session, work folder, provider, registered shell (Windows).
|
|
1047
1143
|
* @param {{ member_id?: string, member_name?: string, format?: 'compact'|'json', refresh?: boolean }} options
|
|
@@ -1174,6 +1270,13 @@ export class ApraFleet {
|
|
|
1174
1270
|
* command, and redacts the value from the returned stdout/stderr. The
|
|
1175
1271
|
* plaintext appears in no field of the result.
|
|
1176
1272
|
*
|
|
1273
|
+
* Bitbucket REST takes the token as a Bearer value (no username, no
|
|
1274
|
+
* email). The optional {{vcs_username}} / {{vcs_username_inline}} pair
|
|
1275
|
+
* substitutes the credential helper's git username (for Bitbucket always
|
|
1276
|
+
* x-bitbucket-api-token-auth) under the same two dialects, and is
|
|
1277
|
+
* redacted on the same footing as the token. A username placeholder
|
|
1278
|
+
* never stands alone -- the command must still carry a token one.
|
|
1279
|
+
*
|
|
1177
1280
|
* @param {VcsCredentialExecOptions} options
|
|
1178
1281
|
* @returns {Promise<{ content: Array<{type: string, text: string}>,
|
|
1179
1282
|
* structuredContent: VcsCredentialExecStructured }>}
|
|
@@ -1223,15 +1326,16 @@ export class ApraFleet {
|
|
|
1223
1326
|
* provenance, and make a local commit scoped to the bible path whose message
|
|
1224
1327
|
* lists each removal. Never pushes; re-running with the
|
|
1225
1328
|
* same ids after resetting to a newer HEAD re-merges, so a rejected push can
|
|
1226
|
-
* be retried. Result JSON: {path, merged, skipped, removed,
|
|
1227
|
-
* backfilled, committed}; extract with parseToolJson(). backfilled counts the
|
|
1329
|
+
* be retried. Result JSON: {path, merged, demoted, skipped, removed,
|
|
1330
|
+
* entry_count, backfilled, committed}; extract with parseToolJson(). backfilled counts the
|
|
1228
1331
|
* existing bible entries with no source_file_hashes (carried over from a
|
|
1229
1332
|
* v1/v2 bible) that gained this KB's stored basis for the same id, because
|
|
1230
1333
|
* it passes the same basis rule at HEAD and cites the same files (legacy
|
|
1231
1334
|
* backfill; only that field changes, nothing is dropped); a backfill alone
|
|
1232
|
-
* makes a commit. Each skipped item is
|
|
1233
|
-
* with reason not_confirmed_or_unknown, no_source_files (a
|
|
1234
|
-
* citing no source file)
|
|
1335
|
+
* makes a commit. Each skipped item is
|
|
1336
|
+
* {id, reason} with reason not_confirmed_or_unknown, no_source_files (a
|
|
1337
|
+
* CONFIRMED id citing no source file), basis_mismatch or
|
|
1338
|
+
* not_demoted_or_unknown (a demoted_ids id). Each removed item is {id, reason}
|
|
1235
1339
|
* with reason superseded or invalidated. A member session without the
|
|
1236
1340
|
* kb_maintainer grant cannot retire a CONFIRMED entry through the kb_* tools:
|
|
1237
1341
|
* kb_invalidate leaves CONFIRMED entries untouched, and kb_capture with
|
|
@@ -1241,8 +1345,15 @@ export class ApraFleet {
|
|
|
1241
1345
|
* a routing guard for agent sessions, not a boundary against a local process
|
|
1242
1346
|
* that can open a FULL session or write the KB directly.
|
|
1243
1347
|
* A CONFIRMED id is admitted only if it passes the same basis rule as kb_export.
|
|
1348
|
+
* demoted_ids records EXPLICIT demotion tombstones: an admitted id is removed from
|
|
1349
|
+
* entries and tombstoned as {id, at, reason}; entry_count counts entries only.
|
|
1244
1350
|
* The removed scope keys (repo_path, repo, repo_remote_url) are refused
|
|
1245
1351
|
* with E-SCOPE-KEY-REMOVED before anything is sent.
|
|
1352
|
+
* Under an http KB provider the call is skipped, never an error: the result
|
|
1353
|
+
* is {path, merged: [], skipped: [], removed: [], entry_count: <entries in the
|
|
1354
|
+
* existing parseable bible, else 0>, backfilled: 0, committed: false,
|
|
1355
|
+
* bible_skipped: true, reason}; the KB is not read and nothing is written or
|
|
1356
|
+
* committed.
|
|
1246
1357
|
* @param {KbBibleCommitOptions} options
|
|
1247
1358
|
*/
|
|
1248
1359
|
async kbBibleCommit(options) {
|
|
@@ -1250,6 +1361,22 @@ export class ApraFleet {
|
|
|
1250
1361
|
return this.mcpClient.callTool('kb_bible_commit', options);
|
|
1251
1362
|
}
|
|
1252
1363
|
|
|
1364
|
+
/**
|
|
1365
|
+
* Withdraw trust from a CONFIRMED entry, lowering it to INFERRED (the
|
|
1366
|
+
* inverse of kb_promote). Not a ladder: an INFERRED/UNVERIFIED target is
|
|
1367
|
+
* REFUSED with E-DEMOTE-NOT-CONFIRMED rather than returned as a no-op.
|
|
1368
|
+
* Appends the reason and the required evidence files as an audit note; promoted_at
|
|
1369
|
+
* and source are left untouched. Result JSON:
|
|
1370
|
+
* {id, previous_confidence, new_confidence}; extract with parseToolJson().
|
|
1371
|
+
* The removed scope keys (repo_path, repo, repo_remote_url) are refused
|
|
1372
|
+
* with E-SCOPE-KEY-REMOVED before anything is sent.
|
|
1373
|
+
* @param {KbDemoteOptions} options
|
|
1374
|
+
*/
|
|
1375
|
+
async kbDemote(options) {
|
|
1376
|
+
assertNoRemovedKbScopeKeys('kb_demote', options);
|
|
1377
|
+
return this.mcpClient.callTool('kb_demote', options);
|
|
1378
|
+
}
|
|
1379
|
+
|
|
1253
1380
|
/**
|
|
1254
1381
|
* Convert a remote member from password to SSH key authentication.
|
|
1255
1382
|
* @param {SetupSshKeyOptions} options
|
|
@@ -1258,6 +1385,29 @@ export class ApraFleet {
|
|
|
1258
1385
|
return this.mcpClient.callTool('setup_ssh_key', options);
|
|
1259
1386
|
}
|
|
1260
1387
|
|
|
1388
|
+
/**
|
|
1389
|
+
* Send a message to a connected member session. member_id is a member
|
|
1390
|
+
* UUID, or "orchestrator" for the operator's own channel-capable
|
|
1391
|
+
* orchestrating session (operator notifications). With probe: true the
|
|
1392
|
+
* server sends nothing and only reports whether a session holds the
|
|
1393
|
+
* target ({ probe: true, member_id, connected, channel_capable }).
|
|
1394
|
+
* @param {{ member_id: string, content: string, reply_to?: string, probe?: boolean }} options
|
|
1395
|
+
*/
|
|
1396
|
+
async sendMessage(options) {
|
|
1397
|
+
return this.mcpClient.callTool('send_message', options);
|
|
1398
|
+
}
|
|
1399
|
+
|
|
1400
|
+
/**
|
|
1401
|
+
* Read-only check of a message target: send_message with probe: true.
|
|
1402
|
+
* Sends nothing. The result text is JSON
|
|
1403
|
+
* { probe: true, member_id, connected, channel_capable }; only a
|
|
1404
|
+
* channel_capable session can receive a message.
|
|
1405
|
+
* @param {string} memberId a member UUID or "orchestrator"
|
|
1406
|
+
*/
|
|
1407
|
+
async probeMessageTarget(memberId) {
|
|
1408
|
+
return this.mcpClient.callTool('send_message', { member_id: memberId, content: '', probe: true });
|
|
1409
|
+
}
|
|
1410
|
+
|
|
1261
1411
|
/**
|
|
1262
1412
|
* Send an email. Pass provider config inline (provider, from, and for
|
|
1263
1413
|
* SMTP: host, port, user, secure). Secrets resolve from the credential
|
|
@@ -1281,8 +1431,11 @@ export class ApraFleet {
|
|
|
1281
1431
|
|
|
1282
1432
|
/**
|
|
1283
1433
|
* code_reindex -- rebuild the code index of the calling session's own repo
|
|
1284
|
-
* (a member session's work folder, otherwise
|
|
1285
|
-
*
|
|
1434
|
+
* (a member session's work folder, otherwise
|
|
1435
|
+
* the first MCP client root (roots/list) inside a git repository with an origin remote, or the server working folder when the client offers no roots;
|
|
1436
|
+
* there is no repo argument). Starts gitnexus analyze detached, always as
|
|
1437
|
+
* a full rebuild (--force; an incremental analyze can corrupt unchanged
|
|
1438
|
+
* symbol rows), with its
|
|
1286
1439
|
* output captured to <data>/code-index/<slug>/analyze.log and returns
|
|
1287
1440
|
* after the first tick. Extract the JSON with parseToolJson(): `outcome`
|
|
1288
1441
|
* is 'started' | 'up-to-date' | 'starting' | 'already-running' |
|
|
@@ -78,7 +78,8 @@ export class ReconnectingHttpTransport extends EventEmitter {
|
|
|
78
78
|
await t.start();
|
|
79
79
|
t.off('error', onInitError);
|
|
80
80
|
if (initError || !t.sessionId) {
|
|
81
|
-
|
|
81
|
+
// close() also releases a session the server already issued.
|
|
82
|
+
releaseTransport(t);
|
|
82
83
|
throw initError || new Error(`Could not open an MCP session at ${url}`);
|
|
83
84
|
}
|
|
84
85
|
const old = this.inner;
|
|
@@ -96,7 +97,10 @@ export class ReconnectingHttpTransport extends EventEmitter {
|
|
|
96
97
|
this.stale = true;
|
|
97
98
|
this.emit('close');
|
|
98
99
|
});
|
|
99
|
-
|
|
100
|
+
// Release the replaced session on the server too (HTTP DELETE, best
|
|
101
|
+
// effort): stop() alone would leave it open there for good when the
|
|
102
|
+
// old connection died while the server stayed up.
|
|
103
|
+
if (old) releaseTransport(old);
|
|
100
104
|
}
|
|
101
105
|
|
|
102
106
|
/** Serialised: concurrent senders share one re-probe/reconnect. */
|
|
@@ -125,6 +129,10 @@ export class ReconnectingHttpTransport extends EventEmitter {
|
|
|
125
129
|
}
|
|
126
130
|
}
|
|
127
131
|
|
|
132
|
+
/**
|
|
133
|
+
* Local-only teardown: aborts the streams but leaves the server session
|
|
134
|
+
* open until the server evicts it. Use close() when done with the transport.
|
|
135
|
+
*/
|
|
128
136
|
stop() {
|
|
129
137
|
this.stopped = true;
|
|
130
138
|
if (this.inner) {
|
|
@@ -134,4 +142,29 @@ export class ReconnectingHttpTransport extends EventEmitter {
|
|
|
134
142
|
t.stop();
|
|
135
143
|
}
|
|
136
144
|
}
|
|
145
|
+
|
|
146
|
+
/** Release the server session (HTTP DELETE, best effort), then stop. */
|
|
147
|
+
async close() {
|
|
148
|
+
this.stopped = true;
|
|
149
|
+
if (this.reconnecting) {
|
|
150
|
+
try { await this.reconnecting; } catch { /* nothing to release */ }
|
|
151
|
+
}
|
|
152
|
+
if (this.inner) {
|
|
153
|
+
const t = this.inner;
|
|
154
|
+
t.once('close', () => this.emit('close'));
|
|
155
|
+
if (typeof t.close === 'function') await t.close();
|
|
156
|
+
else t.stop();
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/** Fire-and-forget release of a replaced inner transport. */
|
|
162
|
+
function releaseTransport(t) {
|
|
163
|
+
try {
|
|
164
|
+
if (typeof t.close === 'function') {
|
|
165
|
+
Promise.resolve(t.close()).catch(() => { /* best effort */ });
|
|
166
|
+
} else {
|
|
167
|
+
t.stop();
|
|
168
|
+
}
|
|
169
|
+
} catch { /* ignore */ }
|
|
137
170
|
}
|
|
@@ -101,6 +101,12 @@ export class StdioTransport extends EventEmitter {
|
|
|
101
101
|
this.process = null;
|
|
102
102
|
}
|
|
103
103
|
}
|
|
104
|
+
|
|
105
|
+
/** Same as stop(): a stdio server lives and dies with its process. Lets
|
|
106
|
+
* every caller end any transport with close(). */
|
|
107
|
+
async close() {
|
|
108
|
+
this.stop();
|
|
109
|
+
}
|
|
104
110
|
}
|
|
105
111
|
|
|
106
112
|
export class StreamableHttpTransport extends EventEmitter {
|
|
@@ -25,6 +25,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
|
|
|
25
25
|
If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
|
|
26
26
|
your tool-loading tool first, before concluding they are unavailable.
|
|
27
27
|
|
|
28
|
+
If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
|
|
29
|
+
`retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
|
|
30
|
+
not help), retry that call ONCE, and if it still fails fall back to text search and
|
|
31
|
+
record the fallback. Never poll `code_status` in a loop waiting for the index.
|
|
32
|
+
|
|
28
33
|
1. When the tools are present, call `kb_session_prime` with `hint_modules` naming the
|
|
29
34
|
subsystems the assigned beads touch. KB knowledge matters most for duplicate
|
|
30
35
|
detection and sprint-set grouping.
|
|
@@ -37,6 +37,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
|
|
|
37
37
|
If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
|
|
38
38
|
your tool-loading tool first, before concluding they are unavailable.
|
|
39
39
|
|
|
40
|
+
If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
|
|
41
|
+
`retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
|
|
42
|
+
not help), retry that call ONCE, and if it still fails fall back to text search and
|
|
43
|
+
record the fallback. Never poll `code_status` in a loop waiting for the index.
|
|
44
|
+
|
|
40
45
|
1. When the tools are present, call `kb_session_prime` with `hint_modules` naming the
|
|
41
46
|
repo's CI workflow files. Known-flaky tests and known CI failure modes are the point
|
|
42
47
|
here -- they change how you read a red run.
|
|
@@ -80,8 +80,11 @@ console.log(JSON.stringify([...allow], null, 2));
|
|
|
80
80
|
|
|
81
81
|
Check every required prefix against this one merged list. If any prefix has
|
|
82
82
|
no covering entry, STOP immediately and return `deployed: false`, listing
|
|
83
|
-
every missing entry in `notes
|
|
84
|
-
`compose_permissions` with the missing grant(s), then
|
|
83
|
+
every missing entry in `notes`, and set `failedStep: "permissions"`, asking the
|
|
84
|
+
orchestrator/operator to run `compose_permissions` with the missing grant(s), then
|
|
85
|
+
re-trigger the sprint. `failedStep` is how the orchestrator knows no deploy command
|
|
86
|
+
ran -- set it only for this Step 0a stop, never for a failure after a deploy command
|
|
87
|
+
ran.
|
|
85
88
|
NEVER add permissions yourself: `.claude/settings.json` changes require a
|
|
86
89
|
team PR, and `.claude/settings.local.json` must be provisioned via the
|
|
87
90
|
`compose_permissions` MCP tool (the provider-agnostic delivery mechanism
|
|
@@ -103,6 +106,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
|
|
|
103
106
|
If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
|
|
104
107
|
your tool-loading tool first, before concluding they are unavailable.
|
|
105
108
|
|
|
109
|
+
If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
|
|
110
|
+
`retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
|
|
111
|
+
not help), retry that call ONCE, and if it still fails fall back to text search and
|
|
112
|
+
record the fallback. Never poll `code_status` in a loop waiting for the index.
|
|
113
|
+
|
|
106
114
|
1. When the tools are present, call `kb_session_prime` with `hint_modules` naming the
|
|
107
115
|
deploy targets in `deploy.md`.
|
|
108
116
|
2. Any judgment that depends on what the KB does or does not record is made from the
|
|
@@ -161,6 +169,16 @@ placeholder):
|
|
|
161
169
|
}
|
|
162
170
|
```
|
|
163
171
|
|
|
172
|
+
A Step 0a stop (missing permissions, no deploy command ran):
|
|
173
|
+
|
|
174
|
+
```json
|
|
175
|
+
{
|
|
176
|
+
"deployed": false,
|
|
177
|
+
"failedStep": "permissions",
|
|
178
|
+
"notes": "Missing permission grant(s): <entries>. Run compose_permissions with them, then re-trigger the sprint."
|
|
179
|
+
}
|
|
180
|
+
```
|
|
181
|
+
|
|
164
182
|
**Precedence**: If your dispatch prompt includes a JSON schema instruction, that schema is
|
|
165
183
|
authoritative -- respond with exactly that JSON and nothing else. It is expected to match
|
|
166
184
|
this contract; if it differs, follow the dispatch prompt.
|
|
@@ -51,6 +51,23 @@ your final `notes`, naming the bead id and the defect. This is a legitimate skip
|
|
|
51
51
|
exception (see Step 3 and Rules); it lets the reviewer route the bead to re-planning in
|
|
52
52
|
the same round.
|
|
53
53
|
|
|
54
|
+
**Needs an operator decision**: when a bead cannot go on until a human chooses between
|
|
55
|
+
real alternatives -- for example the criteria can only be met by upgrading a dependency,
|
|
56
|
+
patching it, or accepting a weaker check, and nothing in the bead, its parent or the code
|
|
57
|
+
says which -- do not guess and do not keep retrying. Leave the bead open and return
|
|
58
|
+
`status: "NEEDS-DECISION"` with a `decision` object: `beadId` (that one open bead),
|
|
59
|
+
`question` (self-contained: what you found, why it blocks the bead, what must be
|
|
60
|
+
decided), `options` (at least two, each `{ "id": "a", "text": "..." }` with what it
|
|
61
|
+
means and costs) and `recommendation` (the option id you recommend, and why). The
|
|
62
|
+
orchestrator files the question for an operator verbatim, sets the bead aside for the
|
|
63
|
+
rest of the run without re-dispatching it, and keeps working other beads; the answer
|
|
64
|
+
reaches a later dispatch through the bead's notes. Use it instead of the
|
|
65
|
+
criteria-defect escape hatch only when the fix is a choice an operator must make, not a
|
|
66
|
+
criteria rewrite a planner can make. Use BLOCKED, not NEEDS-DECISION, for a missing
|
|
67
|
+
secret, missing access, or an unmet prerequisite: those have one fix, not a choice. The
|
|
68
|
+
same-lane stop rule (Step 1) applies to a NEEDS-DECISION bead exactly as to any other
|
|
69
|
+
bead left open.
|
|
70
|
+
|
|
54
71
|
**CI is not yours**: never trigger, wait for or poll a CI run. A criterion that can only
|
|
55
72
|
be met by a CI run is a criteria defect: do the locally checkable work and report the CI
|
|
56
73
|
part under "criteria defects" (see above).
|
|
@@ -80,6 +97,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
|
|
|
80
97
|
If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
|
|
81
98
|
your tool-loading tool first, before concluding they are unavailable.
|
|
82
99
|
|
|
100
|
+
If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
|
|
101
|
+
`retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
|
|
102
|
+
not help), retry that call ONCE, and if it still fails fall back to text search and
|
|
103
|
+
record the fallback. Never poll `code_status` in a loop waiting for the index.
|
|
104
|
+
|
|
83
105
|
The `kb_query` and `code_impact` calls below are EXPECTED, not optional, whenever the
|
|
84
106
|
tools are present. If a tool is genuinely not present (or the KB or code index is not set
|
|
85
107
|
up for this repo), record that in `toolUse` (Output schema) and continue -- never skip
|
|
@@ -105,7 +127,8 @@ silently.
|
|
|
105
127
|
fixture-only files are exempt. Prefer these over grep for symbol lookups, call-chain
|
|
106
128
|
tracing, and impact analysis. If they are absent, fail, or report the repo is not
|
|
107
129
|
indexed, fall back to grep and record it in `toolUse`; do not try to build an index
|
|
108
|
-
yourself.
|
|
130
|
+
yourself. On `E-CODE-INDEX-NOT-READY`, wait once for its `retry_after_ms`, retry
|
|
131
|
+
once, then fall back to grep -- never poll `code_status` in a loop.
|
|
109
132
|
5. Report in `toolUse`: `kb` and `code` are each `used`, `unavailable` or `not_needed`;
|
|
110
133
|
`note` says why for anything not `used`. `used` means the expected call was made
|
|
111
134
|
(`kb_query` for kb -- `kb_session_prime` alone is not `used`; `code_impact`/
|
|
@@ -262,6 +285,18 @@ stop and return:
|
|
|
262
285
|
orchestrator can verify your closes against beads instead of trusting the summary alone.
|
|
263
286
|
Do NOT continue past VERIFY.
|
|
264
287
|
|
|
288
|
+
Whenever you return `status: "BLOCKED"`, also return `blockedIds`: the assigned bead ids
|
|
289
|
+
you left open BECAUSE of the block. Leave out ids you merely did not reach (for example
|
|
290
|
+
lane-mates skipped under the same-lane stop rule) -- the orchestrator sets each
|
|
291
|
+
`blockedIds` bead and everything depending on it aside for the rest of the run, and
|
|
292
|
+
re-dispatches the unreached ones. Example:
|
|
293
|
+
`{ "status": "BLOCKED", "closedIds": ["<id-1>"], "blockedIds": ["<id-2>"], "notes": "..." }`.
|
|
294
|
+
|
|
295
|
+
When a bead needs an operator decision (see "Needs an operator decision" above), stop
|
|
296
|
+
there and return `status: "NEEDS-DECISION"` with its `decision` object, listing in
|
|
297
|
+
`closedIds` whatever you closed before it. Example:
|
|
298
|
+
`{ "status": "NEEDS-DECISION", "closedIds": ["<id-1>"], "notes": "...", "decision": { "beadId": "<id-2>", "question": "...", "options": [{ "id": "a", "text": "..." }, { "id": "b", "text": "..." }], "recommendation": "a, because ..." } }`.
|
|
299
|
+
|
|
265
300
|
|
|
266
301
|
## Branch and secrets rules
|
|
267
302
|
|
|
@@ -303,7 +338,8 @@ or as prose if you are answering a human directly.
|
|
|
303
338
|
- NEVER skip an assigned bead id for convenience -- work them in dependency order. The
|
|
304
339
|
only skip exceptions: has open children, the same-lane stop rule (Step 1) after an
|
|
305
340
|
earlier lane-mate was left open, an unresolved wrap-up ambiguity, missing acceptance
|
|
306
|
-
criteria/context,
|
|
341
|
+
criteria/context, a recorded criteria defect (escape hatch above), or a bead that needs
|
|
342
|
+
an operator decision (returned as NEEDS-DECISION). A missing secret
|
|
307
343
|
is NOT a skip -- close with a blocked reason per Branch and secrets rules.
|
|
308
344
|
- Tests for the changed area must pass before each commit (Step 2.5)
|
|
309
345
|
- No PLAN.md, no progress.json -- beads is the only work tracker
|
|
@@ -18,7 +18,7 @@ wired and queried; do not restate or improvise those rules here.
|
|
|
18
18
|
Your dispatch prompt must supply:
|
|
19
19
|
|
|
20
20
|
- `analysisArtifactFile` (required) -- relative path (under the repo) to write the sprint
|
|
21
|
-
analysis artifact to, e.g. `sprint-
|
|
21
|
+
analysis artifact to, e.g. `docs/sprint-analysis-<slug>.md`. Written, never committed.
|
|
22
22
|
- `analysisText` (required) -- the exact, pre-formatted analysis content to write verbatim.
|
|
23
23
|
- `base-branch` (required) -- for `git log`/`git diff` in Step 2.
|
|
24
24
|
- `branch` (required) -- the sprint branch being harvested.
|
|
@@ -44,6 +44,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
|
|
|
44
44
|
If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
|
|
45
45
|
your tool-loading tool first, before concluding they are unavailable.
|
|
46
46
|
|
|
47
|
+
If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
|
|
48
|
+
`retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
|
|
49
|
+
not help), retry that call ONCE, and if it still fails fall back to text search and
|
|
50
|
+
record the fallback. Never poll `code_status` in a loop waiting for the index.
|
|
51
|
+
|
|
47
52
|
1. When the tools are present, call `kb_session_prime` with `hint_symbols`/`hint_modules`
|
|
48
53
|
relevant to the modules touched during the sprint.
|
|
49
54
|
2. When you extract durable knowledge during harvest -- anything non-obvious that future
|
|
@@ -70,17 +75,15 @@ search also matches value text, so apply only entries whose KEY contains `+all+`
|
|
|
70
75
|
|
|
71
76
|
Your task context includes an `analysisArtifactFile` path and an `analysisText` block.
|
|
72
77
|
|
|
73
|
-
Write the `analysisText` verbatim to the file at `<repo>/<analysisArtifactFile>` (overwrite
|
|
74
|
-
|
|
75
|
-
```bash
|
|
76
|
-
mkdir -p "<repo>/sprint-logs"
|
|
77
|
-
# Write analysisText content to <repo>/<analysisArtifactFile>
|
|
78
|
-
git -C "<repo>" add "<repo>/<analysisArtifactFile>"
|
|
79
|
-
git -C "<repo>" -c user.name='pm' -c user.email='pm@pm.local' commit -m "chore: sprint-analysis <branch> <startedAt>"
|
|
80
|
-
```
|
|
78
|
+
Write the `analysisText` verbatim to the file at `<repo>/<analysisArtifactFile>` (overwrite
|
|
79
|
+
if it exists; create its parent directory if missing).
|
|
81
80
|
|
|
82
81
|
Do NOT reformat or modify the analysisText -- write it exactly as provided.
|
|
83
82
|
|
|
83
|
+
**Do NOT `git add` or commit this file.** It is a local record that stays untracked in the
|
|
84
|
+
working tree; the orchestrator keeps it out of `git status` and out of every commit. Never
|
|
85
|
+
force-add it (`git add -f`), and do not stage it in any later step.
|
|
86
|
+
|
|
84
87
|
## Step 2 -- Read sprint context
|
|
85
88
|
|
|
86
89
|
Read the following to understand what was built:
|
|
@@ -76,6 +76,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
|
|
|
76
76
|
If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
|
|
77
77
|
your tool-loading tool first, before concluding they are unavailable.
|
|
78
78
|
|
|
79
|
+
If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
|
|
80
|
+
`retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
|
|
81
|
+
not help), retry that call ONCE, and if it still fails fall back to text search and
|
|
82
|
+
record the fallback. Never poll `code_status` in a loop waiting for the index.
|
|
83
|
+
|
|
79
84
|
1. When the tools are present, call `kb_session_prime` with `hint_symbols`/`hint_modules`
|
|
80
85
|
relevant to the features you were handed.
|
|
81
86
|
2. Any judgment that depends on what the KB does or does not record (e.g. whether a test
|
|
@@ -105,6 +105,12 @@ code_impact({ target: "<symbol>", direction: "upstream" | "downstream" })
|
|
|
105
105
|
code_query({ query: "<concept or pattern>" })
|
|
106
106
|
```
|
|
107
107
|
|
|
108
|
+
If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
|
|
109
|
+
`retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
|
|
110
|
+
not help), retry that call ONCE, and if it still fails fall back to reading the cited
|
|
111
|
+
files directly and say so in the evidence note. Never poll `code_status` in a loop
|
|
112
|
+
waiting for the index.
|
|
113
|
+
|
|
108
114
|
Decide which entry's claim the CURRENT merged code actually supports. Note the exact
|
|
109
115
|
file + symbol you read that settled it.
|
|
110
116
|
|
|
@@ -63,6 +63,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
|
|
|
63
63
|
If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
|
|
64
64
|
your tool-loading tool first, before concluding they are unavailable.
|
|
65
65
|
|
|
66
|
+
If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
|
|
67
|
+
`retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
|
|
68
|
+
not help), retry that call ONCE, and if it still fails fall back to text search and
|
|
69
|
+
record the fallback. Never poll `code_status` in a loop waiting for the index.
|
|
70
|
+
|
|
66
71
|
1. When the tools are present, call `kb_session_prime` with `hint_symbols`/`hint_modules`
|
|
67
72
|
relevant to the features in the DAG under review.
|
|
68
73
|
2. Any judgment that depends on KB coverage (e.g. whether a task touches unexplored code
|
|
@@ -43,6 +43,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
|
|
|
43
43
|
If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
|
|
44
44
|
your tool-loading tool first, before concluding they are unavailable.
|
|
45
45
|
|
|
46
|
+
If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
|
|
47
|
+
`retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
|
|
48
|
+
not help), retry that call ONCE, and if it still fails fall back to text search and
|
|
49
|
+
record the fallback. Never poll `code_status` in a loop waiting for the index.
|
|
50
|
+
|
|
46
51
|
1. When the tools are present, call `kb_session_prime` with `hint_symbols`/`hint_modules`
|
|
47
52
|
derived from the sprint goals / requirements you are about to decompose.
|
|
48
53
|
2. From whichever source you have (a live `kb_session_prime` result, the injected
|