pi-cowboy 0.15.1 → 0.17.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +11 -8
- package/dist/agents/agent-assets.d.ts +114 -0
- package/dist/agents/agent-assets.js +42 -29
- package/dist/agents/agent-cleanup.d.ts +82 -0
- package/dist/agents/agent-cleanup.js +6 -6
- package/dist/agents/agent-discovery.d.ts +22 -0
- package/dist/agents/agent-discovery.js +7 -3
- package/dist/agents/agent-host.d.ts +212 -0
- package/dist/agents/agent-host.js +6 -3
- package/dist/agents/agent-manager.d.ts +99 -0
- package/dist/agents/agent-manager.js +21 -9
- package/dist/agents/agent-reviver.d.ts +38 -0
- package/dist/agents/agent-runner.d.ts +51 -0
- package/dist/agents/agent-runner.js +22 -31
- package/dist/agents/agent-spawn-store.d.ts +39 -0
- package/dist/agents/agent-template.d.ts +118 -0
- package/dist/agents/agent-template.js +7 -3
- package/dist/agents/agent-types.d.ts +59 -0
- package/dist/agents/agent-types.js +22 -6
- package/dist/agents/batch.d.ts +63 -0
- package/dist/agents/cleanup-policy.d.ts +288 -0
- package/dist/agents/cleanup-policy.js +2 -2
- package/dist/agents/cleanup-report.d.ts +14 -0
- package/dist/agents/default-agents.d.ts +8 -0
- package/dist/agents/harness/claude/index.d.ts +41 -0
- package/dist/agents/harness/claude/index.js +49 -7
- package/dist/agents/harness/claude/staging.d.ts +46 -0
- package/dist/agents/harness/claude/staging.js +3 -2
- package/dist/agents/harness/codex.d.ts +42 -0
- package/dist/agents/harness/codex.js +3 -4
- package/dist/agents/harness/harness-registry.d.ts +114 -0
- package/dist/agents/harness/harness-registry.js +242 -0
- package/dist/agents/harness/opencode/definition.d.ts +21 -0
- package/dist/agents/harness/opencode/index.d.ts +32 -0
- package/dist/agents/harness/opencode/index.js +3 -4
- package/dist/agents/harness/opencode/permissions.d.ts +27 -0
- package/dist/agents/harness/opencode/staging.d.ts +32 -0
- package/dist/agents/harness/opencode/version.d.ts +36 -0
- package/dist/agents/harness/pane-launcher.d.ts +89 -0
- package/dist/agents/harness/pane-launcher.js +23 -22
- package/dist/agents/harness/pi-bolt.d.ts +9 -0
- package/dist/agents/harness/pi-bolt.js +0 -1
- package/dist/agents/harness/pi-compatible.d.ts +48 -0
- package/dist/agents/harness/pi-compatible.js +3 -4
- package/dist/agents/harness/pig.d.ts +10 -0
- package/dist/agents/harness/pig.js +0 -1
- package/dist/agents/harness.d.ts +416 -0
- package/dist/agents/harness.js +46 -57
- package/dist/agents/multiplexer-registry.d.ts +101 -0
- package/dist/agents/multiplexer-registry.js +125 -0
- package/dist/agents/result-file-permissions.d.ts +19 -0
- package/dist/agents/run-state.d.ts +144 -0
- package/dist/agents/schemas/cleanup-batch.schema.d.ts +17 -0
- package/dist/agents/schemas/cowboy-agents.schema.d.ts +51 -0
- package/dist/agents/schemas/cowboy-agents.schema.js +1 -1
- package/dist/agents/schemas/merge-batch.schema.d.ts +21 -0
- package/dist/agents/schemas/steer-batch.schema.d.ts +19 -0
- package/dist/agents/schemas/stop-batch.schema.d.ts +16 -0
- package/dist/agents/spawn-defaults.d.ts +48 -0
- package/dist/agents/spawn-defaults.js +22 -21
- package/dist/agents/subagent-session.d.ts +161 -0
- package/dist/agents/subagent-session.js +8 -5
- package/dist/agents/tool-cleanup.d.ts +43 -0
- package/dist/agents/tool-execution.d.ts +61 -0
- package/dist/agents/tool-merge.d.ts +64 -0
- package/dist/agents/tool-result.d.ts +21 -0
- package/dist/agents/tool-steer.d.ts +40 -0
- package/dist/agents/types.d.ts +94 -0
- package/dist/availability.d.ts +42 -0
- package/dist/concurrency-pools.d.ts +168 -0
- package/dist/concurrency-pools.js +11 -9
- package/dist/config/concurrency-limit.d.ts +12 -0
- package/dist/config/config-io.d.ts +50 -0
- package/dist/config/config-io.js +8 -20
- package/dist/config/config-store.d.ts +193 -0
- package/dist/config/config-store.js +67 -42
- package/dist/config/config-validation.d.ts +3 -0
- package/dist/config/config-validation.js +55 -60
- package/dist/config/layered-config.d.ts +45 -0
- package/dist/config/types.d.ts +8 -0
- package/dist/cow-support-launch.d.ts +18 -0
- package/dist/events.d.ts +9 -0
- package/dist/events.js +71 -19
- package/dist/extension-toggle.d.ts +13 -0
- package/dist/harness-availability-launch.d.ts +47 -0
- package/dist/harness-availability-launch.js +48 -33
- package/dist/host-multiplexer.d.ts +42 -0
- package/dist/host-multiplexer.js +62 -0
- package/dist/index.d.ts +10 -0
- package/dist/index.js +5 -16
- package/dist/infrastructure/exec-path.d.ts +13 -0
- package/dist/infrastructure/exec-sync.d.ts +18 -0
- package/dist/infrastructure/git/cow-clone.d.ts +111 -0
- package/dist/infrastructure/git/git-materializer.d.ts +146 -0
- package/dist/infrastructure/git/git-merger.d.ts +111 -0
- package/dist/infrastructure/git/git-merger.js +1 -1
- package/dist/infrastructure/git/git-retention.d.ts +21 -0
- package/dist/infrastructure/git/git-runner.d.ts +89 -0
- package/dist/infrastructure/git/git-worktree.d.ts +86 -0
- package/dist/infrastructure/git/index.d.ts +11 -0
- package/dist/infrastructure/git-client.d.ts +11 -0
- package/dist/infrastructure/herdr/agent-stopper.d.ts +33 -0
- package/dist/infrastructure/herdr/agents.d.ts +124 -0
- package/dist/infrastructure/herdr/agents.js +1 -1
- package/dist/infrastructure/herdr/herdr-client.d.ts +23 -0
- package/dist/infrastructure/herdr/herdr-transport.d.ts +57 -0
- package/dist/infrastructure/herdr/index.d.ts +15 -0
- package/dist/infrastructure/herdr/panes.d.ts +82 -0
- package/dist/infrastructure/herdr/polling.d.ts +41 -0
- package/dist/infrastructure/herdr/worktrees.d.ts +32 -0
- package/dist/infrastructure/herdr-client.d.ts +6 -0
- package/dist/infrastructure/herdr-host.d.ts +11 -0
- package/dist/infrastructure/herdr-host.js +55 -5
- package/dist/logger.d.ts +13 -0
- package/dist/models/foreign-model-resolver.d.ts +39 -0
- package/dist/models/model-groups.d.ts +56 -0
- package/dist/models/model-precedence.d.ts +135 -0
- package/dist/models/model-precedence.js +20 -7
- package/dist/models/model-request-types.d.ts +51 -0
- package/dist/models/model-request.d.ts +47 -0
- package/dist/models/pi-model-resolver.d.ts +35 -0
- package/dist/orchestrators/briefing-section.d.ts +9 -0
- package/dist/orchestrators/context.d.ts +143 -0
- package/dist/orchestrators/context.js +7 -1
- package/dist/orchestrators/cues.d.ts +31 -0
- package/dist/orchestrators/default-orchestrators.d.ts +10 -0
- package/dist/orchestrators/default-orchestrators.js +7 -2
- package/dist/orchestrators/orchestrator-discovery.d.ts +27 -0
- package/dist/orchestrators/orchestrator-template.d.ts +22 -0
- package/dist/orchestrators/orchestrator-types.d.ts +30 -0
- package/dist/orchestrators/protocol.d.ts +119 -0
- package/dist/orchestrators/protocol.js +4 -3
- package/dist/orchestrators/types.d.ts +18 -0
- package/dist/paths.d.ts +49 -0
- package/dist/paths.js +1 -1
- package/dist/pi-settings.d.ts +3 -0
- package/dist/plugin/contract.d.ts +56 -0
- package/dist/plugin/contract.js +17 -0
- package/dist/plugin/discovery.d.ts +59 -0
- package/dist/plugin/discovery.js +67 -0
- package/dist/plugin/index.d.ts +16 -0
- package/dist/plugin/index.js +14 -0
- package/dist/plugin/loader.d.ts +52 -0
- package/dist/plugin/loader.js +181 -0
- package/dist/plugin/manifest.d.ts +25 -0
- package/dist/plugin/manifest.js +47 -0
- package/dist/predicates.d.ts +18 -0
- package/dist/prompt/prompts.d.ts +40 -0
- package/dist/prompt/skill-loader.d.ts +28 -0
- package/dist/prompt/subagent-system-prompt.d.ts +50 -0
- package/dist/registration.d.ts +43 -0
- package/dist/registration.js +15 -3
- package/dist/session-runtime.d.ts +43 -0
- package/dist/session-runtime.js +89 -0
- package/dist/shell.d.ts +151 -0
- package/dist/shell.js +30 -5
- package/dist/spawn/cow-support.d.ts +26 -0
- package/dist/spawn/crockford-base32.d.ts +46 -0
- package/dist/spawn/crockford-base32.js +2 -2
- package/dist/spawn/herdr-launcher.d.ts +33 -0
- package/dist/spawn/repo-lock.d.ts +21 -0
- package/dist/spawn/sandbox.d.ts +130 -0
- package/dist/spawn/sandbox.js +3 -3
- package/dist/spawn/spawn-coordinator.d.ts +80 -0
- package/dist/spawn/spawn-coordinator.js +12 -10
- package/dist/spawn/spawn-id.d.ts +23 -0
- package/dist/spawn/worktree-policy.d.ts +68 -0
- package/dist/status-note.d.ts +7 -0
- package/dist/subagent/deliverable.d.ts +40 -0
- package/dist/subagent/pane-supervisor.d.ts +33 -0
- package/dist/subagent/pane-supervisor.js +1 -1
- package/dist/subagent/result-artifacts.d.ts +16 -0
- package/dist/subagent/supervisor.d.ts +157 -0
- package/dist/subagent/supervisor.js +4 -4
- package/dist/task-registry.d.ts +88 -0
- package/dist/task-registry.js +3 -3
- package/dist/templates/template-files.d.ts +35 -0
- package/dist/templates/template-files.js +8 -4
- package/dist/types.d.ts +268 -0
- package/dist/ui/action-report.d.ts +29 -0
- package/dist/ui/format.d.ts +17 -0
- package/dist/ui/indicator.d.ts +194 -0
- package/dist/ui/menu/helpers.d.ts +95 -0
- package/dist/ui/menu/menu-agent-settings.d.ts +8 -0
- package/dist/ui/menu/menu-agent-settings.js +18 -10
- package/dist/ui/menu/menu-agent-status-cleanup.d.ts +46 -0
- package/dist/ui/menu/menu-agent-status.d.ts +20 -0
- package/dist/ui/menu/menu-concurrency.d.ts +8 -0
- package/dist/ui/menu/menu-concurrency.js +11 -8
- package/dist/ui/menu/menu-model-settings.d.ts +30 -0
- package/dist/ui/menu/menu-model-settings.js +7 -5
- package/dist/ui/menu/menu-spawn-defaults.d.ts +20 -0
- package/dist/ui/menu/menu-spawn-wizard.d.ts +7 -0
- package/dist/ui/menu/menu-spawn-worktree.d.ts +46 -0
- package/dist/ui/menu/menu-system-prompt.d.ts +6 -0
- package/dist/ui/menu/menu-worktree-command.d.ts +17 -0
- package/dist/ui/menu/menus.d.ts +23 -0
- package/dist/ui/menu/model-picker.d.ts +19 -0
- package/dist/ui/menu/model-picker.js +2 -3
- package/dist/ui/menu/screen-host.d.ts +88 -0
- package/dist/ui/menu/submenus/confirm.d.ts +27 -0
- package/dist/ui/menu/submenus/model-select.d.ts +38 -0
- package/dist/ui/menu/submenus/name-field.d.ts +30 -0
- package/dist/ui/menu/submenus/numeric-input.d.ts +26 -0
- package/dist/ui/menu/submenus/target-select.d.ts +92 -0
- package/dist/ui/menu/submenus/text-editor.d.ts +42 -0
- package/dist/ui/menu/submenus/worktree-command-name.d.ts +40 -0
- package/dist/ui/menu/submenus/worktree-name.d.ts +39 -0
- package/dist/ui/menu/wrappers/settings-list.d.ts +41 -0
- package/dist/ui/searchable-select.d.ts +38 -0
- package/dist/ui/types.d.ts +7 -0
- package/dist/utils.d.ts +39 -0
- package/package.json +3 -2
- package/dist/agents/harness/registry.js +0 -76
- package/dist/agents/harness-family.js +0 -23
package/README.md
CHANGED
|
@@ -12,6 +12,8 @@
|
|
|
12
12
|
|
|
13
13
|
Each agent runs in its own terminal pane inside [Herdr](https://github.com/electric-dragon-80000v/herdr) and works in an isolated copy-on-write Git worktree. You can watch agents work in real time, jump into any pane to steer them, or mix and match harnesses like Pi, Claude Code, OpenCode, and Codex in the same session. When the work is finished, `pi-cowboy` cleans up the leftovers for you.
|
|
14
14
|
|
|
15
|
+
Check out the [demo](https://electric-dragon-80000v.github.io/pi-cowboy/).
|
|
16
|
+
|
|
15
17
|
## Why should I use it?
|
|
16
18
|
|
|
17
19
|
### Focused tasks produce better code
|
|
@@ -193,7 +195,7 @@ When `pi-cowboy` spawns an agent, it picks the model using the first match in th
|
|
|
193
195
|
2. The session per-type model override (`/cowboy` > `Model overrides`)
|
|
194
196
|
3. The config per-type override (`agent.<agent-type>`)
|
|
195
197
|
4. The model set in the [agent template](docs/Agent%20Templates.md) for the launching harness family
|
|
196
|
-
5. The session default model (`/cowboy model
|
|
198
|
+
5. The Pi-family session default model (`/cowboy model`, which picks from Pi's catalogue)
|
|
197
199
|
6. The launching harness's configured default (`agent.default` for the Pi family, or `agent.defaultModelByHarness` for foreign harnesses)
|
|
198
200
|
7. For Pi-family launches, the parent session's active model
|
|
199
201
|
|
|
@@ -228,13 +230,13 @@ Delegates one or more tasks to cowboy agents. By default, the call returns immed
|
|
|
228
230
|
|
|
229
231
|
Each item in `agents[]` takes:
|
|
230
232
|
|
|
231
|
-
| Field | Required | Description
|
|
232
|
-
| -------------- | -------- |
|
|
233
|
-
| `prompt` | yes | Task instructions for the cowboy agent.
|
|
234
|
-
| `task_name` | yes | Short 2-3-word name (e.g. `"fix login flow"`) used to name the agent's branch, worktree, and tab.
|
|
235
|
-
| `agent_type` | no | Agent template to use. Defaults to the type selected at `/cowboy` > `Agent`.
|
|
236
|
-
| `model` | no | Model for this agent as `"provider/model-id"`. Resolved according to [Model resolution](#model-resolution).
|
|
237
|
-
| `harness_type` | no | Harness that launches this agent: `pi`, `pig`, `pi-bolt`, `opencode`, `codex`,
|
|
233
|
+
| Field | Required | Description |
|
|
234
|
+
| -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
235
|
+
| `prompt` | yes | Task instructions for the cowboy agent. |
|
|
236
|
+
| `task_name` | yes | Short 2-3-word name (e.g. `"fix login flow"`) used to name the agent's branch, worktree, and tab. |
|
|
237
|
+
| `agent_type` | no | Agent template to use. Defaults to the type selected at `/cowboy` > `Agent`. |
|
|
238
|
+
| `model` | no | Model for this agent as `"provider/model-id"`. Resolved according to [Model resolution](#model-resolution). |
|
|
239
|
+
| `harness_type` | no | Harness that launches this agent: `pi`, `pig`, `pi-bolt`, `opencode`, `codex`, `claude`, or a harness a plugin registered in this session. Overrides the agent template's `harness_type` and the `agent.harnessType` setting. If the harness is not registered here, or this machine cannot launch it, the call fails before spawning. |
|
|
238
240
|
|
|
239
241
|
### `steer_cowboy_agent`
|
|
240
242
|
|
|
@@ -301,3 +303,4 @@ Yes. You can disable both the cowboy indicator and the grazing cows in `/cowboy`
|
|
|
301
303
|
- [Menu](docs/Menu.md)
|
|
302
304
|
- [Agent Templates](docs/Agent%20Templates.md)
|
|
303
305
|
- [Orchestrator Templates](docs/Orchestrator%20Templates.md)
|
|
306
|
+
- [Plugins](docs/Plugins.md)
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* agent-assets.ts — located-artifacts seam: locate a run's work, then act on it.
|
|
3
|
+
* AgentAssets: locate/observe/deliverable + actuators. AgentAssetsDeps: raw probes it composes.
|
|
4
|
+
* LocateResult: Located (tracked/recovered) | Ambiguous | NotFound.
|
|
5
|
+
* CleanupDeps: injected host/git actuators. PaneRef/LocatedCandidate: addresses.
|
|
6
|
+
* createAgentAssets: bind over probes. createMultiplexerAgentAssets: bind to a session's multiplexer.
|
|
7
|
+
* Authority is per-asset: provenance (worktreeManaged/paneCreated) is memory-only;
|
|
8
|
+
* addresses (workspace/pane/branch/path) are live probes (memory can be stale, not just absent).
|
|
9
|
+
* Unreadable registries degrade to memory's answer, never to absence.
|
|
10
|
+
*/
|
|
11
|
+
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
|
12
|
+
import type { AgentSpawn } from "../types.js";
|
|
13
|
+
import type { BranchCleanupResult, DeleteBranchOptions } from "../infrastructure/git-client.js";
|
|
14
|
+
import type { AgentMultiplexer, AgentHost, AgentHostRef, HostObservation, PlacementCatalog, PlacementRecord, PlacementWorktree } from "./agent-host.js";
|
|
15
|
+
import type { AnyHarnessId, HarnessTeardownContext } from "./harness.js";
|
|
16
|
+
import type { CleanupSource, LocatedArtifacts, RecoveredDeliverable } from "./cleanup-policy.js";
|
|
17
|
+
/**
|
|
18
|
+
* Injected host/git actuators. Host ops take the run's address (bound to release/close, never stop); git ops stay path-based (the host never destroys filesystem state).
|
|
19
|
+
* Function-typed properties, not methods: these are bare injected functions, and callers hand them on as values (`deps.isWorktreeDirty`).
|
|
20
|
+
*/
|
|
21
|
+
export interface CleanupDeps {
|
|
22
|
+
/** Dirty/unverifiable retention probe. */
|
|
23
|
+
isWorktreeDirty: (worktreePath: string) => Promise<boolean | undefined>;
|
|
24
|
+
/** Filesystem probe (injected; this module never touches the filesystem). */
|
|
25
|
+
worktreeExists: (worktreePath: string) => Promise<boolean>;
|
|
26
|
+
/** Drop the worktree association, returning true only when confirmed gone. */
|
|
27
|
+
removeWorktree: (ref: AgentHostRef) => Promise<boolean>;
|
|
28
|
+
/** Remove a checkout that was never adopted into herdr. */
|
|
29
|
+
removeGitWorktree: (worktreePath: string, repoCwd: string) => Promise<boolean>;
|
|
30
|
+
/** Delete the branch a removed worktree carried once it is merged and unattached. */
|
|
31
|
+
deleteBranch: (options: DeleteBranchOptions) => Promise<BranchCleanupResult>;
|
|
32
|
+
/** Close a self-created placement. */
|
|
33
|
+
closePane: (ref: AgentHostRef) => Promise<void>;
|
|
34
|
+
/**
|
|
35
|
+
* Teardown of the harness state one ended run's pane was prepared with —
|
|
36
|
+
* ordered before any worktree dirty probe, see Harness.teardown. The bound
|
|
37
|
+
* actuator resolves the recorded harness and supplies the pi instance.
|
|
38
|
+
*/
|
|
39
|
+
harnessTeardown: (harness: AnyHarnessId, context: HarnessTeardownContext) => Promise<void>;
|
|
40
|
+
}
|
|
41
|
+
export interface PaneRef {
|
|
42
|
+
readonly paneId: string;
|
|
43
|
+
}
|
|
44
|
+
/** One artifact pair answering to a contested id (ambiguity payload). */
|
|
45
|
+
interface LocatedCandidate {
|
|
46
|
+
worktreePath: string;
|
|
47
|
+
branch: string;
|
|
48
|
+
workspaceId?: string;
|
|
49
|
+
}
|
|
50
|
+
/** The located artifacts plus where they came from. */
|
|
51
|
+
export interface Located extends LocatedArtifacts {
|
|
52
|
+
kind: "located";
|
|
53
|
+
/** `tracked` (spawn record named them) or `recovered` (discovery did). */
|
|
54
|
+
source: CleanupSource;
|
|
55
|
+
}
|
|
56
|
+
/** Two artifacts answer to one id. The caller arbitrates; cleanup refuses. */
|
|
57
|
+
export interface Ambiguous {
|
|
58
|
+
kind: "ambiguous";
|
|
59
|
+
id: string;
|
|
60
|
+
candidates: readonly LocatedCandidate[];
|
|
61
|
+
}
|
|
62
|
+
/** Nothing answers to this id (no record, worktree, or proven branch). */
|
|
63
|
+
interface NotFound {
|
|
64
|
+
kind: "not-found";
|
|
65
|
+
id: string;
|
|
66
|
+
}
|
|
67
|
+
export type LocateResult = Located | Ambiguous | NotFound;
|
|
68
|
+
/** The seam: locate an agent's artifacts, then act on them. Injected probes are function-typed properties (see CleanupDeps). */
|
|
69
|
+
export interface AgentAssets extends CleanupDeps {
|
|
70
|
+
/**
|
|
71
|
+
* The multiplexer every address this seam builds belongs to (see hostRefFor in
|
|
72
|
+
* agent-cleanup.ts). It rides here rather than on `CleanupDeps` because only
|
|
73
|
+
* the locator produces addresses; the allocation-failure path consumes them.
|
|
74
|
+
*/
|
|
75
|
+
multiplexer: AgentMultiplexer;
|
|
76
|
+
/** Run's deliverable, derived from the id alone without probing the run; reported, never deleted. */
|
|
77
|
+
deliverable: (id: string) => RecoveredDeliverable;
|
|
78
|
+
/** Locate one agent's artifacts (hint, else discovery); never stops anything — the pane is an address, not a process. */
|
|
79
|
+
locate(id: string, hint?: AgentSpawn): Promise<LocateResult>;
|
|
80
|
+
/** Raw liveness read: undefined = gone, a throw = unreadable (never evidence the run is over); no settlement verdict. */
|
|
81
|
+
observe(pane: PaneRef): Promise<HostObservation | undefined>;
|
|
82
|
+
}
|
|
83
|
+
/** Raw single-plane probes; matching/authority/ambiguity stay in this module so tests fake the planes. Injected probes are function-typed properties (see CleanupDeps). */
|
|
84
|
+
export interface AgentAssetsDeps extends CleanupDeps {
|
|
85
|
+
/** The multiplexer every address this seam builds belongs to. */
|
|
86
|
+
multiplexer: AgentMultiplexer;
|
|
87
|
+
/** Canonicalize a path the way the multiplexer spells its placements (see PlacementCatalog). */
|
|
88
|
+
canonicalizePath: (value: string) => string;
|
|
89
|
+
/** Run's deliverable and whether it exists. */
|
|
90
|
+
deliverable: (id: string) => RecoveredDeliverable;
|
|
91
|
+
/** Raw multiplexer registry read (the multiplexer's `worktree list`); a throw degrades discovery. */
|
|
92
|
+
listWorktrees: () => Promise<readonly PlacementWorktree[]>;
|
|
93
|
+
/** Raw multiplexer placement records (the multiplexer's `agent list`), nameless ones included. */
|
|
94
|
+
listPlacements: () => Promise<readonly PlacementRecord[]>;
|
|
95
|
+
/** One pane's raw state; undefined = gone, a throw = unreadable. */
|
|
96
|
+
readPane(paneId: string): Promise<HostObservation | undefined>;
|
|
97
|
+
/** The worktree root extension worktrees live under; undefined = unresolvable. */
|
|
98
|
+
worktreeRoot(): Promise<string | undefined>;
|
|
99
|
+
/** Entry names directly under `root` (the filesystem fallback). */
|
|
100
|
+
listRootEntries(root: string): Promise<readonly string[]>;
|
|
101
|
+
/** Main-checkout cwd derived from a checkout; undefined = it could not be resolved. */
|
|
102
|
+
resolveRepoCwd(worktreePath: string): Promise<string | undefined>;
|
|
103
|
+
}
|
|
104
|
+
/** Bind the seam over injected probes. */
|
|
105
|
+
export declare function createAgentAssets(deps: AgentAssetsDeps): AgentAssets;
|
|
106
|
+
/**
|
|
107
|
+
* Bind the seam to a session's multiplexer: the multiplexer's own reads come from the
|
|
108
|
+
* runtime's `PlacementCatalog` and its actuators from the runtime's `AgentHost`,
|
|
109
|
+
* so this module names no multiplexer. The rest — git, the filesystem, the config —
|
|
110
|
+
* is multiplexer-neutral and bound here. Failed repo derivation is `undefined` (never
|
|
111
|
+
* a borrowed cwd); failed pane reads throw (unreadable is not gone).
|
|
112
|
+
*/
|
|
113
|
+
export declare function createMultiplexerAgentAssets(pi: ExtensionAPI, host: AgentHost, catalog: PlacementCatalog): AgentAssets;
|
|
114
|
+
export {};
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
* AgentAssets: locate/observe/deliverable + actuators. AgentAssetsDeps: raw probes it composes.
|
|
4
4
|
* LocateResult: Located (tracked/recovered) | Ambiguous | NotFound.
|
|
5
5
|
* CleanupDeps: injected host/git actuators. PaneRef/LocatedCandidate: addresses.
|
|
6
|
-
* createAgentAssets: bind over probes.
|
|
6
|
+
* createAgentAssets: bind over probes. createMultiplexerAgentAssets: bind to a session's multiplexer.
|
|
7
7
|
* Authority is per-asset: provenance (worktreeManaged/paneCreated) is memory-only;
|
|
8
8
|
* addresses (workspace/pane/branch/path) are live probes (memory can be stale, not just absent).
|
|
9
9
|
* Unreadable registries degrade to memory's answer, never to absence.
|
|
@@ -11,12 +11,9 @@
|
|
|
11
11
|
import * as fs from "node:fs";
|
|
12
12
|
import * as path from "node:path";
|
|
13
13
|
import { deleteWorktreeBranch, isWorktreeDirty, removeGitWorktree, resolveMainCheckout, } from "../infrastructure/git-client.js";
|
|
14
|
-
import {
|
|
15
|
-
import { createHerdrHost } from "../infrastructure/herdr-host.js";
|
|
16
|
-
import { getSessionCtx, getStore } from "../shell.js";
|
|
14
|
+
import { getHarnessRegistry, getSessionCtx, getStore } from "../shell.js";
|
|
17
15
|
import { subagentResultFileFor } from "../paths.js";
|
|
18
16
|
import { buildWorktreeBranch, isExtensionWorktree, isSpawnArtifactName, resolveWorktreeRoot, slugifyWorktreeType, } from "../spawn/worktree-policy.js";
|
|
19
|
-
import { harnessFor } from "./harness/registry.js";
|
|
20
17
|
async function probeList(read) {
|
|
21
18
|
try {
|
|
22
19
|
return { ok: true, entries: await read() };
|
|
@@ -26,9 +23,9 @@ async function probeList(read) {
|
|
|
26
23
|
return { ok: false };
|
|
27
24
|
}
|
|
28
25
|
}
|
|
29
|
-
function matchWorktree(entries, worktreePath) {
|
|
30
|
-
const wanted =
|
|
31
|
-
return entries?.find((entry) =>
|
|
26
|
+
function matchWorktree(entries, worktreePath, canonicalize) {
|
|
27
|
+
const wanted = canonicalize(worktreePath);
|
|
28
|
+
return entries?.find((entry) => canonicalize(entry.path) === wanted);
|
|
32
29
|
}
|
|
33
30
|
function paneOf(record) {
|
|
34
31
|
return {
|
|
@@ -37,9 +34,9 @@ function paneOf(record) {
|
|
|
37
34
|
workspaceId: record.workspaceId,
|
|
38
35
|
};
|
|
39
36
|
}
|
|
40
|
-
function paneInWorktree(records, worktreePath) {
|
|
41
|
-
const wanted =
|
|
42
|
-
const record = records?.find((entry) => entry.cwd !== undefined &&
|
|
37
|
+
function paneInWorktree(records, worktreePath, canonicalize) {
|
|
38
|
+
const wanted = canonicalize(worktreePath);
|
|
39
|
+
const record = records?.find((entry) => entry.cwd !== undefined && canonicalize(entry.cwd) === wanted);
|
|
43
40
|
return record === undefined ? undefined : paneOf(record);
|
|
44
41
|
}
|
|
45
42
|
function paneInWorkspace(records, workspaceId) {
|
|
@@ -69,7 +66,7 @@ export function createAgentAssets(deps) {
|
|
|
69
66
|
const out = [];
|
|
70
67
|
const seen = new Set();
|
|
71
68
|
const push = (candidate) => {
|
|
72
|
-
const key =
|
|
69
|
+
const key = deps.canonicalizePath(candidate.path);
|
|
73
70
|
if (seen.has(key))
|
|
74
71
|
return;
|
|
75
72
|
seen.add(key);
|
|
@@ -88,7 +85,7 @@ export function createAgentAssets(deps) {
|
|
|
88
85
|
branch: entry.branch !== undefined && isSpawnArtifactName(entry.branch, id)
|
|
89
86
|
? entry.branch
|
|
90
87
|
: base,
|
|
91
|
-
workspaceId: entry.
|
|
88
|
+
workspaceId: entry.workspaceId,
|
|
92
89
|
});
|
|
93
90
|
}
|
|
94
91
|
// Scan only when the registry answered nothing: adopted checkouts are already listed.
|
|
@@ -126,13 +123,14 @@ export function createAgentAssets(deps) {
|
|
|
126
123
|
let workspaceId = recorded?.workspaceId;
|
|
127
124
|
if (worktreePath !== undefined) {
|
|
128
125
|
// Prefer herdr's live workspace (restarts/re-adopts mint new ids; a dead recorded one fails removal); no open workspace means the git plane removes it.
|
|
129
|
-
const entry = matchWorktree(entries, worktreePath);
|
|
126
|
+
const entry = matchWorktree(entries, worktreePath, deps.canonicalizePath);
|
|
130
127
|
if (entry !== undefined)
|
|
131
|
-
workspaceId = entry.
|
|
128
|
+
workspaceId = entry.workspaceId;
|
|
132
129
|
}
|
|
133
130
|
const pane = worktreePath === undefined
|
|
134
131
|
? recordedPane
|
|
135
|
-
: (paneInWorktree(records, worktreePath) ??
|
|
132
|
+
: (paneInWorktree(records, worktreePath, deps.canonicalizePath) ??
|
|
133
|
+
recordedPane);
|
|
136
134
|
const worktree = worktreePath === undefined
|
|
137
135
|
? null
|
|
138
136
|
: {
|
|
@@ -166,7 +164,7 @@ export function createAgentAssets(deps) {
|
|
|
166
164
|
};
|
|
167
165
|
}
|
|
168
166
|
const found = candidates[0];
|
|
169
|
-
const pane = paneInWorktree(records, found.path) ??
|
|
167
|
+
const pane = paneInWorktree(records, found.path, deps.canonicalizePath) ??
|
|
170
168
|
paneInWorkspace(records, found.workspaceId) ??
|
|
171
169
|
null;
|
|
172
170
|
return {
|
|
@@ -187,7 +185,7 @@ export function createAgentAssets(deps) {
|
|
|
187
185
|
}
|
|
188
186
|
async function locate(id, hint) {
|
|
189
187
|
const worktrees = await probeList(deps.listWorktrees);
|
|
190
|
-
const records = await probeList(deps.
|
|
188
|
+
const records = await probeList(deps.listPlacements);
|
|
191
189
|
const entries = worktrees.ok ? worktrees.entries : undefined;
|
|
192
190
|
const live = records.ok ? records.entries : undefined;
|
|
193
191
|
return hint === undefined
|
|
@@ -195,6 +193,7 @@ export function createAgentAssets(deps) {
|
|
|
195
193
|
: locateTracked(id, hint, entries, live);
|
|
196
194
|
}
|
|
197
195
|
return {
|
|
196
|
+
multiplexer: deps.multiplexer,
|
|
198
197
|
locate,
|
|
199
198
|
observe: (pane) => deps.readPane(pane.paneId),
|
|
200
199
|
deliverable: deps.deliverable,
|
|
@@ -207,21 +206,25 @@ export function createAgentAssets(deps) {
|
|
|
207
206
|
harnessTeardown: deps.harnessTeardown,
|
|
208
207
|
};
|
|
209
208
|
}
|
|
210
|
-
/* ── The
|
|
211
|
-
/**
|
|
212
|
-
|
|
213
|
-
|
|
209
|
+
/* ── The multiplexer composition ────────────────────────────────────────────── */
|
|
210
|
+
/**
|
|
211
|
+
* Bind the seam to a session's multiplexer: the multiplexer's own reads come from the
|
|
212
|
+
* runtime's `PlacementCatalog` and its actuators from the runtime's `AgentHost`,
|
|
213
|
+
* so this module names no multiplexer. The rest — git, the filesystem, the config —
|
|
214
|
+
* is multiplexer-neutral and bound here. Failed repo derivation is `undefined` (never
|
|
215
|
+
* a borrowed cwd); failed pane reads throw (unreadable is not gone).
|
|
216
|
+
*/
|
|
217
|
+
export function createMultiplexerAgentAssets(pi, host, catalog) {
|
|
214
218
|
return createAgentAssets({
|
|
219
|
+
multiplexer: catalog.multiplexer,
|
|
220
|
+
canonicalizePath: (value) => catalog.canonicalizePath(value),
|
|
215
221
|
deliverable: (id) => {
|
|
216
222
|
const resultFile = subagentResultFileFor(id);
|
|
217
223
|
return { path: resultFile, present: fs.existsSync(resultFile) };
|
|
218
224
|
},
|
|
219
|
-
listWorktrees: () => listWorktrees(
|
|
220
|
-
|
|
221
|
-
readPane:
|
|
222
|
-
const info = await getAgentInfo(pi, paneId);
|
|
223
|
-
return info === undefined ? undefined : { state: info.state };
|
|
224
|
-
},
|
|
225
|
+
listWorktrees: () => catalog.listWorktrees(),
|
|
226
|
+
listPlacements: () => catalog.listPlacements(),
|
|
227
|
+
readPane: (paneId) => catalog.observePane(paneId),
|
|
225
228
|
worktreeRoot: async () => {
|
|
226
229
|
const cwd = getSessionCtx().cwd;
|
|
227
230
|
if (!cwd)
|
|
@@ -260,6 +263,16 @@ export function createHerdrAgentAssets(pi) {
|
|
|
260
263
|
closePane: async (ref) => {
|
|
261
264
|
await host.release(ref, "placement");
|
|
262
265
|
},
|
|
263
|
-
harnessTeardown: (harness, context) =>
|
|
266
|
+
harnessTeardown: async (harness, context) => {
|
|
267
|
+
// The id is read back from a recorded spawn rather than resolved here, so
|
|
268
|
+
// a plugin load reset between the launch that recorded it and this
|
|
269
|
+
// teardown (a reload, a session replacement) can leave it registered by
|
|
270
|
+
// nothing. Such an id has no teardown to run — the plugin's code went with
|
|
271
|
+
// its registration — which is the same success as a harness that never
|
|
272
|
+
// prepared.
|
|
273
|
+
await getHarnessRegistry()
|
|
274
|
+
.get(harness)
|
|
275
|
+
?.teardown({ pi, ...context });
|
|
276
|
+
},
|
|
264
277
|
});
|
|
265
278
|
}
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* agent-cleanup.ts — state-changing cleanup orchestration (policy lives in cleanup-policy.ts).
|
|
3
|
+
* createWorktreeTeardown: worktree/branch/pane removal over injected actuators.
|
|
4
|
+
* createCleanup: settled-or-recovered run cleanup over the assets seam.
|
|
5
|
+
* WorktreeTeardown/Cleanup: the two planes. WorktreeTeardownOutcome: removal result.
|
|
6
|
+
* WorktreeRemovalTarget: the address a teardown removes through.
|
|
7
|
+
* AgentCleanupRegistry: spawn lookup/drop surface.
|
|
8
|
+
* Report-gated (only ended runs are cleaned up; live runs are refused, never stopped);
|
|
9
|
+
* ordered: gate before removal, workspace before pane, branch only after confirmed checkout removal.
|
|
10
|
+
*/
|
|
11
|
+
import type { AgentSpawn, WorktreeRetentionReason } from "../types.js";
|
|
12
|
+
import type { BranchCleanupResult } from "../infrastructure/git-client.js";
|
|
13
|
+
import type { AgentHostRef } from "./agent-host.js";
|
|
14
|
+
import type { AgentAssets, CleanupDeps } from "./agent-assets.js";
|
|
15
|
+
import { type CleanupOptions, type CleanupReport, type PaneTarget, type WorktreeRemovalMechanism, type WorktreeTarget } from "./cleanup-policy.js";
|
|
16
|
+
export type { CleanupDeps } from "./agent-assets.js";
|
|
17
|
+
/** The agent-tracking surface cleanup needs — injected by the caller. */
|
|
18
|
+
export interface AgentCleanupRegistry {
|
|
19
|
+
getSpawn(id: string): AgentSpawn | undefined;
|
|
20
|
+
/** Drop a terminal spawn from tracking (after its resources are gone). */
|
|
21
|
+
dropSpawn(spawn: AgentSpawn): void;
|
|
22
|
+
}
|
|
23
|
+
export type WorktreeTeardownOutcome = {
|
|
24
|
+
kind: "removed";
|
|
25
|
+
path: string;
|
|
26
|
+
branchName: string;
|
|
27
|
+
via: WorktreeRemovalMechanism;
|
|
28
|
+
branch: BranchCleanupResult;
|
|
29
|
+
} | {
|
|
30
|
+
kind: "kept";
|
|
31
|
+
path: string;
|
|
32
|
+
reason: WorktreeRetentionReason;
|
|
33
|
+
} | {
|
|
34
|
+
kind: "absent";
|
|
35
|
+
path?: string;
|
|
36
|
+
} | {
|
|
37
|
+
kind: "removal-failed";
|
|
38
|
+
path: string;
|
|
39
|
+
detail: string;
|
|
40
|
+
};
|
|
41
|
+
/** A checkout the multiplexer adopted: removal rides the host address. */
|
|
42
|
+
export type AdoptedWorktreeTarget = WorktreeTarget & {
|
|
43
|
+
workspaceId: string;
|
|
44
|
+
};
|
|
45
|
+
/** A pane the extension created: the only pane cleanup may close. */
|
|
46
|
+
type SelfCreatedPaneTarget = PaneTarget & {
|
|
47
|
+
origin: "self-created";
|
|
48
|
+
};
|
|
49
|
+
/**
|
|
50
|
+
* Removal target: each legal case carries exactly the address it uses. A
|
|
51
|
+
* host-adopted tree removes through its ref; a git-only tree closes a
|
|
52
|
+
* self-created pane through its ref; a detached tree removes through git
|
|
53
|
+
* and carries no ref.
|
|
54
|
+
*/
|
|
55
|
+
export type WorktreeRemovalTarget = {
|
|
56
|
+
kind: "adopted";
|
|
57
|
+
worktree: AdoptedWorktreeTarget;
|
|
58
|
+
pane: PaneTarget | null;
|
|
59
|
+
ref: AgentHostRef;
|
|
60
|
+
} | {
|
|
61
|
+
kind: "closing-pane";
|
|
62
|
+
worktree: WorktreeTarget;
|
|
63
|
+
pane: SelfCreatedPaneTarget;
|
|
64
|
+
ref: AgentHostRef;
|
|
65
|
+
} | {
|
|
66
|
+
kind: "detached";
|
|
67
|
+
worktree: WorktreeTarget;
|
|
68
|
+
pane: PaneTarget | null;
|
|
69
|
+
};
|
|
70
|
+
/** The state-changing teardown plane: worktree, then branch, then pane. */
|
|
71
|
+
interface WorktreeTeardown {
|
|
72
|
+
/** Tear down one worktree; a detached target runs only the git fallback; never stops an agent. */
|
|
73
|
+
removeWorktree(target: WorktreeRemovalTarget, opts?: CleanupOptions): Promise<WorktreeTeardownOutcome>;
|
|
74
|
+
}
|
|
75
|
+
interface Cleanup extends WorktreeTeardown {
|
|
76
|
+
/** Tear down one settled (or recovered) run's artifacts, then report. */
|
|
77
|
+
cleanupAgent(agentId: string, registry: AgentCleanupRegistry, opts?: CleanupOptions): Promise<CleanupReport>;
|
|
78
|
+
}
|
|
79
|
+
/** Bind the teardown plane over its actuators; an absent tree reports before any gate or removal runs. */
|
|
80
|
+
export declare function createWorktreeTeardown(deps: CleanupDeps): WorktreeTeardown;
|
|
81
|
+
/** Bind state-changing cleanup over the assets seam (the composition all callers use). */
|
|
82
|
+
export declare function createCleanup(assets: AgentAssets): Cleanup;
|
|
@@ -14,14 +14,14 @@ import { errorMessage } from "../utils.js";
|
|
|
14
14
|
import { ambiguousReport, assembleReport, assessRemovability, forcedFields, keptReport, paneDispositionFor, planRecovered, recordedSettlement, recoveryGate, recoveryRefusalReason, removalMechanismOf, shouldDropSpawn, } from "./cleanup-policy.js";
|
|
15
15
|
const log = createLogger("cleanup");
|
|
16
16
|
/* ── Addresses ─────────────────────────────────────────────────────────── */
|
|
17
|
-
/** Actuator address: memory's ref refreshed from
|
|
18
|
-
function hostRefFor(located) {
|
|
17
|
+
/** Actuator address: memory's ref refreshed from the multiplexer's live report; recovered runs rebuild it with `paneCreated` false; no pane address means no ref (git plane removes the checkout). `multiplexer` is the session's multiplexer, so the address a persisted spawn carries names the multiplexer that minted it. */
|
|
18
|
+
function hostRefFor(located, multiplexer) {
|
|
19
19
|
const pane = located.pane;
|
|
20
20
|
const workspaceId = pane?.workspaceId ?? located.worktree?.workspaceId;
|
|
21
21
|
if (pane === null || workspaceId === undefined)
|
|
22
22
|
return undefined;
|
|
23
23
|
return {
|
|
24
|
-
|
|
24
|
+
multiplexer,
|
|
25
25
|
name: located.branch,
|
|
26
26
|
paneId: pane.paneId,
|
|
27
27
|
tabId: pane.tabId,
|
|
@@ -127,7 +127,7 @@ export function createWorktreeTeardown(deps) {
|
|
|
127
127
|
const pane = target.pane;
|
|
128
128
|
const ref = target.kind === "detached" ? undefined : target.ref;
|
|
129
129
|
try {
|
|
130
|
-
// Applies to
|
|
130
|
+
// Applies to multiplexer and git targets alike: a rolled-back create has neither checkout nor workspace.
|
|
131
131
|
if (!(await deps.worktreeExists(worktree.worktreePath))) {
|
|
132
132
|
return { kind: "absent", path: worktree.worktreePath };
|
|
133
133
|
}
|
|
@@ -193,7 +193,7 @@ export function createCleanup(assets) {
|
|
|
193
193
|
forceable: false,
|
|
194
194
|
};
|
|
195
195
|
}
|
|
196
|
-
// No recorded end: force overrides without reading; otherwise
|
|
196
|
+
// No recorded end: force overrides without reading; otherwise the multiplexer's live read decides (unreadable refuses — never evidence the run is over).
|
|
197
197
|
if (opts?.force !== undefined) {
|
|
198
198
|
return {
|
|
199
199
|
kind: "torn-down",
|
|
@@ -312,7 +312,7 @@ export function createCleanup(assets) {
|
|
|
312
312
|
});
|
|
313
313
|
}
|
|
314
314
|
}
|
|
315
|
-
const removal = await removeResources(assets, plan, hostRefFor(located));
|
|
315
|
+
const removal = await removeResources(assets, plan, hostRefFor(located, assets.multiplexer));
|
|
316
316
|
const report = assembleReport(agentId, located.source, plan, verdict.settlement, removal, opts);
|
|
317
317
|
// A recovered run has no record to forget; drop only tracked spawns.
|
|
318
318
|
if (shouldDropSpawn(report) && hint !== undefined)
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* agent-discovery.ts — Agent file discovery, parsing, and config merging.
|
|
3
|
+
*
|
|
4
|
+
* Scans user, shared, and project `*.toml` dirs through
|
|
5
|
+
* AgentTemplateSchema into AgentConfigs. Per-field precedence:
|
|
6
|
+
* default < user < shared < project.
|
|
7
|
+
*/
|
|
8
|
+
import { type TemplateNotify, type TemplateRefusal } from "../templates/template-files.js";
|
|
9
|
+
import { type AgentTemplate } from "./agent-template.js";
|
|
10
|
+
import type { AgentConfig } from "./types.js";
|
|
11
|
+
/** One parsed agent template. */
|
|
12
|
+
export type AgentTemplateFile = AgentTemplate;
|
|
13
|
+
/** Shape failures throw; the scanner turns that into a one-line skip warning. */
|
|
14
|
+
export declare function parseAgentFile(content: string): AgentTemplateFile;
|
|
15
|
+
/**
|
|
16
|
+
* Empty array when the directory doesn't exist. Stays shell-free: `notify` and
|
|
17
|
+
* `refuse` are injected, so the session's rules — which harness ids this
|
|
18
|
+
* session runs — are the caller's, not this module's.
|
|
19
|
+
*/
|
|
20
|
+
export declare function scanAgentFilesInDir(dirPath: string, notify?: TemplateNotify, refuse?: TemplateRefusal<AgentTemplateFile>): Promise<AgentTemplateFile[]>;
|
|
21
|
+
/** Per-field precedence: project > shared > user > extension > defaults. A set field wins; undefined falls through. */
|
|
22
|
+
export declare function mergeAgents(defaults: Map<string, AgentConfig>, userAgents: AgentTemplateFile[], sharedAgents: AgentTemplateFile[], projectAgents: AgentTemplateFile[]): Map<string, AgentConfig>;
|
|
@@ -15,9 +15,13 @@ const AGENT_SCAN_WARNING = {
|
|
|
15
15
|
label: "Agent",
|
|
16
16
|
problem: "is not a valid agent template and was skipped",
|
|
17
17
|
};
|
|
18
|
-
/**
|
|
19
|
-
|
|
20
|
-
|
|
18
|
+
/**
|
|
19
|
+
* Empty array when the directory doesn't exist. Stays shell-free: `notify` and
|
|
20
|
+
* `refuse` are injected, so the session's rules — which harness ids this
|
|
21
|
+
* session runs — are the caller's, not this module's.
|
|
22
|
+
*/
|
|
23
|
+
export async function scanAgentFilesInDir(dirPath, notify, refuse) {
|
|
24
|
+
return scanTemplateFilesInDir(dirPath, parseAgentFile, (agent) => agent.name, notify, AGENT_SCAN_WARNING, refuse);
|
|
21
25
|
}
|
|
22
26
|
/** Per-field precedence: project > shared > user > extension > defaults. A set field wins; undefined falls through. */
|
|
23
27
|
export function mergeAgents(defaults, userAgents, sharedAgents, projectAgents) {
|