@apralabs/apra-fleet 0.4.1 → 0.4.2
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 +16 -8
- package/dist/agents/backlog-groomer.md +17 -21
- package/dist/agents/ci-watcher.md +3 -0
- package/dist/agents/deployer.md +22 -44
- package/dist/agents/doer.md +131 -132
- package/dist/agents/harvester.md +20 -32
- package/dist/agents/integ-test-runner.md +81 -113
- package/dist/agents/kb-reconciler.md +31 -42
- package/dist/agents/plan-reviewer.md +32 -44
- package/dist/agents/planner.md +51 -63
- package/dist/agents/regression-test-runner.md +65 -80
- package/dist/agents/reviewer.md +56 -83
- package/dist/agents/schemas/integ-test-runner-output.json +1 -1
- package/dist/agents/schemas/regression-test-runner-output.json +4 -17
- package/dist/cli/auth.d.ts.map +1 -1
- package/dist/cli/auth.js +1 -2
- package/dist/cli/auth.js.map +1 -1
- package/dist/cli/config.d.ts +3 -3
- package/dist/cli/config.d.ts.map +1 -1
- package/dist/cli/config.js +4 -13
- package/dist/cli/config.js.map +1 -1
- package/dist/cli/install.d.ts.map +1 -1
- package/dist/cli/install.js +5 -39
- package/dist/cli/install.js.map +1 -1
- package/dist/cli/register-member.js +1 -1
- package/dist/cli/start.d.ts.map +1 -1
- package/dist/cli/start.js +7 -0
- package/dist/cli/start.js.map +1 -1
- package/dist/cli/uninstall.d.ts.map +1 -1
- package/dist/cli/uninstall.js +5 -3
- package/dist/cli/uninstall.js.map +1 -1
- package/dist/cli/watch.d.ts +26 -3
- package/dist/cli/watch.d.ts.map +1 -1
- package/dist/cli/watch.js +41 -9
- package/dist/cli/watch.js.map +1 -1
- package/dist/os/git-bash-candidates.d.ts +35 -0
- package/dist/os/git-bash-candidates.d.ts.map +1 -0
- package/dist/os/git-bash-candidates.js +46 -0
- package/dist/os/git-bash-candidates.js.map +1 -0
- package/dist/os/index.d.ts +13 -4
- package/dist/os/index.d.ts.map +1 -1
- package/dist/os/index.js +17 -2
- package/dist/os/index.js.map +1 -1
- package/dist/os/linux.js +1 -1
- package/dist/os/linux.js.map +1 -1
- package/dist/os/os-commands.d.ts +7 -0
- package/dist/os/os-commands.d.ts.map +1 -1
- package/dist/os/os-commands.js.map +1 -1
- package/dist/os/windows-gitbash.d.ts +93 -0
- package/dist/os/windows-gitbash.d.ts.map +1 -0
- package/dist/os/windows-gitbash.js +244 -0
- package/dist/os/windows-gitbash.js.map +1 -0
- package/dist/os/windows.d.ts.map +1 -1
- package/dist/os/windows.js +27 -5
- package/dist/os/windows.js.map +1 -1
- package/dist/providers/agy.d.ts +3 -2
- package/dist/providers/agy.d.ts.map +1 -1
- package/dist/providers/agy.js +11 -2
- package/dist/providers/agy.js.map +1 -1
- package/dist/providers/claude.d.ts +3 -2
- package/dist/providers/claude.d.ts.map +1 -1
- package/dist/providers/claude.js +22 -3
- package/dist/providers/claude.js.map +1 -1
- package/dist/providers/codex.d.ts +3 -2
- package/dist/providers/codex.d.ts.map +1 -1
- package/dist/providers/codex.js +5 -2
- package/dist/providers/codex.js.map +1 -1
- package/dist/providers/copilot.d.ts +3 -2
- package/dist/providers/copilot.d.ts.map +1 -1
- package/dist/providers/copilot.js +7 -2
- package/dist/providers/copilot.js.map +1 -1
- package/dist/providers/index.d.ts +0 -1
- package/dist/providers/index.d.ts.map +1 -1
- package/dist/providers/index.js +0 -3
- package/dist/providers/index.js.map +1 -1
- package/dist/providers/none.d.ts +3 -2
- package/dist/providers/none.d.ts.map +1 -1
- package/dist/providers/none.js +5 -2
- package/dist/providers/none.js.map +1 -1
- package/dist/providers/opencode.d.ts +3 -2
- package/dist/providers/opencode.d.ts.map +1 -1
- package/dist/providers/opencode.js +5 -2
- package/dist/providers/opencode.js.map +1 -1
- package/dist/providers/provider.d.ts +16 -7
- package/dist/providers/provider.d.ts.map +1 -1
- package/dist/providers/provider.js +2 -2
- package/dist/providers/provider.js.map +1 -1
- package/dist/services/agent-provisioner.js +2 -2
- package/dist/services/agent-provisioner.js.map +1 -1
- package/dist/services/cloud/activity.js +2 -2
- package/dist/services/cloud/activity.js.map +1 -1
- package/dist/services/context-admission.d.ts.map +1 -1
- package/dist/services/context-admission.js +9 -7
- package/dist/services/context-admission.js.map +1 -1
- package/dist/services/credential-cleanup.d.ts.map +1 -1
- package/dist/services/credential-cleanup.js +22 -3
- package/dist/services/credential-cleanup.js.map +1 -1
- package/dist/services/member-home.d.ts +1 -1
- package/dist/services/member-home.d.ts.map +1 -1
- package/dist/services/member-home.js +15 -12
- package/dist/services/member-home.js.map +1 -1
- package/dist/services/model-pricing.d.ts.map +1 -1
- package/dist/services/model-pricing.js +0 -5
- package/dist/services/model-pricing.js.map +1 -1
- package/dist/services/orphan-recovery.d.ts +6 -3
- package/dist/services/orphan-recovery.d.ts.map +1 -1
- package/dist/services/orphan-recovery.js +17 -14
- package/dist/services/orphan-recovery.js.map +1 -1
- package/dist/services/preflight-check.js +2 -2
- package/dist/services/preflight-check.js.map +1 -1
- package/dist/services/shell-probe.d.ts +131 -0
- package/dist/services/shell-probe.d.ts.map +1 -0
- package/dist/services/shell-probe.js +210 -0
- package/dist/services/shell-probe.js.map +1 -0
- package/dist/services/singleton.d.ts +2 -0
- package/dist/services/singleton.d.ts.map +1 -1
- package/dist/services/singleton.js +1 -1
- package/dist/services/singleton.js.map +1 -1
- package/dist/services/ssh.js +2 -2
- package/dist/services/ssh.js.map +1 -1
- package/dist/services/stall/find-log-file.d.ts.map +1 -1
- package/dist/services/stall/find-log-file.js +22 -16
- package/dist/services/stall/find-log-file.js.map +1 -1
- package/dist/services/stall/read-log-tail.d.ts.map +1 -1
- package/dist/services/stall/read-log-tail.js +6 -5
- package/dist/services/stall/read-log-tail.js.map +1 -1
- package/dist/services/stall/stall-poller.d.ts.map +1 -1
- package/dist/services/stall/stall-poller.js +35 -42
- package/dist/services/stall/stall-poller.js.map +1 -1
- package/dist/services/strategy.d.ts +9 -0
- package/dist/services/strategy.d.ts.map +1 -1
- package/dist/services/strategy.js +40 -6
- package/dist/services/strategy.js.map +1 -1
- package/dist/services/user-config.js +1 -1
- package/dist/services/user-config.js.map +1 -1
- package/dist/services/vcs/azure-devops.d.ts +1 -1
- package/dist/services/vcs/azure-devops.d.ts.map +1 -1
- package/dist/services/vcs/azure-devops.js +105 -10
- package/dist/services/vcs/azure-devops.js.map +1 -1
- package/dist/services/vcs/bitbucket.d.ts.map +1 -1
- package/dist/services/vcs/bitbucket.js +16 -0
- package/dist/services/vcs/bitbucket.js.map +1 -1
- package/dist/services/vcs/github.d.ts.map +1 -1
- package/dist/services/vcs/github.js +24 -0
- package/dist/services/vcs/github.js.map +1 -1
- package/dist/services/vcs/types.d.ts +123 -2
- package/dist/services/vcs/types.d.ts.map +1 -1
- package/dist/skills/fleet-sprint-cli/SKILL.md +2 -1
- package/dist/skills/pm/SKILL.md +0 -1
- package/dist/skills/pm/cost.md +0 -1
- package/dist/skills/pm/fleet-addendum.md +0 -1
- package/dist/tools/check-status.js +3 -3
- package/dist/tools/check-status.js.map +1 -1
- package/dist/tools/cloud-control.js +2 -2
- package/dist/tools/cloud-control.js.map +1 -1
- package/dist/tools/compose-permissions.d.ts.map +1 -1
- package/dist/tools/compose-permissions.js +37 -24
- package/dist/tools/compose-permissions.js.map +1 -1
- package/dist/tools/execute-command.d.ts.map +1 -1
- package/dist/tools/execute-command.js +28 -12
- package/dist/tools/execute-command.js.map +1 -1
- package/dist/tools/execute-prompt.d.ts.map +1 -1
- package/dist/tools/execute-prompt.js +55 -18
- package/dist/tools/execute-prompt.js.map +1 -1
- package/dist/tools/list-members.d.ts.map +1 -1
- package/dist/tools/list-members.js +6 -2
- package/dist/tools/list-members.js.map +1 -1
- package/dist/tools/member-detail.d.ts.map +1 -1
- package/dist/tools/member-detail.js +5 -3
- package/dist/tools/member-detail.js.map +1 -1
- package/dist/tools/member-reservation.d.ts.map +1 -1
- package/dist/tools/member-reservation.js +13 -1
- package/dist/tools/member-reservation.js.map +1 -1
- package/dist/tools/monitor-task.d.ts.map +1 -1
- package/dist/tools/monitor-task.js +17 -2
- package/dist/tools/monitor-task.js.map +1 -1
- package/dist/tools/provision-auth.js +5 -5
- package/dist/tools/provision-auth.js.map +1 -1
- package/dist/tools/provision-vcs-auth.d.ts +5 -2
- package/dist/tools/provision-vcs-auth.d.ts.map +1 -1
- package/dist/tools/provision-vcs-auth.js +58 -52
- package/dist/tools/provision-vcs-auth.js.map +1 -1
- package/dist/tools/register-member.d.ts +18 -12
- package/dist/tools/register-member.d.ts.map +1 -1
- package/dist/tools/register-member.js +42 -4
- package/dist/tools/register-member.js.map +1 -1
- package/dist/tools/remove-member.js +2 -2
- package/dist/tools/remove-member.js.map +1 -1
- package/dist/tools/revoke-vcs-auth.js +2 -2
- package/dist/tools/revoke-vcs-auth.js.map +1 -1
- package/dist/tools/setup-ssh-key.d.ts.map +1 -1
- package/dist/tools/setup-ssh-key.js +2 -1
- package/dist/tools/setup-ssh-key.js.map +1 -1
- package/dist/tools/stop-prompt.js +2 -2
- package/dist/tools/stop-prompt.js.map +1 -1
- package/dist/tools/update-agent-cli.js +2 -2
- package/dist/tools/update-agent-cli.js.map +1 -1
- package/dist/tools/update-member.d.ts +18 -12
- package/dist/tools/update-member.d.ts.map +1 -1
- package/dist/tools/update-member.js +18 -1
- package/dist/tools/update-member.js.map +1 -1
- package/dist/types.d.ts +11 -1
- package/dist/types.d.ts.map +1 -1
- package/dist/utils/agent-helpers.d.ts +36 -0
- package/dist/utils/agent-helpers.d.ts.map +1 -1
- package/dist/utils/agent-helpers.js +39 -1
- package/dist/utils/agent-helpers.js.map +1 -1
- package/dist/utils/platform.d.ts +7 -0
- package/dist/utils/platform.d.ts.map +1 -1
- package/dist/utils/platform.js +11 -1
- package/dist/utils/platform.js.map +1 -1
- package/dist/utils/workspace-trust.d.ts.map +1 -1
- package/dist/utils/workspace-trust.js +5 -1
- package/dist/utils/workspace-trust.js.map +1 -1
- package/dist/workflows/auto-sprint.js +4 -17
- package/package.json +2 -2
- package/packages/apra-fleet-client/src/client/api.mjs +92 -3
- package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +17 -21
- package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +3 -0
- package/packages/apra-fleet-se/apra-pm/agents/deployer.md +22 -44
- package/packages/apra-fleet-se/apra-pm/agents/doer.md +131 -132
- package/packages/apra-fleet-se/apra-pm/agents/harvester.md +20 -32
- package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +81 -113
- package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +31 -42
- package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +32 -44
- package/packages/apra-fleet-se/apra-pm/agents/planner.md +51 -63
- package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +65 -80
- package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +56 -83
- package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-output.json +1 -1
- package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-output.json +4 -17
- package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +0 -1
- package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +0 -1
- package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +0 -1
- package/packages/apra-fleet-se/bin/cli.mjs +132 -3
- package/packages/apra-fleet-se/bin/serve.mjs +36 -1
- package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +151 -33
- package/packages/apra-fleet-se/fleet-sprint/docs/README.md +22 -7
- package/packages/apra-fleet-se/fleet-sprint/docs/dolt-manual-recovery-verified.md +10 -8
- package/packages/apra-fleet-se/fleet-sprint/docs/dolt-sync-redesign.md +9 -4
- package/packages/apra-fleet-se/fleet-sprint/docs/escalate-to-llm-design.md +2 -2
- package/packages/apra-fleet-se/fleet-sprint/docs/shared-orchestrator-reservation-design.md +12 -12
- package/packages/apra-fleet-se/fleet-sprint/docs/stabilization-log.md +14 -4
- package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +275 -99
- package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +67 -16
- package/packages/apra-fleet-se/fleet-sprint/errors.mjs +41 -0
- package/packages/apra-fleet-se/fleet-sprint/runner.js +1140 -209
- package/packages/apra-fleet-se/fleet-sprint/se-os-commands.mjs +134 -0
- package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +154 -0
- package/packages/apra-fleet-se/fleet-sprint/se-windows-gitbash.mjs +97 -0
- package/packages/apra-fleet-se/fleet-sprint/se-windows.mjs +143 -0
- package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +2 -1
- package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +51 -0
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +657 -12
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/dolt.mjs +33 -4
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +60 -43
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +205 -2
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/shell-helpers.mjs +164 -0
- package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +92 -37
- package/packages/apra-fleet-workflow/src/viewer/index.mjs +167 -1
- package/packages/apra-fleet-workflow/src/workflow/index.mjs +435 -31
- package/skills/fleet/SKILL.md +20 -9
- package/skills/fleet/auth-azdevops.md +44 -5
- package/skills/fleet/auth-bitbucket.md +3 -3
- package/skills/fleet/auth-github.md +2 -2
- package/skills/fleet/beads-conflict-resolution.md +141 -0
- package/skills/fleet/beads.md +16 -12
- package/skills/fleet/onboarding.md +4 -4
- package/skills/fleet/permissions.md +6 -6
- package/skills/fleet/skill-matrix.md +1 -1
- package/skills/fleet/troubleshooting.md +2 -1
- package/version.json +1 -1
- package/dist/providers/gemini.d.ts +0 -52
- package/dist/providers/gemini.d.ts.map +0 -1
- package/dist/providers/gemini.js +0 -236
- package/dist/providers/gemini.js.map +0 -1
- package/packages/apra-fleet-se/fleet-sprint/docs/coach-role-design.md +0 -23
package/skills/fleet/SKILL.md
CHANGED
|
@@ -45,6 +45,7 @@ See sub-documents for detailed usage:
|
|
|
45
45
|
- `skill-matrix.md` - skill installation matrix by project + VCS + role
|
|
46
46
|
- `auth-github.md`, `auth-bitbucket.md`, `auth-azdevops.md` - VCS auth provisioning per provider
|
|
47
47
|
- `beads.md` - Beads persistent task DB: commands, backlog ops, session recovery patterns
|
|
48
|
+
- `beads-conflict-resolution.md` - manual dolt SQL recovery when `bd dolt pull`/`push` reports a real merge conflict
|
|
48
49
|
|
|
49
50
|
## Beads - Persistent Task Tracking
|
|
50
51
|
|
|
@@ -60,7 +61,7 @@ The `{{secure.NAME}}` pattern lets you reference stored secrets in any command w
|
|
|
60
61
|
|
|
61
62
|
**How it works:**
|
|
62
63
|
1. Store a secret with `credential_store_set` - Fleet opens an OOB terminal prompt, so the value never appears in chat
|
|
63
|
-
2. Reference it as `{{secure.NAME}}` anywhere in a command string passed to `execute_command`, `register_member`, `update_member`, `provision_vcs_auth`, or `
|
|
64
|
+
2. Reference it as `{{secure.NAME}}` anywhere in a command string passed to `execute_command`, `register_member`, `update_member`, `provision_vcs_auth`, `provision_llm_auth`, or `setup_git_app`
|
|
64
65
|
3. Fleet resolves the token server-side before execution; LLM does not see the secret.
|
|
65
66
|
|
|
66
67
|
**When to use:**
|
|
@@ -204,15 +205,25 @@ The `resume` parameter controls whether a prior session is continued:
|
|
|
204
205
|
|
|
205
206
|
| Value | Behaviour |
|
|
206
207
|
|-------|-----------|
|
|
207
|
-
| `true` (default) | If a session ID is stored for this member, continues it
|
|
208
|
+
| `true` (default) | Best-effort resume of the member's STORED LAST session. If a session ID is stored for this member, continues it; if none exists, starts fresh. |
|
|
208
209
|
| `false` | Always starts a fresh session - ignores any stored session ID. |
|
|
210
|
+
| `"<session-id>"` (string) | EXPLICIT resume of exactly that session, preferred over the member's stored session. Terminal on an unknown/expired id: the call returns structured `{ isError: true, reason: "session_not_found" }`, makes NO LLM call, and does NOT fall back to a fresh session. |
|
|
209
211
|
|
|
210
|
-
`resume`
|
|
211
|
-
|
|
212
|
+
`resume` accepts a boolean OR a session-ID string, so a caller CAN target a specific
|
|
213
|
+
session by value. The `session_id` parameter is a shorthand for the string form
|
|
214
|
+
(`session_id: "X"` is equivalent to `resume: "X"`, and takes precedence over `resume`).
|
|
215
|
+
|
|
216
|
+
Prefer the string form whenever the prompt depends on one specific session's prior
|
|
217
|
+
context. `true` resolves to the member's single globally-stored last session, which is
|
|
218
|
+
shared across every role and has no task scoping - under `true`, a retry can silently
|
|
219
|
+
land in an unrelated role's session and answer with the wrong shape. The string form
|
|
220
|
+
trades that silent-wrong-context failure for a loud, pre-LLM `session_not_found` that the
|
|
221
|
+
caller can handle (typically: re-dispatch once with `resume: false`).
|
|
212
222
|
|
|
213
223
|
**Automatic stale-session recovery:** If `resume=true` and the stored session has expired
|
|
214
224
|
or the provider returns an error, `execute_prompt` retries once automatically with a fresh
|
|
215
|
-
session. This recovery is transparent - no caller intervention required.
|
|
225
|
+
session. This recovery is transparent - no caller intervention required. It applies ONLY
|
|
226
|
+
to `resume: true`; an explicit session-ID string never falls back this way (see the table).
|
|
216
227
|
|
|
217
228
|
**Provider support:**
|
|
218
229
|
|
|
@@ -220,9 +231,9 @@ session. This recovery is transparent - no caller intervention required.
|
|
|
220
231
|
|----------|---------------|-------|
|
|
221
232
|
| Claude | Full | `claude --resume <sessionId>` |
|
|
222
233
|
| Antigravity (agy) | Full | `agy --conversation <sessionId>` |
|
|
234
|
+
| OpenCode | Full | `opencode run --session <sessionId>` (`--continue` when no id is stored) |
|
|
223
235
|
| Codex | Partial | `resume` command supported |
|
|
224
236
|
| Copilot | None | Always starts fresh regardless of `resume` value |
|
|
225
|
-
| Gemini | Full | Native session support |
|
|
226
237
|
|
|
227
238
|
Session IDs are parsed from `execute_prompt` output and stored server-side per member.
|
|
228
239
|
The output footer contains: `session: <sessionId>` when the provider supports it.
|
|
@@ -243,9 +254,9 @@ Per-provider flag behaviour:
|
|
|
243
254
|
|----------|--------------|-------------------|
|
|
244
255
|
| Claude | `--permission-mode auto` | `--dangerously-skip-permissions` |
|
|
245
256
|
| Antigravity (agy) | None (config-file only via `compose_permissions`) | `--dangerously-skip-permissions` |
|
|
257
|
+
| OpenCode | `--auto` | `--dangerously-skip-permissions` |
|
|
246
258
|
| Codex | `--ask-for-approval auto-edit` | `--sandbox danger-full-access --ask-for-approval never` |
|
|
247
259
|
| Copilot | Not supported - warns and runs interactively | Not supported |
|
|
248
|
-
| Gemini | None (config-file only via `compose_permissions`) | `--yolo` |
|
|
249
260
|
|
|
250
261
|
Auto-approval is delivered via config files written by `compose_permissions` - call it before every dispatch.
|
|
251
262
|
|
|
@@ -282,9 +293,9 @@ When you see this notice, surface it to the user verbatim before the rest of the
|
|
|
282
293
|
|
|
283
294
|
| Concern | How to handle |
|
|
284
295
|
|---------|---------------|
|
|
285
|
-
| **Agent context file** | Use `member_detail` -> `llmProvider` to determine filename: CLAUDE.md (Claude), AGY.md (Antigravity),
|
|
296
|
+
| **Agent context file** | Use `member_detail` -> `llmProvider` to determine filename: CLAUDE.md (Claude), AGY.md (Antigravity), AGENTS.md (Codex and OpenCode), COPILOT.md (Copilot) |
|
|
286
297
|
| **Attribution config** | Claude-only (Step 2 in onboarding.md) - skip for all other providers |
|
|
287
|
-
| **Timeouts** | Antigravity
|
|
298
|
+
| **Timeouts** | Antigravity members are slower -> use 2-3x timeout multiplier for `execute_prompt` dispatches to those members. Minimum `timeout_s: 900` for any non-trivial task. |
|
|
288
299
|
|
|
289
300
|
## Fleet Logs
|
|
290
301
|
|
|
@@ -9,15 +9,41 @@ Personal Access Tokens (PATs) with configurable scopes and expiration. Auth: emp
|
|
|
9
9
|
3. Set descriptive name (e.g., "fleet-{name}")
|
|
10
10
|
4. Select required scopes (see below)
|
|
11
11
|
5. Set expiration (recommend: 90 days)
|
|
12
|
-
6. Copy token
|
|
12
|
+
6. Copy token - shown only once
|
|
13
13
|
7. Provide token and org URL when prompted
|
|
14
14
|
|
|
15
|
+
### Expiry Capture (Optional)
|
|
16
|
+
|
|
17
|
+
When first registering a PAT, you can optionally capture its expiration date by passing `pat_expires_at` (ISO 8601, e.g. `2027-08-20T00:00:00Z`) to `provision_vcs_auth`. Azure DevOps exposes no API to read a PAT's expiry back, so this value must come from the operator -- the date chosen in the "Set expiration" step above. It is validated at the schema boundary and rejected if unparseable. The fleet stores this expiry date and checks it against two separate thresholds (see `src/utils/agent-helpers.ts`):
|
|
18
|
+
|
|
19
|
+
- **Minute-scale warning** (`EXPIRY_WARNING_MS`, 10 minutes): fires for any provider once the credential is within 10 minutes of expiry. This threshold was sized for GitHub App tokens (~1hr lifetime).
|
|
20
|
+
- **Day-scale warning** (`DAY_SCALE_WARNING_MS`, 7 days): fires only for providers listed in `DAY_SCALE_WARNING_PROVIDERS`, which currently includes `azure-devops`. Because Azure DevOps PATs run weeks to months (see "Set expiration" above), this gives a heads-up long before the minute-scale check would ever fire.
|
|
21
|
+
|
|
22
|
+
Either warning causes the fleet to request a fresh provisioning before the sprint dispatch rather than failing mid-sprint when the credential becomes invalid.
|
|
23
|
+
|
|
24
|
+
This step is optional; PATs function normally even without expiry tracking. However, recording expiry dates helps prevent surprise authentication failures and reduces retry cycles.
|
|
25
|
+
|
|
15
26
|
## Deploy
|
|
16
27
|
|
|
17
28
|
```
|
|
18
|
-
provision_vcs_auth(member_id, provider: 'azure-devops', org_url: 'https://dev.azure.com/myorg', pat: '...')
|
|
29
|
+
provision_vcs_auth(member_id, provider: 'azure-devops', org_url: 'https://dev.azure.com/myorg', pat: '...', pat_expires_at: '2027-08-20T00:00:00Z')
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Secret-Name Convention
|
|
33
|
+
|
|
34
|
+
The Azure DevOps PAT is stored in the fleet's credential store under a configurable name. **Default:** `azdevops_pat`
|
|
35
|
+
|
|
36
|
+
The credential is entered via the out-of-band prompt during `provision_vcs_auth` and is stored as a secure placeholder. When used in `execute_command` calls, the fleet resolves the placeholder on the server side - the plaintext token never appears in logs, prompts, or LLM transcripts.
|
|
37
|
+
|
|
38
|
+
**Store or reference the default credential:**
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
credential_store_set name=azdevops_pat
|
|
42
|
+
execute_command command="curl -sf -u :{{secure.azdevops_pat}} 'https://dev.azure.com/{org}/_apis/projects?api-version=7.1'"
|
|
19
43
|
```
|
|
20
44
|
|
|
45
|
+
**Per-sprint override:** To use a different credential name for a specific sprint (for example, when working with a different Azure DevOps organization or test repo), pass the `azdevops_pat_secret_name` argument to the sprint invocation (threaded through `packages/apra-fleet-se/fleet-sprint/runner.js`). It must name a credential already stored via `credential_store_set`; the runner validates it as a credential-store name at contract-validation time and uses it instead of the default `azdevops_pat` entry for provisioning, self-heal, and preflight checks on that sprint.
|
|
46
|
+
|
|
21
47
|
## Scopes
|
|
22
48
|
|
|
23
49
|
| Role | PAT Scopes |
|
|
@@ -46,9 +72,21 @@ git ls-remote https://dev.azure.com/{org}/{project}/_git/{repo} HEAD
|
|
|
46
72
|
| TF400813: Resource not available | Verify org URL matches `https://dev.azure.com/{org}` |
|
|
47
73
|
| Clone prompts for password | Re-run `provision_vcs_auth` |
|
|
48
74
|
|
|
75
|
+
## PAT Lifetime and Expiry
|
|
76
|
+
|
|
77
|
+
A fleet provisioning Azure DevOps credentials **cannot self-extend or auto-renew a PAT**. The Azure DevOps PAT lifecycle management API requires an Entra (Azure AD) OAuth token with admin consent, which the fleet does not hold. This is a fundamental design constraint: the fleet stores only the PAT itself, never the credentials needed to mint a fresh PAT or extend an existing one.
|
|
78
|
+
|
|
79
|
+
**Implications:**
|
|
80
|
+
|
|
81
|
+
- PATs must be renewed manually before expiry by re-running `provision_vcs_auth` and providing a fresh token.
|
|
82
|
+
- The optional expiry capture (see Setup section above) enables day-scale preflight warnings so the sprint can request a fresh provisioning before the credential becomes invalid.
|
|
83
|
+
- If a PAT expires mid-sprint, the sprint will fail with auth errors until `provision_vcs_auth` is re-run with a valid token.
|
|
84
|
+
|
|
85
|
+
To avoid disruption, set a calendar reminder to renew PATs well before their expiry date, or use the optional expiry-capture feature to let the fleet warn you in advance.
|
|
86
|
+
|
|
49
87
|
## Storing tokens for reuse
|
|
50
88
|
|
|
51
|
-
After provisioning VCS auth, you can store the Azure DevOps PAT in the credential store for direct use in `execute_command`
|
|
89
|
+
After provisioning VCS auth, you can store the Azure DevOps PAT in the credential store (see Secret-Name Convention section above) for direct use in `execute_command` - for example, calling the Azure DevOps REST API or authenticating git operations manually.
|
|
52
90
|
|
|
53
91
|
**Store an Azure DevOps PAT for reuse:**
|
|
54
92
|
|
|
@@ -63,10 +101,11 @@ execute_command command="curl -sf -u :{{secure.azdevops_pat}} 'https://dev.azur
|
|
|
63
101
|
execute_command command="git remote set-url origin https://token:{{secure.azdevops_pat}}@dev.azure.com/{org}/{project}/_git/{repo}"
|
|
64
102
|
```
|
|
65
103
|
|
|
66
|
-
The token is resolved server-side and redacted in output (`[REDACTED:azdevops_pat]`)
|
|
104
|
+
The token is resolved server-side and redacted in output (`[REDACTED:azdevops_pat]`) - it never appears in the LLM conversation or command logs.
|
|
67
105
|
|
|
68
106
|
## Notes
|
|
69
107
|
|
|
70
108
|
- PAT expiration: default 30 days, max 1 year
|
|
71
|
-
- Azure DevOps does not support app-based tokens
|
|
109
|
+
- Azure DevOps does not support app-based tokens - PATs are the standard
|
|
72
110
|
- Org URL must be base URL without trailing path
|
|
111
|
+
- To learn what scopes are required for your role, see the Scopes table above
|
|
@@ -7,7 +7,7 @@ API tokens (app passwords) tied to a user account. Long-lived, no auto-expire.
|
|
|
7
7
|
1. Go to `https://id.atlassian.com/manage-profile/security/api-tokens`
|
|
8
8
|
(or Bitbucket: Settings > Personal Bitbucket settings > App passwords)
|
|
9
9
|
2. Create app password with required scopes (see below)
|
|
10
|
-
3. Copy token
|
|
10
|
+
3. Copy token - shown only once
|
|
11
11
|
4. Provide token, email, and workspace slug when prompted
|
|
12
12
|
|
|
13
13
|
## Deploy
|
|
@@ -38,7 +38,7 @@ git ls-remote https://bitbucket.org/{workspace}/{repo}.git HEAD
|
|
|
38
38
|
|
|
39
39
|
## Storing tokens for reuse
|
|
40
40
|
|
|
41
|
-
After provisioning VCS auth, you can store the Bitbucket API token in the credential store for direct use in `execute_command`
|
|
41
|
+
After provisioning VCS auth, you can store the Bitbucket API token in the credential store for direct use in `execute_command` - for example, calling the Bitbucket REST API or authenticating git operations manually.
|
|
42
42
|
|
|
43
43
|
**Store a Bitbucket token for reuse:**
|
|
44
44
|
|
|
@@ -53,7 +53,7 @@ execute_command command="curl -sf -u me@example.com:{{secure.bitbucket_token}}
|
|
|
53
53
|
execute_command command="git remote set-url origin https://me@example.com:{{secure.bitbucket_token}}@bitbucket.org/workspace/repo.git"
|
|
54
54
|
```
|
|
55
55
|
|
|
56
|
-
The token is resolved server-side and redacted in output (`[REDACTED:bitbucket_token]`)
|
|
56
|
+
The token is resolved server-side and redacted in output (`[REDACTED:bitbucket_token]`) - it never appears in the LLM conversation or command logs.
|
|
57
57
|
|
|
58
58
|
## Troubleshooting
|
|
59
59
|
|
|
@@ -59,7 +59,7 @@ gh api /user
|
|
|
59
59
|
|
|
60
60
|
## Storing tokens for reuse
|
|
61
61
|
|
|
62
|
-
After provisioning VCS auth, you can also store the token in the credential store so members can use it directly in `execute_command` calls
|
|
62
|
+
After provisioning VCS auth, you can also store the token in the credential store so members can use it directly in `execute_command` calls - for example, when calling the GitHub REST API or authenticating git operations that bypass the configured remote URL.
|
|
63
63
|
|
|
64
64
|
**Store a GitHub PAT for reuse:**
|
|
65
65
|
|
|
@@ -74,7 +74,7 @@ execute_command command="curl -H 'Authorization: Bearer {{secure.github_pat}}'
|
|
|
74
74
|
execute_command command="git remote set-url origin https://token:{{secure.github_pat}}@github.com/Org/Repo.git"
|
|
75
75
|
```
|
|
76
76
|
|
|
77
|
-
The token is resolved server-side and redacted in output (`[REDACTED:github_pat]`)
|
|
77
|
+
The token is resolved server-side and redacted in output (`[REDACTED:github_pat]`) - it never appears in the LLM conversation or command logs.
|
|
78
78
|
|
|
79
79
|
## Troubleshooting
|
|
80
80
|
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
# Beads Conflict Resolution -- Dolt SQL Playbook
|
|
2
|
+
|
|
3
|
+
`bd dolt pull` / `bd dolt push` can fail with a genuine, non-fast-forward divergence:
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
Error: merge origin/main: merge conflicts in issues require operator resolution;
|
|
7
|
+
merge aborted and working set restored
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
This is not corruption and the working set is untouched -- `bd` already aborted the
|
|
11
|
+
merge safely. Resolve it by driving the real `dolt` binary against the same data
|
|
12
|
+
directory over SQL, ephemerally, then pull/push again through `bd` as normal.
|
|
13
|
+
|
|
14
|
+
**Do not `bd init`, `bd init --from-jsonl`, or delete `.beads/` to "fix" this** --
|
|
15
|
+
that discards local issue state. See `beads.md`.
|
|
16
|
+
|
|
17
|
+
For the fully automated version of this same procedure (used by fleet-sprint
|
|
18
|
+
itself at every sync point), see `settleDoltConflicts()` in
|
|
19
|
+
`packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs`, which applies a
|
|
20
|
+
deterministic per-field last-writer-wins rulebook instead of a human picking a
|
|
21
|
+
side. This playbook is the manual fallback -- use it when you need to see the
|
|
22
|
+
actual conflicting content before deciding, or when settle isn't wired for the
|
|
23
|
+
context you're in (e.g. resolving conflicts in the orchestrator's own local
|
|
24
|
+
checkout rather than against a registered fleet member).
|
|
25
|
+
|
|
26
|
+
## 0. Find the real data directory -- never hardcode it
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
bd dolt status
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Read the `Data:` line. **On a machine with multiple worktrees, `bd` resolves to
|
|
33
|
+
one shared `.beads` directory for the whole repo (typically the main checkout's),
|
|
34
|
+
not a per-worktree copy** -- always use the absolute path this command reports,
|
|
35
|
+
never a path you assume from cwd.
|
|
36
|
+
|
|
37
|
+
If it reports `embedded (in-process, no server)`, there's no live server to
|
|
38
|
+
route through -- start an ephemeral one (step 2). If it already reports a live
|
|
39
|
+
server (`host:port`), target that instead of starting a second one.
|
|
40
|
+
|
|
41
|
+
## 1. Ensure the pinned `dolt` binary is present
|
|
42
|
+
|
|
43
|
+
```powershell
|
|
44
|
+
& "$env:USERPROFILE\.apra-fleet\bin\dolt.exe" version # Windows
|
|
45
|
+
```
|
|
46
|
+
```bash
|
|
47
|
+
"$HOME/.apra-fleet/bin/dolt" version # POSIX
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Never install via a package manager (`winget`/`apt`/`brew`) -- it delivers an
|
|
51
|
+
unpinned version that drifts from the repo's pin and can be invisible to
|
|
52
|
+
already-running sessions' PATH. If missing, fetch the pinned release asset
|
|
53
|
+
(`DOLT_VERSION` in `src/cli/dolt-install.ts`) to that exact path.
|
|
54
|
+
|
|
55
|
+
## 2. Start an ephemeral sql-server against that data dir
|
|
56
|
+
|
|
57
|
+
**Windows -- `Start-Process` does NOT actually detach** (dies with the SSH/job
|
|
58
|
+
session). Use WMI:
|
|
59
|
+
|
|
60
|
+
```powershell
|
|
61
|
+
$result = Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments @{
|
|
62
|
+
CommandLine = 'cmd /c ""C:\Users\<you>\.apra-fleet\bin\dolt.exe" sql-server --host 127.0.0.1 --port 13401 --data-dir "<ABSOLUTE data dir from step 0>" > "%TEMP%\dolt-settle-local.log" 2>&1"'
|
|
63
|
+
CurrentDirectory = '<absolute path to your repo checkout>'
|
|
64
|
+
}
|
|
65
|
+
$result.ProcessId # record for teardown -- this is cmd.exe's PID, not dolt's (see step 5)
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Wrapping in `cmd /c ... > log 2>&1` is required to capture startup errors (a bad
|
|
69
|
+
`--data-dir` fails silently otherwise). Verify before proceeding:
|
|
70
|
+
|
|
71
|
+
```powershell
|
|
72
|
+
Test-NetConnection -ComputerName 127.0.0.1 -Port 13401 # expect TcpTestSucceeded: True
|
|
73
|
+
Get-Content "$env:TEMP\dolt-settle-local.log" # expect "Server ready. Accepting connections."
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
**POSIX:** `nohup dolt sql-server --host 127.0.0.1 --port 13401 --data-dir <dir> > /tmp/dolt-recovery.log 2>&1 & disown`
|
|
77
|
+
|
|
78
|
+
## 3. Inspect the conflict before resolving -- do not guess a side
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
dolt --no-tls --host=127.0.0.1 --port=13401 sql -q "
|
|
82
|
+
USE beads;
|
|
83
|
+
SET @@dolt_allow_commit_conflicts = 1;
|
|
84
|
+
CALL DOLT_MERGE('origin/main');
|
|
85
|
+
SELECT \`table\` FROM dolt_conflicts;"
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Two non-obvious flag landmines: `--no-tls` must come *before* `--host`/`--port`
|
|
89
|
+
(order-sensitive), and never pass `--user=root` or `--password` explicitly --
|
|
90
|
+
that switches the client into an interactive credential prompt that then fails
|
|
91
|
+
non-interactively. Omit both and it authenticates as root/empty-password
|
|
92
|
+
silently.
|
|
93
|
+
|
|
94
|
+
For each conflicted table, see which rows and which side is newer:
|
|
95
|
+
|
|
96
|
+
```sql
|
|
97
|
+
SELECT base_id, our_id, their_id, our_updated_at, their_updated_at
|
|
98
|
+
FROM dolt_conflicts_issues; -- table name is `dolt_conflicts_<table>`
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
## 4. Resolve -- per-field last-writer-wins, not a blanket side
|
|
102
|
+
|
|
103
|
+
```sql
|
|
104
|
+
CALL DOLT_CONFLICTS_RESOLVE('--ours', 'issues'); -- our_updated_at newer
|
|
105
|
+
-- or '--theirs' if their_updated_at is newer
|
|
106
|
+
CALL DOLT_COMMIT('-m', 'manual recovery: resolve <issue-id> conflict, <ours|theirs> newer');
|
|
107
|
+
SELECT COUNT(*) FROM dolt_conflicts; -- MUST be 0 before continuing
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
A bare `--ours`/`--theirs` picks the whole row. Only safe when one side is
|
|
111
|
+
strictly newer (verify via `updated_at` from step 3) or you've confirmed the
|
|
112
|
+
older side's content is already fully contained in the newer side -- never
|
|
113
|
+
pick a side just to make the error go away.
|
|
114
|
+
|
|
115
|
+
## 5. Teardown BEFORE republishing -- order matters
|
|
116
|
+
|
|
117
|
+
Embedded-mode `bd` needs Dolt's per-directory exclusive lock; republishing
|
|
118
|
+
while the ephemeral server still holds it fails or silently falls back
|
|
119
|
+
read-only.
|
|
120
|
+
|
|
121
|
+
```powershell
|
|
122
|
+
Get-Process | Where-Object { $_.ProcessName -eq 'dolt' } | Stop-Process -Force
|
|
123
|
+
# the WMI-created PID from step 2 is cmd.exe, not dolt.exe -- find dolt.exe by name, not by that PID
|
|
124
|
+
Test-NetConnection -ComputerName 127.0.0.1 -Port 13401 # expect False
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Then, only after the port is confirmed closed:
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
bd dolt pull # verify
|
|
131
|
+
bd dolt push # republish
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
## Full reference
|
|
135
|
+
|
|
136
|
+
`packages/apra-fleet-se/fleet-sprint/docs/dolt-manual-recovery-verified.md` --
|
|
137
|
+
the original live-verified spec this playbook condenses, including the
|
|
138
|
+
`settleDoltConflicts()` rulebook for tables other than `issues` (union for
|
|
139
|
+
`labels`, plain theirs for machine-local/append-only tables) and the
|
|
140
|
+
`dolt_mode` cleanup guarantee if a recovery ever routes `bd` itself through a
|
|
141
|
+
server.
|
package/skills/fleet/beads.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
# Beads
|
|
1
|
+
# Beads - Persistent Task DB for Fleet Users
|
|
2
2
|
|
|
3
3
|
Beads (`bd`) is a lightweight, dependency-aware task database installed automatically by `apra-fleet install`.
|
|
4
4
|
|
|
5
|
-
**`bd` runs on the orchestrator via `Bash`
|
|
5
|
+
**`bd` runs on the orchestrator via `Bash` - never expose `bd` commands to the user and never run `bd` via `execute_command` on a member.**
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
@@ -24,11 +24,15 @@ bd list --assignee <member> # tasks for a specific member
|
|
|
24
24
|
bd search "text" --status all --json # find existing issues by title (use for dedup)
|
|
25
25
|
```
|
|
26
26
|
|
|
27
|
-
**Never run `bd init` on a repo that already has a `.beads/` directory**
|
|
27
|
+
**Never run `bd init` on a repo that already has a `.beads/` directory** - it pulls from
|
|
28
28
|
remote and recreates the database, discarding local issue state. It is NOT idempotent.
|
|
29
29
|
Only run it once, on a repo with no `.beads/` yet. For a fresh clone or recovering a
|
|
30
30
|
missing/corrupt DB, prefer `bd bootstrap` (non-destructive) over `bd init`.
|
|
31
31
|
|
|
32
|
+
If `bd dolt pull`/`push` instead fails with a real merge conflict ("merge conflicts in
|
|
33
|
+
issues require operator resolution"), see `beads-conflict-resolution.md` - do not
|
|
34
|
+
`bd init` your way out of it.
|
|
35
|
+
|
|
32
36
|
---
|
|
33
37
|
|
|
34
38
|
## When to Use Beads
|
|
@@ -37,7 +41,7 @@ missing/corrupt DB, prefer `bd bootstrap` (non-destructive) over `bd init`.
|
|
|
37
41
|
|----------|-----------|
|
|
38
42
|
| Tracking work across multiple fleet sessions | `bd create` a task per work item; `bd update --assignee <member> --status in_progress` on dispatch |
|
|
39
43
|
| Expressing dependencies between tasks | `bd dep add <blocked-id> <blocker-id>` |
|
|
40
|
-
| Session restart
|
|
44
|
+
| Session restart - instant orientation | `bd ready` - shows all in-flight tasks without reading files |
|
|
41
45
|
| Linking a PR to a task | `bd note <id> "PR: <url>"` |
|
|
42
46
|
|
|
43
47
|
---
|
|
@@ -46,10 +50,10 @@ missing/corrupt DB, prefer `bd bootstrap` (non-destructive) over `bd init`.
|
|
|
46
50
|
|
|
47
51
|
| Priority | Meaning |
|
|
48
52
|
|----------|---------|
|
|
49
|
-
| `0` | Critical
|
|
50
|
-
| `1` | High
|
|
51
|
-
| `2` | Medium
|
|
52
|
-
| `3` | Low
|
|
53
|
+
| `0` | Critical - must fix now |
|
|
54
|
+
| `1` | High - next up |
|
|
55
|
+
| `2` | Medium - current sprint (default if `-p` omitted) |
|
|
56
|
+
| `3` | Low - backlog / deferred |
|
|
53
57
|
| `4` | Trivial |
|
|
54
58
|
|
|
55
59
|
---
|
|
@@ -61,11 +65,11 @@ missing/corrupt DB, prefer `bd bootstrap` (non-destructive) over `bd init`.
|
|
|
61
65
|
bd init
|
|
62
66
|
|
|
63
67
|
# Create a top-level epic for your current effort
|
|
64
|
-
bd create "feat: add SFTP transport" -p 1 #
|
|
68
|
+
bd create "feat: add SFTP transport" -p 1 # -> epic-id
|
|
65
69
|
|
|
66
70
|
# Break it into tasks
|
|
67
|
-
bd create "T1: implement connection" -p 1 --parent <epic-id> #
|
|
68
|
-
bd create "T2: add retry logic" -p 2 --parent <epic-id> #
|
|
71
|
+
bd create "T1: implement connection" -p 1 --parent <epic-id> # -> t1-id
|
|
72
|
+
bd create "T2: add retry logic" -p 2 --parent <epic-id> # -> t2-id
|
|
69
73
|
bd dep add <t2-id> <t1-id> # T2 blocked until T1 is done
|
|
70
74
|
|
|
71
75
|
# Dispatch a member to T1
|
|
@@ -75,7 +79,7 @@ bd update <t1-id> --assignee <member> --status in_progress
|
|
|
75
79
|
bd close <t1-id>
|
|
76
80
|
bd ready # confirms T2 is now unblocked
|
|
77
81
|
|
|
78
|
-
# At completion
|
|
82
|
+
# At completion - link PR
|
|
79
83
|
bd close <epic-id>
|
|
80
84
|
bd note <epic-id> "PR: https://github.com/org/repo/pull/42"
|
|
81
85
|
```
|
|
@@ -14,7 +14,7 @@ Use `member_detail` to determine `llmProvider` and `os`. Run `execute_command` w
|
|
|
14
14
|
- **Antigravity:** `agy --version 2>&1`
|
|
15
15
|
- **Codex:** `codex --version`
|
|
16
16
|
- **Copilot:** `copilot --version`
|
|
17
|
-
- **
|
|
17
|
+
- **OpenCode:** `opencode --version 2>&1`
|
|
18
18
|
|
|
19
19
|
If the LLM CLI is not installed or the command fails, use `update_llm_cli` to install it before proceeding. Do not attempt any prompt dispatch until the CLI is confirmed.
|
|
20
20
|
|
|
@@ -26,7 +26,7 @@ Call `provision_llm_auth`. Skip for local members - they inherit auth from the P
|
|
|
26
26
|
|
|
27
27
|
**Claude only.** Write `{"attribution":{"commit":"","pr":""}}` to `.claude/settings.json` in the member's work folder via `execute_command`. Merge if file already exists.
|
|
28
28
|
|
|
29
|
-
Antigravity, Codex, Copilot, and
|
|
29
|
+
Antigravity, Codex, Copilot, and OpenCode do not support attribution config - skip this step for those providers.
|
|
30
30
|
|
|
31
31
|
## Step 3: Detect VCS Provider
|
|
32
32
|
|
|
@@ -60,7 +60,7 @@ Add to the member's status file:
|
|
|
60
60
|
|
|
61
61
|
```
|
|
62
62
|
## Member Profile
|
|
63
|
-
- LLM Provider: Claude (or agy,
|
|
63
|
+
- LLM Provider: Claude (or agy, codex, etc.)
|
|
64
64
|
- VCS: Bitbucket (kumaakh/apra-lic-mgr)
|
|
65
65
|
- Roles: development, code-review
|
|
66
66
|
- Auth: Bitbucket API token (verified)
|
|
@@ -75,7 +75,7 @@ If the task you are about to dispatch requires an API key, token, or password (e
|
|
|
75
75
|
|
|
76
76
|
**Steps:**
|
|
77
77
|
1. Call `credential_store_set` with a descriptive name (e.g., `github_pat`, `npm_token`, `openai_key`) - Fleet opens an OOB terminal prompt for the value
|
|
78
|
-
2.
|
|
78
|
+
2. Reference the credential by NAME only in the task prompt (e.g. `"authenticate using credential github_pat"`) - never paste the raw `sec://NAME` handle into a prompt or command; `execute_command` rejects any command containing one. The secret value is only injected server-side when `{{secure.NAME}}` appears in an `execute_command` call - never in AI prompt text.
|
|
79
79
|
3. The member uses `{{secure.NAME}}` in `execute_command` - Fleet resolves the value server-side and redacts it from output before the LLM sees it
|
|
80
80
|
|
|
81
81
|
**Example - dispatching a member that needs to push code to GitHub:**
|
|
@@ -41,7 +41,7 @@ Tags determine the primary mode and grant additional tool scopes:
|
|
|
41
41
|
3. Load **custom tag profiles**: for each non-mode tag, load tag-<name>.json and merge its permissions for the primary mode
|
|
42
42
|
4. Load **ledger grants**: merge any permissions previously granted in project_folder/permissions.json
|
|
43
43
|
|
|
44
|
-
All merges are additive (Set-based) - order is independent, duplicates discarded. The final allow list is delivered to the member's provider (Claude,
|
|
44
|
+
All merges are additive (Set-based) - order is independent, duplicates discarded. The final allow list is delivered to the member's provider (Claude, Codex, etc.) in the provider's native config format.
|
|
45
45
|
|
|
46
46
|
### Example
|
|
47
47
|
|
|
@@ -140,13 +140,13 @@ setting `projects[<work_folder>].hasTrustDialogAccepted = true` scoped **strictl
|
|
|
140
140
|
that exact work folder (never a parent directory, never blanket) - delivered over the
|
|
141
141
|
same channel `compose_permissions` already uses, so it works uniformly for local and
|
|
142
142
|
remote (SSH) members. It logs distinctly whether it just seeded trust or found it
|
|
143
|
-
already present. Other providers no-op:
|
|
144
|
-
but already
|
|
143
|
+
already present. Other providers no-op: OpenCode has its own trust gate
|
|
144
|
+
but already bypasses it per-dispatch (`--dangerously-skip-permissions`);
|
|
145
145
|
AGY has no per-project trust concept (machine-global config); Codex/Copilot have no
|
|
146
146
|
known equivalent gate.
|
|
147
147
|
|
|
148
148
|
If `execute_prompt` fails with a `workspace_not_trusted` structured error, the CLI's own
|
|
149
149
|
stderr will contain a `"...this workspace has not been trusted"` message - seed trust
|
|
150
|
-
via `ensureWorkspaceTrusted(workFolder)`
|
|
151
|
-
register_member
|
|
152
|
-
|
|
150
|
+
via `ensureWorkspaceTrusted(workFolder)` -- invoked automatically at
|
|
151
|
+
`register_member`/`update_member`, on every `compose_permissions` call, and as a
|
|
152
|
+
one-shot self-heal inside `execute_prompt` itself -- then retry.
|
|
@@ -38,4 +38,4 @@ stored in the member's `tags` array.
|
|
|
38
38
|
3. GitHub members rarely need extra skills -- gh CLI covers most operations
|
|
39
39
|
4. Bitbucket/Azure DevOps members need provider-specific skills for devops/code-review tags (LLMs lack native API knowledge without skills)
|
|
40
40
|
5. Project-specific skills layer on top of VCS skills
|
|
41
|
-
6. Skills are independent of the member's LLM provider -- a
|
|
41
|
+
6. Skills are independent of the member's LLM provider -- a Codex member needs the same project skills as a Claude member. Skill selection is driven by VCS provider, project, and tags, not LLM provider.
|
|
@@ -5,9 +5,10 @@
|
|
|
5
5
|
| Empty response | Check auth token expiry -> re-provision via `provision_vcs_auth` |
|
|
6
6
|
| Timeout (inactivity) | `timeout_s`: fires when no stdout/stderr output arrives for N seconds (default 300s / 5 min). Applies to all members and all providers - transport-level, not provider-specific. Common cause: test runners and build tools that buffer output (npm test, vitest, cargo build) producing no output for long stretches even while active. Fix: increase `timeout_s` to 600-1200 for build/test dispatches. |
|
|
7
7
|
| Timeout (total) | `max_total_s`: fires after N seconds of total elapsed time regardless of output activity. Provider-agnostic. Use for hard ceilings on long-running jobs. Set alongside `timeout_s` when you need both a silence guard and a wall-clock cap. |
|
|
8
|
-
| Permission denied | Run `compose_permissions` for the member - it produces provider-native config. Claude: check `.claude/settings.local.json`. Agy: check
|
|
8
|
+
| Permission denied | Run `compose_permissions` for the member - it produces provider-native config. Claude: check `.claude/settings.local.json`. Agy: check `.gemini/antigravity-cli/settings.json` in the work folder. Codex: check `.codex/config.toml` approval mode. Copilot: check `.github/copilot/settings.local.json`. |
|
|
9
9
|
| Stuck after reset | Escalate model (cheap->standard->premium). Still stuck? Flag to user |
|
|
10
10
|
| Auth error (401/403) | GitHub App: re-mint via `provision_vcs_auth`. Bitbucket/Azure DevOps: ask user for fresh token, provision, retry. See auth-*.md |
|
|
11
11
|
| Token/password appears in command output | Use `credential_store_set` to store the secret, then reference it as `{{secure.NAME}}` in `execute_command` - Fleet redacts it to `[REDACTED:NAME]` before the LLM sees the output |
|
|
12
12
|
| Need to rotate a credential without re-provisioning | Run `credential_store_delete name=<NAME>` then `credential_store_set name=<NAME>` - the new value is picked up immediately on the next `execute_command` that references `{{secure.NAME}}` |
|
|
13
13
|
| Tool execution issue (unexpected behavior, missing output, silent failure) | Check `APRA_FLEET_DATA_DIR/logs/fleet-<pid>.log` for detailed execution traces. Filter by member with `jq 'select(.member_id == "<uuid>")'` or by tool with `jq 'select(.tag == "<tool>")'`. See the **Fleet Logs** section in SKILL.md for full field reference and `jq` examples. |
|
|
14
|
+
| `bd dolt pull`/`push` fails with "merge conflicts in issues require operator resolution" | Real divergence, not corruption -- do NOT `bd init`/`bd init --from-jsonl`/delete `.beads/`. See `beads-conflict-resolution.md` for the manual dolt SQL recovery playbook. |
|
package/version.json
CHANGED
|
@@ -1,52 +0,0 @@
|
|
|
1
|
-
import type { ProviderAdapter, PromptOptions, ParsedResponse, WorkspaceTrustExecFn, EnsureWorkspaceTrustedResult, SessionIdStrategy, TargetOS } from './provider.js';
|
|
2
|
-
import type { LlmProvider, SSHExecResult } from '../types.js';
|
|
3
|
-
import type { PromptErrorCategory } from '../utils/prompt-errors.js';
|
|
4
|
-
export declare function getAllowedMcpServers(): string;
|
|
5
|
-
export declare class GeminiProvider implements ProviderAdapter {
|
|
6
|
-
readonly name: LlmProvider;
|
|
7
|
-
readonly processName = "gemini";
|
|
8
|
-
readonly authEnvVar = "GEMINI_API_KEY";
|
|
9
|
-
readonly credentialPath = "~/.gemini/";
|
|
10
|
-
readonly instructionFileName = "GEMINI.md";
|
|
11
|
-
cliCommand(args: string): string;
|
|
12
|
-
versionCommand(): string;
|
|
13
|
-
installCommand(os: 'linux' | 'macos' | 'windows'): string;
|
|
14
|
-
updateCommand(): string;
|
|
15
|
-
buildPromptCommand(opts: PromptOptions): string;
|
|
16
|
-
skipPermissionsFlag(): string;
|
|
17
|
-
permissionModeAutoFlag(): string | null;
|
|
18
|
-
resolvePermissionFlag(unattended: false | 'auto' | 'dangerous' | undefined): string;
|
|
19
|
-
parseResponse(result: SSHExecResult): ParsedResponse;
|
|
20
|
-
supportsResume(): boolean;
|
|
21
|
-
supportsMaxTurns(): boolean;
|
|
22
|
-
resumeFlag(sessionId?: string, resuming?: boolean): string;
|
|
23
|
-
sessionIdStrategy(): SessionIdStrategy;
|
|
24
|
-
resolveSessionLogPath(sessionId: string, workFolder: string, homeDir?: string | null, targetOs?: TargetOS): string;
|
|
25
|
-
resolveSessionLogDir(workFolder: string, homeDir?: string | null, targetOs?: TargetOS): string | null;
|
|
26
|
-
modelTiers(): Record<'cheap' | 'standard' | 'premium', string>;
|
|
27
|
-
modelForTier(tier: 'cheap' | 'standard' | 'premium'): string;
|
|
28
|
-
modelFlag(model: string): string;
|
|
29
|
-
agentDirectories(agentName: string): {
|
|
30
|
-
project: string;
|
|
31
|
-
home: string;
|
|
32
|
-
};
|
|
33
|
-
transformAgent(content: string, _relPath: string): string;
|
|
34
|
-
agentNameFlag(agentName: string): string;
|
|
35
|
-
classifyError(output: string): PromptErrorCategory;
|
|
36
|
-
permissionConfigPaths(): string[];
|
|
37
|
-
composePermissionConfig(role: 'doer' | 'reviewer', allow?: string[]): Array<Record<string, unknown> | string>;
|
|
38
|
-
supportsOAuthCopy(): boolean;
|
|
39
|
-
supportsApiKey(): boolean;
|
|
40
|
-
oauthCredentialFiles(): Array<{
|
|
41
|
-
localPath: string;
|
|
42
|
-
remotePath: string;
|
|
43
|
-
}> | null;
|
|
44
|
-
oauthSettingsMerge(): Record<string, unknown> | null;
|
|
45
|
-
oauthEnvVarsToUnset(): string[];
|
|
46
|
-
authEnvVarForToken(_token: string): string;
|
|
47
|
-
wrapWindowsPrompt(setupCmd: string, filePath: string, argList: string, _sessionId?: string, _model?: string): string;
|
|
48
|
-
jsonOutputFlag(): string;
|
|
49
|
-
headlessInvocation(promptLiteral: string): string;
|
|
50
|
-
ensureWorkspaceTrusted(_workFolder: string, _execCommand: WorkspaceTrustExecFn, _agentOs?: 'linux' | 'macos' | 'windows'): Promise<EnsureWorkspaceTrustedResult>;
|
|
51
|
-
}
|
|
52
|
-
//# sourceMappingURL=gemini.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"gemini.d.ts","sourceRoot":"","sources":["../../src/providers/gemini.ts"],"names":[],"mappings":"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"}
|