pi-cowboy 0.15.2 → 0.17.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (221) hide show
  1. package/README.md +12 -9
  2. package/dist/agents/agent-assets.d.ts +114 -0
  3. package/dist/agents/agent-assets.js +42 -29
  4. package/dist/agents/agent-cleanup.d.ts +82 -0
  5. package/dist/agents/agent-cleanup.js +6 -6
  6. package/dist/agents/agent-discovery.d.ts +22 -0
  7. package/dist/agents/agent-discovery.js +7 -3
  8. package/dist/agents/agent-host.d.ts +212 -0
  9. package/dist/agents/agent-host.js +6 -3
  10. package/dist/agents/agent-manager.d.ts +99 -0
  11. package/dist/agents/agent-manager.js +21 -9
  12. package/dist/agents/agent-reviver.d.ts +38 -0
  13. package/dist/agents/agent-runner.d.ts +51 -0
  14. package/dist/agents/agent-runner.js +22 -31
  15. package/dist/agents/agent-spawn-store.d.ts +39 -0
  16. package/dist/agents/agent-template.d.ts +118 -0
  17. package/dist/agents/agent-template.js +7 -3
  18. package/dist/agents/agent-types.d.ts +59 -0
  19. package/dist/agents/agent-types.js +22 -6
  20. package/dist/agents/batch.d.ts +63 -0
  21. package/dist/agents/cleanup-policy.d.ts +288 -0
  22. package/dist/agents/cleanup-policy.js +2 -2
  23. package/dist/agents/cleanup-report.d.ts +14 -0
  24. package/dist/agents/default-agents.d.ts +8 -0
  25. package/dist/agents/harness/claude/index.d.ts +41 -0
  26. package/dist/agents/harness/claude/index.js +49 -7
  27. package/dist/agents/harness/claude/staging.d.ts +46 -0
  28. package/dist/agents/harness/claude/staging.js +3 -2
  29. package/dist/agents/harness/codex.d.ts +42 -0
  30. package/dist/agents/harness/codex.js +3 -4
  31. package/dist/agents/harness/harness-registry.d.ts +126 -0
  32. package/dist/agents/harness/harness-registry.js +272 -0
  33. package/dist/agents/harness/opencode/config.d.ts +39 -0
  34. package/dist/agents/harness/opencode/config.js +85 -0
  35. package/dist/agents/harness/opencode/definition.d.ts +21 -0
  36. package/dist/agents/harness/opencode/index.d.ts +33 -0
  37. package/dist/agents/harness/opencode/index.js +22 -7
  38. package/dist/agents/harness/opencode/permissions.d.ts +27 -0
  39. package/dist/agents/harness/opencode/staging.d.ts +50 -0
  40. package/dist/agents/harness/opencode/staging.js +17 -3
  41. package/dist/agents/harness/opencode/user-config.d.ts +36 -0
  42. package/dist/agents/harness/opencode/user-config.js +172 -0
  43. package/dist/agents/harness/opencode/version.d.ts +36 -0
  44. package/dist/agents/harness/pane-launcher.d.ts +89 -0
  45. package/dist/agents/harness/pane-launcher.js +23 -22
  46. package/dist/agents/harness/pi-bolt.d.ts +9 -0
  47. package/dist/agents/harness/pi-bolt.js +0 -1
  48. package/dist/agents/harness/pi-compatible.d.ts +48 -0
  49. package/dist/agents/harness/pi-compatible.js +3 -4
  50. package/dist/agents/harness/pig.d.ts +10 -0
  51. package/dist/agents/harness/pig.js +0 -1
  52. package/dist/agents/harness.d.ts +459 -0
  53. package/dist/agents/harness.js +46 -57
  54. package/dist/agents/multiplexer-registry.d.ts +101 -0
  55. package/dist/agents/multiplexer-registry.js +125 -0
  56. package/dist/agents/result-file-permissions.d.ts +19 -0
  57. package/dist/agents/run-state.d.ts +144 -0
  58. package/dist/agents/schemas/cleanup-batch.schema.d.ts +17 -0
  59. package/dist/agents/schemas/cowboy-agents.schema.d.ts +51 -0
  60. package/dist/agents/schemas/cowboy-agents.schema.js +1 -1
  61. package/dist/agents/schemas/merge-batch.schema.d.ts +21 -0
  62. package/dist/agents/schemas/steer-batch.schema.d.ts +19 -0
  63. package/dist/agents/schemas/stop-batch.schema.d.ts +16 -0
  64. package/dist/agents/spawn-defaults.d.ts +48 -0
  65. package/dist/agents/spawn-defaults.js +22 -21
  66. package/dist/agents/subagent-session.d.ts +161 -0
  67. package/dist/agents/subagent-session.js +10 -5
  68. package/dist/agents/tool-cleanup.d.ts +43 -0
  69. package/dist/agents/tool-execution.d.ts +61 -0
  70. package/dist/agents/tool-merge.d.ts +64 -0
  71. package/dist/agents/tool-result.d.ts +21 -0
  72. package/dist/agents/tool-steer.d.ts +40 -0
  73. package/dist/agents/types.d.ts +94 -0
  74. package/dist/availability.d.ts +42 -0
  75. package/dist/concurrency-pools.d.ts +168 -0
  76. package/dist/concurrency-pools.js +11 -9
  77. package/dist/config/concurrency-limit.d.ts +12 -0
  78. package/dist/config/config-io.d.ts +59 -0
  79. package/dist/config/config-io.js +12 -20
  80. package/dist/config/config-store.d.ts +201 -0
  81. package/dist/config/config-store.js +89 -42
  82. package/dist/config/config-validation.d.ts +7 -0
  83. package/dist/config/config-validation.js +90 -63
  84. package/dist/config/layered-config.d.ts +47 -0
  85. package/dist/config/layered-config.js +4 -0
  86. package/dist/config/types.d.ts +8 -0
  87. package/dist/cow-support-launch.d.ts +18 -0
  88. package/dist/events.d.ts +9 -0
  89. package/dist/events.js +71 -19
  90. package/dist/extension-toggle.d.ts +13 -0
  91. package/dist/harness-availability-launch.d.ts +47 -0
  92. package/dist/harness-availability-launch.js +48 -33
  93. package/dist/host-multiplexer.d.ts +42 -0
  94. package/dist/host-multiplexer.js +62 -0
  95. package/dist/index.d.ts +10 -0
  96. package/dist/index.js +5 -16
  97. package/dist/infrastructure/exec-path.d.ts +13 -0
  98. package/dist/infrastructure/exec-sync.d.ts +18 -0
  99. package/dist/infrastructure/git/cow-clone.d.ts +111 -0
  100. package/dist/infrastructure/git/git-materializer.d.ts +146 -0
  101. package/dist/infrastructure/git/git-merger.d.ts +111 -0
  102. package/dist/infrastructure/git/git-merger.js +1 -1
  103. package/dist/infrastructure/git/git-retention.d.ts +21 -0
  104. package/dist/infrastructure/git/git-runner.d.ts +89 -0
  105. package/dist/infrastructure/git/git-worktree.d.ts +86 -0
  106. package/dist/infrastructure/git/index.d.ts +11 -0
  107. package/dist/infrastructure/git-client.d.ts +11 -0
  108. package/dist/infrastructure/herdr/agent-stopper.d.ts +33 -0
  109. package/dist/infrastructure/herdr/agents.d.ts +124 -0
  110. package/dist/infrastructure/herdr/agents.js +1 -1
  111. package/dist/infrastructure/herdr/herdr-client.d.ts +23 -0
  112. package/dist/infrastructure/herdr/herdr-transport.d.ts +57 -0
  113. package/dist/infrastructure/herdr/index.d.ts +15 -0
  114. package/dist/infrastructure/herdr/panes.d.ts +82 -0
  115. package/dist/infrastructure/herdr/polling.d.ts +41 -0
  116. package/dist/infrastructure/herdr/worktrees.d.ts +32 -0
  117. package/dist/infrastructure/herdr-client.d.ts +6 -0
  118. package/dist/infrastructure/herdr-host.d.ts +11 -0
  119. package/dist/infrastructure/herdr-host.js +55 -5
  120. package/dist/logger.d.ts +13 -0
  121. package/dist/models/foreign-model-resolver.d.ts +39 -0
  122. package/dist/models/model-groups.d.ts +56 -0
  123. package/dist/models/model-precedence.d.ts +135 -0
  124. package/dist/models/model-precedence.js +20 -7
  125. package/dist/models/model-request-types.d.ts +51 -0
  126. package/dist/models/model-request.d.ts +47 -0
  127. package/dist/models/pi-model-resolver.d.ts +35 -0
  128. package/dist/orchestrators/briefing-section.d.ts +9 -0
  129. package/dist/orchestrators/context.d.ts +143 -0
  130. package/dist/orchestrators/context.js +7 -1
  131. package/dist/orchestrators/cues.d.ts +31 -0
  132. package/dist/orchestrators/default-orchestrators.d.ts +10 -0
  133. package/dist/orchestrators/default-orchestrators.js +7 -2
  134. package/dist/orchestrators/orchestrator-discovery.d.ts +27 -0
  135. package/dist/orchestrators/orchestrator-template.d.ts +22 -0
  136. package/dist/orchestrators/orchestrator-types.d.ts +30 -0
  137. package/dist/orchestrators/protocol.d.ts +119 -0
  138. package/dist/orchestrators/protocol.js +7 -5
  139. package/dist/orchestrators/types.d.ts +18 -0
  140. package/dist/paths.d.ts +49 -0
  141. package/dist/paths.js +1 -1
  142. package/dist/pi-settings.d.ts +3 -0
  143. package/dist/plugin/contract.d.ts +56 -0
  144. package/dist/plugin/contract.js +17 -0
  145. package/dist/plugin/discovery.d.ts +59 -0
  146. package/dist/plugin/discovery.js +67 -0
  147. package/dist/plugin/index.d.ts +16 -0
  148. package/dist/plugin/index.js +14 -0
  149. package/dist/plugin/loader.d.ts +52 -0
  150. package/dist/plugin/loader.js +181 -0
  151. package/dist/plugin/manifest.d.ts +25 -0
  152. package/dist/plugin/manifest.js +47 -0
  153. package/dist/predicates.d.ts +18 -0
  154. package/dist/prompt/prompts.d.ts +40 -0
  155. package/dist/prompt/skill-loader.d.ts +28 -0
  156. package/dist/prompt/subagent-system-prompt.d.ts +50 -0
  157. package/dist/registration.d.ts +43 -0
  158. package/dist/registration.js +15 -3
  159. package/dist/session-runtime.d.ts +43 -0
  160. package/dist/session-runtime.js +92 -0
  161. package/dist/shell.d.ts +151 -0
  162. package/dist/shell.js +30 -5
  163. package/dist/spawn/cow-support.d.ts +26 -0
  164. package/dist/spawn/crockford-base32.d.ts +46 -0
  165. package/dist/spawn/crockford-base32.js +2 -2
  166. package/dist/spawn/herdr-launcher.d.ts +33 -0
  167. package/dist/spawn/repo-lock.d.ts +21 -0
  168. package/dist/spawn/sandbox.d.ts +130 -0
  169. package/dist/spawn/sandbox.js +3 -3
  170. package/dist/spawn/spawn-coordinator.d.ts +80 -0
  171. package/dist/spawn/spawn-coordinator.js +1 -1
  172. package/dist/spawn/spawn-id.d.ts +23 -0
  173. package/dist/spawn/worktree-policy.d.ts +68 -0
  174. package/dist/status-note.d.ts +7 -0
  175. package/dist/subagent/deliverable.d.ts +40 -0
  176. package/dist/subagent/pane-supervisor.d.ts +33 -0
  177. package/dist/subagent/pane-supervisor.js +1 -1
  178. package/dist/subagent/result-artifacts.d.ts +16 -0
  179. package/dist/subagent/supervisor.d.ts +157 -0
  180. package/dist/subagent/supervisor.js +4 -4
  181. package/dist/task-registry.d.ts +88 -0
  182. package/dist/task-registry.js +3 -3
  183. package/dist/templates/template-files.d.ts +35 -0
  184. package/dist/templates/template-files.js +8 -4
  185. package/dist/types.d.ts +268 -0
  186. package/dist/ui/action-report.d.ts +29 -0
  187. package/dist/ui/format.d.ts +17 -0
  188. package/dist/ui/indicator.d.ts +194 -0
  189. package/dist/ui/menu/helpers.d.ts +95 -0
  190. package/dist/ui/menu/menu-agent-settings.d.ts +8 -0
  191. package/dist/ui/menu/menu-agent-settings.js +18 -10
  192. package/dist/ui/menu/menu-agent-status-cleanup.d.ts +46 -0
  193. package/dist/ui/menu/menu-agent-status.d.ts +20 -0
  194. package/dist/ui/menu/menu-concurrency.d.ts +8 -0
  195. package/dist/ui/menu/menu-concurrency.js +11 -8
  196. package/dist/ui/menu/menu-model-settings.d.ts +30 -0
  197. package/dist/ui/menu/menu-model-settings.js +7 -5
  198. package/dist/ui/menu/menu-spawn-defaults.d.ts +20 -0
  199. package/dist/ui/menu/menu-spawn-wizard.d.ts +7 -0
  200. package/dist/ui/menu/menu-spawn-worktree.d.ts +46 -0
  201. package/dist/ui/menu/menu-system-prompt.d.ts +6 -0
  202. package/dist/ui/menu/menu-worktree-command.d.ts +17 -0
  203. package/dist/ui/menu/menus.d.ts +23 -0
  204. package/dist/ui/menu/model-picker.d.ts +19 -0
  205. package/dist/ui/menu/model-picker.js +2 -3
  206. package/dist/ui/menu/screen-host.d.ts +88 -0
  207. package/dist/ui/menu/submenus/confirm.d.ts +27 -0
  208. package/dist/ui/menu/submenus/model-select.d.ts +38 -0
  209. package/dist/ui/menu/submenus/name-field.d.ts +30 -0
  210. package/dist/ui/menu/submenus/numeric-input.d.ts +26 -0
  211. package/dist/ui/menu/submenus/target-select.d.ts +92 -0
  212. package/dist/ui/menu/submenus/text-editor.d.ts +42 -0
  213. package/dist/ui/menu/submenus/worktree-command-name.d.ts +40 -0
  214. package/dist/ui/menu/submenus/worktree-name.d.ts +39 -0
  215. package/dist/ui/menu/wrappers/settings-list.d.ts +41 -0
  216. package/dist/ui/searchable-select.d.ts +38 -0
  217. package/dist/ui/types.d.ts +7 -0
  218. package/dist/utils.d.ts +39 -0
  219. package/package.json +4 -2
  220. package/dist/agents/harness/registry.js +0 -76
  221. package/dist/agents/harness-family.js +0 -23
@@ -0,0 +1,118 @@
1
+ /**
2
+ * agent-template.ts — The Zod schema for one agent template file.
3
+ *
4
+ * Single source of truth for the `.toml` format: snake_case keys, values
5
+ * typed exactly as written, unknown keys rejected so typos fail at load.
6
+ * The type derives via `z.infer`.
7
+ */
8
+ import { z } from "zod";
9
+ import type { HarnessFamily } from "./harness.js";
10
+ import type { ToolFilter } from "./types.js";
11
+ export declare const AgentTemplateSchema: z.ZodObject<{
12
+ name: z.ZodOptional<z.ZodString>;
13
+ display_name: z.ZodOptional<z.ZodString>;
14
+ description: z.ZodOptional<z.ZodString>;
15
+ hidden: z.ZodOptional<z.ZodBoolean>;
16
+ worktree_checkout_type: z.ZodOptional<z.ZodEnum<{
17
+ dirty: "dirty";
18
+ clean: "clean";
19
+ }>>;
20
+ system_prompt: z.ZodOptional<z.ZodString>;
21
+ harness_type: z.ZodOptional<z.ZodString>;
22
+ harness: z.ZodOptional<z.ZodPipe<z.ZodObject<{
23
+ model: z.ZodOptional<z.ZodString>;
24
+ thinking: z.ZodOptional<z.ZodEnum<{
25
+ off: "off";
26
+ minimal: "minimal";
27
+ low: "low";
28
+ medium: "medium";
29
+ high: "high";
30
+ xhigh: "xhigh";
31
+ max: "max";
32
+ }>>;
33
+ extensions: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
34
+ skills: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
35
+ inlined_skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
36
+ fork: z.ZodOptional<z.ZodBoolean>;
37
+ tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
38
+ exclude_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
39
+ include_context_files: z.ZodOptional<z.ZodBoolean>;
40
+ pi: z.ZodOptional<z.ZodObject<{
41
+ model: z.ZodOptional<z.ZodString>;
42
+ thinking: z.ZodOptional<z.ZodEnum<{
43
+ off: "off";
44
+ minimal: "minimal";
45
+ low: "low";
46
+ medium: "medium";
47
+ high: "high";
48
+ xhigh: "xhigh";
49
+ max: "max";
50
+ }>>;
51
+ extensions: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
52
+ skills: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
53
+ inlined_skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
54
+ fork: z.ZodOptional<z.ZodBoolean>;
55
+ tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
56
+ exclude_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
57
+ }, z.core.$strict>>;
58
+ opencode: z.ZodOptional<z.ZodObject<{
59
+ model: z.ZodOptional<z.ZodString>;
60
+ variant: z.ZodOptional<z.ZodString>;
61
+ tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
62
+ exclude_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
63
+ }, z.core.$strict>>;
64
+ codex: z.ZodOptional<z.ZodObject<{
65
+ model: z.ZodOptional<z.ZodString>;
66
+ }, z.core.$strict>>;
67
+ claude: z.ZodOptional<z.ZodObject<{
68
+ model: z.ZodOptional<z.ZodString>;
69
+ tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
70
+ exclude_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
71
+ }, z.core.$strict>>;
72
+ }, z.core.$strict>, z.ZodTransform<{
73
+ toolsByFamily?: Partial<Record<HarnessFamily, ToolFilter>> | undefined;
74
+ modelsByFamily?: Partial<Record<HarnessFamily, string>> | undefined;
75
+ variant?: string | undefined;
76
+ thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;
77
+ extensions?: boolean | string[] | undefined;
78
+ skills?: boolean | string[] | undefined;
79
+ inlined_skills?: string[] | undefined;
80
+ fork?: boolean | undefined;
81
+ include_context_files?: boolean | undefined;
82
+ }, {
83
+ model?: string | undefined;
84
+ thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;
85
+ extensions?: boolean | string[] | undefined;
86
+ skills?: boolean | string[] | undefined;
87
+ inlined_skills?: string[] | undefined;
88
+ fork?: boolean | undefined;
89
+ tools?: string[] | undefined;
90
+ exclude_tools?: string[] | undefined;
91
+ include_context_files?: boolean | undefined;
92
+ pi?: {
93
+ model?: string | undefined;
94
+ thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;
95
+ extensions?: boolean | string[] | undefined;
96
+ skills?: boolean | string[] | undefined;
97
+ inlined_skills?: string[] | undefined;
98
+ fork?: boolean | undefined;
99
+ tools?: string[] | undefined;
100
+ exclude_tools?: string[] | undefined;
101
+ } | undefined;
102
+ opencode?: {
103
+ model?: string | undefined;
104
+ variant?: string | undefined;
105
+ tools?: string[] | undefined;
106
+ exclude_tools?: string[] | undefined;
107
+ } | undefined;
108
+ codex?: {
109
+ model?: string | undefined;
110
+ } | undefined;
111
+ claude?: {
112
+ model?: string | undefined;
113
+ tools?: string[] | undefined;
114
+ exclude_tools?: string[] | undefined;
115
+ } | undefined;
116
+ }>>>;
117
+ }, z.core.$strict>;
118
+ export type AgentTemplate = z.infer<typeof AgentTemplateSchema>;
@@ -9,7 +9,6 @@ import { z } from "zod";
9
9
  import { VALID_THINKING_LEVELS } from "../utils.js";
10
10
  import { VALID_WORKTREE_CHECKOUT_TYPES } from "../spawn/worktree-policy.js";
11
11
  import { compactDefined } from "../templates/template-files.js";
12
- import { HARNESS_IDS } from "./harness.js";
13
12
  const filterList = z.union([z.boolean(), z.array(z.string())]);
14
13
  /**
15
14
  * The pi family's own `[harness]` keys, shared by their `[harness.pi]` table
@@ -141,8 +140,13 @@ export const AgentTemplateSchema = z.strictObject({
141
140
  worktree_checkout_type: z.enum(VALID_WORKTREE_CHECKOUT_TYPES).optional(),
142
141
  /** Absent falls through the merge to inherit an earlier layer's prompt; an explicitly empty string clears it. */
143
142
  system_prompt: z.string().optional(),
144
- /** Which harness owns this agent's launch; omitted falls through to the configured default. */
145
- harness_type: z.enum(HARNESS_IDS).optional(),
143
+ /**
144
+ * Which harness owns this agent's launch; omitted falls through to the
145
+ * configured default. Any id — a built-in's or a plugin's — because the
146
+ * session's registry decides which ids exist (see agent-types.ts): a value no
147
+ * harness registered is a file the scan skips, so a typo stays loud.
148
+ */
149
+ harness_type: z.string().min(1).optional(),
146
150
  /** How the child process is launched. Omitted = every field's default. */
147
151
  harness: HarnessSchema.optional(),
148
152
  });
@@ -0,0 +1,59 @@
1
+ /**
2
+ * agent-types.ts — Unified agent type registry.
3
+ *
4
+ * Precedence: default < extension < user < shared < project. Hidden agents
5
+ * stay registered but are excluded from spawning.
6
+ *
7
+ * The registry is session state; it lives in the shell and is read and written
8
+ * here through the shell getters.
9
+ */
10
+ import type { AgentConfig } from "./types.js";
11
+ interface RegisterAgentsOptions {
12
+ disableDefaultAgents?: boolean;
13
+ }
14
+ /** Warning sink for unloadable agent files; injected so the scan layer stays shell-free. */
15
+ type DiscoveryNotify = (message: string, kind: "warning") => void;
16
+ export declare function registerAgents(userAgents: Map<string, AgentConfig>, options?: RegisterAgentsOptions): void;
17
+ export declare function setAgentScanDirs(userDir: string, projectDir: string, sharedDir?: string): void;
18
+ export declare function scanAndMerge(options?: {
19
+ disableDefaultAgents?: boolean;
20
+ notify?: DiscoveryNotify;
21
+ }): Promise<Map<string, AgentConfig>>;
22
+ /** Worktree agents follow the parent project's uniqueness rules. */
23
+ export declare function discoverNewAgents(worktreeDir?: string, options?: {
24
+ disableDefaultAgents?: boolean;
25
+ notify?: DiscoveryNotify;
26
+ }): Promise<number>;
27
+ /**
28
+ * Result of resolving a type name against the registry.
29
+ *
30
+ * - resolved: exact match, or one case-insensitive match (key is canonical).
31
+ * - ambiguous: several names differ only by case; never a silent pick.
32
+ * - not-found: nothing matches, even after case folding.
33
+ *
34
+ * Only registered names resolve (displayName is display-only). Hidden agents
35
+ * still resolve by name.
36
+ */
37
+ type TypeResolution = {
38
+ kind: "resolved";
39
+ key: string;
40
+ } | {
41
+ kind: "ambiguous";
42
+ candidates: string[];
43
+ } | {
44
+ kind: "not-found";
45
+ };
46
+ export declare function resolveType(name: string): TypeResolution;
47
+ /** Resolve a type, discovering from worktreeDir on miss. Trust/validation checks stay in the caller. */
48
+ export declare function resolveTypeOrDiscover(type: string, worktreeDir?: string, notify?: DiscoveryNotify): Promise<TypeResolution>;
49
+ export declare function getAgentConfig(name: string): AgentConfig | undefined;
50
+ export declare function getAvailableTypes(): string[];
51
+ export declare function getAllTypes(): string[];
52
+ export interface ResolvedAgentConfig {
53
+ displayName: string;
54
+ description: string;
55
+ extensions: true | string[] | false;
56
+ skills: true | string[] | false;
57
+ }
58
+ export declare function getConfig(type: string, loadSkillsImplicitly?: boolean, loadExtensionsImplicitly?: boolean): ResolvedAgentConfig;
59
+ export {};
@@ -8,12 +8,28 @@
8
8
  * here through the shell getters.
9
9
  */
10
10
  import { EXTENSION_AGENTS_DIR } from "../paths.js";
11
- import { getSessionTemplates } from "../shell.js";
11
+ import { getHarnessRegistry, getSessionTemplates, } from "../shell.js";
12
12
  import { scanAgentFilesInDir, mergeAgents, } from "./agent-discovery.js";
13
13
  import { DEFAULT_AGENTS } from "./default-agents.js";
14
14
  function registry() {
15
15
  return getSessionTemplates().agents;
16
16
  }
17
+ /**
18
+ * Why a template's `harness_type` is unusable this session: an id no harness
19
+ * registered — a typo, or a plugin this session did not load. The scan skips
20
+ * the file, so the value never silently degrades to pi. Registration is the
21
+ * test, not availability: a registered harness this machine cannot launch is
22
+ * the template-and-config fallback case, not a typo.
23
+ */
24
+ function unregisteredHarness(template) {
25
+ const id = template.harness_type;
26
+ if (id === undefined)
27
+ return undefined;
28
+ const harnesses = getHarnessRegistry();
29
+ if (harnesses.get(id) !== undefined)
30
+ return undefined;
31
+ return `harness_type "${id}" names no harness this session registered (registered: ${harnesses.ids().join(", ")})`;
32
+ }
17
33
  export function registerAgents(userAgents, options) {
18
34
  const agents = new Map();
19
35
  if (!options?.disableDefaultAgents) {
@@ -40,10 +56,10 @@ export async function scanAndMerge(options) {
40
56
  const [extensionAgents, userAgents, sharedAgents, projectAgents] = await Promise.all([
41
57
  disableDefaults
42
58
  ? Promise.resolve([])
43
- : scanAgentFilesInDir(EXTENSION_AGENTS_DIR, notify),
44
- scanAgentFilesInDir(scanDirs.user, notify),
45
- scanAgentFilesInDir(scanDirs.shared, notify),
46
- scanAgentFilesInDir(scanDirs.project, notify),
59
+ : scanAgentFilesInDir(EXTENSION_AGENTS_DIR, notify, unregisteredHarness),
60
+ scanAgentFilesInDir(scanDirs.user, notify, unregisteredHarness),
61
+ scanAgentFilesInDir(scanDirs.shared, notify, unregisteredHarness),
62
+ scanAgentFilesInDir(scanDirs.project, notify, unregisteredHarness),
47
63
  ]);
48
64
  const defaults = disableDefaults
49
65
  ? new Map()
@@ -64,7 +80,7 @@ export async function discoverNewAgents(worktreeDir, options) {
64
80
  }
65
81
  }
66
82
  if (worktreeDir) {
67
- const worktreeAgents = await scanAgentFilesInDir(worktreeDir, options?.notify);
83
+ const worktreeAgents = await scanAgentFilesInDir(worktreeDir, options?.notify, unregisteredHarness);
68
84
  const wtMerged = mergeAgents(new Map(), [], [], worktreeAgents);
69
85
  for (const [name, config] of wtMerged) {
70
86
  if (!agents.has(name)) {
@@ -0,0 +1,63 @@
1
+ /**
2
+ * batch.ts — the batch pipeline every Cowboy batch tool runs.
3
+ *
4
+ * A batch tool handles one or more items of the same kind, and the sequence is
5
+ * the same for all of them: reject a repeated key before touching anything, run
6
+ * the tool's remaining whole-call guards, handle the items one at a time in
7
+ * input order, and return one text block per item next to the per-item
8
+ * outcomes. A tool supplies only its own parts — which parameter it walks, the
9
+ * per-item work, and the rule for a halted batch.
10
+ */
11
+ import { type ToolResult } from "./tool-result.js";
12
+ /** Between the per-item blocks of a batch result: one batch reads as one document of item blocks. */
13
+ export declare const BATCH_ITEM_SEPARATOR = "\n\n---\n\n";
14
+ /** The array parameter a batch walks. */
15
+ export type BatchParam = "agent_ids" | "branches";
16
+ /** One handled item: its outcome for `details`, and the text block for its slot in the batch text. */
17
+ export interface BatchItem<TOutcome> {
18
+ outcome: TOutcome;
19
+ text: string;
20
+ }
21
+ /** One item an outcome halted the batch on, and how every later item is skipped. */
22
+ type HaltRule<TOutcome, TUnit> = {
23
+ on: (outcome: TOutcome) => boolean;
24
+ skip: (item: string, haltedBy: string) => TUnit;
25
+ };
26
+ /**
27
+ * How a tool produces one item's block. Usually the block reads off the outcome
28
+ * alone, and `render` says how; where it carries per-item state the outcome
29
+ * does not — steer's pre-delivery status, merge's raw git message and
30
+ * outside-repo banner — the handler pairs the outcome with its block instead.
31
+ *
32
+ * The pairing shape comes first because inference does not revisit a union
33
+ * member: a pairing tool's spec has to be matched against it before the
34
+ * renderer's `handleItem`, which would otherwise pin the outcome to the pair.
35
+ */
36
+ type ItemHandler<TOutcome> = {
37
+ handleItem: (item: string) => Promise<BatchItem<TOutcome>>;
38
+ halt?: HaltRule<TOutcome, BatchItem<TOutcome>>;
39
+ } | {
40
+ render: (outcome: TOutcome) => string;
41
+ handleItem: (item: string) => Promise<TOutcome>;
42
+ halt?: HaltRule<TOutcome, TOutcome>;
43
+ };
44
+ /** One batch tool's own parts of the pipeline. */
45
+ export type BatchSpec<TOutcome, TKey extends string> = ItemHandler<TOutcome> & {
46
+ /** Tool name as the model sees it, which opens the duplicate-key error. */
47
+ toolName: string;
48
+ /** The parameter the tool walks, e.g. `agent_ids`. */
49
+ param: BatchParam;
50
+ /** The whole call's items, in input order. */
51
+ items: readonly string[];
52
+ /** The `details` key the outcomes are returned under, e.g. `agents`. */
53
+ detailsKey: TKey;
54
+ /** The tool's whole-call guards beyond the duplicate check; runs before the first item, so a refusal mutates nothing. */
55
+ prepare?: () => void | Promise<void>;
56
+ };
57
+ /**
58
+ * Runs one batch: the duplicate-key guard, the tool's remaining guards, then
59
+ * the items sequentially in input order. Each item contributes exactly one
60
+ * outcome and one text block, so `details` and the text always line up.
61
+ */
62
+ export declare function runBatch<TOutcome, TKey extends string>(spec: BatchSpec<TOutcome, TKey>): Promise<ToolResult<Record<TKey, TOutcome[]>>>;
63
+ export {};
@@ -0,0 +1,288 @@
1
+ /**
2
+ * cleanup-policy.ts — pure cleanup decisions (no I/O).
3
+ * Located artifacts: LocatedWorktree/LocatedPane/LocatedArtifacts.
4
+ * Plan: CleanupPlan/planRecovered. Gate: GateOutcome/assessRemovability.
5
+ * Settlement: SettlementVerdict/recordedSettlement/recoveryGate/recoveryRefusalReason.
6
+ * Report: CleanupReport/keptReport/ambiguousReport/assembleReport/forcedFields/isForceableRefusal/shouldDropSpawn.
7
+ * Removal: RemovalOutcomes/RemovablePlan/WorktreeRemovalMechanism/PaneDisposition/removalMechanismOf/paneDispositionFor.
8
+ * Probes: WorktreeDirtyProbe. Options: CleanupOptions. Source: CleanupSource. Basis: DiscoveryBasis.
9
+ */
10
+ import type { ActivePhase, AgentPhase, AgentSpawn, WorktreeRetentionReason } from "../types.js";
11
+ import type { BranchCleanupResult } from "../infrastructure/git-client.js";
12
+ import type { HostObservation } from "./agent-host.js";
13
+ /** Refusal for a live run: cleanup never stops an agent (a stale registry entry is not evidence work is over; see stop_cowboy_agent). */
14
+ type AgentActiveReason = {
15
+ kind: "agent-active";
16
+ phase: ActivePhase;
17
+ };
18
+ /** Refusal for a recovered run: pane still `working`, or unreadable (never evidence the run is over); basis says which. */
19
+ type RecoveredRefusalReason = {
20
+ kind: "recovered-refusal";
21
+ basis: DiscoveryBasis;
22
+ };
23
+ /** Refusal for a contested id: cleanup picks neither artifact, the report lists both. */
24
+ type AmbiguousArtifactsReason = {
25
+ kind: "ambiguous-artifacts";
26
+ candidates: readonly string[];
27
+ };
28
+ /** Why a worktree was kept instead of removed. */
29
+ export type WorktreeKeptReason = WorktreeRetentionReason | AgentActiveReason | RecoveredRefusalReason | AmbiguousArtifactsReason;
30
+ /** Artifact provenance: `tracked` (spawn record named them) or `recovered` (discovery found them). */
31
+ export type CleanupSource = "tracked" | "recovered";
32
+ /** What the multiplexer's live read showed for a recovered run (`forced` is the operator override). */
33
+ export type DiscoveryBasis = {
34
+ kind: "pane-absent";
35
+ } | {
36
+ kind: "pane-not-working";
37
+ state: HostObservation["state"];
38
+ } | {
39
+ kind: "forced";
40
+ } | {
41
+ kind: "pane-working";
42
+ } | {
43
+ kind: "pane-unreadable";
44
+ detail: string;
45
+ } | {
46
+ kind: "artifacts-ambiguous";
47
+ };
48
+ /** Recovered run's deliverable; reported, never deleted (nobody has read it). */
49
+ export interface RecoveredDeliverable {
50
+ path: string;
51
+ /** Whether a deliverable was actually written (an agent may have died first). */
52
+ present: boolean;
53
+ }
54
+ /** The tracked-path verdict: memory's recorded lifecycle phase is the answer. */
55
+ interface RecordedSettlement {
56
+ kind: "recorded";
57
+ phase: AgentPhase;
58
+ }
59
+ /** Recovered-path verdict: the multiplexer's live read plus the unread deliverable. */
60
+ interface DiscoveredSettlement {
61
+ kind: "discovered";
62
+ basis: DiscoveryBasis;
63
+ deliverable: RecoveredDeliverable;
64
+ }
65
+ /** How cleanup established the run is over: `recorded` (memory is the only settlement witness) or `discovered` (the multiplexer's live read + unread deliverable). */
66
+ export type SettlementVerdict = RecordedSettlement | DiscoveredSettlement;
67
+ export declare function recordedSettlement(spawn: AgentSpawn): RecordedSettlement;
68
+ /**
69
+ * What cleanup reports for the run's pane. `open` is stated only for a pane
70
+ * the seam observed live; `gone` is stated only for an address the multiplexer no
71
+ * longer answers (never `closed`: the extension did not close it);
72
+ * `unknown` is stated only when the read itself failed (never evidence
73
+ * either way); `none` means the run never had a pane address.
74
+ */
75
+ export type PaneOutcome = {
76
+ kind: "closed";
77
+ paneId: string;
78
+ } | {
79
+ kind: "open";
80
+ paneId: string;
81
+ } | {
82
+ kind: "gone";
83
+ paneId: string;
84
+ } | {
85
+ kind: "unknown";
86
+ paneId: string;
87
+ } | {
88
+ kind: "none";
89
+ };
90
+ export type WorktreeOutcome = {
91
+ kind: "removed";
92
+ path: string;
93
+ } | {
94
+ kind: "removal-failed";
95
+ path: string;
96
+ detail: string;
97
+ }
98
+ /** `path` null when the run never recorded one; the reason to keep it rides the report's verdict. */
99
+ | {
100
+ kind: "kept";
101
+ path: string | null;
102
+ } | {
103
+ kind: "absent";
104
+ path: string;
105
+ } | {
106
+ kind: "none";
107
+ };
108
+ /** The override a forced teardown carries: the refusal it bypassed (menu-only; the tool never forces). */
109
+ export type ForcedOverride = {
110
+ reason?: WorktreeKeptReason;
111
+ };
112
+ /**
113
+ * What cleanup did with the run as a whole: tore down its artifacts, or refused
114
+ * to touch them and says why. Only a teardown can carry `forced`; only a refusal
115
+ * carries `forceable` — whether the operator override (`CleanupOptions.force`)
116
+ * can change the answer. The menu offers Force only for a forceable refusal;
117
+ * every other refusal is final.
118
+ */
119
+ export type CleanupVerdictOutcome = {
120
+ kind: "torn-down";
121
+ forced?: ForcedOverride;
122
+ } | {
123
+ kind: "refused";
124
+ reason: WorktreeKeptReason;
125
+ forceable: boolean;
126
+ };
127
+ /** Structured cleanup result for the orchestrator (not prose); report-gated and best effort — unsettled runs are refused, the rest reports what it could not remove. */
128
+ export interface CleanupReport {
129
+ agentId: string;
130
+ /** Where the plan's artifacts came from (see CleanupSource). */
131
+ source: CleanupSource;
132
+ /** The verdict itself: a refusal always names its reason, whether or not a worktree was at stake. */
133
+ outcome: CleanupVerdictOutcome;
134
+ /** The run's established end-state; cleanup never changes run state, only tears down ended runs. */
135
+ settlement: SettlementVerdict;
136
+ /** The subagent's pane after cleanup (none = never had one). */
137
+ pane: PaneOutcome;
138
+ /** The extension-owned worktree after cleanup (none = never created one; absent = already gone from disk). */
139
+ worktree: WorktreeOutcome;
140
+ /** What happened to the agent's branch. */
141
+ branch: BranchCleanupResult;
142
+ /** Branch ref; invariant: present iff the worktree existed (pinned at worktree-create time). */
143
+ branchName?: string;
144
+ }
145
+ export interface CleanupOptions {
146
+ /** Skip the removability gate: remove the worktree even when dirty/unverifiable. `reason` is the refusal this override bypassed. */
147
+ force?: ForcedOverride;
148
+ }
149
+ /** Checkout for one agent id. `repoCwd` derives from the checkout itself — a wrong-repo cwd would delete a same-named branch elsewhere; absent means unresolvable (a refusal, not a fallback). */
150
+ interface LocatedWorktree {
151
+ path: string;
152
+ repoCwd?: string;
153
+ workspaceId?: string;
154
+ }
155
+ /** Pane addressing a run: a live placement record or memory's address. */
156
+ export interface LocatedPane {
157
+ paneId: string;
158
+ tabId?: string;
159
+ workspaceId?: string;
160
+ }
161
+ /** Locator answer for one agent id. Provenance is memory-only; addresses are live probes, which may correct a stale record. */
162
+ export interface LocatedArtifacts {
163
+ id: string;
164
+ /** The run's branch (`cow-<slug>-<id>`), from memory or the discovered checkout. */
165
+ branch: string;
166
+ /** Provenance: the extension created this tree (memory, or the extension-worktree rule). */
167
+ worktreeManaged: boolean;
168
+ /** Provenance: the extension created this pane. Never claimed for a recovered run. */
169
+ paneCreated: boolean;
170
+ /** The checkout memory named or discovery found; null when nothing on disk answers. */
171
+ worktree: LocatedWorktree | null;
172
+ /** The pane addressing this run; null when nothing addresses one. */
173
+ pane: LocatedPane | null;
174
+ }
175
+ /** Pane as cleanup sees it; only `self-created` may be closed. */
176
+ export interface PaneTarget {
177
+ paneId: string;
178
+ /** Self-created panes are closed by cleanup; adopted panes never are. */
179
+ origin: "self-created" | "adopted";
180
+ }
181
+ export interface WorktreeTarget {
182
+ /** Absent for a git-only checkout or a reconstructed spawn without a placement identity. */
183
+ workspaceId?: string;
184
+ worktreePath: string;
185
+ repoCwd: string;
186
+ branchName: string;
187
+ }
188
+ /** What a run owns: no partial worktree state — an unresolved managed tree is `worktree-unlocatable`, never `no-worktree`; `null` is genuine absence. */
189
+ export type CleanupPlan = {
190
+ kind: "worktree";
191
+ worktree: WorktreeTarget;
192
+ pane: PaneTarget | null;
193
+ } | {
194
+ kind: "worktree-unlocatable";
195
+ branchName: string;
196
+ /** null = no path was ever recorded or discovered for the worktree. */
197
+ worktreePath: string | null;
198
+ pane: PaneTarget | null;
199
+ } | {
200
+ kind: "no-worktree";
201
+ pane: PaneTarget | null;
202
+ };
203
+ /** Narrow located artifacts into a plan (pure): resolved managed tree → worktree (missing workspace still goes via git); unresolved managed tree → worktree-unlocatable (never no-worktree, so nothing leaks); recovered panes are never self-created. */
204
+ export declare function planRecovered(artifacts: LocatedArtifacts): CleanupPlan;
205
+ export type GateOutcome = {
206
+ kind: "removable";
207
+ } | {
208
+ kind: "kept";
209
+ reason: WorktreeRetentionReason;
210
+ };
211
+ type WorktreeDirtyProbe = (worktreePath: string) => Promise<boolean | undefined>;
212
+ /** Removability gate: dirty/unverifiable blocks (the only way removal loses work); unmerged does not (the branch survives in the repo); force skips the probe. */
213
+ export declare function assessRemovability(isDirty: WorktreeDirtyProbe, opts: CleanupOptions | undefined, worktree: WorktreeTarget): Promise<GateOutcome>;
214
+ export type RemovalOutcomes = {
215
+ pane: PaneOutcome;
216
+ worktree: WorktreeOutcome;
217
+ branch: BranchCleanupResult;
218
+ };
219
+ /** The plan kinds that can actually be removed (unlocatable never reaches removal). */
220
+ export type RemovablePlan = Extract<CleanupPlan, {
221
+ kind: "worktree" | "no-worktree";
222
+ }>;
223
+ /**
224
+ * Recovered-path settlement: tear down only when the multiplexer's read cannot show
225
+ * live work (pane gone or non-working); `working` refuses. Unreadable reads
226
+ * never reach here — the caller refuses on a throw. (Refusing anything but
227
+ * gone panes would be a one-line change to the second branch.)
228
+ */
229
+ export type RecoveryGate = {
230
+ kind: "allow";
231
+ basis: DiscoveryBasis;
232
+ } | {
233
+ kind: "refuse";
234
+ basis: DiscoveryBasis;
235
+ };
236
+ export declare function recoveryGate(observation: HostObservation | undefined): RecoveryGate;
237
+ export declare function recoveryRefusalReason(basis: DiscoveryBasis): WorktreeKeptReason;
238
+ /** Refusal report shared by all early returns; the reason rides the verdict, so it survives even with no worktree to name. `refusal.forceable` marks a refusal the operator override can change (see CleanupVerdictOutcome). A refusal closes nothing, so its pane is always reported open. */
239
+ export declare function keptReport(agentId: string, source: CleanupSource, plan: CleanupPlan, settlement: SettlementVerdict, refusal: {
240
+ reason: WorktreeKeptReason;
241
+ forceable: boolean;
242
+ }): CleanupReport;
243
+ /** Contested-id report: cleanup removes nothing (not even the branch) and lists candidates for the orchestrator. */
244
+ export declare function ambiguousReport(agentId: string, source: CleanupSource, settlement: SettlementVerdict, candidates: readonly string[]): CleanupReport;
245
+ /**
246
+ * The `forced` marker a teardown earned by overriding a removability gate, as a
247
+ * fragment for its `torn-down` outcome (`{}` for a routine teardown). The tool
248
+ * never forces, so only the menu sets it — and every teardown path spreads this,
249
+ * so the marker is invariant.
250
+ */
251
+ export declare function forcedFields(opts?: CleanupOptions): {
252
+ forced?: ForcedOverride;
253
+ };
254
+ export declare function assembleReport(agentId: string, source: CleanupSource, plan: CleanupPlan, settlement: SettlementVerdict, removal: RemovalOutcomes, opts?: CleanupOptions): CleanupReport;
255
+ /** A report whose refusal the operator override can change — `isForceableRefusal` narrows to it. */
256
+ export type ForceableRefusedReport = CleanupReport & {
257
+ outcome: {
258
+ kind: "refused";
259
+ forceable: true;
260
+ };
261
+ };
262
+ /**
263
+ * Whether the operator override can change a refusal's answer. The menu offers
264
+ * Force only for these: a live run, a contested id, and a tree with no address
265
+ * force can reach are final refusals, not candidates for a second attempt.
266
+ */
267
+ export declare function isForceableRefusal(report: CleanupReport): report is ForceableRefusedReport;
268
+ /**
269
+ * Drop a spawn once its tracked resources are gone; a kept/failed tree
270
+ * keeps its spawn so status still shows why. An absent tree drops too: a
271
+ * checkout that is not on disk cannot be removed and holds no work, and the
272
+ * branch is deliberately NOT deleted on that path (its commits live in the
273
+ * object store), so nothing recordable is lost by forgetting the record.
274
+ */
275
+ export declare function shouldDropSpawn(report: CleanupReport): boolean;
276
+ export type WorktreeRemovalMechanism = "multiplexer" | "git";
277
+ type PaneDisposition = {
278
+ kind: "none";
279
+ } | {
280
+ kind: "closed-with-workspace";
281
+ } | {
282
+ kind: "close";
283
+ } | {
284
+ kind: "leave-open";
285
+ };
286
+ export declare function removalMechanismOf(worktree: WorktreeTarget): WorktreeRemovalMechanism;
287
+ export declare function paneDispositionFor(pane: PaneTarget | null, mechanism: WorktreeRemovalMechanism | null, removed: boolean): PaneDisposition;
288
+ export {};
@@ -191,7 +191,7 @@ export function shouldDropSpawn(report) {
191
191
  return false;
192
192
  }
193
193
  export function removalMechanismOf(worktree) {
194
- return worktree.workspaceId !== undefined ? "herdr" : "git";
194
+ return worktree.workspaceId !== undefined ? "multiplexer" : "git";
195
195
  }
196
196
  export function paneDispositionFor(pane, mechanism, removed) {
197
197
  if (pane === null)
@@ -199,7 +199,7 @@ export function paneDispositionFor(pane, mechanism, removed) {
199
199
  if (!removed)
200
200
  return { kind: "leave-open" };
201
201
  switch (mechanism) {
202
- case "herdr":
202
+ case "multiplexer":
203
203
  return { kind: "closed-with-workspace" };
204
204
  // A git-side removal, or a plan with no tree at all, leaves the pane standing: only a pane the extension created may be closed.
205
205
  case "git":
@@ -0,0 +1,14 @@
1
+ /**
2
+ * cleanup-report.ts — a CleanupReport as prose: the summary the cleanup tool
3
+ * returns and the one line the menus notify. Each artifact's wording is
4
+ * written once here, so the tool's report and the menu's toast agree.
5
+ */
6
+ import type { CleanupReport, WorktreeKeptReason } from "./cleanup-policy.js";
7
+ /** The refusal wording, shared by the report and the menu's force dialog. */
8
+ export declare function formatKeptReason(reason: WorktreeKeptReason): string;
9
+ /** The tool's report: what happened to the run, its pane, worktree and branch. */
10
+ export declare function renderCleanupReport(report: CleanupReport): string;
11
+ /** The same report as one notification-sized line. */
12
+ export declare function summarizeCleanupReport(report: CleanupReport): string;
13
+ /** Whether the teardown left something behind that only the operator can settle. */
14
+ export declare function cleanupNeedsAttention(report: CleanupReport): boolean;
@@ -0,0 +1,8 @@
1
+ /**
2
+ * default-agents.ts — Embedded default agent configurations.
3
+ *
4
+ * Always available; overridable by same-named .toml files. Only
5
+ * general-purpose is embedded — other types are scanned .toml templates.
6
+ */
7
+ import type { AgentConfig } from "./types.js";
8
+ export declare const DEFAULT_AGENTS: Map<string, AgentConfig>;