harma-kit 0.0.0-stage → 0.2.0
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/CHANGELOG.md +31 -0
- package/LICENSE +21 -0
- package/README.md +77 -2
- package/bin/harma.mjs +4 -0
- package/data/catalog.json +1085 -0
- package/docs/agents-and-sessions.md +55 -0
- package/docs/choosing-models.md +83 -0
- package/docs/commands.md +103 -0
- package/docs/development.md +42 -0
- package/docs/how-harma-decides.md +71 -0
- package/docs/troubleshooting.md +41 -0
- package/package.json +49 -4
- package/skill/SKILL.md +122 -0
- package/skill/references/commands.md +49 -0
- package/skill/references/troubleshooting.md +37 -0
- package/src/backends.mjs +233 -0
- package/src/catalog.mjs +54 -0
- package/src/cli.mjs +98 -0
- package/src/commands.mjs +680 -0
- package/src/credits.mjs +101 -0
- package/src/harness.mjs +94 -0
- package/src/install.mjs +106 -0
- package/src/inventory.mjs +72 -0
- package/src/rank.mjs +102 -0
- package/src/roster.mjs +177 -0
- package/src/route.mjs +69 -0
- package/src/state.mjs +134 -0
- package/src/tui.mjs +345 -0
- package/src/usage.mjs +127 -0
- package/src/util.mjs +90 -0
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# harma troubleshooting
|
|
2
|
+
|
|
3
|
+
## Exit code 4: the agent waits on a dialog
|
|
4
|
+
|
|
5
|
+
The agent started but waits on a question, often "trust this folder?" in a new directory, and the task wasn't delivered.
|
|
6
|
+
|
|
7
|
+
1. `harma read <name>` to see the question
|
|
8
|
+
2. Tell the user what it asks and ask them to answer it in the agent's tab or terminal. Don't answer it yourself, even when the answer looks obvious: trust and approval decisions belong to the user
|
|
9
|
+
3. After they confirm, `harma send <name> "<task>" --yes` (this needs their yes for the send)
|
|
10
|
+
|
|
11
|
+
## No usable model for a job
|
|
12
|
+
|
|
13
|
+
`dispatch --task-type` fails when every model on the user's list for that job has a missing CLI or exhausted credits; the hint lists the reason for each. Tell the user and offer options: add a model with `harma select`, wait for the provider's reset, or use `--model` for this dispatch if they pick one. If the user chose "no model" for the job, dispatch refuses it on purpose; ask before working around it.
|
|
14
|
+
|
|
15
|
+
## Selection screen without a terminal
|
|
16
|
+
|
|
17
|
+
`harma select` with no options needs an interactive terminal, which you don't have. Use `harma select --open --wait --json`, or ask in chat and record with `--set`.
|
|
18
|
+
|
|
19
|
+
## Credits are `sconosciuto`
|
|
20
|
+
|
|
21
|
+
harma has no reliable figure. Say so; don't estimate. Suggest one of: install or start CodexBar, enable the provider in CodexBar, or declare a budget in `.harma/config.json`:
|
|
22
|
+
|
|
23
|
+
```json
|
|
24
|
+
{ "budgets": { "codex": { "limit": 100, "currency": "USD" } } }
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## A model has no score
|
|
28
|
+
|
|
29
|
+
The bundled Artificial Analysis snapshot doesn't cover it. If `AA_API_KEY` is set, `harma rank --refresh` may fill it in. An unscored model never appears in proposals, but the user can still choose it.
|
|
30
|
+
|
|
31
|
+
## Cleanup keeps an agent
|
|
32
|
+
|
|
33
|
+
`working` or `blocked` agents, and agents without a known session id, stay open. Check with `harma status --json` and `harma read <name>`. Use `--force` only when the user asks, since it loses that agent's context.
|
|
34
|
+
|
|
35
|
+
## Anything else
|
|
36
|
+
|
|
37
|
+
`harma doctor` lists what's missing (backends, agent CLIs, CodexBar, AA key, installed skill) and how to install it. Don't start, stop or restart a herdr or hc server yourself.
|
package/src/backends.mjs
ADDED
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
// Terminal backends. Both expose the same interface:
|
|
2
|
+
// available() -> {ok, version, detail}
|
|
3
|
+
// start({name, cwd, argv, env, harness, project}) -> {target, tab?, sessionId?}
|
|
4
|
+
// list(project) -> [{target, name, status, cwd, sessionId, owned, raw}]
|
|
5
|
+
// prompt(target, text, {wait, timeoutSec})
|
|
6
|
+
// read(target, lines) -> text
|
|
7
|
+
// close(target) -> {ok}
|
|
8
|
+
// herdr: the full app (workspaces, tabs, panes); one tab per agent in a
|
|
9
|
+
// per-project workspace, so closing an agent closes its window.
|
|
10
|
+
// hc (herdr-core): headless terminals; ownership through labels.
|
|
11
|
+
import { basename } from 'node:path';
|
|
12
|
+
import { createHash } from 'node:crypto';
|
|
13
|
+
import { run, which, parseJson, HarmaError } from './util.mjs';
|
|
14
|
+
import { meta } from './harness.mjs';
|
|
15
|
+
|
|
16
|
+
export function projectId(root) {
|
|
17
|
+
return `${basename(root).toLowerCase().replace(/[^a-z0-9_-]/g, '-').slice(0, 20)}-${createHash('sha1').update(root).digest('hex').slice(0, 6)}`;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
const AGENT_NAME = /^[a-z][a-z0-9_-]{0,31}$/;
|
|
21
|
+
export function checkAgentName(name) {
|
|
22
|
+
if (!AGENT_NAME.test(name ?? '')) {
|
|
23
|
+
throw new HarmaError(`Nome agente non valido: ${name}`, { hint: 'Usa [a-z][a-z0-9_-]{0,31}, es. builder, review-1' });
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
function okJson(res, what) {
|
|
28
|
+
const data = parseJson(res.stdout);
|
|
29
|
+
if (!res.ok) {
|
|
30
|
+
const err = parseJson(res.stderr);
|
|
31
|
+
const e = new HarmaError(`${what} fallito: ${err?.error?.message ?? err?.message ?? (res.stderr.trim() || res.error || `exit ${res.code}`)}`);
|
|
32
|
+
e.code = err?.error?.code ?? null;
|
|
33
|
+
if (!e.code && /\bblocked\b/i.test(res.stderr)) e.code = 'agent_blocked';
|
|
34
|
+
throw e;
|
|
35
|
+
}
|
|
36
|
+
return data;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
// ---------------------------------------------------------------- herdr
|
|
40
|
+
export class HerdrBackend {
|
|
41
|
+
constructor({ bin = 'herdr', env = process.env, config = {} } = {}) {
|
|
42
|
+
this.name = 'herdr';
|
|
43
|
+
this.bin = bin;
|
|
44
|
+
this.env = env;
|
|
45
|
+
this.config = config; // project config (holds herdr.workspace_id)
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
exec(args, opts = {}) { return run(this.bin, args, { env: this.env, ...opts }); }
|
|
49
|
+
|
|
50
|
+
async available() {
|
|
51
|
+
if (!which(this.bin, this.env)) return { ok: false, detail: 'herdr non è nel PATH' };
|
|
52
|
+
const res = await this.exec(['status', 'server'], { timeout: 15_000 });
|
|
53
|
+
const running = /status:\s*running/.test(res.stdout);
|
|
54
|
+
const version = (res.stdout.match(/version:\s*(\S+)/) ?? [])[1] ?? null;
|
|
55
|
+
return { ok: running, version, detail: running ? 'server attivo' : 'server herdr non attivo (avvia herdr)' };
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
async ensureWorkspace(root, project) {
|
|
59
|
+
const known = this.config.herdr?.workspace_id;
|
|
60
|
+
if (known) {
|
|
61
|
+
const got = await this.exec(['workspace', 'get', known]);
|
|
62
|
+
if (got.ok) return { id: known, created: false };
|
|
63
|
+
}
|
|
64
|
+
const res = await this.exec(['workspace', 'create', '--cwd', root, '--label', `harma:${project}`, '--no-focus']);
|
|
65
|
+
const data = okJson(res, 'herdr workspace create');
|
|
66
|
+
const id = data?.result?.workspace?.workspace_id ?? data?.result?.workspace?.id;
|
|
67
|
+
if (!id) throw new HarmaError('herdr workspace create: risposta senza workspace_id');
|
|
68
|
+
return { id, created: true };
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
async start({ name, cwd, argv, env = {}, harness, root, project }) {
|
|
72
|
+
checkAgentName(name);
|
|
73
|
+
const kind = meta(harness).herdrKind;
|
|
74
|
+
if (!kind) throw new HarmaError(`herdr non riconosce ${harness} come agente`, { hint: 'Usa --backend hc per questa CLI' });
|
|
75
|
+
const ws = await this.ensureWorkspace(root, project);
|
|
76
|
+
const tabArgs = ['tab', 'create', '--workspace', ws.id, '--cwd', cwd, '--label', name, '--no-focus'];
|
|
77
|
+
for (const [k, v] of Object.entries(env)) tabArgs.push('--env', `${k}=${v}`);
|
|
78
|
+
const tab = okJson(await this.exec(tabArgs), 'herdr tab create');
|
|
79
|
+
const tabId = tab?.result?.tab?.tab_id;
|
|
80
|
+
const paneId = tab?.result?.root_pane?.pane_id;
|
|
81
|
+
if (!tabId || !paneId) throw new HarmaError('herdr tab create: risposta senza tab_id/pane_id');
|
|
82
|
+
const startArgs = ['agent', 'start', name, '--kind', kind, '--pane', paneId, '--timeout', '60000'];
|
|
83
|
+
if (argv.length > 1) startArgs.push('--', ...argv.slice(1));
|
|
84
|
+
const started = await this.exec(startArgs, { timeout: 90_000 });
|
|
85
|
+
if (!started.ok) {
|
|
86
|
+
const err = parseJson(started.stderr);
|
|
87
|
+
// agent_not_ready keeps the agent: it is blocked at startup (e.g. trust dialog).
|
|
88
|
+
if (err?.error?.code !== 'agent_not_ready') {
|
|
89
|
+
await this.exec(['tab', 'close', tabId]);
|
|
90
|
+
okJson(started, 'herdr agent start');
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
return { target: name, tab: tabId, pane: paneId, workspace: ws.id, workspaceCreated: ws.created };
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
async list() {
|
|
97
|
+
const data = okJson(await this.exec(['agent', 'list']), 'herdr agent list');
|
|
98
|
+
return (data?.result?.agents ?? []).map((a) => ({
|
|
99
|
+
target: a.name ?? a.pane_id,
|
|
100
|
+
name: a.name ?? null,
|
|
101
|
+
kind: a.agent,
|
|
102
|
+
status: a.agent_status ?? null,
|
|
103
|
+
cwd: a.cwd,
|
|
104
|
+
tab: a.tab_id,
|
|
105
|
+
pane: a.pane_id,
|
|
106
|
+
sessionId: a.agent_session?.value ?? null,
|
|
107
|
+
raw: a,
|
|
108
|
+
}));
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
async prompt(target, text, { wait = false, timeoutSec = 600 } = {}) {
|
|
112
|
+
const args = ['agent', 'prompt', target, text];
|
|
113
|
+
if (wait) args.push('--wait', '--timeout', String(timeoutSec * 1000));
|
|
114
|
+
return okJson(await this.exec(args, { timeout: (timeoutSec + 30) * 1000 }), 'herdr agent prompt');
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
async read(target, lines = 120) {
|
|
118
|
+
const res = await this.exec(['agent', 'read', target, '--source', 'recent-unwrapped', '--lines', String(lines)]);
|
|
119
|
+
const data = parseJson(res.stdout);
|
|
120
|
+
if (!res.ok) okJson(res, 'herdr agent read');
|
|
121
|
+
return data?.result?.text ?? data?.result?.content ?? res.stdout;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
async close({ tab, target }) {
|
|
125
|
+
if (!tab) throw new HarmaError(`Nessun tab registrato per ${target}: harma chiude solo le finestre che ha creato`);
|
|
126
|
+
const res = await this.exec(['tab', 'close', tab]);
|
|
127
|
+
return { ok: res.ok, detail: res.ok ? 'tab chiuso' : res.stderr.trim() };
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/** A focused tab in the project workspace running a shell command (used for the select TUI). */
|
|
131
|
+
async openTab({ root, project, label, command }) {
|
|
132
|
+
const ws = await this.ensureWorkspace(root, project);
|
|
133
|
+
const tab = okJson(await this.exec(['tab', 'create', '--workspace', ws.id, '--cwd', root, '--label', label, '--focus']), 'herdr tab create');
|
|
134
|
+
const tabId = tab?.result?.tab?.tab_id;
|
|
135
|
+
const paneId = tab?.result?.root_pane?.pane_id;
|
|
136
|
+
if (!tabId || !paneId) throw new HarmaError('herdr tab create: risposta senza tab_id/pane_id');
|
|
137
|
+
okJson(await this.exec(['pane', 'run', paneId, command]), 'herdr pane run');
|
|
138
|
+
return { tab: tabId, pane: paneId, workspace: ws.id, workspaceCreated: ws.created };
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
/** Only for the workspace harma created for this project (config.herdr.workspace_id). */
|
|
142
|
+
async closeWorkspace(id) {
|
|
143
|
+
const res = await this.exec(['workspace', 'close', id]);
|
|
144
|
+
return { ok: res.ok, detail: res.ok ? `workspace ${id} chiuso` : res.stderr.trim() };
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
// ---------------------------------------------------------------- hc
|
|
149
|
+
export class HcBackend {
|
|
150
|
+
constructor({ bin = 'hc', env = process.env } = {}) {
|
|
151
|
+
this.name = 'hc';
|
|
152
|
+
this.bin = bin;
|
|
153
|
+
this.env = env;
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
exec(args, opts = {}) { return run(this.bin, args, { env: this.env, ...opts }); }
|
|
157
|
+
|
|
158
|
+
async available() {
|
|
159
|
+
if (!which(this.bin, this.env)) {
|
|
160
|
+
return { ok: false, detail: 'hc non è nel PATH (installa herdr-core: https://github.com/herdrdev/herdr-core)' };
|
|
161
|
+
}
|
|
162
|
+
const v = await this.exec(['--version'], { timeout: 10_000 });
|
|
163
|
+
const st = await this.exec(['server', 'status', '--json'], { timeout: 15_000 });
|
|
164
|
+
return { ok: st.ok, version: v.stdout.trim().split(/\s+/).pop() || null, detail: st.ok ? 'core attivo' : 'core non raggiungibile (hc server start)' };
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
async start({ name, cwd, argv, env = {}, project }) {
|
|
168
|
+
checkAgentName(name);
|
|
169
|
+
const args = ['run', '--bg', '--json', '--name', name, '--cwd', cwd,
|
|
170
|
+
'--label', `harma.project=${project}`, '--label', `harma.agent=${name}`, '--outlive-parent'];
|
|
171
|
+
const envPairs = Object.entries(env).map(([k, v]) => `${k}=${v}`);
|
|
172
|
+
args.push('--', ...(envPairs.length ? ['env', ...envPairs] : []), ...argv);
|
|
173
|
+
const data = okJson(await this.exec(args, { timeout: 60_000 }), 'hc run');
|
|
174
|
+
const t = data?.terminal ?? data?.result ?? data;
|
|
175
|
+
return { target: t?.name ?? name, address: t?.address ?? null };
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
async list(project) {
|
|
179
|
+
const args = ['ls', '--json', '--all'];
|
|
180
|
+
if (project) args.push('--label', `harma.project=${project}`);
|
|
181
|
+
const data = okJson(await this.exec(args), 'hc ls');
|
|
182
|
+
const terms = Array.isArray(data) ? data : (data?.terminals ?? []);
|
|
183
|
+
return terms.map((t) => ({
|
|
184
|
+
target: t.name ?? t.address,
|
|
185
|
+
name: t.name ?? null,
|
|
186
|
+
address: t.address,
|
|
187
|
+
status: t.state === 'finished' ? 'finished' : (t.status?.status ?? (typeof t.status === 'string' ? t.status : null)),
|
|
188
|
+
cwd: t.foreground?.cwd ?? t.cwd,
|
|
189
|
+
sessionId: null,
|
|
190
|
+
labels: t.labels ?? {},
|
|
191
|
+
raw: t,
|
|
192
|
+
}));
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
async prompt(target, text, { wait = false, timeoutSec = 600 } = {}) {
|
|
196
|
+
const args = ['send', '--json', target, text];
|
|
197
|
+
if (wait) args.push('--wait', '--timeout', String(timeoutSec));
|
|
198
|
+
return okJson(await this.exec(args, { timeout: (timeoutSec + 30) * 1000 }), 'hc send');
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
async read(target, lines = 120) {
|
|
202
|
+
const res = await this.exec(['read', target, '--lines', String(lines)]);
|
|
203
|
+
if (!res.ok) okJson(res, 'hc read');
|
|
204
|
+
return res.stdout;
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
async close({ target }) {
|
|
208
|
+
const k = await this.exec(['kill', '--json', target]);
|
|
209
|
+
const r = await this.exec(['rm', '--json', target]);
|
|
210
|
+
return { ok: k.ok || r.ok, detail: [k.ok ? 'terminato' : k.stderr.trim(), r.ok ? 'rimosso' : r.stderr.trim()].filter(Boolean).join('; ') };
|
|
211
|
+
}
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
/** Pick the backend: explicit, else configured, else the first that is running (herdr, then hc). */
|
|
215
|
+
export async function selectBackend({ choice, config = {}, env = process.env } = {}) {
|
|
216
|
+
const want = choice ?? (config.backend && config.backend !== 'auto' ? config.backend : null);
|
|
217
|
+
const make = (n) => (n === 'herdr' ? new HerdrBackend({ env, config }) : new HcBackend({ env }));
|
|
218
|
+
if (want) {
|
|
219
|
+
if (!['herdr', 'hc'].includes(want)) throw new HarmaError(`Backend sconosciuto: ${want}`, { hint: 'herdr | hc' });
|
|
220
|
+
const b = make(want);
|
|
221
|
+
const a = await b.available();
|
|
222
|
+
if (!a.ok) throw new HarmaError(`Backend ${want} non disponibile: ${a.detail}`);
|
|
223
|
+
return b;
|
|
224
|
+
}
|
|
225
|
+
const reasons = [];
|
|
226
|
+
for (const n of ['herdr', 'hc']) {
|
|
227
|
+
const b = make(n);
|
|
228
|
+
const a = await b.available();
|
|
229
|
+
if (a.ok) return b;
|
|
230
|
+
reasons.push(`${n}: ${a.detail}`);
|
|
231
|
+
}
|
|
232
|
+
throw new HarmaError('Nessun backend di terminali disponibile', { hint: reasons.join(' · ') });
|
|
233
|
+
}
|
package/src/catalog.mjs
ADDED
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
// The model catalog: models, efforts, prices, Artificial Analysis figures,
|
|
2
|
+
// and how each agent CLI takes a model and an effort.
|
|
3
|
+
// The bundled snapshot (data/catalog.json) is overridden by a user-level
|
|
4
|
+
// refresh (~/.config/harma/catalog.json) when that one is newer.
|
|
5
|
+
import { join, dirname } from 'node:path';
|
|
6
|
+
import { fileURLToPath } from 'node:url';
|
|
7
|
+
import { homedir } from 'node:os';
|
|
8
|
+
import { readJson } from './util.mjs';
|
|
9
|
+
|
|
10
|
+
const BUNDLED = join(dirname(fileURLToPath(import.meta.url)), '..', 'data', 'catalog.json');
|
|
11
|
+
|
|
12
|
+
export function userCatalogPath(env = process.env) {
|
|
13
|
+
const base = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), '.config');
|
|
14
|
+
return join(base, 'harma', 'catalog.json');
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
export function loadCatalog({ env = process.env, path } = {}) {
|
|
18
|
+
if (path) return readJson(path);
|
|
19
|
+
const bundled = readJson(BUNDLED);
|
|
20
|
+
const user = readJson(userCatalogPath(env));
|
|
21
|
+
if (user && (user.generated_at ?? '') >= (bundled?.generated_at ?? '')) {
|
|
22
|
+
return { ...user, origin: 'user-refresh' };
|
|
23
|
+
}
|
|
24
|
+
return { ...bundled, origin: 'bundled' };
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/** "claude-cli" -> "claude"; "claude-cli-zai" -> "claude-zai". */
|
|
28
|
+
export function harnessName(tool) {
|
|
29
|
+
return tool.replace(/-cli(-|$)/, (_, tail) => (tail ? '-' : ''));
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** Harnesses keyed by short name. */
|
|
33
|
+
export function harnesses(catalog) {
|
|
34
|
+
const out = {};
|
|
35
|
+
for (const [tool, h] of Object.entries(catalog.harnesses ?? {})) {
|
|
36
|
+
out[harnessName(tool)] = { tool, ...h };
|
|
37
|
+
}
|
|
38
|
+
return out;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** AA index for a model at an effort: exact effort, else the model's only/"default" row. */
|
|
42
|
+
export function aaIndex(model, effort) {
|
|
43
|
+
const idx = model?.aa?.index;
|
|
44
|
+
if (!idx) return null;
|
|
45
|
+
if (idx[effort] !== undefined) return idx[effort];
|
|
46
|
+
if (idx.default !== undefined && Object.keys(idx).length === 1) return idx.default;
|
|
47
|
+
return null;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
export function aaCost(model, effort) {
|
|
51
|
+
const c = model?.aa?.cost_per_task;
|
|
52
|
+
if (!c) return null;
|
|
53
|
+
return c[effort] ?? (Object.keys(c).length === 1 ? Object.values(c)[0] : null);
|
|
54
|
+
}
|
package/src/cli.mjs
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
import {
|
|
2
|
+
cmdInit, cmdModels, cmdCredits, cmdRank, cmdRoute, cmdDispatch, cmdSend, cmdRead,
|
|
3
|
+
cmdStatus, cmdCosts, cmdCleanup, cmdResume, cmdSelect,
|
|
4
|
+
} from './commands.mjs';
|
|
5
|
+
import { cmdInstall, cmdUninstall, cmdDoctor } from './install.mjs';
|
|
6
|
+
import { HarmaError } from './util.mjs';
|
|
7
|
+
|
|
8
|
+
const BOOLEAN = new Set(['json', 'yes', 'wait', 'refresh', 'dry-run', 'force', 'all', 'print-only', 'help', 'version', 'workspace', 'open', 'accept', 'show', 'close-tab']);
|
|
9
|
+
|
|
10
|
+
export function parseArgs(argv) {
|
|
11
|
+
const flags = { _: [] };
|
|
12
|
+
for (let i = 0; i < argv.length; i++) {
|
|
13
|
+
const a = argv[i];
|
|
14
|
+
if (a === '--') { flags._.push(...argv.slice(i + 1)); break; }
|
|
15
|
+
if (a.startsWith('--')) {
|
|
16
|
+
const [k, inline] = a.slice(2).split(/=(.*)/s);
|
|
17
|
+
if (inline !== undefined) flags[k] = inline;
|
|
18
|
+
else if (BOOLEAN.has(k)) flags[k] = true;
|
|
19
|
+
else if (i + 1 < argv.length) flags[k] = argv[++i];
|
|
20
|
+
else throw new HarmaError(`--${k} richiede un valore`);
|
|
21
|
+
} else if (a === '-h') flags.help = true;
|
|
22
|
+
else flags._.push(a);
|
|
23
|
+
}
|
|
24
|
+
return flags;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
export const HELP = `harma — un modello orchestratore che dirige gli altri agenti del progetto
|
|
28
|
+
|
|
29
|
+
Uso: harma <comando> [opzioni] (--json su ogni comando per output leggibile da un agente)
|
|
30
|
+
|
|
31
|
+
Progetto
|
|
32
|
+
init --orchestrator <harness>:<model> --effort <level> [--backend auto|herdr|hc] [--policy confirm|auto-within-budget]
|
|
33
|
+
|
|
34
|
+
Conoscere le risorse
|
|
35
|
+
models CLI di agenti, modelli ed effort su questa macchina
|
|
36
|
+
credits crediti e limiti per provider (CodexBar, budget, stima dai log)
|
|
37
|
+
rank [--refresh] [--top N] intelligenza per modello × effort (Artificial Analysis)
|
|
38
|
+
route <tipo> [--author h:m] classifica per: pianificazione, sviluppo, review, debugging, ricerca, estrazione
|
|
39
|
+
|
|
40
|
+
Scegliere i modelli (l'utente valida o cambia le proposte)
|
|
41
|
+
select TUI: modello ed effort per l'orchestratore; per ogni lavoro uno o più
|
|
42
|
+
modelli in ordine (al dispatch: il primo con crediti utilizzabili)
|
|
43
|
+
select --open [--wait] apre la TUI in un tab herdr (o terminale hc) e aspetta il salvataggio
|
|
44
|
+
select --accept | --set "sviluppo=codex:gpt-6.1-sol@high|claude:claude-sonnet-5-5@high,review=none" | --show
|
|
45
|
+
|
|
46
|
+
Delegare (con policy "confirm" serve --yes, dopo il consenso dell'utente)
|
|
47
|
+
dispatch --name <n> (--model h:m [--effort e] | --task-type <tipo>) [--prompt "…" | --prompt-file f] [--wait] [--yes]
|
|
48
|
+
send <nome> "<testo>" [--wait] [--yes]
|
|
49
|
+
read <nome> [--lines N]
|
|
50
|
+
|
|
51
|
+
Sorvegliare
|
|
52
|
+
status [--all] stato di ogni agente aperto
|
|
53
|
+
costs costo per agente, crediti per provider, indicazioni di delega
|
|
54
|
+
|
|
55
|
+
Pulire e riprendere
|
|
56
|
+
cleanup [--dry-run] [--agent <nome>] [--force] [--workspace] salva l'id di sessione e chiude le finestre finite
|
|
57
|
+
resume <nome> [--yes] [--print-only] riapre la sessione salvata con il suo contesto
|
|
58
|
+
|
|
59
|
+
Installazione
|
|
60
|
+
install [--target claude|codex|both] [--force] installa la skill
|
|
61
|
+
uninstall [--target …]
|
|
62
|
+
doctor controlla l'ambiente
|
|
63
|
+
`;
|
|
64
|
+
|
|
65
|
+
const COMMANDS = {
|
|
66
|
+
init: cmdInit, models: cmdModels, credits: cmdCredits, rank: cmdRank, route: cmdRoute,
|
|
67
|
+
dispatch: cmdDispatch, send: cmdSend, read: cmdRead, status: cmdStatus, costs: cmdCosts,
|
|
68
|
+
cleanup: cmdCleanup, resume: cmdResume, select: cmdSelect, install: cmdInstall, uninstall: cmdUninstall, doctor: cmdDoctor,
|
|
69
|
+
};
|
|
70
|
+
|
|
71
|
+
export async function main(argv, opts = {}) {
|
|
72
|
+
const out = opts.out ?? ((s) => process.stdout.write(s + '\n'));
|
|
73
|
+
const err = opts.err ?? ((s) => process.stderr.write(s + '\n'));
|
|
74
|
+
let flags;
|
|
75
|
+
try { flags = parseArgs(argv); } catch (e) { err(`harma: ${e.message}`); return 2; }
|
|
76
|
+
const [cmd, ...rest] = flags._;
|
|
77
|
+
if (flags.version || cmd === 'version') {
|
|
78
|
+
const { readFileSync } = await import('node:fs');
|
|
79
|
+
out(JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version);
|
|
80
|
+
return 0;
|
|
81
|
+
}
|
|
82
|
+
if (!cmd || flags.help || cmd === 'help') { out(HELP); return 0; }
|
|
83
|
+
const fn = COMMANDS[cmd];
|
|
84
|
+
if (!fn) { err(`harma: comando sconosciuto "${cmd}"\n\n${HELP}`); return 2; }
|
|
85
|
+
flags._ = rest;
|
|
86
|
+
try {
|
|
87
|
+
const res = await fn(flags, { ...opts, out });
|
|
88
|
+
return res?.exitCode ?? 0;
|
|
89
|
+
} catch (e) {
|
|
90
|
+
if (e instanceof HarmaError) {
|
|
91
|
+
if (flags.json) out(JSON.stringify({ error: e.message, hint: e.hint ?? null }));
|
|
92
|
+
else err(`harma: ${e.message}${e.hint ? `\n → ${e.hint}` : ''}`);
|
|
93
|
+
return e.exitCode ?? 1;
|
|
94
|
+
}
|
|
95
|
+
err(`harma: errore inatteso: ${e.stack ?? e}`);
|
|
96
|
+
return 1;
|
|
97
|
+
}
|
|
98
|
+
}
|