@luminascale/shepherd 0.0.0-stage → 0.6.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/.agents/agents/README.md +12 -0
- package/.agents/agents/planner.md +38 -0
- package/.agents/agents/reviewer.md +38 -0
- package/.agents/agents/scout.md +43 -0
- package/.agents/agents/worker.md +33 -0
- package/.agents/skills/smoke-test/SKILL.md +155 -0
- package/.agents/skills/smoke-test/references/forensics.md +46 -0
- package/.agents/skills/smoke-test/scripts/live-smoke-poll.mjs +130 -0
- package/.github/workflows/publish.yml +77 -0
- package/.pi/prompts/release.md +21 -0
- package/.prettierrc +10 -0
- package/AGENTS.md +88 -0
- package/CONTRIBUTING.md +177 -0
- package/LICENSE +201 -0
- package/README.md +397 -2
- package/docs/README.md +26 -0
- package/docs/guides/agent-definitions.md +42 -0
- package/docs/guides/diagnostics.md +199 -0
- package/docs/guides/installation.md +61 -0
- package/docs/guides/tool-reference.md +55 -0
- package/docs/manual-tests/ping-pong-peer-messaging.md +147 -0
- package/docs/plans/agent-labels.md +257 -0
- package/docs/plans/architecture.md +110 -0
- package/docs/plans/settings-scope.md +163 -0
- package/docs/plans/tool-surface-split.md +278 -0
- package/docs/reference/dictionary +26 -0
- package/docs/releasing.md +47 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/baseline.md +115 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/handoff.md +564 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase10-notes.md +109 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase6-notes.md +69 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase7-notes.md +100 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase8-notes.md +127 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase9-notes.md +104 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/plan.md +1093 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/spec.md +583 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/tasks.md +838 -0
- package/docs/specs/006-shepherd-tool-rendering/plan.md +175 -0
- package/docs/specs/006-shepherd-tool-rendering/spec.md +469 -0
- package/index.ts +602 -0
- package/package.json +112 -4
- package/scripts/capture-system-prompt.mjs +45 -0
- package/scripts/extract-pi-system-prompt.mjs +277 -0
- package/scripts/host-impact.mjs +74 -0
- package/scripts/resolve-agent.mjs +43 -0
- package/scripts/show-shepherd-orchestrator.mjs +58 -0
- package/scripts/show-shepherd-prompt.mjs +96 -0
- package/scripts/verify-suites.mjs +67 -0
- package/specs/001-artifacts/spec.md +436 -0
- package/specs/002-simplify-agent-orchestration/plan.md +287 -0
- package/specs/002-simplify-agent-orchestration/spec.md +323 -0
- package/specs/002-simplify-agent-orchestration/tasks.md +212 -0
- package/specs/003-orchestrator-session-artifacts/plan.md +396 -0
- package/specs/003-orchestrator-session-artifacts/spec.md +453 -0
- package/specs/003-orchestrator-session-artifacts/tasks.md +141 -0
- package/specs/004-asynchronous-prompt-watchers/plan.md +139 -0
- package/specs/004-asynchronous-prompt-watchers/spec.md +202 -0
- package/specs/004-asynchronous-prompt-watchers/tasks.md +126 -0
- package/specs/005-per-workspace-settings/plan.md +230 -0
- package/specs/005-per-workspace-settings/spec.md +368 -0
- package/specs/005-per-workspace-settings/tasks.md +178 -0
- package/specs/006-dual-runtime-herdr-durable/intent.md +86 -0
- package/specs/006-dual-runtime-herdr-durable/journal.md +80 -0
- package/specs/006-dual-runtime-herdr-durable/plan.md +242 -0
- package/specs/006-dual-runtime-herdr-durable/spec.md +389 -0
- package/specs/006-dual-runtime-herdr-durable/tasks.md +199 -0
- package/specs/007-unwatched-completion-notice/journal.md +145 -0
- package/specs/007-unwatched-completion-notice/plan.md +186 -0
- package/specs/007-unwatched-completion-notice/spec.md +284 -0
- package/specs/007-unwatched-completion-notice/tasks.md +147 -0
- package/specs/008-remote-machine-sheep/intent.md +174 -0
- package/specs/008-remote-machine-sheep/journal.md +57 -0
- package/specs/008-remote-machine-sheep/prerequisites.md +219 -0
- package/specs/009-hc-runtime/intent.md +44 -0
- package/specs/009-hc-runtime/plan.md +49 -0
- package/specs/009-hc-runtime/spec.md +118 -0
- package/specs/009-hc-runtime/tasks.md +62 -0
- package/specs/010-unseen-watch-parity/intent.md +57 -0
- package/specs/010-unseen-watch-parity/journal.md +172 -0
- package/specs/010-unseen-watch-parity/plan.md +74 -0
- package/specs/010-unseen-watch-parity/spec.md +191 -0
- package/specs/010-unseen-watch-parity/tasks.md +119 -0
- package/specs/011-hc-background-poll/intent.md +57 -0
- package/specs/011-hc-background-poll/journal.md +95 -0
- package/specs/011-hc-background-poll/plan.md +87 -0
- package/specs/011-hc-background-poll/spec.md +141 -0
- package/specs/011-hc-background-poll/tasks.md +83 -0
- package/specs/012-steer-default/intent.md +12 -0
- package/specs/012-steer-default/journal.md +40 -0
- package/specs/012-steer-default/plan.md +7 -0
- package/specs/012-steer-default/spec.md +42 -0
- package/specs/012-steer-default/tasks.md +6 -0
- package/specs/013-opencode-shepherd/handoff-t011.md +94 -0
- package/specs/013-opencode-shepherd/intent.md +59 -0
- package/specs/013-opencode-shepherd/plan.md +204 -0
- package/specs/013-opencode-shepherd/spec.md +258 -0
- package/specs/013-opencode-shepherd/tasks.md +263 -0
- package/src/core/artifact-sessions.ts +835 -0
- package/src/core/config.ts +329 -0
- package/src/core/discovery.ts +342 -0
- package/src/core/herdr.ts +1 -0
- package/src/core/host.ts +77 -0
- package/src/core/ids.ts +78 -0
- package/src/core/lifecycle.ts +1 -0
- package/src/core/messaging.ts +1 -0
- package/src/core/migration.ts +55 -0
- package/src/core/orchestration.ts +1 -0
- package/src/core/types.ts +143 -0
- package/src/core/unseen-completions.ts +114 -0
- package/src/extension/cli.ts +417 -0
- package/src/extension/config.ts +1 -0
- package/src/extension/settings-ui.ts +296 -0
- package/src/extension/shepherd-done.ts +768 -0
- package/src/extension/shepherd.ts +2548 -0
- package/src/extension/system-prompt.ts +38 -0
- package/src/extension/unseen-completions.ts +237 -0
- package/src/opencode/actions.ts +794 -0
- package/src/opencode/bridge.ts +777 -0
- package/src/opencode/display.ts +36 -0
- package/src/opencode/fieldnotes.ts +60 -0
- package/src/opencode/host.ts +62 -0
- package/src/opencode/orphans.ts +162 -0
- package/src/opencode/server.ts +458 -0
- package/src/runtimes/backend.ts +119 -0
- package/src/runtimes/detect.ts +102 -0
- package/src/runtimes/hc/hc.ts +527 -0
- package/src/runtimes/hc/runtime.ts +1898 -0
- package/src/runtimes/herdr/herdr.ts +912 -0
- package/src/runtimes/herdr/lifecycle.ts +1712 -0
- package/src/runtimes/herdr/messaging.ts +703 -0
- package/src/runtimes/herdr/orchestration.ts +1583 -0
- package/src/runtimes/herdr/runtime.ts +224 -0
- package/src/runtimes/runtime.ts +133 -0
- package/src/runtimes/settle-observations.ts +114 -0
- package/test/fixtures/context-project/AGENTS.md +2 -0
- package/test/fixtures/home/.agents/agents/same.md +6 -0
- package/test/fixtures/home/.agents/agents/shared-only.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/invalid-thinking.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/model-empty.md +7 -0
- package/test/fixtures/home/.pi/agent/agents/model-explicit.md +7 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-absent.md +5 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-false.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-invalid.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-true.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-false.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-invalid.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-pi-docs.md +7 -0
- package/test/fixtures/home/.pi/agent/agents/omit-true.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/only-user.md +9 -0
- package/test/fixtures/home/.pi/agent/agents/same.md +6 -0
- package/test/fixtures/proj/.agents/agents/proj-shared.md +6 -0
- package/test/fixtures/proj/.pi/agents/project-pi.md +6 -0
- package/test/fixtures/proj/.pi/agents/same.md +6 -0
- package/test/helpers/fake-clock.mjs +39 -0
- package/test/helpers/feature-contracts.mjs +44 -0
- package/test/helpers/test-utils.mjs +44 -0
- package/test/verify-artifact-sessions.mjs +258 -0
- package/test/verify-backend.mjs +297 -0
- package/test/verify-child-mislabel.mjs +135 -0
- package/test/verify-child-surface.mjs +321 -0
- package/test/verify-cli.mjs +197 -0
- package/test/verify-command-ux.mjs +100 -0
- package/test/verify-compat.mjs +32 -0
- package/test/verify-cross-host-notes.mjs +128 -0
- package/test/verify-delegate.mjs +161 -0
- package/test/verify-detect.mjs +151 -0
- package/test/verify-discovery.mjs +239 -0
- package/test/verify-done-nudge.mjs +238 -0
- package/test/verify-effective-prompt.mjs +98 -0
- package/test/verify-hc-matrix.mjs +246 -0
- package/test/verify-hc-poll.mjs +260 -0
- package/test/verify-host-docs.mjs +66 -0
- package/test/verify-host-impact.mjs +49 -0
- package/test/verify-ids.mjs +141 -0
- package/test/verify-launch.mjs +183 -0
- package/test/verify-message-routing.mjs +560 -0
- package/test/verify-messaging.mjs +303 -0
- package/test/verify-migration-notice.mjs +74 -0
- package/test/verify-multi-wait.mjs +42 -0
- package/test/verify-opencode-display.mjs +47 -0
- package/test/verify-opencode-fieldnotes.mjs +121 -0
- package/test/verify-opencode-notice.mjs +77 -0
- package/test/verify-opencode-nudge.mjs +116 -0
- package/test/verify-opencode-orphans.mjs +160 -0
- package/test/verify-opencode-surface.mjs +107 -0
- package/test/verify-packaging.mjs +82 -0
- package/test/verify-parent-surface.mjs +118 -0
- package/test/verify-phase0.mjs +95 -0
- package/test/verify-registry.mjs +124 -0
- package/test/verify-rename-migration.mjs +111 -0
- package/test/verify-rendering.mjs +379 -0
- package/test/verify-session-boundary.mjs +146 -0
- package/test/verify-settings.mjs +260 -0
- package/test/verify-stale-wait.mjs +339 -0
- package/test/verify-status-widget.mjs +377 -0
- package/test/verify-status.mjs +172 -0
- package/test/verify-task-completion.mjs +156 -0
- package/test/verify-task-failures.mjs +201 -0
- package/test/verify-task-mislabel.mjs +143 -0
- package/test/verify-task-registry.mjs +194 -0
- package/test/verify-task-watchers.mjs +217 -0
- package/test/verify-tool-schemas.mjs +120 -0
- package/test/verify-unseen-completions.mjs +1211 -0
- package/test/verify-watchers.mjs +181 -0
|
@@ -0,0 +1,417 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shared CLI grammar for pi-shepherd.
|
|
3
|
+
*
|
|
4
|
+
* One options table defines how a shepherd command is spelled as a line of
|
|
5
|
+
* flags and positionals:
|
|
6
|
+
* - `parseShepherdCli` turns `/shepherd …` tokens into doAction args
|
|
7
|
+
* (the human command surface),
|
|
8
|
+
* - `formatShepherdCommand` renders doAction args back into the compact
|
|
9
|
+
* CLI-style text used by tool-call previews (the model surface).
|
|
10
|
+
*
|
|
11
|
+
* The two are the inverse of each other: they read and write the same
|
|
12
|
+
* `OPTION_SPECS` table, so a rendered line always parses back to the same
|
|
13
|
+
* args.
|
|
14
|
+
*/
|
|
15
|
+
|
|
16
|
+
import { resolve } from 'node:path';
|
|
17
|
+
import { lifecycleRegistry } from '../runtimes/herdr/orchestration.ts';
|
|
18
|
+
|
|
19
|
+
export const SCOPE_VALUES = ['user', 'project', 'both'] as const;
|
|
20
|
+
export const PLACEMENT_VALUES = ['pane_right', 'pane_down', 'tab', 'workspace'] as const;
|
|
21
|
+
export const SOURCE_VALUES = ['visible', 'recent', 'recent-unwrapped', 'detection'] as const;
|
|
22
|
+
|
|
23
|
+
interface OptionSpec {
|
|
24
|
+
/** Canonical CLI flag name (without `--`). */
|
|
25
|
+
flag: string;
|
|
26
|
+
/** Extra accepted spellings for the human CLI. */
|
|
27
|
+
aliases?: string[];
|
|
28
|
+
/** doAction args key. */
|
|
29
|
+
key: string;
|
|
30
|
+
/** Restricted value set (validated, and used in error hints). */
|
|
31
|
+
values?: readonly string[];
|
|
32
|
+
/** Value must be an integer (coerced from string). */
|
|
33
|
+
integer?: boolean;
|
|
34
|
+
/** Value must be `true`/`false` (coerced to boolean). */
|
|
35
|
+
boolean?: boolean;
|
|
36
|
+
/** Bare flag: no value, always sets true. */
|
|
37
|
+
bare?: boolean;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
const OPTION_SPECS: Record<string, OptionSpec> = {
|
|
41
|
+
// Scope remains available for `agents` discovery; it is intentionally not a
|
|
42
|
+
// spawn option because spawn must use the persisted settings scope.
|
|
43
|
+
agentScope: { flag: 'scope', aliases: ['agent-scope'], key: 'agentScope', values: SCOPE_VALUES },
|
|
44
|
+
label: { flag: 'label', key: 'label' },
|
|
45
|
+
placement: { flag: 'placement', key: 'placement', values: PLACEMENT_VALUES },
|
|
46
|
+
cwd: { flag: 'cwd', key: 'cwd' },
|
|
47
|
+
lines: { flag: 'lines', key: 'lines', integer: true },
|
|
48
|
+
source: { flag: 'source', key: 'source', values: SOURCE_VALUES },
|
|
49
|
+
timeout: { flag: 'timeout', key: 'timeout', integer: true },
|
|
50
|
+
};
|
|
51
|
+
|
|
52
|
+
const FLAG_LOOKUP = new Map<string, OptionSpec>();
|
|
53
|
+
for (const spec of Object.values(OPTION_SPECS)) {
|
|
54
|
+
FLAG_LOOKUP.set(spec.flag, spec);
|
|
55
|
+
for (const alias of spec.aliases ?? []) FLAG_LOOKUP.set(alias, spec);
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
// Which option keys each command verb accepts (renderer and parser agree).
|
|
59
|
+
const SPAWN_OPTION_KEYS = ['label', 'placement', 'cwd'];
|
|
60
|
+
const READ_OPTION_KEYS = ['lines', 'source'];
|
|
61
|
+
|
|
62
|
+
const USAGE =
|
|
63
|
+
'Usage: /shepherd <agents [user|project|both] | herd | spawn <agent> [options] | status <agent|id> | read <target> [options] | settings>\n' +
|
|
64
|
+
' spawn options: --label \"task label\", --placement pane_right|pane_down|tab|workspace, --cwd <path>\n' +
|
|
65
|
+
' read options: --lines <n>, --source ' +
|
|
66
|
+
SOURCE_VALUES.join('|');
|
|
67
|
+
|
|
68
|
+
// ── Parsing ──────────────────────────────────────────────────────────────────
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* Split a command line into tokens. The inverse of `formatShepherdCommand`'s
|
|
72
|
+
* CLI quoting: whitespace separates tokens, and a `"` starts a quoted run that
|
|
73
|
+
* is decoded as a JSON string (so `--cwd="/a b"` re-parses to the value `/a b`).
|
|
74
|
+
* A quoted run may appear mid-token (e.g. immediately after `--cwd=`), so its
|
|
75
|
+
* decoded value is appended to the surrounding token. Because `cliValue` wraps
|
|
76
|
+
* values via `JSON.stringify`, every quoted run is a valid JSON string literal.
|
|
77
|
+
*/
|
|
78
|
+
export function tokenizeCli(input: string): string[] {
|
|
79
|
+
const tokens: string[] = [];
|
|
80
|
+
let cur = '';
|
|
81
|
+
let i = 0;
|
|
82
|
+
const push = () => {
|
|
83
|
+
if (cur !== '') tokens.push(cur);
|
|
84
|
+
cur = '';
|
|
85
|
+
};
|
|
86
|
+
while (i < input.length) {
|
|
87
|
+
const c = input[i];
|
|
88
|
+
if (c === '"') {
|
|
89
|
+
// Capture one JSON string literal and decode it, appending to `cur`
|
|
90
|
+
// so `--cwd=<quoted>` keeps the flag prefix attached.
|
|
91
|
+
let j = i + 1;
|
|
92
|
+
let body = '';
|
|
93
|
+
while (j < input.length) {
|
|
94
|
+
if (input[j] === '\\') {
|
|
95
|
+
body += input[j] + (input[j + 1] ?? '');
|
|
96
|
+
j += 2;
|
|
97
|
+
continue;
|
|
98
|
+
}
|
|
99
|
+
if (input[j] === '"') break;
|
|
100
|
+
body += input[j];
|
|
101
|
+
j++;
|
|
102
|
+
}
|
|
103
|
+
try {
|
|
104
|
+
cur += JSON.parse('"' + body + '"');
|
|
105
|
+
} catch {
|
|
106
|
+
cur += body; // malformed quote — keep the raw run rather than crashing
|
|
107
|
+
}
|
|
108
|
+
i = j + 1;
|
|
109
|
+
continue;
|
|
110
|
+
}
|
|
111
|
+
if (c === ' ' || c === '\t') {
|
|
112
|
+
push();
|
|
113
|
+
i++;
|
|
114
|
+
continue;
|
|
115
|
+
}
|
|
116
|
+
cur += c;
|
|
117
|
+
i++;
|
|
118
|
+
}
|
|
119
|
+
push();
|
|
120
|
+
return tokens;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
export type ParsedShepherdCommand =
|
|
124
|
+
| { action: 'agents'; args: Record<string, unknown> }
|
|
125
|
+
| { action: 'herd'; args: Record<string, unknown> }
|
|
126
|
+
| { action: 'spawn'; args: Record<string, unknown> }
|
|
127
|
+
| { action: 'status'; args: Record<string, unknown> }
|
|
128
|
+
| { action: 'read'; args: Record<string, unknown> };
|
|
129
|
+
|
|
130
|
+
export type ParseShepherdCliResult = ParsedShepherdCommand | { error: string };
|
|
131
|
+
|
|
132
|
+
/**
|
|
133
|
+
* Parse `--flag value` / `--flag=value` / bare flags tokens into an options
|
|
134
|
+
* object using the shared table. Non-`--` tokens are collected into
|
|
135
|
+
* `positional` (the caller decides how many are allowed).
|
|
136
|
+
*/
|
|
137
|
+
function parseFlags(
|
|
138
|
+
tokens: string[],
|
|
139
|
+
from: number,
|
|
140
|
+
allowed: readonly string[],
|
|
141
|
+
positional: string[]
|
|
142
|
+
): { options: Record<string, unknown>; error?: string } {
|
|
143
|
+
const allowedSet = new Set(allowed);
|
|
144
|
+
const options: Record<string, unknown> = {};
|
|
145
|
+
for (let i = from; i < tokens.length; i++) {
|
|
146
|
+
const token = tokens[i];
|
|
147
|
+
if (!token.startsWith('--')) {
|
|
148
|
+
positional.push(token);
|
|
149
|
+
continue;
|
|
150
|
+
}
|
|
151
|
+
const eq = token.indexOf('=');
|
|
152
|
+
const flag = (eq >= 0 ? token.slice(0, eq) : token).replace(/^--/, '');
|
|
153
|
+
const spec = FLAG_LOOKUP.get(flag);
|
|
154
|
+
if (!spec || !allowedSet.has(spec.key))
|
|
155
|
+
return { options, error: `Unknown option "--${flag}".` };
|
|
156
|
+
if (spec.bare) {
|
|
157
|
+
if (eq >= 0) return { options, error: `Option --${spec.flag} takes no value.` };
|
|
158
|
+
options[spec.key] = true;
|
|
159
|
+
continue;
|
|
160
|
+
}
|
|
161
|
+
const raw = eq >= 0 ? token.slice(eq + 1) : tokens[++i];
|
|
162
|
+
if (raw === undefined || raw === '' || raw.startsWith('--'))
|
|
163
|
+
return { options, error: `Missing value for --${spec.flag}.` };
|
|
164
|
+
if (spec.values && !spec.values.includes(raw))
|
|
165
|
+
return {
|
|
166
|
+
options,
|
|
167
|
+
error: `Invalid value "${raw}" for --${spec.flag}; use ${spec.values.join(', ')}.`,
|
|
168
|
+
};
|
|
169
|
+
if (spec.integer) {
|
|
170
|
+
if (!/^-?\d+$/.test(raw))
|
|
171
|
+
return { options, error: `Value "${raw}" for --${spec.flag} must be an integer.` };
|
|
172
|
+
options[spec.key] = Number(raw);
|
|
173
|
+
} else if (spec.boolean) {
|
|
174
|
+
if (raw !== 'true' && raw !== 'false')
|
|
175
|
+
return { options, error: `Value "${raw}" for --${spec.flag} must be true or false.` };
|
|
176
|
+
options[spec.key] = raw === 'true';
|
|
177
|
+
} else {
|
|
178
|
+
options[spec.key] = raw;
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
return { options };
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
/**
|
|
185
|
+
* Resolve a human status target (agent name, lifecycle id, or pane id) to the
|
|
186
|
+
* opaque lifecycle id the status action uses. Falls back to the supplied value
|
|
187
|
+
* so the registry can return its useful unknown-id error.
|
|
188
|
+
*/
|
|
189
|
+
export function statusHandleTarget(target: string): string {
|
|
190
|
+
for (const handle of lifecycleRegistry.allAgents()) {
|
|
191
|
+
if (handle.id === target || handle.agent === target || handle.paneId === target) {
|
|
192
|
+
return handle.id;
|
|
193
|
+
}
|
|
194
|
+
}
|
|
195
|
+
return target;
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
/**
|
|
199
|
+
* Parse the tokens of a `/shepherd` invocation into doAction args.
|
|
200
|
+
* `settings` is command-only and handled by the caller before parsing.
|
|
201
|
+
*/
|
|
202
|
+
export function parseShepherdCli(tokens: string[]): ParseShepherdCliResult {
|
|
203
|
+
const action = tokens[0] ?? '';
|
|
204
|
+
|
|
205
|
+
if (action === 'herd') {
|
|
206
|
+
if (tokens.length > 1) return { error: `/shepherd herd takes no arguments.\n${USAGE}` };
|
|
207
|
+
return { action: 'herd', args: { action: 'herd' } };
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
if (action === 'agents') {
|
|
211
|
+
// Scope may be a positional (`agents both`) or a flag (`agents --scope both`).
|
|
212
|
+
const positional: string[] = [];
|
|
213
|
+
const { options, error } = parseFlags(tokens, 1, ['agentScope'], positional);
|
|
214
|
+
if (error) return { error: `${error}\n${USAGE}` };
|
|
215
|
+
const positionalScope = positional[0];
|
|
216
|
+
if (positional.length > 1 || (positionalScope && 'agentScope' in options))
|
|
217
|
+
return {
|
|
218
|
+
error: `/shepherd agents takes at most one scope argument (positional or --scope).\n${USAGE}`,
|
|
219
|
+
};
|
|
220
|
+
const scope = positionalScope ?? (options.agentScope as string | undefined);
|
|
221
|
+
if (scope && !SCOPE_VALUES.includes(scope as 'user'))
|
|
222
|
+
return { error: `Invalid scope "${scope}"; use ${SCOPE_VALUES.join(', ')}.` };
|
|
223
|
+
return {
|
|
224
|
+
action: 'agents',
|
|
225
|
+
args: { action: 'agents', ...(scope ? { agentScope: scope } : {}) },
|
|
226
|
+
};
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
if (action === 'spawn') {
|
|
230
|
+
const positional: string[] = [];
|
|
231
|
+
const { options, error } = parseFlags(tokens, 1, SPAWN_OPTION_KEYS, positional);
|
|
232
|
+
if (error) return { error: `${error}\n${USAGE}` };
|
|
233
|
+
const [agent, ...extra] = positional;
|
|
234
|
+
if (!agent) return { error: `spawn requires an agent name.\n${USAGE}` };
|
|
235
|
+
if (extra.length > 0) return { error: `Unexpected argument "${extra[0]}".\n${USAGE}` };
|
|
236
|
+
return {
|
|
237
|
+
action: 'spawn',
|
|
238
|
+
args: { action: 'spawn', agent, label: options.label ?? '', ...options },
|
|
239
|
+
};
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
if (action === 'status') {
|
|
243
|
+
if (tokens.length > 2) return { error: `/shepherd status takes exactly one target.\n${USAGE}` };
|
|
244
|
+
const target = tokens[1];
|
|
245
|
+
if (!target) return { error: `status requires an agent name or lifecycle id.\n${USAGE}` };
|
|
246
|
+
return { action: 'status', args: { action: 'status', id: statusHandleTarget(target) } };
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
if (action === 'read') {
|
|
250
|
+
const positional: string[] = [];
|
|
251
|
+
const { options, error } = parseFlags(tokens, 1, READ_OPTION_KEYS, positional);
|
|
252
|
+
if (error) return { error: `${error}\n${USAGE}` };
|
|
253
|
+
const [name, ...extra] = positional;
|
|
254
|
+
if (!name)
|
|
255
|
+
return { error: `read requires a target (agent name, pane id, or lifecycle id).\n${USAGE}` };
|
|
256
|
+
if (extra.length > 0) return { error: `Unexpected argument "${extra[0]}".\n${USAGE}` };
|
|
257
|
+
return { action: 'read', args: { action: 'read', name, ...options } };
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
if (tokens.length === 0)
|
|
261
|
+
return {
|
|
262
|
+
error: `Provide an action. Try: agents, herd, spawn <agent>, status <target>, read <target>, or settings.\n${USAGE}`,
|
|
263
|
+
};
|
|
264
|
+
return {
|
|
265
|
+
error: `Unknown action "${action}". Try: agents, herd, spawn <agent>, status <target>, read <target>, or settings.\n${USAGE}`,
|
|
266
|
+
};
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
// ── Rendering (inverse of the parser) ───────────────────────────────────────
|
|
270
|
+
|
|
271
|
+
/**
|
|
272
|
+
* Tool transports may materialize optional spawn defaults before the renderer
|
|
273
|
+
* sees them. Keep those implementation defaults out of user-facing text so a
|
|
274
|
+
* required-only call still reads like a required-only call.
|
|
275
|
+
*/
|
|
276
|
+
export function omitMaterializedDefaults(
|
|
277
|
+
verb: string,
|
|
278
|
+
options: Record<string, any>,
|
|
279
|
+
defaultCwd = process.cwd()
|
|
280
|
+
): Record<string, any> {
|
|
281
|
+
const result = { ...options };
|
|
282
|
+
if (verb !== 'spawn') return result;
|
|
283
|
+
if (result.placement === 'tab') delete result.placement;
|
|
284
|
+
if (typeof result.cwd === 'string' && resolve(result.cwd) === resolve(defaultCwd))
|
|
285
|
+
delete result.cwd;
|
|
286
|
+
return result;
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
/** Keep tool-call previews compact without rendering an empty placeholder. */
|
|
290
|
+
function previewText(value: unknown, maxLength = 40): string {
|
|
291
|
+
const text = typeof value === 'string' ? value.replace(/\s+/g, ' ').trim() : String(value ?? '');
|
|
292
|
+
return text.length > maxLength ? `${text.slice(0, maxLength)}…` : text;
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
/** Render opaque lifecycle ids as compact CLI-like values. */
|
|
296
|
+
function handlePreview(value: unknown, maxLength = 40): string {
|
|
297
|
+
const rawId =
|
|
298
|
+
typeof value === 'string'
|
|
299
|
+
? value
|
|
300
|
+
: value && typeof value === 'object' && 'id' in value
|
|
301
|
+
? (value as any).id
|
|
302
|
+
: undefined;
|
|
303
|
+
if (typeof rawId === 'string') {
|
|
304
|
+
try {
|
|
305
|
+
const agent = lifecycleRegistry.getAgent(rawId);
|
|
306
|
+
return previewText(
|
|
307
|
+
`${agent.handle.agent}${agent.handle.label ? `: ${agent.handle.label}` : ''}`,
|
|
308
|
+
maxLength
|
|
309
|
+
);
|
|
310
|
+
} catch {
|
|
311
|
+
try {
|
|
312
|
+
const prompt = lifecycleRegistry.getPrompt(rawId) as any;
|
|
313
|
+
const agent = lifecycleRegistry.getAgent(prompt.handle.agentId);
|
|
314
|
+
return previewText(
|
|
315
|
+
`${agent.handle.agent}${agent.handle.label ? `: ${agent.handle.label}` : ''}`,
|
|
316
|
+
maxLength
|
|
317
|
+
);
|
|
318
|
+
} catch {
|
|
319
|
+
/* retain opaque id for unknown handles */
|
|
320
|
+
}
|
|
321
|
+
}
|
|
322
|
+
}
|
|
323
|
+
if (Array.isArray(value)) {
|
|
324
|
+
return `[${value.map(item => handlePreview(item, maxLength)).join(', ')}]`;
|
|
325
|
+
}
|
|
326
|
+
|
|
327
|
+
if (value && typeof value === 'object' && 'id' in value) {
|
|
328
|
+
return previewText((value as { id?: unknown }).id, maxLength);
|
|
329
|
+
}
|
|
330
|
+
|
|
331
|
+
// A few providers serialize nested legacy handle arguments before they reach the
|
|
332
|
+
// renderer. Keep the display useful even though prepareArguments normalizes
|
|
333
|
+
// them before execution.
|
|
334
|
+
if (typeof value === 'string') {
|
|
335
|
+
try {
|
|
336
|
+
const parsed: unknown = JSON.parse(value);
|
|
337
|
+
if (parsed && typeof parsed === 'object') return handlePreview(parsed, maxLength);
|
|
338
|
+
} catch {
|
|
339
|
+
// It may simply be an id, so fall through.
|
|
340
|
+
}
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
return previewText(value, maxLength);
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
/** Quote values that would otherwise be ambiguous in a command-like preview. */
|
|
347
|
+
function cliValue(value: unknown, maxLength = 80): string {
|
|
348
|
+
const text = previewText(value, maxLength);
|
|
349
|
+
return /[\s"'=]/.test(text) ? JSON.stringify(text) : text;
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
function cliOption(key: string, value: unknown, maxLength = 80): string {
|
|
353
|
+
if (value === undefined || value === null || value === '') return '';
|
|
354
|
+
const spec = OPTION_SPECS[key];
|
|
355
|
+
// Bare flags render without a value; `false` cannot be expressed as a bare
|
|
356
|
+
// flag, so it is omitted (the schema default applies).
|
|
357
|
+
if (spec.bare) return value ? `--${spec.flag}` : '';
|
|
358
|
+
// Booleans render as `--flag=true|false` so the parser round-trips them.
|
|
359
|
+
const text = typeof value === 'boolean' ? String(value) : cliValue(value, maxLength);
|
|
360
|
+
return `--${spec.flag}=${text}`;
|
|
361
|
+
}
|
|
362
|
+
|
|
363
|
+
export interface ShepherdCommandRender {
|
|
364
|
+
verb: string;
|
|
365
|
+
/** Positional args + options as `x y --flag=v …` (no leading verb/space). */
|
|
366
|
+
rest: string;
|
|
367
|
+
}
|
|
368
|
+
|
|
369
|
+
/**
|
|
370
|
+
* Render doAction args into the compact CLI-style line the tool-call preview
|
|
371
|
+
* shows. Flags come from the shared OPTION_SPECS table so every rendered line
|
|
372
|
+
* parses back with `parseShepherdCli`. Defaults that were not supplied are
|
|
373
|
+
* intentionally omitted, which keeps options like --scope visible without
|
|
374
|
+
* dumping internal implementation details (paneId, tabId, workspaceId).
|
|
375
|
+
*/
|
|
376
|
+
export function formatShepherdCommand(
|
|
377
|
+
verb: string,
|
|
378
|
+
options: Record<string, any>,
|
|
379
|
+
expanded = false
|
|
380
|
+
): ShepherdCommandRender {
|
|
381
|
+
const displayOptions = omitMaterializedDefaults(verb, options);
|
|
382
|
+
const valueLimit = expanded ? Number.POSITIVE_INFINITY : 80;
|
|
383
|
+
const idLimit = expanded ? Number.POSITIVE_INFINITY : 48;
|
|
384
|
+
const tokens: string[] = [];
|
|
385
|
+
const add = (key: string) => {
|
|
386
|
+
const option = cliOption(key, options[key], valueLimit);
|
|
387
|
+
if (option) tokens.push(option);
|
|
388
|
+
};
|
|
389
|
+
|
|
390
|
+
switch (verb) {
|
|
391
|
+
case 'spawn':
|
|
392
|
+
tokens.push(cliValue(displayOptions.agent, valueLimit));
|
|
393
|
+
for (const key of SPAWN_OPTION_KEYS) {
|
|
394
|
+
const option = cliOption(key, displayOptions[key], valueLimit);
|
|
395
|
+
if (option) tokens.push(option);
|
|
396
|
+
}
|
|
397
|
+
break;
|
|
398
|
+
case 'prompt':
|
|
399
|
+
tokens.push(handlePreview(options.id, idLimit));
|
|
400
|
+
if (options.message !== undefined) tokens.push(cliValue(options.message, valueLimit));
|
|
401
|
+
add('timeout');
|
|
402
|
+
break;
|
|
403
|
+
case 'status':
|
|
404
|
+
case 'close':
|
|
405
|
+
tokens.push(handlePreview(options.id, idLimit));
|
|
406
|
+
break;
|
|
407
|
+
case 'agents':
|
|
408
|
+
add('agentScope');
|
|
409
|
+
break;
|
|
410
|
+
case 'read':
|
|
411
|
+
tokens.push(cliValue(options.name, valueLimit));
|
|
412
|
+
for (const key of READ_OPTION_KEYS) add(key);
|
|
413
|
+
break;
|
|
414
|
+
}
|
|
415
|
+
|
|
416
|
+
return { verb, rest: tokens.join(' ') };
|
|
417
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from '../core/config.ts';
|