@chankov/agent-fleet 2.0.14 → 2.0.15
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/.pi/agent-fleet/scripts/fleet.ts +2 -1
- package/.pi/extensions/compact-and-continue/README.md +2 -2
- package/.pi/harnesses/agent-hub/README.md +89 -10
- package/.pi/harnesses/agent-hub/budget-recovery.ts +2 -2
- package/.pi/harnesses/agent-hub/commands/context.ts +2 -0
- package/.pi/harnesses/agent-hub/commands/recover.ts +13 -4
- package/.pi/harnesses/agent-hub/commands/task-triage-recover.ts +12 -0
- package/.pi/harnesses/agent-hub/commands/task-triage-waive.ts +12 -0
- package/.pi/harnesses/agent-hub/context/budgets.ts +9 -7
- package/.pi/harnesses/agent-hub/deterministic-fs.ts +51 -12
- package/.pi/harnesses/agent-hub/dispatch-native-complete.ts +4 -0
- package/.pi/harnesses/agent-hub/dispatch-native-prepare.ts +14 -3
- package/.pi/harnesses/agent-hub/dispatch-native-types.ts +3 -0
- package/.pi/harnesses/agent-hub/dispatch-native.ts +9 -1
- package/.pi/harnesses/agent-hub/dispatch-triage-eval.ts +2 -1
- package/.pi/harnesses/agent-hub/dispatch-triage-runtime.ts +2 -0
- package/.pi/harnesses/agent-hub/dispatch-triage-state.ts +23 -5
- package/.pi/harnesses/agent-hub/docs-lane.js +2 -1
- package/.pi/harnesses/agent-hub/evidence-manifest.ts +51 -0
- package/.pi/harnesses/agent-hub/filesystem-tool.ts +75 -11
- package/.pi/harnesses/agent-hub/index.ts +246 -19
- package/.pi/harnesses/agent-hub/lifecycle/context-pressure.ts +13 -5
- package/.pi/harnesses/agent-hub/no-progress.ts +232 -28
- package/.pi/harnesses/agent-hub/orchestration-activation.ts +112 -0
- package/.pi/harnesses/agent-hub/orchestration-metrics.ts +78 -0
- package/.pi/harnesses/agent-hub/orchestration-route.ts +76 -0
- package/.pi/harnesses/agent-hub/package.json +1 -1
- package/.pi/harnesses/agent-hub/policy/work-mode.ts +14 -5
- package/.pi/harnesses/agent-hub/process-obligations.ts +116 -15
- package/.pi/harnesses/agent-hub/prompts/fragments.ts +9 -11
- package/.pi/harnesses/agent-hub/recover-policy.ts +18 -1
- package/.pi/harnesses/agent-hub/recover-state.ts +1 -1
- package/.pi/harnesses/agent-hub/recovery-contract.ts +70 -0
- package/.pi/harnesses/agent-hub/rerun-policy.ts +40 -0
- package/.pi/harnesses/agent-hub/research/runtime.ts +2 -0
- package/.pi/harnesses/agent-hub/research/spawn-run.ts +15 -6
- package/.pi/harnesses/agent-hub/return-contract.js +27 -5
- package/.pi/harnesses/agent-hub/review-closure.ts +43 -0
- package/.pi/harnesses/agent-hub/routing-observation.ts +41 -0
- package/.pi/harnesses/agent-hub/routing-proposal.ts +46 -0
- package/.pi/harnesses/agent-hub/run-budget.js +12 -0
- package/.pi/harnesses/agent-hub/scope-gate.js +23 -2
- package/.pi/harnesses/agent-hub/session-audit.ts +94 -8
- package/.pi/harnesses/agent-hub/spawn.ts +10 -2
- package/.pi/harnesses/agent-hub/system1-activity.ts +116 -1
- package/.pi/harnesses/agent-hub/system1-communication-store.ts +47 -13
- package/.pi/harnesses/agent-hub/system1-report.ts +50 -0
- package/.pi/harnesses/agent-hub/system1-runtime.ts +3 -2
- package/.pi/harnesses/agent-hub/task-triage-authorization.ts +122 -0
- package/.pi/harnesses/agent-hub/task-triage-config.ts +37 -0
- package/.pi/harnesses/agent-hub/task-triage-contract.ts +19 -0
- package/.pi/harnesses/agent-hub/task-triage-obligations.ts +104 -0
- package/.pi/harnesses/agent-hub/task-triage-policy.ts +16 -0
- package/.pi/harnesses/agent-hub/task-triage-runtime.ts +125 -0
- package/.pi/harnesses/agent-hub/task-triage-stage-guard.ts +21 -0
- package/.pi/harnesses/agent-hub/task-triage-state.ts +46 -0
- package/.pi/harnesses/agent-hub/tools/action-executors.ts +33 -10
- package/.pi/harnesses/agent-hub/tools/dispatch-agent.ts +1 -1
- package/.pi/harnesses/agent-hub/tools/dispatch-execution.ts +86 -26
- package/.pi/harnesses/agent-hub/tools/herdr-executors.ts +9 -0
- package/.pi/harnesses/agent-hub/ui/fleet-dashboard.ts +9 -6
- package/.pi/harnesses/agent-hub/ui/fleet-source.ts +6 -2
- package/.pi/harnesses/agent-hub/ui/system1-communication.ts +1 -1
- package/.pi/harnesses/agent-hub/work-mode.ts +13 -8
- package/.pi/harnesses/coms/package.json +1 -1
- package/.pi/harnesses/damage-control-continue/package.json +1 -1
- package/.pi/harnesses/lib/context-budget-hub-prompt.ts +6 -1
- package/.pi/harnesses/lib/fleet-dashboard-view.ts +29 -4
- package/.pi/harnesses/lib/fleet-read-model.ts +73 -0
- package/.pi/harnesses/lib/system1/demo.ts +2 -4
- package/.pi/harnesses/lib/system1/selection.js +11 -0
- package/.pi/prompts/af-build.md +9 -6
- package/.versions/2.0.15/.pi/agent-fleet/hermes/README.md +347 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/desktop-plugins/agent-fleet-herdr/plugin.js +1291 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/desktop-plugins/agent-fleet-herdr/presentation.js +672 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/desktop-plugins/agent-fleet-monitor/plugin.js +19 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/desktop-plugins/agent-fleet-monitor/state.js +10 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/gates/gate-o-capability.md +8 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/gates/gate-o-validator-fixtures.json +1 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/dashboard/activity.py +773 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/dashboard/coms_registry.py +134 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/dashboard/coms_send.py +350 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/dashboard/herdr_source.py +193 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/dashboard/manifest.json +4 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/dashboard/plugin_api.py +444 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/dashboard/sessions.py +205 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/dashboard/tasks.py +300 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/dashboard/watch.py +819 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/plugin.yaml +8 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/plugins/agent-fleet-monitor/dashboard/adapter.py +139 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/plugins/agent-fleet-monitor/dashboard/manifest.json +11 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/plugins/agent-fleet-monitor/dashboard/plugin_api.py +50 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/skills/hub-conductor/SKILL.md +84 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/skills/hub-liaison/SKILL.md +84 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/skills/hub-watchdog/SKILL.md +76 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/skills/hub-watchdog/manifest.json +1 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/skills/hub-watchdog/scripts/watchdog.py +249 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/skills/hub-watchdog/scripts/watchdog_actions.py +124 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/skills/hub-watchdog/scripts/watchdog_contract.py +76 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/skills/hub-watchdog/scripts/watchdog_delivery.py +10 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/skills/hub-watchdog/scripts/watchdog_engine.py +128 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/skills/hub-watchdog/scripts/watchdog_judgment.py +41 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/skills/hub-watchdog/scripts/watchdog_recovery.py +103 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/skills/hub-watchdog/scripts/watchdog_state.py +163 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/skills/hub-watchdog/scripts/watchdog_transport.py +138 -0
- package/.versions/2.0.15/.pi/agent-fleet/hermes/watchdog-tests/__init__.py +0 -0
- package/.versions/2.0.15/.pi/agent-fleet/hooks/coms-stop-hook.mjs +84 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/claude-code-preflight.ts +70 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/coms-claude-bridge.ts +411 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/coms-cli.ts +425 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/coms-hermes-bridge.ts +413 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/fleet-codex-client.ts +69 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/fleet-codex-read.py +148 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/fleet.ts +217 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/flow.ts +157 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/hermes-monitor-capability-runner.ts +25 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/hermes-monitor-scenario.ts +474 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/hermes-watchdog-capability-probe.ts +45 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/install-hermes-plugin.sh +180 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/lib/claude-bridge-core.ts +210 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/lib/coms-envelope.ts +582 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/lib/fake-herdr-server.ts +88 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/lib/fleet-codex-catalog.ts +63 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/lib/fleet-codex-operations.ts +190 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/lib/fleet-codex-session.ts +166 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/lib/fleet-codex-transport.ts +124 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/lib/fleet-command.ts +252 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/lib/flow-command.ts +98 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/lib/flow-maintenance.ts +230 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/lib/herdr-layout.ts +281 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/lib/hermes-bridge-core.ts +241 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/lib/hermes-monitor-events.ts +1 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/lib/hermes-monitor-herdr.ts +2 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/lib/hermes-monitor-model.ts +3 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/lib/hermes-monitor-registry.ts +2 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/lib/hermes-monitor-socket.ts +2 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/lib/hermes-monitor-store.ts +2 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/lib/monitor-env.ts +146 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/lib/peer-launch.ts +318 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/lib/persona-banner.ts +62 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/lib/persona-dirs.ts +25 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/lib/runtime-dependencies.js +124 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/lib/spawn-stagger.ts +101 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/lib/team-project.ts +178 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/lib/team-snapshot.ts +147 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/package-lock.json +35 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/package.json +9 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/peer-banner.ts +41 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/peer-launch.ts +283 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/team-snapshot.ts +237 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/team-up.ts +378 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/lib/agent-phase.ts +179 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/lib/changes.ts +61 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/lib/debate.ts +149 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/lib/env.ts +34 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/lib/envelopes.ts +169 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/lib/gates.ts +81 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/lib/git.ts +96 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/lib/isolated-snapshot.ts +125 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/lib/merge.ts +95 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/lib/model-profile.ts +22 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/lib/model-visibility.ts +92 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/lib/permissions.ts +130 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/lib/personas.ts +57 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/lib/poll.ts +86 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/lib/project-policy.ts +34 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/lib/quality.ts +64 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/lib/run.ts +108 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/lib/scout-data-boundary.ts +55 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/lib/trace.ts +34 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/lib/voices.ts +128 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/lib/writer-lease.ts +112 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/tsconfig.json +22 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/wf-build-test.ts +61 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/wf-debate.ts +87 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/wf-document.ts +50 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/wf-poll.ts +95 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/wf-quality.ts +20 -0
- package/.versions/2.0.15/.pi/agent-fleet/scripts/workflows/wf-scout.ts +40 -0
- package/.versions/2.0.15/.pi/agents/dispatch-policy.yaml +32 -0
- package/.versions/2.0.15/.pi/agents/model-profiles.yaml +134 -0
- package/.versions/2.0.15/.pi/agents/peers.yaml +147 -0
- package/.versions/2.0.15/.pi/agents/teams.yaml +41 -0
- package/.versions/2.0.15/.pi/agents/voices.yaml +13 -0
- package/.versions/2.0.15/.pi/damage-control-rules.yaml +297 -0
- package/.versions/2.0.15/.pi/extensions/btw/README.md +120 -0
- package/.versions/2.0.15/.pi/extensions/btw/index.ts +914 -0
- package/.versions/2.0.15/.pi/extensions/btw/package.json +6 -0
- package/.versions/2.0.15/.pi/extensions/btw/state.js +179 -0
- package/.versions/2.0.15/.pi/extensions/chrome-devtools-mcp/README.md +55 -0
- package/.versions/2.0.15/.pi/extensions/chrome-devtools-mcp/index.ts +93 -0
- package/.versions/2.0.15/.pi/extensions/chrome-devtools-mcp/package.json +6 -0
- package/.versions/2.0.15/.pi/extensions/compact-and-continue/README.md +42 -0
- package/.versions/2.0.15/.pi/extensions/compact-and-continue/index.ts +120 -0
- package/.versions/2.0.15/.pi/extensions/compact-and-continue/package.json +6 -0
- package/.versions/2.0.15/.pi/extensions/mcp-bridge/README.md +46 -0
- package/.versions/2.0.15/.pi/extensions/mcp-bridge/index.ts +206 -0
- package/.versions/2.0.15/.pi/extensions/mcp-bridge/package.json +6 -0
- package/.versions/2.0.15/.pi/extensions/package-lock.json +1175 -0
- package/.versions/2.0.15/.pi/extensions/package.json +9 -0
- package/.versions/2.0.15/.pi/extensions/pi-voice-stt/README.md +224 -0
- package/.versions/2.0.15/.pi/extensions/pi-voice-stt/config.ts +198 -0
- package/.versions/2.0.15/.pi/extensions/pi-voice-stt/examples/stt.json +35 -0
- package/.versions/2.0.15/.pi/extensions/pi-voice-stt/index.ts +248 -0
- package/.versions/2.0.15/.pi/extensions/pi-voice-stt/package.json +6 -0
- package/.versions/2.0.15/.pi/extensions/pi-voice-stt/providers.ts +214 -0
- package/.versions/2.0.15/.pi/extensions/pi-voice-stt/recorder.ts +158 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/README.md +1448 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/acceptance.ts +199 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/access-approval.ts +135 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/artifacts.js +146 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/assertion-ledger.js +67 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/assist-profile.ts +16 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/backend-policy.js +174 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/bounded-output.ts +26 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/budget-continuation.ts +13 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/budget-recovery.ts +214 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/capability-confirmation.ts +47 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/capability-packs.ts +184 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/agent-model-thinking.ts +10 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/agent-model.ts +10 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/agent-models-substitute.ts +10 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/agents-add.ts +9 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/agents-drop.ts +9 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/agents-history.ts +9 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/agents-kill.ts +10 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/agents-list.ts +9 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/agents-restart.ts +10 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/agents-save.ts +9 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/agents-team.ts +9 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/audit.ts +9 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/budget-continue.ts +10 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/compound.ts +9 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/coms.ts +9 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/context-command.ts +9 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/context.ts +47 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/debate.ts +9 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/dispatch-policy.ts +9 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/handoff.ts +10 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/hub-report.ts +9 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/models.ts +10 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/poll.ts +9 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/recover.ts +61 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/retry.ts +10 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/task-triage-recover.ts +12 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/task-triage-waive.ts +12 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/watchdog.ts +9 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/work-mode.ts +29 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/commands/zoom.ts +10 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/config/agents.ts +178 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/config/model-profiles.ts +236 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/config/overrides.ts +160 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/context/agent-state.ts +30 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/context/assertions-artifacts.ts +221 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/context/budgets.ts +206 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/context/hub-state.ts +40 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/context-budget-snapshot.ts +105 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/context-pressure.ts +191 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/context-window.js +108 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/debate-command.ts +176 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/delegate.ts +467 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/deterministic-fs.ts +166 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/diagnostic-probe-extension.ts +26 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/diagnostic-series-budget.ts +178 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/dispatch-coms.ts +252 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/dispatch-core.ts +27 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/dispatch-native-complete.ts +173 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/dispatch-native-prepare.ts +259 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/dispatch-native-spawn.ts +231 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/dispatch-native-types.ts +260 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/dispatch-native.ts +234 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/dispatch-observability.ts +225 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/dispatch-triage-contract.ts +38 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/dispatch-triage-eval.ts +76 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/dispatch-triage-policy.ts +29 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/dispatch-triage-runtime.ts +55 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/dispatch-triage-state.ts +33 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/docs-lane.js +123 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/drift-judge.ts +352 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/drift-runtime.ts +480 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/drift-system1-policy.ts +39 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/drift-system1.ts +469 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/drift-watchdog.js +349 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/evidence-manifest.ts +51 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/evidence-rules.js +96 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/execution-evidence.ts +80 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/external-blocker.js +85 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/filesystem-tool.ts +137 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/fixtures/registration-surface.json +64 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/fixtures/t0a-synthetic/catalog.ts +189 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/footer.ts +30 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/helpers.ts +270 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/hub-state-audit.js +65 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/index.ts +2597 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/input/completions.ts +82 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/input/shortcuts.ts +20 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/lifecycle/context-pressure.ts +133 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/lifecycle/monitor-session.ts +104 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/lifecycle/session-orchestration.ts +143 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/lifecycle/turn-handlers.ts +74 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/monitor-control.ts +9 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/monitor-invoke-journal.ts +131 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/monitor-invoke.ts +92 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/monitor-lifecycle.ts +13 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/monitor-publisher.ts +59 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/monitor-recovery.ts +3 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/monitor-runtime.ts +3 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/monitor-session-bridge.ts +266 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/no-progress.ts +563 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/orchestration-activation.ts +112 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/orchestration-metrics.ts +78 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/orchestration-route.ts +76 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/package.json +7 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/peer-spawn-plan.ts +116 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/policy/models.ts +153 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/policy/profile-activation.ts +62 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/policy/profile-runtime.ts +120 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/policy/roster.ts +94 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/policy/work-mode.ts +135 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/poll-command.ts +176 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/presentation.ts +48 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/proactive-config.ts +40 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/proactive-evaluate.ts +138 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/proactive-feedback.ts +104 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/proactive-findings.ts +115 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/proactive-local.ts +88 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/proactive-observer.ts +105 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/proactive-rules.ts +143 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/proactive-runtime.ts +316 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/proactive-selection.ts +68 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/proactive-snapshot-worker.mjs +12 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/proactive-snapshot.ts +243 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/proactive-types.ts +63 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/process-obligations.ts +158 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/prompts/context.ts +54 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/prompts/fragments.ts +116 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/prompts/session-start.ts +90 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/prompts/system-prompt.ts +122 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/provider-semaphore.js +138 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/reconcile.ts +26 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/recover-policy.ts +44 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/recover-state.ts +104 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/recovery-contract.ts +150 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/rerun-policy.ts +40 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/research/controls.ts +74 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/research/runtime.ts +197 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/research/spawn-run.ts +183 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/research-watchdog.ts +40 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/return-contract.js +349 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/return-extract.js +77 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/review-closure.ts +43 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/review-findings.js +104 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/routing-observation.ts +41 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/routing-proposal.ts +46 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/run-budget.js +554 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/run-namespace.js +93 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/runtime-test-check.ts +54 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/safety-routing.ts +22 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/scope-gate.js +144 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/session-audit.ts +313 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/session-health.js +110 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/session-start.ts +42 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/spawn.ts +534 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/system1-activity.ts +625 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/system1-communication-store.ts +129 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/system1-report.ts +275 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/system1-runtime.ts +280 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/task-resume-contract.ts +70 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/task-triage-authorization.ts +122 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/task-triage-config.ts +37 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/task-triage-contract.ts +19 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/task-triage-live-stage-boundary.mjs +49 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/task-triage-live-stage-closure.user-run.mjs +336 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/task-triage-obligations.ts +104 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/task-triage-policy.ts +16 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/task-triage-review-contract.mjs +43 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/task-triage-reviewer-only-contract.mjs +156 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/task-triage-reviewer-only-diagnostics.mjs +112 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/task-triage-reviewer-only.user-run.mjs +157 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/task-triage-runtime.ts +125 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/task-triage-stage-guard.ts +21 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/task-triage-state.ts +46 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/timeline.ts +72 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/tool-catalog-runtime.ts +68 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/tool-catalog-state.ts +123 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/tool-protocol.ts +134 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/tools/action-executors.ts +208 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/tools/coms-tools.ts +139 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/tools/context.ts +144 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/tools/dispatch-agent.ts +88 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/tools/dispatch-execution.ts +558 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/tools/dispatch-triage.ts +16 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/tools/execution-orchestration.ts +22 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/tools/fleet-tools.ts +200 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/tools/herdr-executors.ts +95 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/tools/run-flow.ts +136 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/tools/set-task-tier.ts +31 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/tools/spawn-research.ts +65 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/tools/team-adjust.ts +29 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/tools/verification-contract.ts +80 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/tsconfig.json +22 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/types.ts +66 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/ui/activity-dots.ts +25 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/ui/context-budget.ts +87 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/ui/detail-panel.ts +192 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/ui/fleet-actions.ts +78 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/ui/fleet-dashboard.ts +155 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/ui/fleet-editor.ts +44 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/ui/fleet-source.ts +179 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/ui/grid.ts +159 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/ui/history-store.ts +137 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/ui/history.ts +234 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/ui/pool.ts +103 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/ui/running-strip.ts +2 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/ui/system1-communication.ts +59 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/ui/zoom.ts +206 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/unknown-tool-counter.ts +116 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/version.ts +42 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/watchdog-evaluation.ts +110 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/work-mode-controls.ts +56 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/work-mode.ts +179 -0
- package/.versions/2.0.15/.pi/harnesses/agent-hub/write-isolation.ts +187 -0
- package/.versions/2.0.15/.pi/harnesses/ask-user-remote/README.md +59 -0
- package/.versions/2.0.15/.pi/harnesses/ask-user-remote/index.ts +558 -0
- package/.versions/2.0.15/.pi/harnesses/ask-user-remote/questions.ts +161 -0
- package/.versions/2.0.15/.pi/harnesses/ask-user-remote/race-core.js +124 -0
- package/.versions/2.0.15/.pi/harnesses/ask-user-remote/runtime-ask.ts +68 -0
- package/.versions/2.0.15/.pi/harnesses/coms/README.md +100 -0
- package/.versions/2.0.15/.pi/harnesses/coms/index.ts +282 -0
- package/.versions/2.0.15/.pi/harnesses/coms/package.json +7 -0
- package/.versions/2.0.15/.pi/harnesses/coms/version.ts +42 -0
- package/.versions/2.0.15/.pi/harnesses/damage-control-continue/README.md +135 -0
- package/.versions/2.0.15/.pi/harnesses/damage-control-continue/index.ts +550 -0
- package/.versions/2.0.15/.pi/harnesses/damage-control-continue/package.json +7 -0
- package/.versions/2.0.15/.pi/harnesses/damage-control-continue/version.ts +42 -0
- package/.versions/2.0.15/.pi/harnesses/lib/changed-file-diagnostics.ts +642 -0
- package/.versions/2.0.15/.pi/harnesses/lib/coms-core-io.ts +385 -0
- package/.versions/2.0.15/.pi/harnesses/lib/coms-core.ts +577 -0
- package/.versions/2.0.15/.pi/harnesses/lib/coms-registry-entry.ts +94 -0
- package/.versions/2.0.15/.pi/harnesses/lib/context-budget-child-prompt.ts +219 -0
- package/.versions/2.0.15/.pi/harnesses/lib/context-budget-hub-prompt.ts +121 -0
- package/.versions/2.0.15/.pi/harnesses/lib/context-budget-view.ts +107 -0
- package/.versions/2.0.15/.pi/harnesses/lib/context-budget.ts +114 -0
- package/.versions/2.0.15/.pi/harnesses/lib/damage-control-shared.ts +197 -0
- package/.versions/2.0.15/.pi/harnesses/lib/deterministic-handle-path.ts +23 -0
- package/.versions/2.0.15/.pi/harnesses/lib/fixtures/context-budget-profiles.json +11 -0
- package/.versions/2.0.15/.pi/harnesses/lib/fixtures/hub-prompt-operator.legacy.txt +73 -0
- package/.versions/2.0.15/.pi/harnesses/lib/fixtures/hub-prompt-orchestrator.legacy.txt +73 -0
- package/.versions/2.0.15/.pi/harnesses/lib/fleet-dashboard-ops.ts +178 -0
- package/.versions/2.0.15/.pi/harnesses/lib/fleet-dashboard-view.ts +172 -0
- package/.versions/2.0.15/.pi/harnesses/lib/fleet-detail-view.ts +339 -0
- package/.versions/2.0.15/.pi/harnesses/lib/fleet-overlay.ts +26 -0
- package/.versions/2.0.15/.pi/harnesses/lib/fleet-panel.ts +34 -0
- package/.versions/2.0.15/.pi/harnesses/lib/fleet-read-model.ts +609 -0
- package/.versions/2.0.15/.pi/harnesses/lib/fleet-selection.ts +24 -0
- package/.versions/2.0.15/.pi/harnesses/lib/fleet-strip-controller.ts +75 -0
- package/.versions/2.0.15/.pi/harnesses/lib/fleet-strip-view.ts +179 -0
- package/.versions/2.0.15/.pi/harnesses/lib/fleet-transcript-store.ts +244 -0
- package/.versions/2.0.15/.pi/harnesses/lib/herdr-client.ts +472 -0
- package/.versions/2.0.15/.pi/harnesses/lib/herdr-presence.ts +399 -0
- package/.versions/2.0.15/.pi/harnesses/lib/hermes-monitor-events.ts +136 -0
- package/.versions/2.0.15/.pi/harnesses/lib/hermes-monitor-herdr.ts +28 -0
- package/.versions/2.0.15/.pi/harnesses/lib/hermes-monitor-model.ts +18 -0
- package/.versions/2.0.15/.pi/harnesses/lib/hermes-monitor-registry.ts +6 -0
- package/.versions/2.0.15/.pi/harnesses/lib/hermes-monitor-socket.ts +163 -0
- package/.versions/2.0.15/.pi/harnesses/lib/hermes-monitor-store.ts +31 -0
- package/.versions/2.0.15/.pi/harnesses/lib/spawned-peers.js +191 -0
- package/.versions/2.0.15/.pi/harnesses/lib/system1/config.js +61 -0
- package/.versions/2.0.15/.pi/harnesses/lib/system1/contracts.ts +152 -0
- package/.versions/2.0.15/.pi/harnesses/lib/system1/demo.ts +104 -0
- package/.versions/2.0.15/.pi/harnesses/lib/system1/jev.ts +503 -0
- package/.versions/2.0.15/.pi/harnesses/lib/system1/selection.js +11 -0
- package/.versions/2.0.15/.pi/harnesses/lib/system1/service.ts +245 -0
- package/.versions/2.0.15/.pi/harnesses/lib/update-check.ts +222 -0
- package/.versions/2.0.15/.pi/harnesses/package-lock.json +2039 -0
- package/.versions/2.0.15/.pi/harnesses/package.json +10 -0
- package/.versions/2.0.15/.pi/prompts/af-build.md +27 -0
- package/.versions/2.0.15/.pi/prompts/af-code-simplify.md +22 -0
- package/.versions/2.0.15/.pi/prompts/af-constraints.md +31 -0
- package/.versions/2.0.15/.pi/prompts/af-plan.md +17 -0
- package/.versions/2.0.15/.pi/prompts/af-review.md +16 -0
- package/.versions/2.0.15/.pi/prompts/af-set-hermes-telegram.md +15 -0
- package/.versions/2.0.15/.pi/prompts/af-set-hermes-watchdog.md +6 -0
- package/.versions/2.0.15/.pi/prompts/af-setup-rules.md +20 -0
- package/.versions/2.0.15/.pi/prompts/af-ship.md +17 -0
- package/.versions/2.0.15/.pi/prompts/af-spec.md +15 -0
- package/.versions/2.0.15/.pi/prompts/af-test.md +19 -0
- package/.versions/2.0.15/.pi/skills/bowser/SKILL.md +145 -0
- package/.versions/2.0.15/.version +1 -0
- package/.versions/2.0.15/agents/architect.md +24 -0
- package/.versions/2.0.15/agents/bowser.md +28 -0
- package/.versions/2.0.15/agents/builder.md +55 -0
- package/.versions/2.0.15/agents/code-reviewer.md +209 -0
- package/.versions/2.0.15/agents/deep-researcher.md +32 -0
- package/.versions/2.0.15/agents/documenter.md +22 -0
- package/.versions/2.0.15/agents/orchestrator.md +22 -0
- package/.versions/2.0.15/agents/plan-reviewer.md +83 -0
- package/.versions/2.0.15/agents/planner.md +105 -0
- package/.versions/2.0.15/agents/releaser.md +24 -0
- package/.versions/2.0.15/agents/researcher.md +30 -0
- package/.versions/2.0.15/agents/security-auditor.md +167 -0
- package/.versions/2.0.15/agents/test-engineer.md +153 -0
- package/.versions/2.0.15/agents/web-debugger.md +44 -0
- package/.versions/2.0.15/agents/web-performance-auditor.md +194 -0
- package/.versions/2.0.15/bin/catalog/harness-runtime-closure.json +73 -0
- package/.versions/2.0.15/codex/fleet-session-client/SKILL.md +34 -0
- package/.versions/2.0.15/codex/fleet-session-client.zip +0 -0
- package/.versions/2.0.15/docs/ARCHITECTURE.md +829 -0
- package/.versions/2.0.15/docs/agent-fleet-setup.md +1090 -0
- package/.versions/2.0.15/docs/claude-code-coms-bridge.md +134 -0
- package/.versions/2.0.15/docs/codex-session-bridge.md +219 -0
- package/.versions/2.0.15/docs/coms-hermes-bridge.md +188 -0
- package/.versions/2.0.15/docs/getting-started.md +126 -0
- package/.versions/2.0.15/docs/npm-install.md +525 -0
- package/.versions/2.0.15/docs/pi-extensions.md +454 -0
- package/.versions/2.0.15/docs/pi-setup.md +92 -0
- package/.versions/2.0.15/docs/skill-anatomy.md +150 -0
- package/.versions/2.0.15/install-manifest.json +3193 -0
- package/.versions/2.0.15/justfile +247 -0
- package/.versions/2.0.15/manifest-meta.json +1071 -0
- package/.versions/2.0.15/references/accessibility-checklist.md +160 -0
- package/.versions/2.0.15/references/communication-contract.md +26 -0
- package/.versions/2.0.15/references/definition-of-done.md +67 -0
- package/.versions/2.0.15/references/fleet-coordination-patterns.md +171 -0
- package/.versions/2.0.15/references/observability-checklist.md +92 -0
- package/.versions/2.0.15/references/orchestration-patterns.md +370 -0
- package/.versions/2.0.15/references/performance-checklist.md +236 -0
- package/.versions/2.0.15/references/prompting-patterns.md +380 -0
- package/.versions/2.0.15/references/security-checklist.md +245 -0
- package/.versions/2.0.15/references/testing-patterns.md +235 -0
- package/.versions/2.0.15/references/workflow-authoring.md +304 -0
- package/.versions/2.0.15/skills/_internal/grilling.md +59 -0
- package/.versions/2.0.15/skills/browser-testing-with-devtools/SKILL.md +351 -0
- package/.versions/2.0.15/skills/code-review-and-quality/SKILL.md +396 -0
- package/.versions/2.0.15/skills/compound-learning/SKILL.md +137 -0
- package/.versions/2.0.15/skills/constraint-driven-development/SKILL.md +338 -0
- package/.versions/2.0.15/skills/constraint-driven-development/references/floor-guard.md +99 -0
- package/.versions/2.0.15/skills/context-engineering/SKILL.md +341 -0
- package/.versions/2.0.15/skills/deprecation-and-migration/SKILL.md +247 -0
- package/.versions/2.0.15/skills/designing-agents/SKILL.md +394 -0
- package/.versions/2.0.15/skills/designing-agents/pi-harness-authoring.md +222 -0
- package/.versions/2.0.15/skills/drafting-workflows/SKILL.md +143 -0
- package/.versions/2.0.15/skills/drafting-workflows/scripts/make-workflow.ts +177 -0
- package/.versions/2.0.15/skills/frontend-ui-engineering/SKILL.md +328 -0
- package/.versions/2.0.15/skills/git-workflow-and-versioning/SKILL.md +316 -0
- package/.versions/2.0.15/skills/idea-refine/SKILL.md +182 -0
- package/.versions/2.0.15/skills/idea-refine/examples.md +238 -0
- package/.versions/2.0.15/skills/idea-refine/frameworks.md +99 -0
- package/.versions/2.0.15/skills/idea-refine/refinement-criteria.md +113 -0
- package/.versions/2.0.15/skills/idea-refine/scripts/idea-refine.sh +15 -0
- package/.versions/2.0.15/skills/incremental-implementation/SKILL.md +353 -0
- package/.versions/2.0.15/skills/interview-me/SKILL.md +226 -0
- package/.versions/2.0.15/skills/orchestration-verification/SKILL.md +182 -0
- package/.versions/2.0.15/skills/peer-coms/SKILL.md +90 -0
- package/.versions/2.0.15/skills/performance-optimization/SKILL.md +496 -0
- package/.versions/2.0.15/skills/planning-and-task-breakdown/SKILL.md +318 -0
- package/.versions/2.0.15/skills/repository-ai-setup/SKILL.md +117 -0
- package/.versions/2.0.15/skills/repository-ai-setup/references/agent-fleet-ai-state.template.json +4 -0
- package/.versions/2.0.15/skills/repository-ai-setup/references/apply-contract.md +74 -0
- package/.versions/2.0.15/skills/repository-ai-setup/references/provenance-template.md +16 -0
- package/.versions/2.0.15/skills/repository-ai-setup/references/setup-flow.md +108 -0
- package/.versions/2.0.15/skills/repository-ai-setup/references/verify-setup.md +20 -0
- package/.versions/2.0.15/skills/security-and-hardening/SKILL.md +524 -0
- package/.versions/2.0.15/skills/spec-driven-development/SKILL.md +295 -0
- package/.versions/2.0.15/skills/using-agent-skills/SKILL.md +198 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/LICENSE +21 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/README.md +430 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md +367 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/browser-testing-with-devtools/SKILL.md +317 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/ci-cd-and-automation/SKILL.md +390 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/code-review-and-quality/SKILL.md +396 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/code-simplification/SKILL.md +331 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/constraint-driven-development/SKILL.md +311 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/constraint-driven-development/references/floor-guard.md +99 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/context-engineering/SKILL.md +337 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md +300 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/deprecation-and-migration/SKILL.md +247 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md +288 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md +243 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/frontend-ui-engineering/SKILL.md +328 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/git-workflow-and-versioning/SKILL.md +355 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/idea-refine/SKILL.md +178 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/idea-refine/examples.md +238 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/idea-refine/frameworks.md +99 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/idea-refine/refinement-criteria.md +113 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/idea-refine/scripts/idea-refine.sh +15 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/incremental-implementation/SKILL.md +249 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/interview-me/SKILL.md +225 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md +238 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/performance-optimization/SKILL.md +496 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/planning-and-task-breakdown/SKILL.md +257 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/security-and-hardening/SKILL.md +524 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md +330 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md +216 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/spec-driven-development/SKILL.md +245 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md +398 -0
- package/.versions/2.0.15/vendor/agent-skills-upstream/skills/using-agent-skills/SKILL.md +192 -0
- package/CHANGELOG.md +6 -0
- package/README.md +1 -1
- package/agents/builder.md +2 -2
- package/bin/cli.js +16 -2
- package/bin/lib/apply.js +5 -0
- package/bin/lib/doctor.js +85 -12
- package/bin/lib/reconcile.js +9 -1
- package/bin/lib/state.js +1 -0
- package/bin/lib/task-triage-setup.js +76 -0
- package/bin/lib/transaction.js +4 -0
- package/docs/ARCHITECTURE.md +99 -24
- package/docs/agent-fleet-setup.md +179 -6
- package/docs/npm-install.md +64 -15
- package/docs/pi-extensions.md +1 -1
- package/install-manifest.json +13 -3
- package/manifest-meta.json +6 -0
- package/package.json +9 -2
- package/skills/incremental-implementation/SKILL.md +64 -13
- package/skills/planning-and-task-breakdown/SKILL.md +43 -14
- package/skills/using-agent-skills/SKILL.md +2 -2
|
@@ -0,0 +1,1448 @@
|
|
|
1
|
+
# agent-hub
|
|
2
|
+
|
|
3
|
+
The unified Agent Fleet runtime for pi, with [`coms`](../coms/README.md) **embedded**. Bare
|
|
4
|
+
`just fleet` loads Fleet Core and starts `agent-hub` in **operator** work mode with direct coding
|
|
5
|
+
and orchestration tools, but no standing native roster. The same live session can switch to
|
|
6
|
+
**orchestrator** work mode, which removes direct coding tools and drives native specialists under
|
|
7
|
+
the Verification Contract. Fleet Core loads first: [`damage-control-continue`](../damage-control-continue/README.md),
|
|
8
|
+
[`ask-user-remote`](../ask-user-remote/README.md), STT, Compact & Continue, BTW, and the update
|
|
9
|
+
checker. Both work modes can adjust the native roster, run research, collaborate with Pi/Claude
|
|
10
|
+
peers, and hand the session to a visible coms peer.
|
|
11
|
+
|
|
12
|
+
> Consolidates the retired `agent-team` dispatcher into this harness and embeds the ported `coms`
|
|
13
|
+
> P2P layer from [`pi-vs-claude-code`](https://github.com/disler/pi-vs-claude-code) by
|
|
14
|
+
> [disler](https://github.com/disler) (MIT). See the
|
|
15
|
+
> [extension catalog](../../../docs/pi-extensions.md) and the
|
|
16
|
+
> [design plan](../../../docs/plans/agent-hub/).
|
|
17
|
+
|
|
18
|
+
**Optional ChatGPT client:** `just fleet --agents <roster> --peers <preset> --project <name>` can supply the live Pi session that the experimental [ChatGPT Fleet session client](https://github.com/chankov/agent-fleet/blob/main/docs/codex-session-bridge.md) selects. Hermes remains the inbound `ask_user` route.
|
|
19
|
+
|
|
20
|
+
## System 1 task triage (active experimental; off by default)
|
|
21
|
+
|
|
22
|
+
Task triage is a separate consumer of the existing TypeSafe `jev-1.13.0` service,
|
|
23
|
+
not `dispatch_triage` persona advice, watchdog calibration or the spend tier.
|
|
24
|
+
Select experimental `system1-task-triage` with separate task-context consent;
|
|
25
|
+
Default/Full and `--yes` alone do not enable it. Over an existing desired file,
|
|
26
|
+
use `--save-desired` for permanent headless opt-in/disable. Setup proposes absent
|
|
27
|
+
nonsecret consumer/provider configs transactionally and never flips a human off
|
|
28
|
+
config or collects a key. Runtime dependencies and caller key readiness remain
|
|
29
|
+
separate. See [exact config and setup](../../../docs/agent-fleet-setup.md#task-triage-active-experimental-off-by-default).
|
|
30
|
+
|
|
31
|
+
An enabled consumer evaluates accepted user task input before the first model
|
|
32
|
+
turn, including when the dispatcher skips `set_task_tier` or watchdog is off.
|
|
33
|
+
Limits: 40 KiB aggregate user task/clarifications, 64 KiB state, 100 logical calls
|
|
34
|
+
per saved session and 2,000 ms per evaluation. Identical input/scope is cached;
|
|
35
|
+
new scope can require another call. Reset, compaction, resume or work-mode change
|
|
36
|
+
does not refill the allowance. No file bodies/tool outputs/environment are sent
|
|
37
|
+
by this consumer; sensitive/oversized input is refused, not silently truncated.
|
|
38
|
+
|
|
39
|
+
Independent predicates add review for requested security changes (p ≥0.80),
|
|
40
|
+
plan/review for broad changes (p ≥0.85), and exact-action one-use confirmation for
|
|
41
|
+
requested potentially irreversible execution (p ≥0.80). They do not change the
|
|
42
|
+
tier/model/roster, increase spend or authorize effects. Review is before task
|
|
43
|
+
acceptance, not a blanket authoring ban. Low probability is never safety clearance.
|
|
44
|
+
Baseline and source additions persist through failures, disable and resume.
|
|
45
|
+
|
|
46
|
+
Missing roles require the human `/af-agents-add planner`, `/af-agents-add
|
|
47
|
+
code-reviewer` (or a permitted reviewer), or `/af-agents-team` path. Budget
|
|
48
|
+
exhaustion needs existing explicit continuation, not automatic escalation.
|
|
49
|
+
`/af-task-triage-waive <addition-id> <reason>` uses a correlated human answer for
|
|
50
|
+
one current addition; it remains waived rather than satisfied and cannot erase
|
|
51
|
+
baseline/other additions. `/af-task-triage-recover` performs checked process
|
|
52
|
+
append/readback, not JSONL editing. Pending input must be bound before dependent
|
|
53
|
+
effects. Direct Hub bash/edit/write confirmation is exact-call/input/cwd-bound.
|
|
54
|
+
It shows complete tool inputs as JSON and working directory, not merely a hash;
|
|
55
|
+
the **8 KiB (8192 bytes)** detail cap refuses missing, invalid, sensitive,
|
|
56
|
+
terminal/bidi-control, mismatched or oversized inputs **without truncation or
|
|
57
|
+
partial redaction**. JSON escapes preserve non-ASCII data. Sensitive-text refusal
|
|
58
|
+
is heuristic, not complete secret/PII detection. Inputs, cwd, task/revision,
|
|
59
|
+
operation and call ID are rechecked before one-use consumption. The human
|
|
60
|
+
question is **not local-only**: the existing ask-user local/remote human route
|
|
61
|
+
can carry action paths/content. Metadata-only audit does not sanitize ordinary
|
|
62
|
+
Pi tool/session rendering, human-route records or clipboard. Unsupported
|
|
63
|
+
child/coms/remote action bindings refuse that effect. Damage-control
|
|
64
|
+
and existing review/acceptance gates remain independent.
|
|
65
|
+
|
|
66
|
+
The full Fleet dashboard shows assessment, probabilities, active/waived additions,
|
|
67
|
+
effective stages and blockers even with no workers; it adds no small-strip badge.
|
|
68
|
+
Fleet `1` offers separately enabled memory-only capture with the unchanged
|
|
69
|
+
32 KiB viewer cap; larger otherwise-valid payloads are withheld. `/af-audit`
|
|
70
|
+
separates logical reservations/physical attempts/unknown usage and action grant,
|
|
71
|
+
consumption and tool result. Provider ok, assessment applied, process complete,
|
|
72
|
+
a waiver and tool-result success are not independent semantic acceptance. Trace
|
|
73
|
+
failure is optional; authoritative process/grant/consumption persistence failure
|
|
74
|
+
blocks the dependent effect.
|
|
75
|
+
|
|
76
|
+
Disable with the complete remaining feature set plus `--save-desired`, then
|
|
77
|
+
restart/resume; the human config and old task obligations survive. Cancel current
|
|
78
|
+
work normally if immediate stopping is needed. Active experimental is not live
|
|
79
|
+
accuracy, calibration, universal remote protection or release authority.
|
|
80
|
+
`npm run test:task-triage` is the guarded source regression suite and is included
|
|
81
|
+
in `npm run test:full`; scripted fixture reviews never replace independent
|
|
82
|
+
semantic review.
|
|
83
|
+
|
|
84
|
+
## Proactive turn review (experimental; off by default)
|
|
85
|
+
|
|
86
|
+
This is a **separate, per-repository, session-bound** advisory consumer of the
|
|
87
|
+
shared System 1 foundation, not the native watchdog's System 1 shortcut. The
|
|
88
|
+
human-owned `.ai/proactive-review.json` is never created by setup. Missing/off
|
|
89
|
+
means zero proactive capture, inference and feedback. Enabled `shadow` or
|
|
90
|
+
`advisory` requires explicit include scope; `remoteContext: "disabled"` is
|
|
91
|
+
local-only (reviewed deterministic validators, no semantic provider check),
|
|
92
|
+
while `selected-excerpts` additionally permits bounded source/assistant
|
|
93
|
+
excerpts to the already configured System 1 provider when ready. Shadow only
|
|
94
|
+
observes; advisory can deliver ≤3 current findings at the same owner's next
|
|
95
|
+
**natural** context hook (≤1,500 characters, once per finding revision).
|
|
96
|
+
There is no autonomous turn, fix, termination, permission, or acceptance gate;
|
|
97
|
+
the existing watchdog retains independent authority. Never interpret a
|
|
98
|
+
suspicion, uncovered rule, unavailable model, or lack of findings as verified
|
|
99
|
+
correctness.
|
|
100
|
+
|
|
101
|
+
Hub/direct and supported native Pi specialist turns are instrumented; nested
|
|
102
|
+
delegates, research helpers, coms peers and Hermes are not. Source and explicit
|
|
103
|
+
plan/rules are bound to the session's immutable snapshot; delivery checks
|
|
104
|
+
current source hashes and the session-bound rule revision. Rule discovery is read-only, source-bound and
|
|
105
|
+
bounded; missing/partial/unsupported coverage is visible rather than passed.
|
|
106
|
+
Editing rules during a session does **not** reload them: restart to adopt edits.
|
|
107
|
+
Bounded private snapshots support local validated evidence readback, while
|
|
108
|
+
operator history, `/af-hub-report` and `/af-audit` expose metadata-only
|
|
109
|
+
projections. Feedback never creates a new Pi turn. Native delivery without a
|
|
110
|
+
receipt remains unknown; rare async-close errors remain a nonblocking risk.
|
|
111
|
+
The tested native integration uses repo-local Pi 0.84.2; Node 18 covers only
|
|
112
|
+
extracted-package CLI/doctor compatibility, not the TypeScript observer.
|
|
113
|
+
|
|
114
|
+
See [config, limits, exact explicit human-label schema, offline installed
|
|
115
|
+
runbook, rollback and separately consented pilot](../../../docs/agent-fleet-setup.md#proactive-turn-review-experimental).
|
|
116
|
+
Use `/af-hub-report` and `/af-audit` without labels for read-only session
|
|
117
|
+
status; `--labels /absolute/path/to/CURRENT_SESSION/artifacts/labels.json`
|
|
118
|
+
requires an explicitly provided file in the current session, never auto-loads
|
|
119
|
+
labels and does not transmit payloads. Only retained findings expose label
|
|
120
|
+
keys in the local evidence view (Fleet Dashboard `p` → `n` → `e`, or specialist
|
|
121
|
+
detail `n` → `e`); unavailable evidence shows no template. Checked-clear
|
|
122
|
+
units have no operator-accessible keys, so human miss/true-negative labeling
|
|
123
|
+
and full recall evaluation are not operational; absent labels remain unknown.
|
|
124
|
+
Only the project's `rules:` roots are catalogued; an inactive session binding
|
|
125
|
+
proposal is not installed configuration or a loaded skill. C5 visibility and
|
|
126
|
+
the earlier C6 offline/package review do not constitute final post-fix review,
|
|
127
|
+
a live pilot or C7 acceptance. No release, deployment, repo config edit or
|
|
128
|
+
remote request is authorized by this README. Roll back with the complete
|
|
129
|
+
`{"version":1,"mode":"off"}` config and restart; cancel current work if
|
|
130
|
+
immediate stopping is necessary, without destructive artifact cleanup.
|
|
131
|
+
|
|
132
|
+
## Work Mode, roster, and topology
|
|
133
|
+
|
|
134
|
+
These are independent runtime axes:
|
|
135
|
+
|
|
136
|
+
- **Work Mode** — `/af-work-mode operator|orchestrator` switches prompt and active tools without
|
|
137
|
+
restarting or losing session state; `/af-work-mode` without an argument and **Alt+M** open the
|
|
138
|
+
two-option picker. Operator keeps `read`, `bash`, `edit`, `write`, approved extension tools, and
|
|
139
|
+
orchestration. Orchestrator withholds direct coding tools but keeps dispatch, research, assertions,
|
|
140
|
+
roster controls, `ask_user`, read-only `filesystem` stat/inventory/excerpt/readback, ready coms, and ready Herdr tools.
|
|
141
|
+
Self-read stops above 64 KiB for one file or for the turn; use research or a specialist and pass the path.
|
|
142
|
+
`dispatch_triage` is listed only when that consumer can evaluate. Snapshot stays profile-gated.
|
|
143
|
+
In orchestrator work mode, raw Herdr panes are auxiliary-process orchestration—not a route around delegation for reading,
|
|
144
|
+
editing, testing, or implementing code.
|
|
145
|
+
- **Native roster** — local headless Pi specialists from `.pi/agents/teams.yaml`. Bare Fleet starts
|
|
146
|
+
empty; select one with `--agents frontend` or add one live with `/af-agents-add code-reviewer`.
|
|
147
|
+
- **Peer topology** — separate long-lived Pi or Claude Code processes from `peers.yaml`, connected
|
|
148
|
+
by coms and optionally placed in sibling Herdr panes. `--peers frontend` selects a standing
|
|
149
|
+
preset; `--herdr` creates a Hub-only workspace through the empty `base` preset.
|
|
150
|
+
Switching from Operator to Orchestrator with no active agents automatically loads the first valid
|
|
151
|
+
team in configuration order (`default` in the shipped configuration), skipping empty teams and teams
|
|
152
|
+
with missing personas. Existing agents are kept. If no valid team is available, the switch is refused
|
|
153
|
+
with a warning. The selected team is saved in the session just like a manual team selection.
|
|
154
|
+
Budgets, nested delegation, and Verification Contract rigor follow the **task tier**, not Work Mode.
|
|
155
|
+
Orchestrator turn dispatches are the exception: trivial/small rise to at least 3 per turn unless
|
|
156
|
+
`max-dispatches-per-turn` sets a lower ceiling. Research calls and the task envelope stay on the tier.
|
|
157
|
+
|
|
158
|
+
All Hub slash commands, including `/af-handoff`, are registered in both work modes. A command whose
|
|
159
|
+
runtime capability is unavailable refuses with remediation rather than disappearing. `--no-coms`
|
|
160
|
+
disables only embedded coms; direct operator work and native dispatch remain available.
|
|
161
|
+
|
|
162
|
+
### Automatic capability surfaces
|
|
163
|
+
|
|
164
|
+
Capability packs load **automatically** from the current request, work mode, task tier, pending work,
|
|
165
|
+
and runtime state; there is no activation command. `core` is always present. Orchestrator work mode
|
|
166
|
+
always includes `fleet`; explicit delegation/research, acceptance work, an existing coms peer, a
|
|
167
|
+
Herdr pane/watcher request, and explicit or imminent compaction respectively add `fleet`,
|
|
168
|
+
`verification`, `peer`, `workspace`, and `compaction`. A ready coms or Herdr runtime is only
|
|
169
|
+
**readiness**, not intent: its tools and policy remain model-inactive until requested.
|
|
170
|
+
|
|
171
|
+
Ambiguous delegation, peer, or workspace intent provisionally exposes the smallest relevant pack
|
|
172
|
+
and records its reason in the state capsule and `/af-context`. Before that pack's first side effect,
|
|
173
|
+
the Hub asks one focused `ask_user` confirmation. Confirming promotes it for the task; reject or
|
|
174
|
+
cancel removes it and leaves no message, child, or pane behind. Active task packs persist through
|
|
175
|
+
follow-up turns so a workflow does not lose tools. They shrink only through
|
|
176
|
+
`set_task_tier(new_task: true)` (apart from mandatory work mode and pending-operation leases), never
|
|
177
|
+
merely because the next message sounds different. Compaction is the transient exception:
|
|
178
|
+
a task-triage assessment refresh preserves the current input's already-resolved explicit
|
|
179
|
+
compaction intent without re-reading task text or promoting declined packs. The next
|
|
180
|
+
ordinary input/reset/restore clears that explicit intent; context-pressure and pending-operation
|
|
181
|
+
leases remain independent. Showing `request_compaction` does not itself execute compaction.
|
|
182
|
+
|
|
183
|
+
`/af-context` separates stable replacement-prompt cost from the volatile state capsule and active
|
|
184
|
+
schemas. Inactive and ready-but-inactive packs cost zero model-visible characters. Provider totals,
|
|
185
|
+
including cache read/write when Pi supplies them, remain authoritative; deterministic character
|
|
186
|
+
figures are regression diagnostics and never invent provider usage.
|
|
187
|
+
|
|
188
|
+
### Context-pressure and resume recovery
|
|
189
|
+
|
|
190
|
+
Pre-turn surface cost and live conversation pressure are different budgets. `/af-context` separates
|
|
191
|
+
the stable replacement prompt, volatile state capsule, and active tool schemas; user and assistant
|
|
192
|
+
messages plus tool results then accumulate during a turn. A long tool loop can therefore reach the
|
|
193
|
+
model window even while every standing prompt ceiling remains green.
|
|
194
|
+
|
|
195
|
+
The Hub samples live provider usage and projects each finalized tool result before another model
|
|
196
|
+
request:
|
|
197
|
+
|
|
198
|
+
- Below **80%**, pressure is `normal`.
|
|
199
|
+
- At **80%**, pressure becomes `warning`; the compact recovery surface is exposed transiently and
|
|
200
|
+
ordinary work may continue.
|
|
201
|
+
- At **90%**, the Hub aborts the next same-turn provider request, waits until the tool result and
|
|
202
|
+
aborted turn are persisted, and starts one automatic Pi compaction. Only one recovery may run at
|
|
203
|
+
a time. Input received while startup or same-turn recovery is active is retained in memory,
|
|
204
|
+
including images, then replayed once after compaction succeeds.
|
|
205
|
+
|
|
206
|
+
The status line and `/af-context` show the pressure phase, measured usage, both thresholds, episode,
|
|
207
|
+
and last recovery outcome. Persisted pressure diagnostics contain numeric/enumerated metadata only;
|
|
208
|
+
they never include prompts, tool output, credentials, error bodies, or compaction summaries.
|
|
209
|
+
|
|
210
|
+
If automatic recovery reports `failed`, the queued input remains retained. Use Pi's built-in manual
|
|
211
|
+
fallback, or switch to a model with a larger context window:
|
|
212
|
+
|
|
213
|
+
```text
|
|
214
|
+
/compact Preserve the current goal, decisions, assertions, pending operations, blockers, and next step.
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
A resumed orchestrator session can also require roster recovery. The Hub persists only the selected
|
|
218
|
+
team name and resolves it again against the current `.pi/agents/teams.yaml` and persona files. If the
|
|
219
|
+
team is missing, renamed, empty, or stale, the Hub preserves orchestrator work mode, keeps direct coding
|
|
220
|
+
tools unavailable, and blocks model input rather than inventing a roster or silently downgrading.
|
|
221
|
+
Recover with one of these explicit choices:
|
|
222
|
+
|
|
223
|
+
```text
|
|
224
|
+
/af-agents-team # select a currently valid team in the live session
|
|
225
|
+
/af-work-mode operator # explicitly leave delegate-only work mode and restore direct tools
|
|
226
|
+
just fleet --agents <name> # restart through the public Fleet CLI
|
|
227
|
+
just fleet --work-mode operator # restart explicitly as an operator
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
For a direct Pi launch, the roster flag is `--agent-team <name>` and the work mode flag is
|
|
231
|
+
`--work-mode operator`; explicit startup flags take precedence over persisted selections. Fix stale
|
|
232
|
+
team/persona declarations before selecting them.
|
|
233
|
+
|
|
234
|
+
The Pi session JSONL under `~/.pi/agent/sessions/` is the authoritative append-only conversation and
|
|
235
|
+
recovery record. Context overflow or a stale roster does **not** by itself mean that file is corrupt.
|
|
236
|
+
Inspect it through `/session`, resume it through `/resume` or Pi's session flags, and recover through
|
|
237
|
+
compaction or the commands above. Never edit, truncate, reorder, or synthesize JSONL entries to
|
|
238
|
+
recover a session.
|
|
239
|
+
|
|
240
|
+
## What it does
|
|
241
|
+
|
|
242
|
+
The whole dispatch loop, end to end:
|
|
243
|
+
|
|
244
|
+
```mermaid
|
|
245
|
+
sequenceDiagram
|
|
246
|
+
autonumber
|
|
247
|
+
actor U as You
|
|
248
|
+
participant H as Hub (dispatcher)
|
|
249
|
+
participant S as Specialist (e.g. builder)
|
|
250
|
+
participant R as Research helper
|
|
251
|
+
participant D as Disk (.pi/agent-sessions/)
|
|
252
|
+
|
|
253
|
+
U->>H: task
|
|
254
|
+
H->>D: set_assertions — Verification Contract persisted
|
|
255
|
+
H->>S: dispatch_agent (task + advisory scope)
|
|
256
|
+
S-->>H: NEEDS_RESEARCH: how does X work?
|
|
257
|
+
H->>R: spawn_research (researcher / deep-researcher)
|
|
258
|
+
R->>D: write findings file
|
|
259
|
+
R-->>H: one-line notice + path
|
|
260
|
+
H->>S: resume with file paths — never raw findings
|
|
261
|
+
S-->>H: structured return + named evidence
|
|
262
|
+
H->>D: update_assertion
|
|
263
|
+
H-->>U: Assertions: 2✓ 1○ 1✗ · open: A4
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
Every borrowed idea from another harness passes one test before it lands: *does this persistently enter the dispatcher context?* If yes, it goes to disk or a one-line status instead.
|
|
267
|
+
|
|
268
|
+
`agent-hub` is the supported home for the former standalone dispatcher features:
|
|
269
|
+
|
|
270
|
+
- **Dispatcher grid** — a live dashboard of the active, dynamically adjustable native roster from `.pi/agents/teams.yaml`.
|
|
271
|
+
- **Context budget** — `/af-context` opens a separate read-only full-screen diagnostic in either work mode. It shows provider totals and cache fields beside named, metadata-only estimates; `loaded-excluded` Pi inputs are discovered but contribute zero to the replacement Hub prompt. Each specialist, research helper, delegate, and peer remains a separate context plane with its own model window. Component token estimates are heuristic/provider-scaled, never exact claims; unavailable peer/provider detail is labelled explicitly and raw prompts, schemas, and conversation text are never retained or displayed.
|
|
272
|
+
- **Specialist delegation** — `dispatch_agent` sends writable tasks to configured specialists.
|
|
273
|
+
- **Research helpers** — the dispatcher invokes `spawn_research` automatically for read-only
|
|
274
|
+
investigation; specialists can trigger the separate automatic `NEEDS_RESEARCH:` pipe described
|
|
275
|
+
below. Managed research children use a replacement read-only prompt with `--no-skills` and
|
|
276
|
+
`--no-context-files`; managed specialists receive a selected context manifest (persona, applicable
|
|
277
|
+
policy paths, and named skill paths) rather than inherited global skill/context loading. Two
|
|
278
|
+
`kind: research` personas ship by default: `researcher` (`gpt-6-luna`, low thinking) for simple
|
|
279
|
+
reads and `deep-researcher` (`grok-4.7`, medium thinking) for hard, cross-cutting investigation.
|
|
280
|
+
The dispatcher routes by persona; each persona's model + thinking level is shown in its catalog.
|
|
281
|
+
Live helpers appear in the Fleet Dashboard (`Alt+A`) and bounded fleet widget while they are
|
|
282
|
+
running. On every terminal outcome (success, error, timeout, spawn/preflight failure, or operator
|
|
283
|
+
kill) the live `rN` handle is removed immediately.
|
|
284
|
+
Session, transcript, and `findings/*.md` files remain on disk for the requester, and
|
|
285
|
+
`/af-agents-history` keeps the audit/timing record. Finished helpers cannot be restarted; a new
|
|
286
|
+
request always creates a fresh helper. `rN` handles are never reused during a Hub session.
|
|
287
|
+
- **Human handoff path** — `ask_user` is exposed by the `ask-user-remote` wrapper (capturing stock
|
|
288
|
+
`pi-ask-user` and optionally racing a `user-remote` bridge), so specialists can bubble decisions
|
|
289
|
+
back through the dispatcher.
|
|
290
|
+
- **Auto-research pipe (`NEEDS_RESEARCH:`)** — a specialist that lacks information pauses by ending
|
|
291
|
+
its turn with `NEEDS_RESEARCH: <question>` lines (mirror of the `ASK_USER:` protocol). The hub
|
|
292
|
+
intercepts them **in code**: it fans out read-only research helpers (max 4 questions per pause,
|
|
293
|
+
2 pauses per dispatch), writes each helper's findings to `.pi/agent-sessions/findings/*.md`, and
|
|
294
|
+
resumes the specialist's session with the file paths. The dispatcher LLM sees only a one-line
|
|
295
|
+
notice — raw findings never enter its context. Findings files are wiped at session start.
|
|
296
|
+
- **Verification Contract (assertion ledger)** — the dispatcher owns a ledger of checkable
|
|
297
|
+
acceptance assertions built from the request *before* any builder runs, so a clearly stated
|
|
298
|
+
requirement is never silently dropped. `set_assertions` records the numbered, tagged assertions
|
|
299
|
+
(`test` | `runtime-ui` | `code-grep` | `manual`, one pass condition each, plus a required
|
|
300
|
+
`source` naming where the requirement comes from) and rebuilds the whole
|
|
301
|
+
ledger on a "wrong again" regression reset; `update_assertion` marks each one proven (named
|
|
302
|
+
evidence required), unproven, or failed after a verification gate; `get_assertions` reads the
|
|
303
|
+
full ledger (ids, tags, pass conditions, evidence) back. The hub persists the ledger to
|
|
304
|
+
`.pi/agent-sessions/assertions.json` (wiped at session start like `findings/`) and renders a
|
|
305
|
+
one-line status (`Assertions: 2✓ 1○ 1✗ · open: A4`) so the contract survives compaction without
|
|
306
|
+
re-flooding the dispatcher LLM context — after a compaction the dispatcher calls `get_assertions`
|
|
307
|
+
to recover the full text the status line omits. The `orchestrator` persona drives it — a deep-researcher
|
|
308
|
+
parity inventory for "behave like" requests, runtime proof for UI/visibility assertions, the
|
|
309
|
+
regression reset on a re-ask — per
|
|
310
|
+
[`orchestration-verification`](../../../skills/orchestration-verification/SKILL.md). The hub also
|
|
311
|
+
machine-parses each assertion-carrying specialist's structured return, writes the full raw output
|
|
312
|
+
to `.pi/agent-sessions/sessions/<sessionId>/artifacts/returns/<agentKey>-<dispatchId>.md`, surfaces only a compact
|
|
313
|
+
`details.structuredReturn` digest plus `details.returnPath`, and marks contract notices such as
|
|
314
|
+
missing assertion ids or evidence-less `assertions_proven` entries (demoted to unproven in the
|
|
315
|
+
tool text). `details.fullOutput` remains for `/af-zoom`/compatibility, but dispatcher-visible text is
|
|
316
|
+
digest + path oriented. `update_assertion(status: "proven")` validates evidence by assertion tag:
|
|
317
|
+
test evidence needs a command/test and outcome, `code-grep` needs pattern plus result sample,
|
|
318
|
+
manual needs user/`ask_user` confirmation, and `runtime-ui` needs an existing artifact path under
|
|
319
|
+
`.pi/agent-sessions/artifacts/evidence/`. **Advisory by design** (PRD open question 2): status is
|
|
320
|
+
surfaced and "proven" requires named evidence, but a dispatch is never hard-refused on an unproven
|
|
321
|
+
assertion — code-enforcement is the Checkpoint A decision. Two contract rules ARE enforced at the
|
|
322
|
+
tool: a batch with any sourceless assertion is refused with the offending ids named (a specialist
|
|
323
|
+
told to prove `A9` must be able to read its origin instead of spending a dispatch and an ASK_USER
|
|
324
|
+
cycle asking where `A9` was defined), and a batch over **8** open assertions is accepted with a
|
|
325
|
+
warning suggesting the split — declare the batch the next dispatches actually prove, and
|
|
326
|
+
`set_assertions` the next one when it starts.
|
|
327
|
+
- **Artifact bus** — session handoffs live under `.pi/agent-sessions/artifacts/` with conventional
|
|
328
|
+
`returns/`, `failures/`, `plans/`, `reviews/`, `inventories/`, and `evidence/` subdirectories, all
|
|
329
|
+
**archived** into an immutable `runs/<runId>/` namespace at session start rather than wiped (see
|
|
330
|
+
[Immutable per-run artifact namespaces](#immutable-per-run-artifact-namespaces-run-namespacejs)),
|
|
331
|
+
so a later session can never overwrite an earlier one's returns. `failures/` is separate on purpose: a run
|
|
332
|
+
that errored or timed out produced no specialist result, so its output goes there and the dispatch
|
|
333
|
+
result names it a **delivery failure** carrying no assertion evidence. Filing a 142-byte coms error
|
|
334
|
+
stub as `returns/code-reviewer-run4.md` once cost a 103-second dispatch investigating a review that
|
|
335
|
+
had in fact succeeded — only its reply was lost. `dispatch_agent` and `spawn_research` accept optional
|
|
336
|
+
`artifacts: string[]` paths (repo-relative or session-artifact-relative); the hub validates that
|
|
337
|
+
they stay inside the repo/session roots and injects only the path plus first heading/one-line
|
|
338
|
+
preview, never file bodies. Document-producing specialists are instructed to write plans, reviews,
|
|
339
|
+
inventories, and reports to the real session path
|
|
340
|
+
`.pi/agent-sessions/artifacts/<kind>/<agentKey>-run<N>.md` when their tools allow it, then report/pass
|
|
341
|
+
the artifact-relative handoff path `artifacts/<kind>/<agentKey>-run<N>.md`, finish with that path plus
|
|
342
|
+
a ≤10-line digest, and still include structured returns when assertions are carried. Repo-root
|
|
343
|
+
`./artifacts/...` files are not session artifacts. Planner's existing PLAN_FILE behavior is preserved;
|
|
344
|
+
the artifact path is an additional handoff channel.
|
|
345
|
+
- **Dispatch scope advisory** — `dispatch_agent` accepts optional `scope: string[]` for writable
|
|
346
|
+
builder-style runs. The orchestrator should derive these globs from the plan task's file list,
|
|
347
|
+
and skip scope for exploratory/reconnaissance work where the right files are not known yet. The
|
|
348
|
+
hub snapshots git status before the writable dispatch, diffs after the whole tool call (including
|
|
349
|
+
auto-research resumes), and reports out-of-scope paths in `details.scopeViolations` plus a ⚠ text
|
|
350
|
+
notice. This is advisory only: the hub never blocks completion, reverts files, or escalates
|
|
351
|
+
automatically. Known limitation: concurrent writable dispatches can only be attributed
|
|
352
|
+
approximately, so overlapping runs are flagged in the notice.
|
|
353
|
+
- **Agent controls** — `/af-zoom` inspects a live agent timeline; `/af-agents-history` replays the run as a
|
|
354
|
+
timeline (orchestrator turns, dispatches, research helpers) with per-agent durations, parallel-run
|
|
355
|
+
markers, and a grand total; kill/restart controls manage running child agents; per-agent `model:`
|
|
356
|
+
fields select models from team config. `/af-agents-kill <name|rN|all>` SIGTERMs a specialist (keeping
|
|
357
|
+
its standing card) or kills a currently running research helper (`all` clears every live helper).
|
|
358
|
+
`/af-agents-restart <name>` re-runs a specialist's last task fresh; research helpers cannot be
|
|
359
|
+
restarted. `/af-zoom <name|rN>` opens a running helper through the Fleet data model. Research spawning
|
|
360
|
+
and follow-up reconnaissance are automated through `spawn_research` and `NEEDS_RESEARCH:`; there are
|
|
361
|
+
no dedicated research lifecycle slash commands.
|
|
362
|
+
Restartable team specialists at or above 70% context render
|
|
363
|
+
their context percentage with a warning marker/color in the Fleet Dashboard, and their next
|
|
364
|
+
`dispatch_agent` result adds a `/af-agents-restart <persona>` hint. Research helpers are not warned,
|
|
365
|
+
and the hub never restarts specialists automatically.
|
|
366
|
+
- **Model switching** — a persona's frontmatter `models:` list declares the models it may switch to
|
|
367
|
+
(the default `model:` is implicitly a candidate). `/af-agent-model <persona>` picks from that list;
|
|
368
|
+
the choice lasts for the session and takes effect on the persona's next dispatch
|
|
369
|
+
(`/af-agents-restart <persona>` applies it immediately). The dot form
|
|
370
|
+
`/af-agent-model <persona>.<role>` switches a delegate sub-role's model instead — its candidates are
|
|
371
|
+
the role's declared default plus the parent persona's own candidate list; the switch is applied
|
|
372
|
+
when the parent is next dispatched (it lands in the serialized delegate config, so nested
|
|
373
|
+
children inherit it). `/af-models [profile]` applies a named profile
|
|
374
|
+
from `.pi/agents/model-profiles.yaml` — a macro over the same declared candidates, validated at
|
|
375
|
+
session start (a profile with any entry outside a persona's candidates is dropped whole, with an
|
|
376
|
+
error). This is the legacy flat format. Version 2 profiles also set all child roles, thinking,
|
|
377
|
+
dispatcher, watchdog/extraction, poll/debate and routing from one selection; they declare their
|
|
378
|
+
own models without project candidate overrides. See [complete model profiles](../../../docs/agent-fleet-setup.md#complete-model-profiles). Those
|
|
379
|
+
declared-candidate commands stay within their lists; Fleet Detail and the session-wide
|
|
380
|
+
substitution target picker intentionally use Pi's currently available registry. When an effective project or session override
|
|
381
|
+
fails with a model/provider error or aborted request before work begins (including local-model
|
|
382
|
+
memory-limit failures), the hub retries once with the model originally declared in the persona
|
|
383
|
+
frontmatter. For **write-capable** runs this is pre-work only: no fallback occurs after text
|
|
384
|
+
output, a tool call, cancellation, timeout, drift stop, or a Pi process-spawn failure, avoiding
|
|
385
|
+
duplicate writes. **Read-only children and research helpers** (tools limited to
|
|
386
|
+
`read,grep,find,ls`) also retry once when the provider fails *mid-run* — re-running a reader
|
|
387
|
+
repeats nothing, and those are exactly the children that exist to protect their parent's context,
|
|
388
|
+
so losing one to a local-endpoint OOM halfway through discards work for no safety gain. A
|
|
389
|
+
terminated run (watchdog, deadline, cancellation) never retries either way: that is a verdict on
|
|
390
|
+
the work, not a provider outage. The failed attempt is removed from the child session before retry. Per project,
|
|
391
|
+
`model.<persona>:` / `models.<persona>:` keys under `## agent-hub` in
|
|
392
|
+
`.ai/agent-fleet-overrides.md` replace a persona's default model / candidate list.
|
|
393
|
+
Research personas (`researcher` / `deep-researcher`, `kind: research`) are switchable the same
|
|
394
|
+
way — `/af-agent-model <persona>` and `/af-agent-model-thinking <persona>` accept them alongside team
|
|
395
|
+
members. Since research helpers are spawned fresh through `spawn_research`, the switch lands on
|
|
396
|
+
their next spawn (there is no running instance to `/af-agents-restart`).
|
|
397
|
+
`/af-agent-models-substitute [<source> <target>]` saves a runtime source → target mapping for
|
|
398
|
+
the current session. With no arguments it opens the same two-step visual picker as `m` in Fleet
|
|
399
|
+
Dashboard: first choose a source from every model configured across persona defaults, candidates,
|
|
400
|
+
fallbacks, and delegate sub-roles; then choose a target from Pi's currently available models. The
|
|
401
|
+
two-argument form performs the same operation directly. The mapping is resolved when work is
|
|
402
|
+
spawned rather than eagerly copied into today's roster, so team members, research personas, and
|
|
403
|
+
delegate sub-roles activated or created later in the session inherit it automatically. Existing
|
|
404
|
+
runs are not interrupted, and all mappings reset at the next `session_start`.
|
|
405
|
+
- **Thinking levels** — each persona's frontmatter `thinking:` sets its pi `--thinking`
|
|
406
|
+
reasoning effort (`off` · `minimal` · `low` · `medium` · `high` · `xhigh`). `/af-agent-model-thinking
|
|
407
|
+
<persona>` switches it among those six levels for the session; like a model switch it takes effect
|
|
408
|
+
on the persona's next dispatch (`/af-agents-restart <persona>` applies it now), and selecting the
|
|
409
|
+
frontmatter default clears the override. The level shows as a short badge after the model
|
|
410
|
+
everywhere a model is rendered — `gpt-5.5 (xh)` in the dashboard (`min`/`low`/`med`/`hi`/`xh`; `off` shows no badge). Per project, a `thinking.<persona>:` key
|
|
411
|
+
under `## agent-hub` in `.ai/agent-fleet-overrides.md` replaces a persona's default level.
|
|
412
|
+
- **Mid-turn delegation (`delegate` tool)** — a persona that declares a `subagents:` map in its
|
|
413
|
+
frontmatter (`role: { model, tools? }` entries, or an indented `model:`/`tools:` block per role)
|
|
414
|
+
gets a real mid-turn `delegate(role, instruction, context?, allow_write?)` tool, injected as an
|
|
415
|
+
extra `-e delegate.ts` extension into its spawned process (the `delegate` tool name is appended to
|
|
416
|
+
its `--tools` allowlist — pi filters extension tools too). Only declared roles are spawnable, on
|
|
417
|
+
their declared models — model choice is configuration, never the child LLM's. Budgets are readable
|
|
418
|
+
refusals: at most 4 delegate children per dispatch, tree-wide, and a per-persona `delegate_depth:`
|
|
419
|
+
budget capped at 1 (the default). Children spawned with remaining depth 0 do not receive the
|
|
420
|
+
`delegate` extension/tool. Write safety: children run read-only (`read,grep,find,ls`) unless a
|
|
421
|
+
SINGLE live child gets `allow_write: true`, which inherits the parent's tools intersected with the
|
|
422
|
+
role's `tools:` cap; if a declared role cap leaves no available tools, delegation is refused.
|
|
423
|
+
Concurrent children are always forced read-only. Children stream timeline events through
|
|
424
|
+
`.pi/agent-sessions/delegations/<persona>/events.jsonl`; the hub tails it and renders nested rows
|
|
425
|
+
under the parent's card (child id, model, tokens, status),
|
|
426
|
+
each openable with `/af-zoom <child-id>`. Each child also writes its full final output to
|
|
427
|
+
`.pi/agent-sessions/delegations/<persona>/results/<childId>.md`; the parent receives only status,
|
|
428
|
+
a required final `DIGEST:` section (≤30 lines with path:line citations), and the result-file path.
|
|
429
|
+
If a child omits `DIGEST:`, the parent gets the first ~30 lines plus a no-DIGEST warning and the
|
|
430
|
+
result path. Spend rolls up: every child row and the parent's subtree
|
|
431
|
+
total show tokens, and a session-wide `Δ delegated` counter sits in the status line.
|
|
432
|
+
`/af-agents-kill` on the parent SIGTERMs its whole process group, so the delegation tree dies with
|
|
433
|
+
it. `context: fork` is accepted but treated as a summary brief in v1. Per project,
|
|
434
|
+
`subagents.<persona>.<role>:` and `delegate-depth.<persona>:` keys under `## agent-hub` in
|
|
435
|
+
`.ai/agent-fleet-overrides.md` replace individual sub-roles / the depth budget. An overridden
|
|
436
|
+
role retains its frontmatter model as a one-shot fallback under the same pre-work-only safety
|
|
437
|
+
rule; delegate cards and results show the model that ultimately ran. Six personas ship with
|
|
438
|
+
declared sub-roles, on a three-tier OpenAI model ladder — `gpt-5.3-codex-spark` for
|
|
439
|
+
recon/grep sweeps, `gpt-5.4` for analysis sweeps, the `gpt-5.5` (or opus) parent reserved for
|
|
440
|
+
synthesis and verdicts:
|
|
441
|
+
- `code-reviewer` — `preflight`+`docs` (spark), `quality`+`perf` (gpt-5.4); its first delegate
|
|
442
|
+
call is always `preflight`, which studies the project rules and the files under review and
|
|
443
|
+
returns a summary that drives the rest of the fan-out. Deep security review is not a
|
|
444
|
+
sub-role — it belongs to the separate `security-auditor` persona, which the reviewer
|
|
445
|
+
recommends dispatching when it spots deeper risk.
|
|
446
|
+
- `planner` — `scout`+`rules` (spark) fan out before the plan is drafted; `risk` (gpt-5.4)
|
|
447
|
+
optionally challenges the draft breakdown.
|
|
448
|
+
- `plan-reviewer` — `feasibility` (gpt-5.4) checks plan claims against the actual codebase;
|
|
449
|
+
`deps` (spark) verifies dependency ordering and file overlap. No preflight — the plan is
|
|
450
|
+
the map.
|
|
451
|
+
- `security-auditor` — solo `recon` (spark) maps the attack surface first, then
|
|
452
|
+
`input-sweep` (gpt-5.4) and `secrets-sweep` (spark) fan out; exploit reasoning stays with
|
|
453
|
+
the parent.
|
|
454
|
+
- `builder` — `recon` (spark) maps call sites before edits; `verifier` (spark, the one
|
|
455
|
+
`allow_write: true` child) runs the test suite after them. Implementation is never
|
|
456
|
+
delegated.
|
|
457
|
+
- `test-engineer` — `coverage-scout`+`conventions` (spark) inventory gaps and test patterns;
|
|
458
|
+
test writing is never delegated.
|
|
459
|
+
- **Default damage-control guardrails** — `just fleet` and `just fleet --no-coms` load the
|
|
460
|
+
`damage-control-continue` harness before `agent-hub`, so dispatcher tool calls are checked against
|
|
461
|
+
`.pi/damage-control-rules.yaml` and a blocked call feeds back instead of aborting the turn. A
|
|
462
|
+
guardrail is also re-loaded into every native specialist, research helper, and nested delegate
|
|
463
|
+
(see [Safety scope](#safety-scope)). Missing safety plumbing refuses child dispatch.
|
|
464
|
+
- **Embedded coms** — the dispatcher is a discoverable peer on the local machine. Multiple
|
|
465
|
+
`agent-hub` (or plain `coms`) sessions on the same box find each other through per-project registry
|
|
466
|
+
files and exchange messages over a unix socket (named pipe on Windows).
|
|
467
|
+
|
|
468
|
+
`/af-zoom <name|rN|child-id>` opens the selected agent's full-screen stream detail. For fleet rows,
|
|
469
|
+
it uses the [Fleet Dashboard detail controls](#fleet-dashboard-and-detail); a directly addressed
|
|
470
|
+
fallback stream keeps the legacy zoom controls. Both overlays size to the terminal.
|
|
471
|
+
|
|
472
|
+
### `/af-agents-history`
|
|
473
|
+
|
|
474
|
+
`/af-agents-history` (or **`h`** while the Fleet Dashboard is open) opens a read-only overlay (same chrome as `/af-zoom`) that replays the session as an
|
|
475
|
+
execution **tree**:
|
|
476
|
+
|
|
477
|
+
- **Orchestrator turns** — each dispatcher turn that actually dispatched something is a depth-0 row
|
|
478
|
+
labelled `(dispatcher)`. Chat-only turns add no rows.
|
|
479
|
+
- **Dispatched specialists and research helpers** nest one level beneath the turn that launched them;
|
|
480
|
+
**delegate sub-sub-agents** nest one level deeper still under the specialist that spawned them — in
|
|
481
|
+
start order at every level.
|
|
482
|
+
- **Parallel runs** — siblings whose run times overlap are marked with a `│→` connector, so a
|
|
483
|
+
concurrent fan-out reads as a visually grouped block.
|
|
484
|
+
- **Real-work durations** — each row shows that node's *own* work: its span **minus the time it spent
|
|
485
|
+
awaiting children**. A dispatcher blocked on six concurrent agents is credited only for the time it
|
|
486
|
+
actually worked between/around the awaits, never for the await itself — so the same wall-clock isn't
|
|
487
|
+
counted twice up the tree. The same subtraction applies to a specialist awaiting its own delegate
|
|
488
|
+
children. Format: plain seconds under a minute (`42sec`), `m:ss` above it (`10:20min` for 620s).
|
|
489
|
+
Running rows tick live (the overlay re-renders once a second) and a new dispatch appears the instant
|
|
490
|
+
it starts.
|
|
491
|
+
- **Footer** shows `Σ real work <total> · <n> runs (agents <a> + dispatchers <d>)` — the real work of
|
|
492
|
+
*everyone*: the dispatched specialists' and research helpers' full runtime (`agents`) plus each
|
|
493
|
+
dispatcher turn's own work (`dispatchers` — its span minus the time it awaited agents **and** the
|
|
494
|
+
human via `ask_user`). Wall-clock is deliberately **not** shown: it would fold in the idle gaps
|
|
495
|
+
while you're away between turns, and `ask_user` waits are subtracted for the same reason.
|
|
496
|
+
|
|
497
|
+
Navigate with `↑/↓`, press `G` to jump back to the live tail, and `Q`/`Esc` to close. The log resets
|
|
498
|
+
on each session start.
|
|
499
|
+
|
|
500
|
+
The default agent view includes a collapsed fleet summary below the editor. When the installed public
|
|
501
|
+
SDK editor contract can be positively verified, an empty focused editor can activate its bounded
|
|
502
|
+
inspection window with the registered `Alt+I` shortcut; the same chord collapses it, and `j`/`k`
|
|
503
|
+
select. Enter opens detail, while `x`/`r` use the same two-press confirmation and ownership checks as
|
|
504
|
+
the dashboard. Plain and Alt arrow keys remain editor input unchanged and exactly once. Existing
|
|
505
|
+
`Alt+M` and `Alt+A` shortcuts continue to open the work-mode picker and Fleet Dashboard exactly once
|
|
506
|
+
from either widget state. Autocomplete, paste, key release,
|
|
507
|
+
non-empty/unfocused editors, modal UI, RPC/print/headless modes, and unsupported custom editors do not
|
|
508
|
+
activate it; unsupported environments retain a noninteractive summary without a key hint. The window
|
|
509
|
+
uses at most `floor(terminal.rows / 3)` rows including chrome, retains completed/error runs for exactly
|
|
510
|
+
10 seconds (or while the same selected run is pinned), and separates active peers from task counts.
|
|
511
|
+
Both fleet surfaces scrub terminal controls and size Unicode by display cells. A confirmed coms kill
|
|
512
|
+
aborts only the local request—the confirmation explicitly notes that the peer pane keeps running.
|
|
513
|
+
The coms pool panel remains at the **bottom of the Fleet Dashboard**.
|
|
514
|
+
|
|
515
|
+
### Work Mode picker
|
|
516
|
+
|
|
517
|
+
Press **`Alt+M`** or run **`/af-work-mode`** to open the work mode picker:
|
|
518
|
+
**operator** (direct tools) or **orchestrator** (delegate-only). Arrow keys move, Enter applies,
|
|
519
|
+
and Esc cancels with no change. Switching to Orchestrator with no agents auto-loads the first valid
|
|
520
|
+
configured team. On macOS, the outer terminal must send Option as Meta or Alt+M will not reach
|
|
521
|
+
the Hub. In Terminal.app, enable **Use Option as Meta key** under **Settings → Profiles → Keyboard**
|
|
522
|
+
for the profile used by the window. If Option+M inserts `µ`, this setting is not enabled. `Command+M`
|
|
523
|
+
is Terminal.app's Minimize shortcut, not a Fleet shortcut. For details, see the
|
|
524
|
+
[macOS terminal note](../../../docs/pi-extensions.md).
|
|
525
|
+
|
|
526
|
+
### Fleet Dashboard and detail
|
|
527
|
+
|
|
528
|
+
Press **`Alt+A`** or run **`/af-agents-list`** to open the full-screen **Fleet Dashboard**. It is a
|
|
529
|
+
live overlay backed by the same fleet source as the compact widget and lists specialists, true nested
|
|
530
|
+
delegates, running research helpers, and coms peers. Dashboard filtering remains independent from the
|
|
531
|
+
widget, and `/af-zoom` continues to use an unfiltered key lookup.
|
|
532
|
+
The bordered **coms** panel is pinned to the bottom of this overlay. The dashboard shows status,
|
|
533
|
+
hierarchy, model, context/tokens, elapsed time, tool count, and recent work; its summary counts
|
|
534
|
+
running/done/failed rows, overlap-aware wall time, and visible token totals. Finished/idle/stale
|
|
535
|
+
rows are hidden by default.
|
|
536
|
+
|
|
537
|
+
- **`↑`/`↓`** or **`j`/`k`** selects a row; **`PgUp`/`PgDn`** pages; **Enter** opens its full-screen
|
|
538
|
+
detail view. **`h`** opens the same history overlay as `/af-agents-history` (Esc/`q` returns to the dashboard).
|
|
539
|
+
- **`f`** starts a name/model/recent-work filter; type the query and press **Enter** to apply it, or
|
|
540
|
+
**Esc** to clear it. **`a`** toggles finished rows.
|
|
541
|
+
- **`x`** requests a kill and **`r`** requests a restart; press the same key again within two seconds
|
|
542
|
+
to confirm. Kill acts on a local running specialist, a coms-backed specialist, or a research helper.
|
|
543
|
+
Confirmed restart terminates a running specialist when necessary, clears its session, and re-dispatches
|
|
544
|
+
its previous task fresh; it is refused for peer/delegate/research rows and rows with no previous task.
|
|
545
|
+
If a research detail view is already open when that helper finishes, it stays as a read-only terminal
|
|
546
|
+
snapshot until Esc; returning to the dashboard shows no completed research row.
|
|
547
|
+
- **`q`** or **Esc** closes the dashboard.
|
|
548
|
+
|
|
549
|
+
The detail view streams the selected local agent's assistant text, provider-emitted thinking, tool
|
|
550
|
+
arguments, and tool results (including success/error and duration). Normal events request an immediate
|
|
551
|
+
render; a 2-second ticker recovers missed file notifications and advances elapsed time. Use **`v`** to
|
|
552
|
+
switch between scan-friendly **Compact** rows and wrapped **Verbose** output. The choice is preserved
|
|
553
|
+
while drilling into other rows in the same open dashboard.
|
|
554
|
+
|
|
555
|
+
Use **`↑`/`↓`**, **`PgUp`/`PgDn`**, and **Home**/**End** to navigate. Manual movement pauses tail-follow;
|
|
556
|
+
**End** restores it. **Enter** expands a selected tool row in Compact mode and **Ctrl+C** copies the
|
|
557
|
+
selected entry. **`m`** replaces the log area with a full-screen picker containing every model currently
|
|
558
|
+
reported by Pi's available-model registry. Use **`↑`/`↓`**, **`PgUp`/`PgDn`**, or **Home**/**End**, then
|
|
559
|
+
**Enter** to apply; **Esc** cancels back to the logs.
|
|
560
|
+
|
|
561
|
+
Each local run also writes an append-only transcript under `.pi/agent-sessions/transcripts/`. The
|
|
562
|
+
directory/file permissions are owner-only (0700/0600 where the platform supports them), large events
|
|
563
|
+
are chunked, and the live in-memory window is bounded. Common authorization headers, API keys, access
|
|
564
|
+
tokens, passwords, provider tokens, and private-key blocks become `[REDACTED]` **before both persistence
|
|
565
|
+
and display**. This is pattern-based protection, so operators should still avoid deliberately printing
|
|
566
|
+
unknown secret formats.
|
|
567
|
+
|
|
568
|
+
“Thinking” means only text explicitly emitted by the provider/runtime; hidden model reasoning is not
|
|
569
|
+
available, and personas with thinking disabled have no thinking rows. Model switching works for local
|
|
570
|
+
specialists, a currently running research helper, and nested delegate roles. It applies on the next dispatch or
|
|
571
|
+
continuation and never interrupts a running child. A coms-backed specialist stores the choice for native
|
|
572
|
+
fallback runs; external coms peers control their own model, have no picker, and have no local transcript.
|
|
573
|
+
**Esc**/**`q`** returns to the dashboard. **`/af-zoom <name|rN>`** opens this same detail view directly.
|
|
574
|
+
|
|
575
|
+
### Version footer
|
|
576
|
+
|
|
577
|
+
`agent-hub` renders its local harness version first in its custom footer:
|
|
578
|
+
`agent fleet v<version> · <model><thinking> · <team>`. It replaces pi's default footer, so it does **not**
|
|
579
|
+
consume or render the shared version status; it reads its own adjacent stamped manifest directly.
|
|
580
|
+
The three persistent-UI harnesses (`agent-hub`, `coms`, and
|
|
581
|
+
`damage-control-continue`) still register that one shared key, which gives default footers one
|
|
582
|
+
version in stacked non-hub sessions. In the supported guardrail-plus-hub stack, the hub's custom
|
|
583
|
+
footer supplies the single visible version. Damage-Control can update its own safety status after
|
|
584
|
+
a violation without overwriting the shared version entry. The canonical source is the
|
|
585
|
+
repository-root `package.json`; the adjacent harness manifest is a synchronized stamp maintained
|
|
586
|
+
by `bin/sync-harness-versions.js`. Its local `version.ts` reader intentionally stays with the
|
|
587
|
+
harness for copied or symlinked installs, but those installs still need the pre-existing full
|
|
588
|
+
`.pi/harnesses/` dependency installation.
|
|
589
|
+
|
|
590
|
+
The `agent fleet` half of the label is an OSC 8 terminal hyperlink to the project homepage —
|
|
591
|
+
clickable in terminals that support hyperlinks, ignored (rendered as plain text) elsewhere, and
|
|
592
|
+
free of footer columns because pi strips OSC sequences before measuring width. It opens the
|
|
593
|
+
repository in a browser, not a TUI panel: pi has no mouse tracking, so a click never reaches the
|
|
594
|
+
harness. `AGENT_FLEET_NO_LINKS=1` restores the plain label on multiplexers that mangle OSC 8
|
|
595
|
+
(GNU screen, tmux before 3.4).
|
|
596
|
+
|
|
597
|
+
### Voice dictation indicator
|
|
598
|
+
|
|
599
|
+
The custom footer renders the optional [`pi-voice-stt`](../../extensions/pi-voice-stt/README.md)
|
|
600
|
+
extension's recording indicator on a line **below the model line** — e.g.
|
|
601
|
+
`● REC 0:01 ⏎ send · esc cancel` while recording, or a `transcribing…` dot. Because agent-hub
|
|
602
|
+
replaces pi's built-in footer (where that indicator normally lives), it reads the extension's
|
|
603
|
+
`setStatus("voice-stt", …)` value via the footer data provider and surfaces it itself. The
|
|
604
|
+
indicator only appears once `pi-voice-stt` is installed and configured; otherwise the footer is
|
|
605
|
+
the single model line. Press **`Alt+S`** to start/stop dictation as in a normal pi session.
|
|
606
|
+
|
|
607
|
+
## Configuration
|
|
608
|
+
|
|
609
|
+
At session start, `agent-hub` reads `.ai/agent-fleet-overrides.md` in the workspace. The
|
|
610
|
+
canonical section name is `## agent-hub` (the legacy `## agent-team` name is still accepted):
|
|
611
|
+
|
|
612
|
+
```markdown
|
|
613
|
+
## agent-hub
|
|
614
|
+
# Replace Bulgarian with any language name.
|
|
615
|
+
language: Bulgarian
|
|
616
|
+
```
|
|
617
|
+
|
|
618
|
+
Omit the section to keep the default `English`. `language` applies to dispatcher replies,
|
|
619
|
+
`ask_user` questions and `context` fields, handoff summaries, and user-facing status text;
|
|
620
|
+
specialist task strings stay in English.
|
|
621
|
+
|
|
622
|
+
The same section can point the team at the project's own rule files and documentation
|
|
623
|
+
entry points:
|
|
624
|
+
|
|
625
|
+
```markdown
|
|
626
|
+
## agent-hub
|
|
627
|
+
rules: docs/rules, .ai/rules
|
|
628
|
+
docs: Docs/AGENTS.md, Docs/architecture/ARCHITECTURE_OVERVIEW.md
|
|
629
|
+
```
|
|
630
|
+
|
|
631
|
+
`rules:` lists repo-relative folders of HOW rules — implementation patterns the work must
|
|
632
|
+
comply with. Resolution is **index-first**: a folder with a top-level `README.md`/`index.md`
|
|
633
|
+
is treated as curated — personas read the index first and follow its loading manifest
|
|
634
|
+
(session bundles, conditional-load lists) instead of bulk-reading the tree; a folder without
|
|
635
|
+
an index is searched **recursively** through all subfolders. When set, every dispatched
|
|
636
|
+
specialist's system prompt gains a "Project rules" block naming the folders and the
|
|
637
|
+
resolution order; the planner and code-reviewer personas additionally validate their subject
|
|
638
|
+
against the relevant rules and pass them on (cited in plan acceptance criteria / handed to
|
|
639
|
+
delegate sub-reviewers).
|
|
640
|
+
|
|
641
|
+
`docs:` lists repo-relative WHAT/WHY documentation entry points — canonical files (e.g. an
|
|
642
|
+
`AGENTS.md`, an architecture overview) or doc folders (personas start from the folder's
|
|
643
|
+
README/index). Docs orient rather than bind: every dispatched specialist **and every research
|
|
644
|
+
helper** gains a "Project docs" block telling it to read the entry points relevant to its
|
|
645
|
+
task and follow their links instead of bulk-reading doc trees. The code-reviewer flags
|
|
646
|
+
changes that alter documented behavior without a doc update; the documenter treats the entry
|
|
647
|
+
points and the trees they link as the documentation it maintains.
|
|
648
|
+
|
|
649
|
+
`research-keep:` is **removed**. An existing key warns at session start and has no effect; delete it.
|
|
650
|
+
Live research helpers disappear from the Fleet Dashboard when they finish. Session/transcript/findings
|
|
651
|
+
files and `/af-agents-history` records remain.
|
|
652
|
+
|
|
653
|
+
### Bounded local-disk searches
|
|
654
|
+
|
|
655
|
+
Every `read`, `grep`, `find`, and `ls` call made by a native research helper or a nested
|
|
656
|
+
`delegate` child has a **parent-side** watchdog. The default is **120 seconds per tool call**;
|
|
657
|
+
it is a per-tool bound, not a whole-run deadline — the whole-run bound is the execution
|
|
658
|
+
mode's per-run deadline below. Configure it in the repository-standard overrides file:
|
|
659
|
+
|
|
660
|
+
```markdown
|
|
661
|
+
## agent-hub
|
|
662
|
+
recon-search-timeout-s: 120 # integer 1..3600
|
|
663
|
+
# recon-search-timeout-s: off # disable this per-tool watchdog
|
|
664
|
+
```
|
|
665
|
+
|
|
666
|
+
Invalid values warn at session start and use 120. Calls are tracked independently by their
|
|
667
|
+
JSONL `toolCallId`; a repeated start/update cannot extend an existing deadline. A timeout returns
|
|
668
|
+
`tool_timeout` with the call metadata, ends the research/delegate lifecycle, sends SIGTERM to the
|
|
669
|
+
child's explicitly owned process group, then SIGKILL after a finite grace period. The parent also
|
|
670
|
+
has a final settlement timer, so it settles rather than waiting indefinitely for `close` or
|
|
671
|
+
inherited pipe drain. If child/process-group death cannot be confirmed after this bounded cleanup,
|
|
672
|
+
the timeout metadata reports `terminationConfirmed: false`: this prevents the parent hanging, but
|
|
673
|
+
may indicate an uninterruptible OS-level process that needs operator attention. This group
|
|
674
|
+
ownership covers descendants even when the pi leader exits first; nested delegates own their groups
|
|
675
|
+
and forward parent cancellation, avoiding detached-orphan processes. Caller
|
|
676
|
+
cancellation follows the same bounded cleanup path but is reported as `cancelled`, not
|
|
677
|
+
`tool_timeout`.
|
|
678
|
+
|
|
679
|
+
### Task-tier budgets
|
|
680
|
+
|
|
681
|
+
The hub runs **per-user-turn budgets enforced in code**, not prose, keyed off the current
|
|
682
|
+
**task tier**. This is the guardrail against runaway orchestration (the observed failure
|
|
683
|
+
mode: 100+ dispatches and 100M+ tokens for one task, most of it re-billed stale specialist
|
|
684
|
+
context).
|
|
685
|
+
|
|
686
|
+
| Budget (per user turn) | trivial | small | feature | project |
|
|
687
|
+
|-----------------------------------|---------|-------|---------|---------|
|
|
688
|
+
| `dispatch_agent` calls | 1 | 2 | 8 | 12 |
|
|
689
|
+
| `spawn_research` calls | 1 | 2 | 4 | 6 |
|
|
690
|
+
| Turn wall clock | 15 min | 15 min| 60 min | 90 min |
|
|
691
|
+
| Per-run deadline (specialist/research/delegate) | 10 min | 10 min | 30 min | 30 min |
|
|
692
|
+
| Specialist session recycled after | 3 runs | 3 runs| 5 runs | 5 runs |
|
|
693
|
+
| Nested delegation | off | off | on | on |
|
|
694
|
+
|
|
695
|
+
When a budget is exhausted, the runtime pauses `dispatch_agent`/`spawn_research` and opens
|
|
696
|
+
one localized Yes/No confirmation through the existing `ask-user-remote` wrapper. If the wrapper
|
|
697
|
+
is unavailable, it uses a local dialog; without either channel it stops. **Yes** renews the budget
|
|
698
|
+
and continues the original operation without another model call. Concurrent refusals share one
|
|
699
|
+
question and one renewal. **No**, cancellation, or confirmation failure latches a task-scoped stop
|
|
700
|
+
and aborts the parent loop. Only the human's `/af-budget-continue` command reopens that question;
|
|
701
|
+
the command itself neither grants budget nor dispatches work. Prose and magic-marker tool calls
|
|
702
|
+
cannot authorize renewal. A normal new user message still opens a fresh turn window, but cannot
|
|
703
|
+
clear a declined confirmation. Time blocked in any `ask_user` question is
|
|
704
|
+
excluded from the turn wall clock, so a slow human answer cannot exhaust the next dispatch.
|
|
705
|
+
Raise the task with `set_task_tier` when the work outgrew the current envelope. Override keys
|
|
706
|
+
in `.ai/agent-fleet-overrides.md` are a **ceiling** (`min` with the tier); `off` stays at the
|
|
707
|
+
tier rather than lifting the cap. A leftover `mode:` key is ignored with a warning.
|
|
708
|
+
|
|
709
|
+
```markdown
|
|
710
|
+
## agent-hub
|
|
711
|
+
max-dispatches-per-turn: 8 # integer ceiling, or off (stays at the tier)
|
|
712
|
+
max-research-per-turn: 4 # integer ceiling, or off (stays at the tier)
|
|
713
|
+
turn-wall-time-s: 3600 # integer ceiling, or off (stays at the tier)
|
|
714
|
+
agent-turn-timeout-s: 1800 # whole-run deadline per spawned run; integer or off
|
|
715
|
+
session-recycle-runs: 5 # recycle a specialist session after N resumed runs; integer or off
|
|
716
|
+
run-history-keep: 10 # previous sessions' artifact archives to retain; integer or off
|
|
717
|
+
```
|
|
718
|
+
|
|
719
|
+
#### Task budget (the bound a turn window cannot provide)
|
|
720
|
+
|
|
721
|
+
A per-message allowance cannot bound a task. In the run this guardrail comes from, every
|
|
722
|
+
steering message opened a fresh window of 8 dispatches and 60 minutes, so no counter ever
|
|
723
|
+
bound: one workspace stayed open **47 hours**, while the same change made in a narrow
|
|
724
|
+
workspace took **13 minutes**.
|
|
725
|
+
|
|
726
|
+
So there is a second envelope, **`TASK_BUDGET_MULTIPLIER` (3) × the turn envelope**, whose
|
|
727
|
+
counters are **not** reset by a user message:
|
|
728
|
+
|
|
729
|
+
| | per turn (`feature`) | per task |
|
|
730
|
+
|---|---|---|
|
|
731
|
+
| `dispatch_agent` | 8 | 24 |
|
|
732
|
+
| `spawn_research` | 4 | 12 |
|
|
733
|
+
| clock | 60 min wall | 180 min **active** |
|
|
734
|
+
|
|
735
|
+
Exhausting it is a **hard stop**: the refusal says so, and another user message does not
|
|
736
|
+
reopen it. The hub asks one localized Yes/No `ask_user` question. **Yes** opens one audited
|
|
737
|
+
continuation tranche and resumes directly; it resets the task dispatch/research counters,
|
|
738
|
+
active-time clock, review allowance, and the current turn budget while preserving the task
|
|
739
|
+
tier, assertion ledger, capability packs, label, blockers, and accumulated progress. **No**
|
|
740
|
+
(or cancellation) stops. Each accepted tranche appends `agent-hub-budget-continuation` with
|
|
741
|
+
bounded prior usage, allowlisted process/session/pane identity, and runtime task/tranche/request
|
|
742
|
+
correlation. A reset invalidates pending answers; late or repeated answers cannot renew another task.
|
|
743
|
+
`/af-poll` and `/af-debate` use the same runtime confirmation gate for task and turn budgets.
|
|
744
|
+
|
|
745
|
+
`set_task_tier` with `new_task: true` remains the lifecycle action for genuinely different work.
|
|
746
|
+
It clears task identity/state as well as counters and appends an `agent-hub-task-reset` audit
|
|
747
|
+
entry. Do not use it merely to continue the same task. The status chip still shows both turn and
|
|
748
|
+
task usage (`… · task 4/18`).
|
|
749
|
+
|
|
750
|
+
The reasoning: three full envelopes still require an explicit human decision, but that decision
|
|
751
|
+
is now a single confirmation rather than a fake new task followed by a second message.
|
|
752
|
+
|
|
753
|
+
Both turn and task clocks charge **active time only** — turns that actually ran, minus the
|
|
754
|
+
time the dispatcher sat blocked on `ask_user`. Inter-turn idle costs nothing, because no turn
|
|
755
|
+
is open across it. Raw wall clock would bill a lunch break, an overnight pause, and every long
|
|
756
|
+
human answer against the task; at `fast` mode's 45-minute envelope a coffee break would
|
|
757
|
+
hard-stop a task with two dispatches spent. A false stop is worse than no stop — it teaches
|
|
758
|
+
people to reset the task window reflexively, and that reset is the one thing that has to
|
|
759
|
+
stay deliberate. Dispatch and research counts remain the honest hard stops.
|
|
760
|
+
|
|
761
|
+
The **auto-research pipe** (specialist emits `NEEDS_RESEARCH`, the hub fans out read-only
|
|
762
|
+
helpers in code) stays exempt from the TURN budget — it is hub mechanics, not a dispatcher
|
|
763
|
+
decision, and it must not steal the dispatcher's slots — but it **is** charged against the
|
|
764
|
+
task envelope. At 2 rounds × 4 questions per dispatch and 18 dispatches per task, leaving it
|
|
765
|
+
uncounted would have put 144 research runs inside the bound that is supposed to be the outer
|
|
766
|
+
one. When the task's research envelope is spent the pipe does not spawn and the specialist is
|
|
767
|
+
not resumed; the dispatch result says so.
|
|
768
|
+
|
|
769
|
+
Two related always-on behaviors: specialist **context pressure is measured over
|
|
770
|
+
input + cacheRead + cacheWrite** (resumed sessions re-send their whole accumulated context
|
|
771
|
+
as cache reads — counting `input` alone hid that entirely), and a specialist session is
|
|
772
|
+
**recycled** (fresh session, no `-c` resume) once it has served `session-recycle-runs` runs
|
|
773
|
+
or its measured context passes 60%. The dispatch result notes the recycle so the dispatcher
|
|
774
|
+
knows the specialist starts without session memory — task text and `artifacts:` paths must
|
|
775
|
+
carry the state, which the deliverable-to-file protocol already ensures.
|
|
776
|
+
|
|
777
|
+
Context is measured against **that agent's own** model window, resolved from pi's model
|
|
778
|
+
registry (`ctx.modelRegistry.find`) with the source recorded on every resolution. Dividing a
|
|
779
|
+
49k local model's usage by the dispatcher's window is what produced unactionable readings
|
|
780
|
+
like `⚠ Planner context at 315%`; a reading above 100% now emits a one-time diagnostic that
|
|
781
|
+
names the window and where the number came from, so a mis-resolved window is distinguishable
|
|
782
|
+
from a genuine overflow. Two recycle rules follow from it: a session at or past a **full**
|
|
783
|
+
window is recycled unconditionally (no threshold override keeps it alive), and a resumed
|
|
784
|
+
session whose *projected* prompt — prior tokens plus this task — would overflow is recycled
|
|
785
|
+
**before** the spawn instead of after the run.
|
|
786
|
+
|
|
787
|
+
#### Per-provider concurrency
|
|
788
|
+
|
|
789
|
+
A dispatch may fan out to four delegate children at once and several specialists can be
|
|
790
|
+
mid-run, with nothing bounding how many requests land on one provider. That is fine against
|
|
791
|
+
a hosted endpoint and not against a local one. Requests are capped per process — **2 in
|
|
792
|
+
flight for `custom/*` and `omlx/*` by default, unlimited elsewhere**:
|
|
793
|
+
|
|
794
|
+
```bash
|
|
795
|
+
AGENT_HUB_PROVIDER_LIMITS="custom=4" # raise the local cap
|
|
796
|
+
AGENT_HUB_PROVIDER_LIMITS="custom=off" # disable it
|
|
797
|
+
AGENT_HUB_PROVIDER_LIMITS="custom=2,ollama=1"
|
|
798
|
+
```
|
|
799
|
+
|
|
800
|
+
Queued runs still execute — they wait for a permit, and the wait is announced rather than
|
|
801
|
+
looking like a hang. The cap applies per **level** of the delegation tree (each pi process
|
|
802
|
+
runs its own semaphore over the children it spawns), and a nested spawn reuses its parent's
|
|
803
|
+
permit, so a child can never wait on its own ancestor. The drift judge and the return
|
|
804
|
+
extractor are deliberately ungated: both run while a specialist holds a permit, so queueing
|
|
805
|
+
them behind it would stall the watchdog meant to stop it.
|
|
806
|
+
|
|
807
|
+
The per-run deadline lands as `turn_timeout` (exit 124) with partial output preserved, for
|
|
808
|
+
dispatched specialists, research helpers, and nested delegate children alike — a hung child
|
|
809
|
+
can no longer hold its parent for hours.
|
|
810
|
+
|
|
811
|
+
### Task triage (complexity tiers)
|
|
812
|
+
|
|
813
|
+
The dispatcher classifies the current TASK with the `set_task_tier` tool BEFORE its first
|
|
814
|
+
dispatch — `trivial` / `small` / `feature` / `project` — and that classification *is* the
|
|
815
|
+
budget envelope (see the table above). The tier shows in the `hub-tier` status chip
|
|
816
|
+
(`Tier: small · …`), with a trailing `?` while it is only assumed.
|
|
817
|
+
|
|
818
|
+
Skipping the call makes the hub assume **`small`**, not `feature`. Because the tier is
|
|
819
|
+
task-scoped, a skipped triage latches for the whole task — and skipped triage is precisely
|
|
820
|
+
the case where the dispatcher was not thinking about proportionality. Assuming `feature`
|
|
821
|
+
there would unlock planner/plan-reviewer/security-auditor, loosen the review caps, and hand
|
|
822
|
+
out the full feature envelope: the over-apparatus failure mode, granted by forgetting a tool
|
|
823
|
+
call. Assuming `small` costs one explicit escalation when the work really is bigger, which
|
|
824
|
+
is the cheap direction to be wrong in. An assumed tier is not a ratchet baseline either: the
|
|
825
|
+
dispatcher's own first `set_task_tier` is treated as an initial declaration, so it never
|
|
826
|
+
needs a `reason` it had no way to know it needed.
|
|
827
|
+
|
|
828
|
+
The tier is **task-scoped and ratcheted**. It survives the user's next message, and it
|
|
829
|
+
moves in one direction cheaply: **lowering it is always free, raising it requires a
|
|
830
|
+
`reason`** naming what the ask turned out to contain (refused in code otherwise). A
|
|
831
|
+
turn-scoped tier could not bind on a steered run — every correction reset it to null, the
|
|
832
|
+
next dispatch re-assumed `feature`, and the effective tier drifted to the ceiling, because
|
|
833
|
+
nobody ever re-declares `trivial` after a steering message.
|
|
834
|
+
|
|
835
|
+
Three guards are enforced in code, not prose:
|
|
836
|
+
|
|
837
|
+
- **Duplicate-dispatch guard** — refuses re-dispatching the same agent with a
|
|
838
|
+
near-identical task inside one turn.
|
|
839
|
+
- **Tier persona gate** — at `trivial`/`small`, `dispatch_agent`/`spawn_research` refuse
|
|
840
|
+
`planner`, `plan-reviewer`, `architect`, `security-auditor` and `deep-researcher`
|
|
841
|
+
(`run-budget.js`). Each opens a document/finding loop whose output then has to be
|
|
842
|
+
executed and re-reviewed; the escape hatch is raising the tier *with a reason*, not a
|
|
843
|
+
flag. The refusal costs no budget slot.
|
|
844
|
+
- **Review round cap** — review dispatches per TASK are capped by tier (trivial/small 1,
|
|
845
|
+
feature 2, project uncapped) and the (N+1)-th is refused without spending a budget slot.
|
|
846
|
+
This is where the review ratchet is actually cut: findings become requirements and the
|
|
847
|
+
enlarged requirement set justifies the next round, so the round is the thing to bound.
|
|
848
|
+
- **Review finding budget** — a review persona's dispatch carries a blocking-finding cap
|
|
849
|
+
tied to the tier (trivial 1, small 2, feature 5, project uncapped) plus the rule that a
|
|
850
|
+
blocking finding may only enforce an invariant the task/plan/rules already state. The hub
|
|
851
|
+
**counts** what came back (`review-findings.js`) and appends a visible notice when the
|
|
852
|
+
return exceeds the cap — it never reclassifies a finding. No rule the hub can evaluate
|
|
853
|
+
distinguishes "invents a manifest nobody asked for" from "this logs a connection string";
|
|
854
|
+
both are a heading and a bullet, and silently demoting the second by position would, on
|
|
855
|
+
the day it matters, move a real security finding into the section nobody acts on.
|
|
856
|
+
|
|
857
|
+
Every budget/gate refusal is counted in `/af-hub-report`.
|
|
858
|
+
|
|
859
|
+
### Docs lane (`docs-lane.js`)
|
|
860
|
+
|
|
861
|
+
A dispatch whose declared `scope` is documentation only — `Docs/**`, `**/*.md`,
|
|
862
|
+
`artifacts/evidence/*.png`, `.changeset/**` — runs in the single-worker docs lane:
|
|
863
|
+
|
|
864
|
+
- dispatching a review persona (`code-reviewer`, `plan-reviewer`, `security-auditor`,
|
|
865
|
+
`test-engineer`) on it is **refused** and costs no budget slot;
|
|
866
|
+
- any other persona's result carries a note telling the dispatcher not to open a review
|
|
867
|
+
gate for it.
|
|
868
|
+
|
|
869
|
+
An absent or empty `scope` is never the lighter lane — unknown is not docs. The refusal is
|
|
870
|
+
overridable per dispatch with `review_reason: "<why>"` for the cases that do warrant a gate
|
|
871
|
+
(the doc publishes a credential, or states a contract other systems depend on).
|
|
872
|
+
|
|
873
|
+
### External-blocker stop (`external-blocker.js`)
|
|
874
|
+
|
|
875
|
+
A specialist that cannot proceed without something outside the fleet's reach — an account,
|
|
876
|
+
a permission, a deployment credential, a telemetry destination, a console-only action —
|
|
877
|
+
emits `EXTERNAL_BLOCKED: <what is missing, who owns it, what it blocks>` (the protocol is
|
|
878
|
+
injected into every specialist prompt). The hub records it and **refuses the next
|
|
879
|
+
dispatch/research** with an owner-escalation packet: what is missing and who owns it, which
|
|
880
|
+
assertions are blocked, what is already proven and where, and the human's options (provide
|
|
881
|
+
access / waive as UNPROVEN / drop from scope).
|
|
882
|
+
|
|
883
|
+
The gate opens when the human has been addressed — an `ask_user` call, or the next user
|
|
884
|
+
message. Without `ask_user` installed it fires exactly once, so a session that cannot reach
|
|
885
|
+
the human can still finish and report instead of deadlocking.
|
|
886
|
+
|
|
887
|
+
This exists because the alternative is the most expensive failure mode observed: with no
|
|
888
|
+
correlation destination available, a run kept substituting internal work for the missing
|
|
889
|
+
external fact — scripts, manifests, fixtures, diagnostic packets — for hours, and the
|
|
890
|
+
assertion still ended UNPROVEN.
|
|
891
|
+
|
|
892
|
+
### Immutable per-run artifact namespaces (`run-namespace.js`)
|
|
893
|
+
|
|
894
|
+
Session start used to `rm -rf` `.pi/agent-sessions/artifacts/`, and specialist returns were
|
|
895
|
+
named by a per-session counter (`returns/builder-run1.md`). Both halves of that failed at
|
|
896
|
+
once: the next session's `builder-run1.md` claimed the same path as the previous one's, and
|
|
897
|
+
the wipe deleted the originals first — a post-mortem had to record eleven implementation
|
|
898
|
+
returns and two review artifacts as NOT RECOVERABLE.
|
|
899
|
+
|
|
900
|
+
Now each session **archives** the previous session's artifacts into
|
|
901
|
+
`.pi/agent-sessions/runs/<runId>/artifacts/` — a namespace written once and never reused —
|
|
902
|
+
alongside a read-only `meta.json` (run id, archive time, project, workspace, per-kind
|
|
903
|
+
artifact counts) and an appended `runs/index.json`. `runId` is a sortable UTC timestamp plus
|
|
904
|
+
a random suffix, so two sessions starting in the same second still get distinct namespaces.
|
|
905
|
+
Retention is `run-history-keep` (default 10, `off` keeps everything); an empty artifact tree
|
|
906
|
+
is not archived. If archiving fails the artifacts are **left in place** rather than deleted:
|
|
907
|
+
a stale tree is recoverable, a deleted one is not.
|
|
908
|
+
|
|
909
|
+
### Drift watchdog (in-flight observation)
|
|
910
|
+
|
|
911
|
+
An armed dispatch is observed **while it runs**, from the same JSON event stream that
|
|
912
|
+
drives the cards — not post-hoc:
|
|
913
|
+
|
|
914
|
+
- **Layer 1 — deterministic rules, zero tokens** (`drift-watchdog.js`): a write/edit
|
|
915
|
+
outside the dispatch's declared `scope` globs, the identical tool call repeated 4×,
|
|
916
|
+
5 consecutive failed tool calls, or 200 total tool calls in one run.
|
|
917
|
+
- **Layer 2 — LLM judge, escalation only**: when a rule fires (single-flight, 90 s
|
|
918
|
+
success cooldown), a one-shot cheap run (default model: the researcher persona's; override with
|
|
919
|
+
`watchdog-judge-model`) reads the original task + declared scope + recent tool trail and
|
|
920
|
+
answers `VERDICT: ON_TRACK|DRIFTING|STUCK`. An unavailable judge has no verdict:
|
|
921
|
+
it is recorded as `judge_unavailable` and, if the attempt and signal remain live,
|
|
922
|
+
is retried once after 5 seconds with new snapshot/LLM-attempt IDs. A second failure
|
|
923
|
+
is exhausted, not a successful 90-second cooldown.
|
|
924
|
+
- **Intervention**: DRIFTING/STUCK terminates the run as **`drift_stop`** (exit 125,
|
|
925
|
+
partial output preserved) and the dispatch result instructs: re-dispatch ONCE with a
|
|
926
|
+
corrected, narrowed task — never the same task unchanged.
|
|
927
|
+
|
|
928
|
+
Enablement is dynamic. In **operator** work mode, precedence is the `watchdog: true|false`
|
|
929
|
+
param on a single `dispatch_agent` call → a per-agent override (`/af-watchdog builder
|
|
930
|
+
on|off|clear`) → the hub-wide setting (`/af-watchdog on|off|auto`, default `auto`, project
|
|
931
|
+
default via the `watchdog:` overrides key): `on`/`auto` arm and `off` disarms. In
|
|
932
|
+
**orchestrator** work mode, hub `auto`/`on` auto-arms; dispatch `watchdog: false` cannot
|
|
933
|
+
disarm it. Opt out with hub `/af-watchdog off` (or override `watchdog: off`), or a per-agent
|
|
934
|
+
`off`. Read-only research helpers are not monitored — they already run under the per-tool
|
|
935
|
+
watchdog + turn deadline and cannot write.
|
|
936
|
+
|
|
937
|
+
### Opt-in System 1 drift observations
|
|
938
|
+
|
|
939
|
+
`watchdog-system1: off|shadow|active` in `## agent-hub` defaults to `off`.
|
|
940
|
+
The separate experimental `system1` feature, valid `.ai/system1.json`, a
|
|
941
|
+
caller-injected key and an armed native watchdog are also needed. `shadow`
|
|
942
|
+
runs System 1 independently of the immediately started LLM judge; it cannot
|
|
943
|
+
stop a specialist. `active` is an **uncalibrated experiment in every installed
|
|
944
|
+
workspace**, requiring explicit `watchdog-system1: active` opt-in; default remains
|
|
945
|
+
off. Only advisory `scope` may bypass LLM on provider `on_track` with confidence
|
|
946
|
+
and on-track distribution ≥0.95 and all three predicate probabilities ≤0.05.
|
|
947
|
+
Terminal `loop`, `failures`, and `toolcap` always go to LLM. `/af-watchdog`
|
|
948
|
+
shows `experimental: scope only; G2 not validated`; an unavailable/mismatched
|
|
949
|
+
provider falls back to LLM. Production approved profiles are still empty.
|
|
950
|
+
This is not G2 approval or a safety guarantee: the experiment can miss a scope
|
|
951
|
+
advisory. This watchdog consumer adds no automatic hook for research, coms or normal Hub
|
|
952
|
+
requests; the separately consented task-triage consumer owns its own Hub input hook.
|
|
953
|
+
|
|
954
|
+
The limited **System 1** state includes reviewed task text, normalized
|
|
955
|
+
relative paths, structured tool kinds/outcomes and counters, not tool
|
|
956
|
+
args/commands/bodies or outputs. The existing parallel **LLM judge** still
|
|
957
|
+
receives the original task, scope and a recent trail containing up to 120
|
|
958
|
+
characters of raw tool arguments per call. Review pilot inputs and expected
|
|
959
|
+
tool arguments; unexpected agent actions remain a residual risk. Even task/path
|
|
960
|
+
names can leak information: the intended future pilot is agent-fleet-only,
|
|
961
|
+
without client data or secrets. The native spawn filters the shared
|
|
962
|
+
key from merged child env, not from files or unrelated launchers. The below-chat
|
|
963
|
+
Fleet strip holds the recent S1 result for 10 s; `/af-agents` Enter shows the
|
|
964
|
+
owner check and safe history. `/af-watchdog` shows current readiness and
|
|
965
|
+
blocking reason; `/af-hub-report` separates checks, evaluations and LLM
|
|
966
|
+
attempts from worker token usage; `/af-audit` exposes safe lifecycle/decision
|
|
967
|
+
metadata. Trace lives at `<sessionDir>/artifacts/watchdog/events.jsonl`; a
|
|
968
|
+
crash or unknown usage is not reported as success or zero. The offline G2
|
|
969
|
+
report requires human labels keyed by session/dispatch/attempt/check,
|
|
970
|
+
`snapshotId` **and** `llmAttemptId`; older five-ID labels cannot qualify.
|
|
971
|
+
No routine chat messages or extra model turns are sent for progress.
|
|
972
|
+
|
|
973
|
+
To roll back, set the consumer to `off` for the **next** Hub session; cancel a
|
|
974
|
+
current run normally if needed. G1 requires outbound state and real UI review
|
|
975
|
+
before any shadow pilot. G2 separately requires human-labelled held-out
|
|
976
|
+
session evidence and explicit maintainer approval for a production policy
|
|
977
|
+
profile. Offline tests and demo/doctor readiness do not grant either gate.
|
|
978
|
+
|
|
979
|
+
### Dynamic teams
|
|
980
|
+
|
|
981
|
+
Rosters start from `.pi/agents/teams.yaml` but are not frozen there:
|
|
982
|
+
|
|
983
|
+
- `/af-agents-add <persona>…` / `/af-agents-drop <persona>…` — restructure the ACTIVE team
|
|
984
|
+
live (drop refuses running or last members; session files are kept for re-adding).
|
|
985
|
+
- `/af-agents-save <name>` — persist the current roster as a named team back into
|
|
986
|
+
`teams.yaml` (targeted block upsert; comments and other teams untouched).
|
|
987
|
+
- `team_adjust` — the dispatcher itself may add/drop a persona **with a stated reason**;
|
|
988
|
+
disabled at trivial/small tiers, capped at 8 roster members, and every change is notified to the
|
|
989
|
+
human. The system prompt is rebuilt each turn, so changes take effect immediately.
|
|
990
|
+
|
|
991
|
+
### `/af-hub-report`
|
|
992
|
+
|
|
993
|
+
Per-turn cost accounting: dispatches (agent, status, elapsed, billed/output tokens),
|
|
994
|
+
research runs, session recycles, drift stops, and budget/duplicate refusals — for the
|
|
995
|
+
current turn, the last completed turn, and session totals. Billed tokens count
|
|
996
|
+
input + cacheRead + cacheWrite, the same measure the recycler uses. System 1
|
|
997
|
+
usage is reported separately; unavailable metadata remains unknown.
|
|
998
|
+
|
|
999
|
+
Paths that don't exist produce a session-start warning, never an error. The full key list for
|
|
1000
|
+
`## agent-hub` (models, sub-roles, depth budgets, persona gate, research retention, watchdog,
|
|
1001
|
+
mode/budget keys) is documented in `docs/agent-fleet-setup.md`.
|
|
1002
|
+
|
|
1003
|
+
## The coms layer
|
|
1004
|
+
|
|
1005
|
+
> The runtime coordination protocols this layer implements (sentinels, push over
|
|
1006
|
+
> polling, barriers, fan-out digests, racing) are catalogued in
|
|
1007
|
+
> [references/fleet-coordination-patterns.md](../../../references/fleet-coordination-patterns.md).
|
|
1008
|
+
|
|
1009
|
+
### Fleet tools (herdr)
|
|
1010
|
+
|
|
1011
|
+
Inside a [herdr](https://herdr.dev) pane with a live server, the dispatcher's tool
|
|
1012
|
+
surface additionally gets (absent otherwise, like coms):
|
|
1013
|
+
|
|
1014
|
+
- `herdr_spawn_peer` — stand up a constrained Fleet peer through the shared peer-launch resolver.
|
|
1015
|
+
The peer joins **this session's `--project` pool** (the model cannot override it), and a name
|
|
1016
|
+
declared in `.pi/agents/peers.yaml` keeps its declared `runner:`/`extensions:`/`env_file:`,
|
|
1017
|
+
including `runner: claude-code`; undeclared explicit shapes may select a Pi persona, identity-only
|
|
1018
|
+
Fleet Core peer, or Claude Code. Manifest-declared env is the only env admitted. The peer gets a
|
|
1019
|
+
sibling pane in the current workspace/tab, not a second process in the Hub pane. A spawn by name
|
|
1020
|
+
therefore produces the same declared agent as a preset launch. A persona peer **boots idle**
|
|
1021
|
+
and does nothing until a `coms_send` reaches it, so the call waits (bounded, ~45s) for it to
|
|
1022
|
+
register and returns `peer_ready` plus its coms name instead of a bare pane id; on failure it
|
|
1023
|
+
returns the pane's last output, which means the peer did not start rather than that it is slow.
|
|
1024
|
+
Peers spawned but never addressed are named at turn end and in `/af-hub-report` with a close
|
|
1025
|
+
suggestion — closing stays the human's call.
|
|
1026
|
+
Mechanism: herdr's `pane.split` takes **no command** — it opens a shell — so the spawn splits,
|
|
1027
|
+
waits for the pane's prompt, and types the argv (text and Enter sent separately, because bash
|
|
1028
|
+
bracketed paste would swallow a newline). Only `layout.apply` pane nodes carry an argv, which is
|
|
1029
|
+
why declarative preset layouts were never affected by this.
|
|
1030
|
+
- `herdr_spawn_pane` — create an arbitrary command pane when a constrained/addressable Fleet peer
|
|
1031
|
+
is not the desired shape; raw commands are intentionally excluded from `herdr_spawn_peer`.
|
|
1032
|
+
Orchestrators may use this for auxiliary processes such as watchers or servers, never to bypass
|
|
1033
|
+
delegate-only implementation policy.
|
|
1034
|
+
- `herdr_read_pane` — bounded `pane.read` (≤200 lines), read-to-decide on workers/tools;
|
|
1035
|
+
messaging still goes through coms, and peer busy state comes from `coms_list`, not from
|
|
1036
|
+
reading the screen
|
|
1037
|
+
- `herdr_close_pane` — kills a pane; **asks the human to confirm every call**; the
|
|
1038
|
+
bash-level `herdr pane close`/`workspace close`/`server stop` verbs are hard-blocked
|
|
1039
|
+
for spawned specialists by `.pi/damage-control-rules.yaml`
|
|
1040
|
+
- `herdr_notify` — desktop notification to reach the human when they are away
|
|
1041
|
+
|
|
1042
|
+
This closes the fleet loop: spawn a worker, watch it, notify the human, tear it down —
|
|
1043
|
+
without leaving the session. Claude Code panes join the same pool via the
|
|
1044
|
+
[coms bridge](../../../docs/claude-code-coms-bridge.md).
|
|
1045
|
+
|
|
1046
|
+
### Presence backend (herdr or files)
|
|
1047
|
+
|
|
1048
|
+
Presence is pluggable, exactly as in the standalone [coms harness](../coms/README.md#presence-backends-herdr-vs-files):
|
|
1049
|
+
inside a [herdr](https://herdr.dev) pane with a live server, the ping cycle is replaced by
|
|
1050
|
+
push events (`agent.list` + `events.subscribe`) and the hub reports itself into the herdr
|
|
1051
|
+
sidebar (`custom_status` = `<name> <pct>% q<depth>`); everywhere else the original 10s
|
|
1052
|
+
ping loop runs unchanged. The file registry is written in both backends, and the
|
|
1053
|
+
pool-scope boundary is enforced identically.
|
|
1054
|
+
|
|
1055
|
+
### Identity
|
|
1056
|
+
|
|
1057
|
+
Each session registers a coms identity at start-up, resolved in this precedence order:
|
|
1058
|
+
|
|
1059
|
+
1. **CLI flags** — `--name`, `--purpose`, `--project`, `--color`, `--explicit`
|
|
1060
|
+
2. **Defaults** — auto-generated name `hub-<id>`, purpose `agent-hub dispatcher`, project
|
|
1061
|
+
`default`, a deterministic color derived from the session id
|
|
1062
|
+
|
|
1063
|
+
Names are de-duplicated per project (`resolveUniqueName`), so two hubs that both want `architect`
|
|
1064
|
+
become `architect` and `architect-2`. `--explicit` marks a **private** peer — kept out of every
|
|
1065
|
+
pool by default, so it is neither listed nor reachable until a human opts in with `/af-coms --all`
|
|
1066
|
+
(see [Pool scope is the reach boundary](#pool-scope-is-the-reach-boundary)). The registry lives
|
|
1067
|
+
under `~/.pi/coms/projects/<project>/agents/<name>.json` and is created at runtime.
|
|
1068
|
+
|
|
1069
|
+
### Commands & tools (local dispatcher plus coms)
|
|
1070
|
+
|
|
1071
|
+
- `/af-coms` — coms control surface (peer list / status)
|
|
1072
|
+
- `/af-handoff <peer>` — hand the whole session off to a coms peer (see [Handoff](#handoff))
|
|
1073
|
+
- `/af-poll [--panel NAME] [--persona NAME] <question>` — ask every voice in a named model panel (from `.pi/agents/voices.yaml`) the same question. `--panel` wins; else `poll-panel:` in `## agent-hub`; else a refusal listing available panels. Counts as **one** turn-budget dispatch. The main loop gets an immediate `POLL STARTED` receipt (no dispatcher turn), then one `POLL VOICE` line per finished voice, then the digest. Full opinions stay on disk under `.pi/agent-sessions/artifacts/polls/<runId>/`.
|
|
1074
|
+
- `/af-debate [--panel NAME] [--persona NAME] [--rounds N] <question>` — same panel, 2–5 harness-mediated rounds (default 3). Each surviving voice sees the labeled positions of the others from the previous round. There is no judge and no hidden merge. Counts as **one** turn-budget dispatch. Per-round files land under `.pi/agent-sessions/artifacts/polls/<runId>/debate/round-<n>/`.
|
|
1075
|
+
- `/af-compound [focus]` — end-of-session **compound-learning pass**: the dispatcher composes a
|
|
1076
|
+
candidate-lessons brief from the session (corrections, recurring findings, root causes),
|
|
1077
|
+
confirms it with the user, then dispatches the `documenter` to land the approved lessons as
|
|
1078
|
+
minimal diffs on the project's `rules:`/`docs:` targets per `skills/compound-learning/SKILL.md`.
|
|
1079
|
+
Requires the `documenter` persona in the active team; run it before `/af-handoff` or session end.
|
|
1080
|
+
- `coms_list` — discover the peers in your pool: names, models, live context usage, purpose,
|
|
1081
|
+
`pane_id`, and `status` (`idle` | `working` | `booting`). Check status before sending: `working`
|
|
1082
|
+
means your send waits behind the peer's current turn, `booting` means it is not addressable yet.
|
|
1083
|
+
This is the field whose absence drove 127 `herdr_read_pane` calls in one session. Scoped
|
|
1084
|
+
to your project and excluding private peers; the LLM cannot widen it (see
|
|
1085
|
+
[Pool scope is the reach boundary](#pool-scope-is-the-reach-boundary)).
|
|
1086
|
+
- `coms_send` — send a prompt to a peer **in your pool**; returns a `msg_id`
|
|
1087
|
+
- `coms_await` — **block** until that `msg_id`'s reply lands (default 30 min,
|
|
1088
|
+
`PI_COMS_TIMEOUT_MS`)
|
|
1089
|
+
- `coms_get` — **non-blocking** poll of a `msg_id` (status `pending|complete|error`)
|
|
1090
|
+
|
|
1091
|
+
`/af-coms` and `/af-handoff` tab-complete live peer names **in your pool**.
|
|
1092
|
+
|
|
1093
|
+
### Pool scope is the reach boundary
|
|
1094
|
+
|
|
1095
|
+
The set of peers shown in the pool widget is the security boundary: **a peer is reachable only if it
|
|
1096
|
+
is in your pool.** `coms_list`, `coms_send`, and `/af-handoff` all resolve targets through the same
|
|
1097
|
+
`peersInScope()` helper, so the dispatcher can never message a peer it cannot see. Two knobs define
|
|
1098
|
+
the pool, and **both are human-only** — the LLM cannot widen scope to reach more peers:
|
|
1099
|
+
|
|
1100
|
+
- **Project** — defaults to your own `identity.project`. A human can retarget with `/af-coms --project
|
|
1101
|
+
<name>` (one project) or `/af-coms --all` (every project). `coms_list`'s own parameters cannot
|
|
1102
|
+
override this; an LLM request for a wider project is clamped back to the current pool and flagged.
|
|
1103
|
+
- **Explicit (private) peers** — excluded from every pool by default. `/af-coms --all` opts them in.
|
|
1104
|
+
|
|
1105
|
+
This closes a cross-project leak where a peer reachable through the mesh was *not* shown in the
|
|
1106
|
+
default project-scoped pool — so it could be messaged without being "connected." Now the reachable
|
|
1107
|
+
set is always a subset of what the widget shows. To reach a peer outside the pool, a human widens
|
|
1108
|
+
scope first; the dispatcher is told to **ask** rather than attempt it, and not to pass cross-project
|
|
1109
|
+
context to a peer the human has not approved.
|
|
1110
|
+
|
|
1111
|
+
### Peer as subagent
|
|
1112
|
+
|
|
1113
|
+
The dispatcher uses a peer as a subagent by pairing the tools: `coms_send(target, prompt)` to
|
|
1114
|
+
issue the task, then `coms_await(msg_id)` to block for the reply (or `coms_get` to poll). This sits
|
|
1115
|
+
alongside `dispatch_agent` — local persona specialists are dispatched as subprocesses; remote peers
|
|
1116
|
+
are reached over coms. The two paths stay explicit for the LLM, but
|
|
1117
|
+
[coms-backed dispatch](#coms-backed-dispatch-dispatch-policyyaml) can route a `dispatch_agent` call
|
|
1118
|
+
to a same-name peer under the hood. (The specialist-level `delegate` tool is a third,
|
|
1119
|
+
nested path: a dispatched specialist spawning its own declared sub-agents — it does not auto-route
|
|
1120
|
+
between local and remote either.) Multi-hop is inherited from coms: a peer handling a dispatched task can `coms_send`
|
|
1121
|
+
onward, hops accumulating up to `MAX_HOPS` (5).
|
|
1122
|
+
|
|
1123
|
+
### Coms-backed dispatch (dispatch-policy.yaml)
|
|
1124
|
+
|
|
1125
|
+
`just fleet --agents <roster> --peers <preset>` boots the Hub next to standing peers from
|
|
1126
|
+
`.pi/agents/peers.yaml` — and some
|
|
1127
|
+
of them (e.g. `code-reviewer`, `plan-reviewer` with `runner: claude-code`) intentionally share a name
|
|
1128
|
+
with a team member. `.pi/agents/dispatch-policy.yaml` tells the dispatcher to serve such members
|
|
1129
|
+
**through the peer** instead of spawning a native subagent:
|
|
1130
|
+
|
|
1131
|
+
```yaml
|
|
1132
|
+
default: native # coms = substitute ANY member with a live same-name pool peer
|
|
1133
|
+
grace_s: 30 # poll window for coms-required members
|
|
1134
|
+
substitutions:
|
|
1135
|
+
code-reviewer:
|
|
1136
|
+
prefer: coms
|
|
1137
|
+
fallback: native # none = coms-required: refuse with guidance instead of spawning
|
|
1138
|
+
# timeout_s: 3600 # per-member reply timeout (default PI_COMS_TIMEOUT_MS, 30 min)
|
|
1139
|
+
```
|
|
1140
|
+
|
|
1141
|
+
Semantics:
|
|
1142
|
+
|
|
1143
|
+
- **One API with an explicit override.** `dispatch_agent(..., backend: "auto"|"native"|"coms")`
|
|
1144
|
+
defaults to `auto`, which follows this policy. `native` always starts the local Pi specialist even
|
|
1145
|
+
when a same-name peer is live. `coms` requires that live same-name peer and never falls back to
|
|
1146
|
+
native. The whole downstream pipeline — structured return contract,
|
|
1147
|
+
`ASK_USER:` extraction, the NEEDS_RESEARCH auto-research pipe, assertions, history, the grid —
|
|
1148
|
+
consumes a coms reply exactly like a subagent's final output (the dispatch protocols ride in the
|
|
1149
|
+
message body, since a standing peer only receives a user prompt).
|
|
1150
|
+
- **Decided per dispatch, against the live pool.** Hub and peers boot in parallel, so the first
|
|
1151
|
+
dispatch may land before the peer registers: with `fallback: native` it runs natively (one notice
|
|
1152
|
+
per member per team activation), and later dispatches pick up the peer once it is live. With
|
|
1153
|
+
`fallback: none` the dispatch polls the pool for `grace_s` seconds, then refuses with remediation
|
|
1154
|
+
steps. The name match is scoped to the coms pool — the same security boundary as `coms_send`.
|
|
1155
|
+
- **Standing context is the point.** Re-dispatches (ASK_USER answers, research resumes) go back to
|
|
1156
|
+
the same peer session, so a Claude Code reviewer keeps its review context across rounds.
|
|
1157
|
+
- **Visibility.** The member's grid card shows a `⇄coms <peer-model>` badge, history entries are
|
|
1158
|
+
annotated `(coms)`, and `/af-dispatch-policy` prints the resolved routing per member with live-peer
|
|
1159
|
+
status.
|
|
1160
|
+
- **Limitations.** `/af-agents-kill` on a coms-backed run only abandons the wait — the peer keeps
|
|
1161
|
+
running in its own pane and cannot be killed from the hub (`/af-agents-restart` abandons, then
|
|
1162
|
+
re-dispatches). `/af-zoom` shows only the final reply (there is no stream), tool counts stay 0, and
|
|
1163
|
+
context% is a registry snapshot. `/af-agent-model` overrides apply only to native(-fallback) runs —
|
|
1164
|
+
the peer's model is set in `peers.yaml`.
|
|
1165
|
+
|
|
1166
|
+
Missing file = everything native. HOW a peer runs (persona, model, `runner: claude-code`, env) stays
|
|
1167
|
+
in `peers.yaml`; this file only decides WHEN the hub prefers a peer over a native spawn.
|
|
1168
|
+
|
|
1169
|
+
### Handoff
|
|
1170
|
+
|
|
1171
|
+
`/af-handoff <peer>` transfers the session to another **main** agent. Following the plan's
|
|
1172
|
+
**decision G1**, it does *not* try to extract a compaction summary; instead it asks the dispatcher
|
|
1173
|
+
LLM to compose a **self-contained brief** ("everything the target needs, assume no shared history"),
|
|
1174
|
+
then `coms_send`s that brief to the peer, `coms_await`s the reply, and relays it back — in the
|
|
1175
|
+
configured user-facing language. When the handoff `coms_send` fires, the hub appends machine-generated
|
|
1176
|
+
sections after the LLM brief: `## Verification ledger (verbatim, machine-appended)` with every current
|
|
1177
|
+
assertion in canonical ledger form, and `## Artifact index` with artifact paths plus first headings.
|
|
1178
|
+
The target peer must treat the machine-appended ledger as the contract, not the paraphrased brief.
|
|
1179
|
+
The target peer takes over; the source relays the result. There is no raw session copy (pi sessions
|
|
1180
|
+
aren't portable between live agents). The target must be a peer in your pool — `/af-handoff` resolves
|
|
1181
|
+
through the same [scope boundary](#pool-scope-is-the-reach-boundary) as `coms_send`, so you cannot
|
|
1182
|
+
hand a session to a peer you cannot see.
|
|
1183
|
+
|
|
1184
|
+
### Pool widget
|
|
1185
|
+
|
|
1186
|
+
A live "pool" widget lists connected peers with name, model, and live context usage, refreshed by a
|
|
1187
|
+
ping cycle; a keepalive cycle re-writes this session's own registry entry (and self-heals it if an
|
|
1188
|
+
external prune removed it). Both timers are `unref`'d so they never hold the process open.
|
|
1189
|
+
|
|
1190
|
+
### Purpose
|
|
1191
|
+
|
|
1192
|
+
The coms identity `purpose` is the `--purpose` CLI flag when set, otherwise the default
|
|
1193
|
+
`agent-hub dispatcher`. There is no runtime dispatcher-persona picker.
|
|
1194
|
+
|
|
1195
|
+
### Graceful degradation
|
|
1196
|
+
|
|
1197
|
+
If the coms socket can't bind at start-up (`comsReady` stays `false`), the session degrades to a
|
|
1198
|
+
local dispatcher without coms: the `coms_*` tools are withheld from `setActiveTools`, the
|
|
1199
|
+
`/af-handoff` command refuses with a notice, and the "Peer agents (coms)" prompt section is omitted.
|
|
1200
|
+
Orchestration, research helpers, and the grid keep working.
|
|
1201
|
+
|
|
1202
|
+
### Tool surface
|
|
1203
|
+
|
|
1204
|
+
`setActiveTools` always preserves the orchestration surface and adds runtime-ready capabilities.
|
|
1205
|
+
Operator work mode also preserves the baseline direct/extension tools; orchestrator work mode does not.
|
|
1206
|
+
Coms tools are active only when coms is ready, Herdr tools only in a live Herdr pane, and `ask_user`
|
|
1207
|
+
only when registered. Work mode switching recomputes this list live without touching session state.
|
|
1208
|
+
|
|
1209
|
+
`set_assertions` / `update_assertion` / `get_assertions` are the always-on Verification Contract ledger tools (see
|
|
1210
|
+
[What it does](#what-it-does)); like `dispatch_agent` / `spawn_research` they stay on the
|
|
1211
|
+
orchestration surface in both work modes.
|
|
1212
|
+
|
|
1213
|
+
## Optional Hermes local monitor transport
|
|
1214
|
+
|
|
1215
|
+
The optional monitor is an Agent Fleet-owned transport boundary, not a Hermes runtime API or a
|
|
1216
|
+
bundled Hermes plugin. When enabled, `agent-hub` publishes dispatcher-turn and specialist-run
|
|
1217
|
+
state and owns generation-safe cancellation. A separate local Hermes UI or operator client may
|
|
1218
|
+
consume the owner-only discovery + Unix-socket contract documented in
|
|
1219
|
+
[`.pi/agent-fleet/hermes/README.md`](../../agent-fleet/hermes/README.md#local-agent-hub-monitor-integration).
|
|
1220
|
+
|
|
1221
|
+
Set these before the hub starts:
|
|
1222
|
+
|
|
1223
|
+
```bash
|
|
1224
|
+
export AGENT_FLEET_PROFILE_ID="approved-profile-id"
|
|
1225
|
+
export AGENT_FLEET_MONITOR_RUNTIME_DIR="/absolute/owner-only/runtime-root"
|
|
1226
|
+
```
|
|
1227
|
+
|
|
1228
|
+
Both are required for monitor startup; the runtime root must be absolute and owner-only, and the
|
|
1229
|
+
profile ID must be a safe identifier. The monitor also starts only for a Herdr-backed hub with
|
|
1230
|
+
`HERDR_WORKSPACE_ID` and `HERDR_PANE_ID`; retain those values and `HERDR_SOCKET_PATH` in the
|
|
1231
|
+
standard `just fleet --agents <roster> --peers <preset>` flow. Workspace labels are display metadata, not monitor identity.
|
|
1232
|
+
|
|
1233
|
+
The live contract exposes three authenticated newline-delimited JSON requests: `snapshot`, cursor-
|
|
1234
|
+
based `output`, and exact-generation `cancel`. The monitor is local-only and fails closed when its
|
|
1235
|
+
profile discovery, lease, token, or Unix socket is unavailable. A native cancel targets only the
|
|
1236
|
+
matching hub-owned process generation. A coms cancel abandons the local wait only; its peer can
|
|
1237
|
+
continue. Neither path controls or closes a Herdr workspace/pane.
|
|
1238
|
+
|
|
1239
|
+
Example startup:
|
|
1240
|
+
|
|
1241
|
+
```bash
|
|
1242
|
+
monitor_runtime="${XDG_RUNTIME_DIR:?}/agent-fleet-monitor"
|
|
1243
|
+
install -d -m 700 "$monitor_runtime"
|
|
1244
|
+
AGENT_FLEET_PROFILE_ID=dev \
|
|
1245
|
+
AGENT_FLEET_MONITOR_RUNTIME_DIR="$monitor_runtime" \
|
|
1246
|
+
just fleet --agents default --peers default
|
|
1247
|
+
```
|
|
1248
|
+
|
|
1249
|
+
No Desktop/backend plugin installation is required or provided. Consumers must re-discover after
|
|
1250
|
+
lease or socket loss and must never persist or log the token.
|
|
1251
|
+
|
|
1252
|
+
## Requires
|
|
1253
|
+
|
|
1254
|
+
- `.pi/agents/teams.yaml` for fixed specialist teams, the referenced persona `.md` files, and
|
|
1255
|
+
(strongly recommended) [`pi-ask-user`](https://github.com/edlsh/pi-ask-user).
|
|
1256
|
+
- `.pi/damage-control-rules.yaml` for every guarded `just fleet` Pi mode.
|
|
1257
|
+
- Nothing extra in-repo for coms — the peer registry lives at `~/.pi/coms/` and is created at
|
|
1258
|
+
runtime.
|
|
1259
|
+
|
|
1260
|
+
## Usage
|
|
1261
|
+
|
|
1262
|
+
```bash
|
|
1263
|
+
# Unified Fleet interface (Fleet Core + Agent Hub are loaded together)
|
|
1264
|
+
just fleet
|
|
1265
|
+
just fleet --work-mode operator --agents frontend --project myrepo
|
|
1266
|
+
just fleet --agents frontend --peers frontend --project myrepo
|
|
1267
|
+
|
|
1268
|
+
# equivalent direct guarded launch
|
|
1269
|
+
pi -e .pi/harnesses/damage-control-continue/index.ts -e .pi/harnesses/ask-user-remote/index.ts -e .pi/harnesses/agent-hub/index.ts
|
|
1270
|
+
pi -e .pi/harnesses/damage-control-continue/index.ts -e .pi/harnesses/ask-user-remote/index.ts -e .pi/harnesses/agent-hub/index.ts --name releaser --explicit
|
|
1271
|
+
|
|
1272
|
+
# direct unguarded launch, only when you intentionally want to skip damage-control
|
|
1273
|
+
pi -e .pi/harnesses/agent-hub/index.ts
|
|
1274
|
+
```
|
|
1275
|
+
|
|
1276
|
+
Identity flags: `--name`, `--purpose`, `--project`, `--color`, `--explicit`.
|
|
1277
|
+
|
|
1278
|
+
### Safety scope
|
|
1279
|
+
|
|
1280
|
+
`just fleet` and `just fleet --no-coms` load Fleet Core before `agent-hub`, so guardrails and `ask_user` apply
|
|
1281
|
+
to hub/dispatcher tool calls in that parent pi process — and because it is the *continue* variant, a
|
|
1282
|
+
blocked dispatcher call feeds back and the turn keeps going rather than aborting. Specialist and
|
|
1283
|
+
research agents are spawned as separate pi subprocesses with `--no-extensions` — but `agent-hub`
|
|
1284
|
+
resolves `damage-control-continue` from this session's `-e` flags, else the repo-local harness, and
|
|
1285
|
+
re-loads it into every native specialist, research helper, and nested delegate via explicit `-e`.
|
|
1286
|
+
`--no-extensions` keeps discovery off, so children never auto-load `.pi/extensions/` utilities or
|
|
1287
|
+
recursively re-load `agent-hub`; the explicit guardrail still checks every child's tool calls against
|
|
1288
|
+
`.pi/damage-control-rules.yaml`. Protected-path blocks escalate to the hub for explicit approval;
|
|
1289
|
+
protected deletions offer only Deny or Allow once, while inherently dangerous command patterns are
|
|
1290
|
+
non-exemptible. Denial or timeout blocks the call without aborting the child's turn. If continue
|
|
1291
|
+
cannot be resolved, dispatch is refused—children are never spawned unguarded. Research helpers are
|
|
1292
|
+
additionally read-only by construction. Guided setup enforces `agent-hub` ⇒
|
|
1293
|
+
`damage-control-continue` + `ask-user-remote`.
|
|
1294
|
+
|
|
1295
|
+
### Related recipes
|
|
1296
|
+
|
|
1297
|
+
```bash
|
|
1298
|
+
# Operator/native work without coms
|
|
1299
|
+
just fleet --no-coms
|
|
1300
|
+
|
|
1301
|
+
# Hub-only Herdr workspace and a combined topology
|
|
1302
|
+
just fleet --herdr --project af
|
|
1303
|
+
just fleet --agents default --peers docs --project af
|
|
1304
|
+
just fleet --agents default --peers docs --project af --dry-run
|
|
1305
|
+
|
|
1306
|
+
# Compatibility aliases (accepted with migration warnings)
|
|
1307
|
+
just fleet hub --solo
|
|
1308
|
+
just fleet team docs
|
|
1309
|
+
|
|
1310
|
+
# Snapshot refs / close cleanly / restore conversations
|
|
1311
|
+
just fleet snapshot docs
|
|
1312
|
+
just fleet down docs
|
|
1313
|
+
just fleet resume docs
|
|
1314
|
+
```
|
|
1315
|
+
|
|
1316
|
+
`peers.yaml` groups reusable peers into named teams; each entry is `name` / `persona`
|
|
1317
|
+
(+ optional `model`). The persona's frontmatter `description`/`color` become the peer's
|
|
1318
|
+
coms purpose/color.
|
|
1319
|
+
|
|
1320
|
+
## How it differs from its sources
|
|
1321
|
+
|
|
1322
|
+
- **Embedded, not stacked (decision 1).** coms is folded into this one `index.ts`; the identity
|
|
1323
|
+
flags are registered once. Loading `coms` as a second `-e` would double-register
|
|
1324
|
+
`--name/--purpose/...` and abort start-up.
|
|
1325
|
+
- **Single `session_start`.** coms init is folded into the former dispatcher's `session_start` and
|
|
1326
|
+
guarded by `if (!comsReady)`, so `/new` reuses the same peer identity (no leaked socket).
|
|
1327
|
+
- **Dispatcher is also a peer.** `setActiveTools` lists `coms_*` alongside `dispatch_agent` +
|
|
1328
|
+
`spawn_research` (+ `ask_user`); the system prompt gains a "Peer agents (coms)" section when coms
|
|
1329
|
+
is ready. The persona's `description` drives the coms `purpose` (decision 6 / Phase 6 peer
|
|
1330
|
+
mapping) instead of a static `--purpose`.
|
|
1331
|
+
- **`/af-handoff` uses an LLM-composed brief**, not a compaction-summary extraction (decision G1).
|
|
1332
|
+
- **Clean shutdown** SIGTERMs any running specialist/research children, clears the coms pool
|
|
1333
|
+
widget, and removes the registry entry on `session_shutdown` / SIGINT / SIGTERM.
|
|
1334
|
+
|
|
1335
|
+
### Execution evidence isolation
|
|
1336
|
+
|
|
1337
|
+
New sessions allocate `.pi/agent-sessions/sessions/<UUID>/`; startup does not migrate,
|
|
1338
|
+
clear or prune legacy shared files. Each native/coms dispatch and research helper has
|
|
1339
|
+
a UUID and a create-exclusive `dispatches/<UUID>/request.json` / `result.json` bundle.
|
|
1340
|
+
Requests retain task/scope and copies of supplied input artifacts; results preserve
|
|
1341
|
+
output/diagnostics and transcript/session paths (`details.evidencePath`). Native
|
|
1342
|
+
continuation copies the previous raw session into the new dispatch, never rewrites it;
|
|
1343
|
+
delegation events also live under the dispatch. Counters remain UI labels, not evidence IDs.
|
|
1344
|
+
|
|
1345
|
+
`run-history-keep` keeps its configured limit, applied to **closed, fully settled new
|
|
1346
|
+
sessions whose owning process is gone**. Live, unfinished, pending and malformed
|
|
1347
|
+
namespaces are protected. A crash without a close marker is retained for manual
|
|
1348
|
+
inspection, not silently classified as safely deletable. Follow absolute paths from
|
|
1349
|
+
tool results; `artifacts/...` is a session-relative handoff alias, not a read-tool path.
|
|
1350
|
+
|
|
1351
|
+
### No-progress stops
|
|
1352
|
+
|
|
1353
|
+
Unchanged failed dispatch/research retries are refused across turns using normalized
|
|
1354
|
+
actor, structured scope, input artifacts, actual execution conditions and worktree
|
|
1355
|
+
state, not task wording or scope_mode. Research scope is advisory, not isolation.
|
|
1356
|
+
|
|
1357
|
+
Operator cancellation fences the **agent identity**, including disjoint scopes,
|
|
1358
|
+
model/prose changes and dispatch/research inputs. Other agents' already-running work
|
|
1359
|
+
is not cancelled. `/af-recover inspect <operationId>` reports safe attempt state and
|
|
1360
|
+
missing prerequisites; `retry|reconcile|abandon <operationId> <attemptId>` validate IDs.
|
|
1361
|
+
Legacy `/af-retry <dispatchId>` resolves the same retry handler for cancellation and
|
|
1362
|
+
settled indeterminate failures. Both retry spellings ask the human once, warning that an
|
|
1363
|
+
indeterminate attempt may already have partial effects and retry can duplicate them;
|
|
1364
|
+
there is at most one indeterminate grant per operation. Neither command executes or
|
|
1365
|
+
renews budget: after authorization, explicitly invoke the code-rendered original
|
|
1366
|
+
`dispatch_agent(...)` or `spawn_research(...)` contract. Pending/unknown process,
|
|
1367
|
+
duplicate grant, stale response, or unavailable original contract is not permission
|
|
1368
|
+
to replay. T3 protocol errors still need trusted effects evidence and corrected conditions;
|
|
1369
|
+
unknown-tool needs a catalog change. `reconcile` requires attributable unchanged-current-
|
|
1370
|
+
revision readback and independent nonblocking review; it clears a technical block only,
|
|
1371
|
+
retaining failed delivery and every open AF-MIN-CHANGE/test/review/plan obligation. `abandon`
|
|
1372
|
+
does not satisfy dependent work. Audit exports IDs/statuses only, never prompts, nonces,
|
|
1373
|
+
raw contracts or evidence paths.
|
|
1374
|
+
|
|
1375
|
+
Non-busy recovery refusals use separate accounting and never consume turn/task launch
|
|
1376
|
+
counters. A `not_started` preflight refusal (runtime-owned, `started:false`, `effects:none`)
|
|
1377
|
+
records 0 launches and 0 indeterminate attempts; correcting the prerequisite and re-invoking
|
|
1378
|
+
explicitly needs no slash reset, grant, or reconcile. Exhaustion
|
|
1379
|
+
returns budget_refused; no new limit, parent abort, retry, wait or queue is added.
|
|
1380
|
+
Busy operations that never started spend no allowance and record no failure. Turn reports no
|
|
1381
|
+
longer charge refusals as dispatches; refusal totals count every refusal while launch
|
|
1382
|
+
counters count only real child executions. Session execution totals
|
|
1383
|
+
still count real dispatch attempts rather than guard refusals.
|
|
1384
|
+
|
|
1385
|
+
The shared recovery contract is fail-closed. Protocol errors require changed
|
|
1386
|
+
conditions plus a trusted prior-effects inspection. The internal task-generation-bound
|
|
1387
|
+
establishEffects port accepts a retained inspection reference; it is not a model
|
|
1388
|
+
parameter or a promise that T3 exists. Launch/close/termination lifecycle facts are
|
|
1389
|
+
produced by the native spawn path and the research spawn path (safety refusal and spawn
|
|
1390
|
+
failure never launched; timeout without close stays uncertain). Unknown-tool
|
|
1391
|
+
recovery has a task-generation-bound catalog-change port; a trusted catalog-change
|
|
1392
|
+
producer must still supply the evidence — prose alone never authorizes it.
|
|
1393
|
+
|
|
1394
|
+
### Runtime verification contract
|
|
1395
|
+
|
|
1396
|
+
set_assertions.test_command declares an exact bash verification command for a test
|
|
1397
|
+
or code-grep requirement. It does not execute the command. For code-grep, the command
|
|
1398
|
+
must exit nonzero when the declared presence/absence condition fails. Native children
|
|
1399
|
+
run it through the existing approved bash path after edits. The child-loaded
|
|
1400
|
+
runtime-test-check observer preserves Pi's configured shell/prefix, execution context,
|
|
1401
|
+
renderers and tool_result error flag; the parent retains command, actual exit and
|
|
1402
|
+
before/after revisions, binding source/text/reference/critical conditions to task ID.
|
|
1403
|
+
Compilation only checks the minimal change requirement, never semantic assertions.
|
|
1404
|
+
|
|
1405
|
+
manual/runtime-ui requirements are explicitly unsupported by this producer. A test
|
|
1406
|
+
or code-grep without a command/check remains missing/unverified; a model's proven
|
|
1407
|
+
stamp is not runtime proof. Fresh bound runtime checks supersede old claimed ledger
|
|
1408
|
+
stamps; stale runtime checks do not. Runtime refs and claimedEvidenceRefs are separate.
|
|
1409
|
+
|
|
1410
|
+
agent-fleet.runtime-result/v1 reports orthogonal execution, changes, verification,
|
|
1411
|
+
acceptance and compatibility dimensions. Acceptance requires completed execution,
|
|
1412
|
+
current task, certain changed state, and all requirements/checks passing with current
|
|
1413
|
+
revision and retained runtime evidence. Missing/failed/stale/unsupported checks,
|
|
1414
|
+
unchanged/missing deliverables and uncertain attribution never accept, at any tier.
|
|
1415
|
+
needs_verification means unaccepted, not nearly done.
|
|
1416
|
+
|
|
1417
|
+
**Semantic limitation (operator accepted):** specialist-authored tests may pass the
|
|
1418
|
+
runtime gate. Runtime proves execution/state, NOT the adequacy of those tests or
|
|
1419
|
+
code-grep predicates. Separate code review remains required; accepted is not human
|
|
1420
|
+
Checkpoint A approval. No live model runs or T3/T7 implementation are included.
|
|
1421
|
+
|
|
1422
|
+
### Explicit delivery contract
|
|
1423
|
+
|
|
1424
|
+
`dispatch_agent` accepts `deliverables: string[]` of exact expected output files.
|
|
1425
|
+
The worker receives their absolute paths. The hub reads every expected file back,
|
|
1426
|
+
records size/hash/preview and whether it changed, retains the inspected content, and
|
|
1427
|
+
saves `details.assessmentPath`. Missing files, directories and unsafe symlink paths
|
|
1428
|
+
do not pass readback. An existing unchanged file is not attributed to this run.
|
|
1429
|
+
|
|
1430
|
+
Exit 0 returns `executionStatus: completed`, **not** acceptance. Without qualifying runtime checks, tool status is
|
|
1431
|
+
`completed_unverified` or `verification_failed` and `accepted: false`. Only the
|
|
1432
|
+
runtime verification contract above can produce `accepted: true`. Every delivered return is
|
|
1433
|
+
saved even without assertion IDs. Pending peer delivery remains pending.
|
|
1434
|
+
|
|
1435
|
+
Scope roots are checked before budget confirmation/counters. Missing roots are not
|
|
1436
|
+
zero-match success. Set `scope_mode: create` explicitly to permit a new root. A new
|
|
1437
|
+
exact file in an existing directory is permitted when declared in `deliverables`;
|
|
1438
|
+
otherwise a missing dotted name such as `RIN.Video` is still treated as a missing
|
|
1439
|
+
root, not guessed to be a file. Free-form prose and XML are never executed as tools.
|
|
1440
|
+
|
|
1441
|
+
## System 1 communication and dispatch advice
|
|
1442
|
+
|
|
1443
|
+
Fleet `1` opens a read-only request/response viewer. Press `e` to enable memory-only
|
|
1444
|
+
capture, Enter to inspect a pair, left/right and Enter to copy, `d` to disable and
|
|
1445
|
+
clear. `j` navigation is unchanged. The optional `dispatch_triage` tool is for the
|
|
1446
|
+
orchestrator, not a human slash command; all dispatch gates remain authoritative.
|
|
1447
|
+
See [the guide](../../../docs/system1-dispatch-triage.md) for opt-in configuration,
|
|
1448
|
+
privacy boundaries, evaluation commands and outstanding live acceptance.
|