pi-cowboy 0.0.0 → 0.3.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +281 -2
- package/agents/explore.toml +40 -0
- package/dist/agents/agent-assets.js +261 -0
- package/dist/agents/agent-cleanup.js +284 -0
- package/dist/agents/agent-discovery.js +108 -0
- package/dist/agents/agent-host.js +10 -0
- package/dist/agents/agent-manager.js +367 -0
- package/dist/agents/agent-reviver.js +64 -0
- package/dist/agents/agent-runner.js +288 -0
- package/dist/agents/agent-spawn-store.js +57 -0
- package/dist/agents/agent-template.js +46 -0
- package/dist/agents/agent-types.js +144 -0
- package/dist/agents/batch.js +92 -0
- package/dist/agents/cleanup-policy.js +194 -0
- package/dist/agents/cleanup-report.js +128 -0
- package/dist/agents/default-agents.js +19 -0
- package/dist/agents/harness/pi-bolt.js +15 -0
- package/dist/agents/harness/pi-compatible.js +68 -0
- package/dist/agents/harness/pig.js +16 -0
- package/dist/agents/harness/registry.js +27 -0
- package/dist/agents/harness.js +32 -0
- package/dist/agents/result-file-permissions.js +29 -0
- package/dist/agents/run-state.js +270 -0
- package/dist/agents/schemas/cleanup-batch.schema.js +19 -0
- package/dist/agents/schemas/cowboy-agents.schema.js +39 -0
- package/dist/agents/schemas/merge-batch.schema.js +25 -0
- package/dist/agents/schemas/steer-batch.schema.js +22 -0
- package/dist/agents/schemas/stop-batch.schema.js +18 -0
- package/dist/agents/spawn-defaults.js +70 -0
- package/dist/agents/subagent-session.js +601 -0
- package/dist/agents/tool-cleanup.js +57 -0
- package/dist/agents/tool-execution.js +125 -0
- package/dist/agents/tool-merge.js +190 -0
- package/dist/agents/tool-result.js +17 -0
- package/dist/agents/tool-steer.js +89 -0
- package/dist/agents/types.js +1 -0
- package/dist/availability.js +38 -0
- package/dist/config/config-io.js +261 -0
- package/dist/config/config-store.js +321 -0
- package/dist/config/config-validation.js +173 -0
- package/dist/config/layered-config.js +117 -0
- package/dist/config/types.js +23 -0
- package/dist/cow-support-launch.js +43 -0
- package/dist/events.js +146 -0
- package/dist/extension-toggle.js +28 -0
- package/dist/harness-availability-launch.js +23 -0
- package/dist/index.js +52 -0
- package/dist/infrastructure/exec-path.js +35 -0
- package/dist/infrastructure/git/cow-clone.js +398 -0
- package/dist/infrastructure/git/git-materializer.js +342 -0
- package/dist/infrastructure/git/git-merger.js +234 -0
- package/dist/infrastructure/git/git-retention.js +43 -0
- package/dist/infrastructure/git/git-runner.js +145 -0
- package/dist/infrastructure/git/git-worktree.js +143 -0
- package/dist/infrastructure/git/index.js +11 -0
- package/dist/infrastructure/git-client.js +11 -0
- package/dist/infrastructure/herdr/agent-stopper.js +60 -0
- package/dist/infrastructure/herdr/agents.js +329 -0
- package/dist/infrastructure/herdr/herdr-client.js +36 -0
- package/dist/infrastructure/herdr/herdr-transport.js +158 -0
- package/dist/infrastructure/herdr/index.js +15 -0
- package/dist/infrastructure/herdr/panes.js +174 -0
- package/dist/infrastructure/herdr/polling.js +44 -0
- package/dist/infrastructure/herdr/worktrees.js +76 -0
- package/dist/infrastructure/herdr-client.js +6 -0
- package/dist/infrastructure/herdr-host.js +163 -0
- package/dist/logger.js +79 -0
- package/dist/models/model-groups.js +72 -0
- package/dist/models/model-precedence.js +50 -0
- package/dist/models/model-request.js +108 -0
- package/dist/orchestrators/briefing-section.js +14 -0
- package/dist/orchestrators/context.js +116 -0
- package/dist/orchestrators/cues.js +90 -0
- package/dist/orchestrators/default-orchestrators.js +36 -0
- package/dist/orchestrators/orchestrator-discovery.js +68 -0
- package/dist/orchestrators/orchestrator-template.js +43 -0
- package/dist/orchestrators/orchestrator-types.js +78 -0
- package/dist/orchestrators/protocol.js +292 -0
- package/dist/orchestrators/types.js +7 -0
- package/dist/paths.js +66 -0
- package/dist/pi-settings.js +7 -0
- package/dist/predicates.js +25 -0
- package/dist/prompt/prompts.js +110 -0
- package/dist/prompt/skill-loader.js +153 -0
- package/dist/prompt/subagent-system-prompt.js +173 -0
- package/dist/registration.js +220 -0
- package/dist/shell.js +225 -0
- package/dist/spawn/cow-support.js +53 -0
- package/dist/spawn/herdr-launcher.js +80 -0
- package/dist/spawn/repo-lock.js +34 -0
- package/dist/spawn/sandbox.js +286 -0
- package/dist/spawn/spawn-coordinator.js +255 -0
- package/dist/spawn/spawn-id.js +39 -0
- package/dist/spawn/worktree-policy.js +137 -0
- package/dist/status-note.js +30 -0
- package/dist/subagent/ipc-protocol.js +68 -0
- package/dist/subagent/ipc.js +110 -0
- package/dist/subagent/pane-supervisor.js +24 -0
- package/dist/subagent/socket-ipc.js +240 -0
- package/dist/subagent/supervisor.js +315 -0
- package/dist/task-registry.js +258 -0
- package/dist/templates/template-files.js +84 -0
- package/dist/types.js +84 -0
- package/dist/ui/action-report.js +21 -0
- package/dist/ui/format.js +47 -0
- package/dist/ui/indicator.js +480 -0
- package/dist/ui/menu/helpers.js +227 -0
- package/dist/ui/menu/menu-agent-settings.js +182 -0
- package/dist/ui/menu/menu-agent-status.js +444 -0
- package/dist/ui/menu/menu-concurrency.js +226 -0
- package/dist/ui/menu/menu-model-settings.js +244 -0
- package/dist/ui/menu/menu-spawn-defaults.js +71 -0
- package/dist/ui/menu/menu-spawn-wizard.js +367 -0
- package/dist/ui/menu/menu-spawn-worktree.js +107 -0
- package/dist/ui/menu/menu-system-prompt.js +104 -0
- package/dist/ui/menu/menu-worktree-command.js +150 -0
- package/dist/ui/menu/menus.js +187 -0
- package/dist/ui/menu/model-picker.js +160 -0
- package/dist/ui/menu/screen-host.js +87 -0
- package/dist/ui/menu/submenus/confirm.js +23 -0
- package/dist/ui/menu/submenus/model-select.js +42 -0
- package/dist/ui/menu/submenus/name-field.js +43 -0
- package/dist/ui/menu/submenus/numeric-input.js +61 -0
- package/dist/ui/menu/submenus/target-select.js +129 -0
- package/dist/ui/menu/submenus/text-editor.js +49 -0
- package/dist/ui/menu/submenus/worktree-command-name.js +73 -0
- package/dist/ui/menu/submenus/worktree-name.js +53 -0
- package/dist/ui/menu/wrappers/settings-list.js +101 -0
- package/dist/ui/searchable-select.js +147 -0
- package/dist/ui/types.js +1 -0
- package/dist/utils.js +70 -0
- package/docs/assets/grazing.png +0 -0
- package/docs/assets/herdr-containers.png +0 -0
- package/docs/assets/logo-transparent.png +0 -0
- package/orchestrators/with-code-review.toml +20 -0
- package/package.json +109 -3
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* model-request.ts — the cowboy_agent tool's model request and its resolution.
|
|
3
|
+
* Provenance is structural: the caller's OPTIONAL `model` param and the
|
|
4
|
+
* `tool_call` listener's `_configuredModel` channel are separate keys with one
|
|
5
|
+
* writer each, so a caller's model can never be mistaken for the injected
|
|
6
|
+
* value (which would silently run a different model).
|
|
7
|
+
*
|
|
8
|
+
* Resolution is the catalog lookup plus a credential probe. The probe exists
|
|
9
|
+
* because a catalog model with no credential stalls: the child prints its auth
|
|
10
|
+
* error and never settles on its own. Probing first turns that stall into a
|
|
11
|
+
* failed tool call. The probe reads `getProviderAuthStatus(provider).configured`
|
|
12
|
+
* — the same gate the child's session applies at turn start — and it is the
|
|
13
|
+
* only source: no fallback paths. It is a proxy, not a guarantee: it reads
|
|
14
|
+
* this session's in-memory credential status, so a present-but-unusable
|
|
15
|
+
* credential still passes.
|
|
16
|
+
*/
|
|
17
|
+
import { isRecord } from "../predicates.js";
|
|
18
|
+
import { errorMessage, findModelInRegistry } from "../utils.js";
|
|
19
|
+
/** The args key the `tool_call` listener injects the configured default under. */
|
|
20
|
+
export const CONFIGURED_MODEL_KEY = "_configuredModel";
|
|
21
|
+
/** Absent/null/empty/whitespace read as unset. */
|
|
22
|
+
export function readModelKey(value) {
|
|
23
|
+
return typeof value === "string" && value.trim() !== ""
|
|
24
|
+
? value.trim()
|
|
25
|
+
: undefined;
|
|
26
|
+
}
|
|
27
|
+
/** The caller's own request, or undefined. Read through here, never re-derived from args after the listener ran. */
|
|
28
|
+
export function readModelRequest(params) {
|
|
29
|
+
const called = readModelKey(params.model);
|
|
30
|
+
if (called)
|
|
31
|
+
return { source: "call", key: called };
|
|
32
|
+
const configured = readModelKey(params[CONFIGURED_MODEL_KEY]);
|
|
33
|
+
if (configured)
|
|
34
|
+
return { source: "configured", key: configured };
|
|
35
|
+
return undefined;
|
|
36
|
+
}
|
|
37
|
+
function modelKey(model) {
|
|
38
|
+
return `${model.provider}/${model.id}`;
|
|
39
|
+
}
|
|
40
|
+
function resolvedModel(model) {
|
|
41
|
+
return { kind: "resolved", model, modelKey: modelKey(model) };
|
|
42
|
+
}
|
|
43
|
+
/** Matches pi's own wording for a missing credential. */
|
|
44
|
+
function missingCredential(provider) {
|
|
45
|
+
return `No API key found for "${provider}"`;
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* Only an explicit FALSE reads as `unusable`. A probe that throws or answers
|
|
49
|
+
* an unrecognized shape is `inconclusive` — the probe could not complete, not
|
|
50
|
+
* proof of no credential — and the caller treats it like `usable`.
|
|
51
|
+
*/
|
|
52
|
+
function probeCredentials(registry, model) {
|
|
53
|
+
let status;
|
|
54
|
+
try {
|
|
55
|
+
status = registry.getProviderAuthStatus(model.provider);
|
|
56
|
+
}
|
|
57
|
+
catch (err) {
|
|
58
|
+
return { verdict: "inconclusive", reason: errorMessage(err) };
|
|
59
|
+
}
|
|
60
|
+
if (!isRecord(status) || typeof status.configured !== "boolean") {
|
|
61
|
+
return {
|
|
62
|
+
verdict: "inconclusive",
|
|
63
|
+
reason: "the registry reported no credential status for the provider",
|
|
64
|
+
};
|
|
65
|
+
}
|
|
66
|
+
return status.configured
|
|
67
|
+
? { verdict: "usable" }
|
|
68
|
+
: { verdict: "unusable", reason: missingCredential(model.provider) };
|
|
69
|
+
}
|
|
70
|
+
/** Every pre-spawn refusal states what failed and that nothing ran. */
|
|
71
|
+
function refusal(lead, reason) {
|
|
72
|
+
return `${lead}: ${reason}. Nothing was spawned.`;
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* Runs BEFORE worktree resolution, so a refusal fails the call without
|
|
76
|
+
* spawning anything or touching the in-flight attempt. Catalog rules: `call`
|
|
77
|
+
* is strict (unknown key throws — silently running another model is worse);
|
|
78
|
+
* `configured` keeps the soft fallback to the parent for a key gone from the
|
|
79
|
+
* catalog; no request pins the parent's model. Credentials are never
|
|
80
|
+
* softened, whatever the source: substituting another model would run one
|
|
81
|
+
* nobody asked for. `{ kind: "none" }` means no model to hand the child.
|
|
82
|
+
*/
|
|
83
|
+
export function resolveModelRequest(request, registry, parent) {
|
|
84
|
+
if (!request) {
|
|
85
|
+
if (!parent)
|
|
86
|
+
return { kind: "none" };
|
|
87
|
+
const probe = probeCredentials(registry, parent);
|
|
88
|
+
if (probe.verdict !== "unusable")
|
|
89
|
+
return resolvedModel(parent);
|
|
90
|
+
throw new Error(refusal(`The parent session's model "${modelKey(parent)}" did not resolve credentials in this session`, probe.reason));
|
|
91
|
+
}
|
|
92
|
+
const found = request.source === "call"
|
|
93
|
+
? findModelInRegistry(request.key, registry, undefined)
|
|
94
|
+
: findModelInRegistry(request.key, registry, parent);
|
|
95
|
+
if (!found) {
|
|
96
|
+
if (request.source === "call") {
|
|
97
|
+
throw new Error(`Model "${request.key}" is not available in this session. Nothing was spawned.`);
|
|
98
|
+
}
|
|
99
|
+
return { kind: "none" };
|
|
100
|
+
}
|
|
101
|
+
const probe = probeCredentials(registry, found);
|
|
102
|
+
if (probe.verdict !== "unusable")
|
|
103
|
+
return resolvedModel(found);
|
|
104
|
+
if (request.source === "call") {
|
|
105
|
+
throw new Error(refusal(`Model "${modelKey(found)}" cannot authenticate in this session`, probe.reason));
|
|
106
|
+
}
|
|
107
|
+
throw new Error(refusal(`The subagent model "${modelKey(found)}" for this configured default cannot authenticate in this session`, probe.reason));
|
|
108
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* briefing-section.ts — Renders the resolved template's `guidance` as the
|
|
3
|
+
* briefing's `## Orchestrator Guidance` section.
|
|
4
|
+
*
|
|
5
|
+
* Renders `guidance` verbatim. Spliced in LAST by buildLaunchPlan, so the
|
|
6
|
+
* guidance stays maximally close to the work in every inference request.
|
|
7
|
+
*/
|
|
8
|
+
/** The `## Orchestrator Guidance` section, or `""` when the template declared none. */
|
|
9
|
+
export function buildOrchestrationGuidance(agentGuidance) {
|
|
10
|
+
if (!agentGuidance?.trim())
|
|
11
|
+
return "";
|
|
12
|
+
// Template-authored text: copied byte-for-byte, never trimmed or reworded.
|
|
13
|
+
return ["## Orchestrator Guidance", "", agentGuidance].join("\n");
|
|
14
|
+
}
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* context.ts — Per-cue template variables and the pure builders producing them.
|
|
3
|
+
*
|
|
4
|
+
* A variable exists only on the cue that renders it, so a template naming
|
|
5
|
+
* what its cue cannot supply fails validation instead of rendering empty.
|
|
6
|
+
* Builders take explicit inputs (never an AgentSpawn). An inapplicable fact
|
|
7
|
+
* is ABSENT — never empty-string filler — so templates branch with
|
|
8
|
+
* `{{#name}}` / `{{^name}}`.
|
|
9
|
+
*
|
|
10
|
+
* The flat `{{snake_case}}` keys are the Mustache contract: the worktree
|
|
11
|
+
* facts and the settled outcome each have exactly one present shape and one
|
|
12
|
+
* absent shape, so a half-present worktree or a result alongside an error
|
|
13
|
+
* cannot be constructed.
|
|
14
|
+
*/
|
|
15
|
+
// --- Builders ---
|
|
16
|
+
/** The present worktree block; the caller adds it only when there is a tree. */
|
|
17
|
+
function worktreeVariables(worktree) {
|
|
18
|
+
return {
|
|
19
|
+
has_worktree: true,
|
|
20
|
+
worktree_path: worktree.path,
|
|
21
|
+
worktree_branch: worktree.branch,
|
|
22
|
+
};
|
|
23
|
+
}
|
|
24
|
+
/** Exactly one outcome shape; an empty result is absent, never filler. */
|
|
25
|
+
function outcomeVariables(outcome) {
|
|
26
|
+
switch (outcome.kind) {
|
|
27
|
+
case "completed":
|
|
28
|
+
return outcome.result !== "" ? { result: outcome.result } : {};
|
|
29
|
+
case "failed":
|
|
30
|
+
return { error: outcome.error };
|
|
31
|
+
case "stopped":
|
|
32
|
+
return {};
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
/** The settled worktree block, or nothing when there is no tree. */
|
|
36
|
+
function settledWorktreeVariables(worktree) {
|
|
37
|
+
if (!worktree)
|
|
38
|
+
return {};
|
|
39
|
+
return {
|
|
40
|
+
...worktreeVariables(worktree),
|
|
41
|
+
...(worktree.retention !== undefined
|
|
42
|
+
? { retention: worktree.retention }
|
|
43
|
+
: {}),
|
|
44
|
+
...(worktree.processAlive ? { process_alive: true } : {}),
|
|
45
|
+
};
|
|
46
|
+
}
|
|
47
|
+
export function spawnCueContext(input) {
|
|
48
|
+
if (!input.worktree)
|
|
49
|
+
return { agent_id: input.agentId };
|
|
50
|
+
return { agent_id: input.agentId, ...worktreeVariables(input.worktree) };
|
|
51
|
+
}
|
|
52
|
+
/** Context for the queued acknowledgement. */
|
|
53
|
+
export function queuedCueContext(input) {
|
|
54
|
+
return {
|
|
55
|
+
...spawnCueContext(input),
|
|
56
|
+
queue_running: input.queueRunning,
|
|
57
|
+
queue_running_label: input.queueRunning === 1 ? "agent" : "agents",
|
|
58
|
+
};
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* Context for the settled report. `statusNote` keeps its own leading space
|
|
62
|
+
* (getStatusNote formats it that way); the cue interpolates it bare.
|
|
63
|
+
* `retention`/`process_alive` exist only for a worktree settle —
|
|
64
|
+
* `process_alive` only when true — since templates branch on absence.
|
|
65
|
+
*/
|
|
66
|
+
export function settledCueContext(input) {
|
|
67
|
+
const { outcome, statusNote, worktree } = input;
|
|
68
|
+
return {
|
|
69
|
+
...outcomeVariables(outcome),
|
|
70
|
+
...(statusNote ? { status_note: statusNote } : {}),
|
|
71
|
+
...settledWorktreeVariables(worktree),
|
|
72
|
+
};
|
|
73
|
+
}
|
|
74
|
+
const SPAWNED_CUE_VARIABLES = {
|
|
75
|
+
agent_id: true,
|
|
76
|
+
has_worktree: true,
|
|
77
|
+
worktree_path: true,
|
|
78
|
+
worktree_branch: true,
|
|
79
|
+
};
|
|
80
|
+
const QUEUED_CUE_VARIABLES = {
|
|
81
|
+
agent_id: true,
|
|
82
|
+
has_worktree: true,
|
|
83
|
+
worktree_path: true,
|
|
84
|
+
worktree_branch: true,
|
|
85
|
+
queue_running: true,
|
|
86
|
+
queue_running_label: true,
|
|
87
|
+
};
|
|
88
|
+
const SETTLED_CUE_VARIABLES = {
|
|
89
|
+
result: true,
|
|
90
|
+
error: true,
|
|
91
|
+
status_note: true,
|
|
92
|
+
has_worktree: true,
|
|
93
|
+
worktree_path: true,
|
|
94
|
+
worktree_branch: true,
|
|
95
|
+
retention: true,
|
|
96
|
+
process_alive: true,
|
|
97
|
+
};
|
|
98
|
+
/** Variable names the spawned cue may reference. */
|
|
99
|
+
export const spawnedCueVariables = Object.keys(SPAWNED_CUE_VARIABLES);
|
|
100
|
+
/** Variable names the queued cue may reference. */
|
|
101
|
+
export const queuedCueVariables = Object.keys(QUEUED_CUE_VARIABLES);
|
|
102
|
+
/** Variable names the settled cue may reference. */
|
|
103
|
+
export const settledCueVariables = Object.keys(SETTLED_CUE_VARIABLES);
|
|
104
|
+
/** The variable set for one cue event; undefined for a runtime-unknown event. */
|
|
105
|
+
export function cueVariables(event) {
|
|
106
|
+
switch (event) {
|
|
107
|
+
case "spawned":
|
|
108
|
+
return spawnedCueVariables;
|
|
109
|
+
case "queued":
|
|
110
|
+
return queuedCueVariables;
|
|
111
|
+
case "settled":
|
|
112
|
+
return settledCueVariables;
|
|
113
|
+
default:
|
|
114
|
+
return undefined;
|
|
115
|
+
}
|
|
116
|
+
}
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* cues.ts — Cue rendering and validation.
|
|
3
|
+
*
|
|
4
|
+
* Rendering is IDENTITY for the facts: HTML escaping is disabled, so a cue
|
|
5
|
+
* reproduces code/Markdown/prose byte-for-byte. Validation is per-cue: a
|
|
6
|
+
* template may only name variables its own cue supplies, so a typo fails at
|
|
7
|
+
* load time instead of rendering as an invisible empty string.
|
|
8
|
+
*
|
|
9
|
+
* Partials and delimiter changes are rejected: a cue must be self-contained.
|
|
10
|
+
* Comments and `{{{ }}}`/`{{& }}` are ordinary Mustache.
|
|
11
|
+
*/
|
|
12
|
+
import Mustache from "mustache";
|
|
13
|
+
import { cueVariables } from "./context.js";
|
|
14
|
+
const OK = { ok: true };
|
|
15
|
+
const UNESCAPED = "&";
|
|
16
|
+
/** Token types carrying a variable name (sections resolve one too). */
|
|
17
|
+
const NAME_BEARING_TYPES = new Set(["name", UNESCAPED, "#", "^"]);
|
|
18
|
+
/** Render one event's cue against that event's context. Absent facts render as nothing, never "null". */
|
|
19
|
+
export function renderCue(cues, event, context) {
|
|
20
|
+
return Mustache.render(cues[event], context, undefined, {
|
|
21
|
+
// Cue text is plain TUI text, not HTML, and mustache calls this hook with
|
|
22
|
+
// whatever the template interpolated — an arbitrary value by design.
|
|
23
|
+
// oxlint-disable-next-line typescript/no-base-to-string -- the interpolated value is arbitrary
|
|
24
|
+
escape: (value) => (value == null ? "" : String(value)),
|
|
25
|
+
});
|
|
26
|
+
}
|
|
27
|
+
function spanChildren(span) {
|
|
28
|
+
const children = span[4];
|
|
29
|
+
return Array.isArray(children)
|
|
30
|
+
? children
|
|
31
|
+
: undefined;
|
|
32
|
+
}
|
|
33
|
+
/** First structural/variable problem in a token tree, if any. */
|
|
34
|
+
function findTemplateProblem(spans, allowed, event) {
|
|
35
|
+
for (const span of spans) {
|
|
36
|
+
const [type, value] = span;
|
|
37
|
+
if (type === ">") {
|
|
38
|
+
return `partials are not supported: "{{>${value}}}"`;
|
|
39
|
+
}
|
|
40
|
+
if (type === "=") {
|
|
41
|
+
return `delimiter changes are not supported: "{{=${value}=}}"`;
|
|
42
|
+
}
|
|
43
|
+
if (NAME_BEARING_TYPES.has(type) && !allowed.includes(value)) {
|
|
44
|
+
return `unknown variable "{{${value}}}" — allowed variables for the ${event} cue: ${allowed.join(", ")}`;
|
|
45
|
+
}
|
|
46
|
+
const children = spanChildren(span);
|
|
47
|
+
if (children) {
|
|
48
|
+
const childProblem = findTemplateProblem(children, allowed, event);
|
|
49
|
+
if (childProblem)
|
|
50
|
+
return childProblem;
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
return undefined;
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* Validate one cue template against its event's variable set. Rejects unknown
|
|
57
|
+
* variables, partials, and delimiter changes with a one-line reason the
|
|
58
|
+
* caller surfaces verbatim in a skip warning.
|
|
59
|
+
*/
|
|
60
|
+
export function validateCueTemplate(event, template) {
|
|
61
|
+
const allowed = cueVariables(event);
|
|
62
|
+
if (!allowed) {
|
|
63
|
+
return { ok: false, reason: `unknown cue event "${event}"` };
|
|
64
|
+
}
|
|
65
|
+
let spans;
|
|
66
|
+
try {
|
|
67
|
+
spans = Mustache.parse(template);
|
|
68
|
+
}
|
|
69
|
+
catch (err) {
|
|
70
|
+
const message = err instanceof Error ? err.message : String(err);
|
|
71
|
+
return {
|
|
72
|
+
ok: false,
|
|
73
|
+
reason: `unparsable template: ${message.replace(/\s+/g, " ").trim()}`,
|
|
74
|
+
};
|
|
75
|
+
}
|
|
76
|
+
const problem = findTemplateProblem(spans, allowed, event);
|
|
77
|
+
return problem ? { ok: false, reason: problem } : OK;
|
|
78
|
+
}
|
|
79
|
+
/** Validate every cue a template defines (the base supplies the rest). Returns the first failure. */
|
|
80
|
+
export function validateOrchestratorCues(cues) {
|
|
81
|
+
for (const event of Object.keys(cues)) {
|
|
82
|
+
const template = cues[event];
|
|
83
|
+
if (template === undefined)
|
|
84
|
+
continue;
|
|
85
|
+
const result = validateCueTemplate(event, template);
|
|
86
|
+
if (!result.ok)
|
|
87
|
+
return result;
|
|
88
|
+
}
|
|
89
|
+
return OK;
|
|
90
|
+
}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* default-orchestrators.ts — Embedded default orchestration templates.
|
|
3
|
+
*
|
|
4
|
+
* Always available; a `.toml` file with the same name overrides. `default`
|
|
5
|
+
* reproduces the pre-cue single-phase wording byte-for-byte (pinned by
|
|
6
|
+
* test/orchestrator-cues.test.ts) and is the BASE every other name starts
|
|
7
|
+
* from: a loaded template overrides only the cue events it defines.
|
|
8
|
+
*/
|
|
9
|
+
/** Spawn acknowledgement. The worktree line lives in `{{#has_worktree}}` — it exists only for a worktree run. */
|
|
10
|
+
const SPAWNED_CUE = `Success! You delegated to an agent. A notification will arrive when done - USER: do not poll, don't check status and don't duplicate the delegated work!{{#has_worktree}}
|
|
11
|
+
(Worktree: {{worktree_path}} (branch {{worktree_branch}}) — the agent's commits land on that branch, never on main. Merge it with the merge_cowboy_branch tool when done, then remove the worktree with cleanup_cowboy_agent.){{/has_worktree}}
|
|
12
|
+
|
|
13
|
+
Agent ID: {{agent_id}}`;
|
|
14
|
+
/** Queued acknowledgement: why the task has not started and what the limit is doing. */
|
|
15
|
+
const QUEUED_CUE = `Agent QUEUED — the concurrency limit is reached ({{queue_running}} {{queue_running_label}} already spawned), so this task is waiting for a slot. It is NOT spawned yet: the process has not started. It will start automatically when another agent settles; you'll get a message when it starts and when it settles. Do NOT re-delegate — this task IS in flight.{{#has_worktree}}
|
|
16
|
+
(Worktree: {{worktree_path}} (branch {{worktree_branch}}) — the agent's commits land on that branch, never on main. Merge it with the merge_cowboy_branch tool when done, then remove the worktree with cleanup_cowboy_agent.){{/has_worktree}}
|
|
17
|
+
|
|
18
|
+
Agent ID: {{agent_id}}`;
|
|
19
|
+
/** Settled report: result, error, worktree verdict, process liveness, status note. */
|
|
20
|
+
const SETTLED_CUE = `{{result}}{{#error}}
|
|
21
|
+
|
|
22
|
+
Error: {{error}}{{/error}}{{#has_worktree}}
|
|
23
|
+
(Worktree: {{worktree_path}} (branch {{worktree_branch}}){{#retention}} — KEPT: {{retention}}{{/retention}}.{{#process_alive}} The agent process and its herdr pane stay until you call cleanup_cowboy_agent — its pane is closed, which ends that process.{{/process_alive}} {{#retention}}Clean the worktree up, then call cleanup_cowboy_agent to remove it.{{/retention}}{{^retention}}The worktree stays until you call cleanup_cowboy_agent to remove it — call it once the branch is merged or rejected.{{/retention}}){{/has_worktree}}{{status_note}}`;
|
|
24
|
+
export const DEFAULT_ORCHESTRATORS = {
|
|
25
|
+
default: {
|
|
26
|
+
name: "default",
|
|
27
|
+
displayName: "Default",
|
|
28
|
+
// The cues already carry the delegation/merge/cleanup wording, so a default delegation adds no guidance section.
|
|
29
|
+
guidance: "",
|
|
30
|
+
cues: {
|
|
31
|
+
spawned: SPAWNED_CUE,
|
|
32
|
+
queued: QUEUED_CUE,
|
|
33
|
+
settled: SETTLED_CUE,
|
|
34
|
+
},
|
|
35
|
+
},
|
|
36
|
+
};
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* orchestrator-discovery.ts — Orchestrator file discovery, parsing, and merging.
|
|
3
|
+
*
|
|
4
|
+
* Scans `~/.pi/agent/orchestrators/`, `<project>/.agents/orchestrators/`, and
|
|
5
|
+
* `<project>/.pi/orchestrators/` for `*.toml` (`name`, `display_name`,
|
|
6
|
+
* `guidance`, `[cues]`). `guidance` is subagent-facing prose
|
|
7
|
+
* copied verbatim into the child prompt — never rendered as a cue — defaulted
|
|
8
|
+
* from the base template when omitted.
|
|
9
|
+
*
|
|
10
|
+
* Merging is per cue over the code `default` base; `display_name` / `guidance`
|
|
11
|
+
* are replaced wholesale by the highest layer.
|
|
12
|
+
*/
|
|
13
|
+
import { parseTemplateToml, scanTemplateFilesInDir, } from "../templates/template-files.js";
|
|
14
|
+
import { DEFAULT_ORCHESTRATORS } from "./default-orchestrators.js";
|
|
15
|
+
import { OrchestratorTemplateSchema, } from "./orchestrator-template.js";
|
|
16
|
+
const ORCHESTRATOR_SCAN_WARNING = {
|
|
17
|
+
label: "Orchestrator",
|
|
18
|
+
problem: "is not a valid orchestrator template and was skipped",
|
|
19
|
+
};
|
|
20
|
+
// --- parseOrchestratorFile ---
|
|
21
|
+
/** Parse one orchestrator template file. Shape and cue-variable failures throw here and become the scanner's one-line skip warning. */
|
|
22
|
+
export function parseOrchestratorFile(content) {
|
|
23
|
+
return OrchestratorTemplateSchema.parse(parseTemplateToml(content));
|
|
24
|
+
}
|
|
25
|
+
// --- scanOrchestratorFilesInDir ---
|
|
26
|
+
/** Scan a directory for `.toml` orchestrators (empty array when missing). A nameless file is skipped; an invalid one is skipped with a one-line warning via `notify`. */
|
|
27
|
+
export async function scanOrchestratorFilesInDir(dirPath, notify) {
|
|
28
|
+
return scanTemplateFilesInDir(dirPath, parseOrchestratorFile, (orchestrator) => orchestrator.name, notify, ORCHESTRATOR_SCAN_WARNING);
|
|
29
|
+
}
|
|
30
|
+
// --- mergeOrchestrators ---
|
|
31
|
+
/**
|
|
32
|
+
* Merge defaults with user, shared, and project overrides (highest to lowest:
|
|
33
|
+
* project > shared > user > defaults). Every name starts from the code
|
|
34
|
+
* `default` base; a loaded template replaces only the cue events it defines.
|
|
35
|
+
*/
|
|
36
|
+
export function mergeOrchestrators(defaults, userOrchestrators, sharedOrchestrators, projectOrchestrators) {
|
|
37
|
+
const result = new Map(defaults instanceof Map ? defaults : Object.entries(defaults));
|
|
38
|
+
const base = result.get("default") ?? DEFAULT_ORCHESTRATORS.default;
|
|
39
|
+
for (const layer of [
|
|
40
|
+
userOrchestrators,
|
|
41
|
+
sharedOrchestrators,
|
|
42
|
+
projectOrchestrators,
|
|
43
|
+
]) {
|
|
44
|
+
for (const template of layer) {
|
|
45
|
+
if (!template.name)
|
|
46
|
+
continue;
|
|
47
|
+
result.set(template.name, applyOverride(result.get(template.name) ?? namedBase(template.name, base), template));
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
return result;
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* The base a name that is not registered yet starts from: the `default`
|
|
54
|
+
* template's cues and guidance, carried under this name — whose own name is
|
|
55
|
+
* its display name, since only an explicit `display_name` names it otherwise.
|
|
56
|
+
*/
|
|
57
|
+
function namedBase(name, defaultConfig) {
|
|
58
|
+
return { ...defaultConfig, name, displayName: name };
|
|
59
|
+
}
|
|
60
|
+
function applyOverride(base, template) {
|
|
61
|
+
return {
|
|
62
|
+
...base,
|
|
63
|
+
name: template.name ?? base.name,
|
|
64
|
+
displayName: template.display_name ?? base.displayName,
|
|
65
|
+
cues: { ...base.cues, ...template.cues },
|
|
66
|
+
guidance: template.guidance ?? base.guidance,
|
|
67
|
+
};
|
|
68
|
+
}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* orchestrator-template.ts — The Zod schema for one orchestrator template file.
|
|
3
|
+
*
|
|
4
|
+
* Single source of truth for the `.toml` format: snake_case keys, strict at
|
|
5
|
+
* the root AND inside `[cues]` so a typo'd cue event fails at load time. The
|
|
6
|
+
* TypeScript type is derived with `z.infer`.
|
|
7
|
+
*
|
|
8
|
+
* Shape is Zod's job; cue variables are cues.ts's — a failure lands as a Zod
|
|
9
|
+
* issue on that cue's own path (`cues.spawned: unknown variable ...`).
|
|
10
|
+
*/
|
|
11
|
+
import { z } from "zod";
|
|
12
|
+
import { validateCueTemplate } from "./cues.js";
|
|
13
|
+
const CUE_EVENTS = ["spawned", "queued", "settled"];
|
|
14
|
+
/** The `[cues]` table: strict, and variable-validated per present cue. */
|
|
15
|
+
const CuesSchema = z
|
|
16
|
+
.strictObject({
|
|
17
|
+
spawned: z.string().optional(),
|
|
18
|
+
queued: z.string().optional(),
|
|
19
|
+
settled: z.string().optional(),
|
|
20
|
+
})
|
|
21
|
+
.superRefine((cues, ctx) => {
|
|
22
|
+
for (const event of CUE_EVENTS) {
|
|
23
|
+
const template = cues[event];
|
|
24
|
+
if (template === undefined)
|
|
25
|
+
continue;
|
|
26
|
+
const validation = validateCueTemplate(event, template);
|
|
27
|
+
if (!validation.ok) {
|
|
28
|
+
ctx.addIssue({
|
|
29
|
+
code: "custom",
|
|
30
|
+
message: validation.reason,
|
|
31
|
+
path: [event],
|
|
32
|
+
});
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
});
|
|
36
|
+
export const OrchestratorTemplateSchema = z.strictObject({
|
|
37
|
+
name: z.string().optional(),
|
|
38
|
+
display_name: z.string().optional(),
|
|
39
|
+
/** Subagent-facing instruction, copied verbatim; omitted means the base template's applies. */
|
|
40
|
+
guidance: z.string().optional(),
|
|
41
|
+
/** Only the events this file defines; the base supplies the rest. */
|
|
42
|
+
cues: CuesSchema.optional(),
|
|
43
|
+
});
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* orchestrator-types.ts — Unified orchestrator template registry.
|
|
3
|
+
*
|
|
4
|
+
* Embedded defaults overlaid with TOML templates. Precedence: default <
|
|
5
|
+
* extension < user < shared < project; the code `default` is the per-cue base
|
|
6
|
+
* for every registered name.
|
|
7
|
+
*
|
|
8
|
+
* The registry is session state; it lives in the shell and is read and written
|
|
9
|
+
* here through the shell getters.
|
|
10
|
+
*/
|
|
11
|
+
import { EXTENSION_ORCHESTRATORS_DIR } from "../paths.js";
|
|
12
|
+
import { getSessionTemplates, } from "../shell.js";
|
|
13
|
+
import { DEFAULT_ORCHESTRATORS } from "./default-orchestrators.js";
|
|
14
|
+
import { mergeOrchestrators, scanOrchestratorFilesInDir, } from "./orchestrator-discovery.js";
|
|
15
|
+
function registry() {
|
|
16
|
+
return getSessionTemplates().orchestrators;
|
|
17
|
+
}
|
|
18
|
+
export function registerOrchestrators(loaded, options) {
|
|
19
|
+
const orchestrators = new Map();
|
|
20
|
+
if (!options?.disableDefaultOrchestrators) {
|
|
21
|
+
for (const [name, config] of Object.entries(DEFAULT_ORCHESTRATORS)) {
|
|
22
|
+
orchestrators.set(name, config);
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
for (const [name, config] of loaded) {
|
|
26
|
+
orchestrators.set(name, config);
|
|
27
|
+
}
|
|
28
|
+
registry().orchestrators = orchestrators;
|
|
29
|
+
}
|
|
30
|
+
export function setOrchestratorScanDirs(userDir, projectDir, sharedDir) {
|
|
31
|
+
registry().scanDirs = {
|
|
32
|
+
user: userDir,
|
|
33
|
+
project: projectDir,
|
|
34
|
+
shared: sharedDir ?? "",
|
|
35
|
+
};
|
|
36
|
+
}
|
|
37
|
+
/** Scan every orchestrator directory and merge it over the code defaults. */
|
|
38
|
+
export async function scanAndMergeOrchestrators(options) {
|
|
39
|
+
const disableDefaults = options?.disableDefaultOrchestrators === true;
|
|
40
|
+
const notify = options?.notify;
|
|
41
|
+
const scanDirs = registry().scanDirs;
|
|
42
|
+
const [extensionOrchestrators, userOrchestrators, sharedOrchestrators, projectOrchestrators,] = await Promise.all([
|
|
43
|
+
disableDefaults
|
|
44
|
+
? Promise.resolve([])
|
|
45
|
+
: scanOrchestratorFilesInDir(EXTENSION_ORCHESTRATORS_DIR, notify),
|
|
46
|
+
scanOrchestratorFilesInDir(scanDirs.user, notify),
|
|
47
|
+
scanOrchestratorFilesInDir(scanDirs.shared, notify),
|
|
48
|
+
scanOrchestratorFilesInDir(scanDirs.project, notify),
|
|
49
|
+
]);
|
|
50
|
+
const defaults = disableDefaults
|
|
51
|
+
? new Map()
|
|
52
|
+
: DEFAULT_ORCHESTRATORS;
|
|
53
|
+
const withExtension = mergeOrchestrators(defaults, extensionOrchestrators, [], []);
|
|
54
|
+
return mergeOrchestrators(withExtension, userOrchestrators, sharedOrchestrators, projectOrchestrators);
|
|
55
|
+
}
|
|
56
|
+
/** Resolve a name to its config: exact match wins, then a single case-insensitive one. `undefined` when nothing matches — including a case-ambiguous name, where picking one would be a guess. */
|
|
57
|
+
export function resolveOrchestrator(name) {
|
|
58
|
+
const { orchestrators } = registry();
|
|
59
|
+
if (!name)
|
|
60
|
+
return undefined;
|
|
61
|
+
const exact = orchestrators.get(name);
|
|
62
|
+
if (exact)
|
|
63
|
+
return exact;
|
|
64
|
+
const lower = name.toLowerCase();
|
|
65
|
+
const candidates = [];
|
|
66
|
+
for (const [key, config] of orchestrators) {
|
|
67
|
+
if (key.toLowerCase() === lower)
|
|
68
|
+
candidates.push(config);
|
|
69
|
+
}
|
|
70
|
+
return candidates.length === 1 ? candidates[0] : undefined;
|
|
71
|
+
}
|
|
72
|
+
export function getOrchestrator(name) {
|
|
73
|
+
return resolveOrchestrator(name);
|
|
74
|
+
}
|
|
75
|
+
/** Registered orchestrator names, in registration order. */
|
|
76
|
+
export function getAvailableOrchestrators() {
|
|
77
|
+
return [...registry().orchestrators.values()].map((config) => config.name);
|
|
78
|
+
}
|