harma-kit 0.0.0-stage → 0.1.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 +21 -0
- package/LICENSE +21 -0
- package/README.md +118 -2
- package/bin/harma.mjs +4 -0
- package/data/catalog.json +1085 -0
- package/package.json +48 -4
- package/skill/SKILL.md +131 -0
- package/src/backends.mjs +222 -0
- package/src/catalog.mjs +54 -0
- package/src/cli.mjs +92 -0
- package/src/commands.mjs +522 -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/route.mjs +69 -0
- package/src/state.mjs +134 -0
- package/src/usage.mjs +127 -0
- package/src/util.mjs +90 -0
package/src/harness.mjs
ADDED
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
// How harma drives each agent CLI ("harness"): launch argv for a model and an
|
|
2
|
+
// effort, which CodexBar provider meters it, which herdr agent kind it is,
|
|
3
|
+
// how its native session id is obtained and how a session is resumed.
|
|
4
|
+
import { randomUUID } from 'node:crypto';
|
|
5
|
+
import { harnesses } from './catalog.mjs';
|
|
6
|
+
import { HarmaError } from './util.mjs';
|
|
7
|
+
|
|
8
|
+
// Facts not in the model catalog. Session/resume syntax verified with
|
|
9
|
+
// `claude --help` (2.1.319) and `codex resume --help` (codex-cli 0.167.0).
|
|
10
|
+
export const HARNESS_META = {
|
|
11
|
+
claude: { herdrKind: 'claude', codexbar: 'claude', logs: 'claude', presetSession: '--session-id', resume: (id) => ['claude', '--resume', id] },
|
|
12
|
+
codex: { herdrKind: 'codex', codexbar: 'codex', logs: 'codex', resume: (id) => ['codex', 'resume', id] },
|
|
13
|
+
agy: { herdrKind: 'agy', codexbar: 'antigravity' },
|
|
14
|
+
kimi: { herdrKind: 'kimi', codexbar: 'kimi' },
|
|
15
|
+
grok: { herdrKind: 'grok', codexbar: 'grok' },
|
|
16
|
+
muse: { herdrKind: 'muse', codexbar: 'muse', interactiveBinary: 'muse' },
|
|
17
|
+
qwen: { herdrKind: 'qwen', codexbar: 'qwencloud' },
|
|
18
|
+
mmx: { codexbar: 'minimax' },
|
|
19
|
+
vibe: { codexbar: 'mistral' },
|
|
20
|
+
// Claude Code pointed at another provider: needs that provider's env set up.
|
|
21
|
+
'claude-moonshot': { codexbar: 'moonshot', variantOf: 'claude' },
|
|
22
|
+
'claude-zai': { codexbar: 'zai', variantOf: 'claude' },
|
|
23
|
+
};
|
|
24
|
+
|
|
25
|
+
export function meta(name) {
|
|
26
|
+
return HARNESS_META[name] ?? {};
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/** Parse "codex:gpt-6-astra" or a bare model id (harness inferred from the catalog). */
|
|
30
|
+
export function parseTarget(spec, catalog) {
|
|
31
|
+
if (!spec) throw new HarmaError('Manca il modello: usa <harness>:<model>, es. codex:gpt-6-astra');
|
|
32
|
+
const hs = harnesses(catalog);
|
|
33
|
+
if (spec.includes(':')) {
|
|
34
|
+
const [harness, model] = spec.split(/:(.*)/s);
|
|
35
|
+
if (!hs[harness]) throw new HarmaError(`Harness sconosciuto: ${harness}`, { hint: `Noti: ${Object.keys(hs).join(', ')}` });
|
|
36
|
+
return { harness, model };
|
|
37
|
+
}
|
|
38
|
+
const owners = Object.entries(hs).filter(([n, h]) => h.models?.[spec] && !meta(n).variantOf).map(([n]) => n);
|
|
39
|
+
if (owners.length === 1) return { harness: owners[0], model: spec };
|
|
40
|
+
if (owners.length > 1) throw new HarmaError(`Il modello ${spec} gira su più CLI: ${owners.join(', ')}`, { hint: 'Specifica <harness>:<model>' });
|
|
41
|
+
throw new HarmaError(`Modello sconosciuto: ${spec}`, { hint: 'Vedi `harma models`' });
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
export function effortValues(harness, model, catalog) {
|
|
45
|
+
const h = harnesses(catalog)[harness];
|
|
46
|
+
return h?.models?.[model]?.effort_values ?? h?.effort_values ?? catalog.models?.[model]?.efforts ?? [];
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* The argv and env that start <harness> on <model> at <effort>.
|
|
51
|
+
* Returns {argv, env, effortApplied, sessionId, notes}.
|
|
52
|
+
*/
|
|
53
|
+
export function launchSpec({ harness, model, effort }, catalog, { sessionId } = {}) {
|
|
54
|
+
const h = harnesses(catalog)[harness];
|
|
55
|
+
if (!h) throw new HarmaError(`Harness sconosciuto: ${harness}`);
|
|
56
|
+
const m = meta(harness);
|
|
57
|
+
const hm = h.models?.[model];
|
|
58
|
+
if (!hm) throw new HarmaError(`${harness} non serve il modello ${model}`, { hint: `Modelli: ${Object.keys(h.models ?? {}).join(', ')}` });
|
|
59
|
+
|
|
60
|
+
const allowed = effortValues(harness, model, catalog);
|
|
61
|
+
if (effort && allowed.length && !allowed.includes(effort)) {
|
|
62
|
+
throw new HarmaError(`Effort ${effort} non supportato da ${harness}:${model}`, { hint: `Valori: ${allowed.join(', ')}` });
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
const binary = m.interactiveBinary ?? h.binary.split(' ')[0];
|
|
66
|
+
const name = (effort && hm.names?.[effort]) || hm.name || model;
|
|
67
|
+
const argv = [binary];
|
|
68
|
+
const env = {};
|
|
69
|
+
const notes = [];
|
|
70
|
+
if (h.model_flag) argv.push(h.model_flag, name);
|
|
71
|
+
else notes.push('questa CLI non ha un flag per il modello: usa quello configurato');
|
|
72
|
+
|
|
73
|
+
let effortApplied = false;
|
|
74
|
+
if (effort && h.effort_via) {
|
|
75
|
+
const [kind, key] = h.effort_via.split(/:(.*)/s);
|
|
76
|
+
if (kind === 'flag') { argv.push(key, effort); effortApplied = true; }
|
|
77
|
+
else if (kind === 'config') { argv.push('-c', `${key}="${effort}"`); effortApplied = true; }
|
|
78
|
+
else if (kind === 'env') { env[key] = effort; effortApplied = true; }
|
|
79
|
+
}
|
|
80
|
+
if (effort && !effortApplied) notes.push(`effort ${effort} non impostabile per ${harness}: resta il default della CLI`);
|
|
81
|
+
|
|
82
|
+
let sid = null;
|
|
83
|
+
if (m.presetSession) {
|
|
84
|
+
sid = sessionId ?? randomUUID();
|
|
85
|
+
argv.push(m.presetSession, sid);
|
|
86
|
+
}
|
|
87
|
+
return { argv, env, effortApplied, sessionId: sid, notes, billing: h.billing };
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
export function resumeArgv(harness, sessionId) {
|
|
91
|
+
const m = meta(harness);
|
|
92
|
+
if (!sessionId) return null;
|
|
93
|
+
return m.resume ? m.resume(sessionId) : null;
|
|
94
|
+
}
|
package/src/install.mjs
ADDED
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
// install / uninstall / doctor.
|
|
2
|
+
// The skill directory (skill/) is copied to ~/.claude/skills/harma and/or
|
|
3
|
+
// ~/.codex/skills/harma. Both hosts load <dir>/SKILL.md.
|
|
4
|
+
import { cpSync, rmSync, existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
|
|
5
|
+
import { join, dirname } from 'node:path';
|
|
6
|
+
import { fileURLToPath } from 'node:url';
|
|
7
|
+
import { homedir } from 'node:os';
|
|
8
|
+
import { which, run, HarmaError } from './util.mjs';
|
|
9
|
+
import { loadCatalog } from './catalog.mjs';
|
|
10
|
+
import { aaKey } from './rank.mjs';
|
|
11
|
+
import { HerdrBackend, HcBackend } from './backends.mjs';
|
|
12
|
+
|
|
13
|
+
const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
|
|
14
|
+
const SKILL_SRC = join(PKG_ROOT, 'skill');
|
|
15
|
+
const MARKER = '.installed-by-harma';
|
|
16
|
+
|
|
17
|
+
export function skillTargets(target, env = process.env) {
|
|
18
|
+
const home = env.HOME || homedir();
|
|
19
|
+
const all = {
|
|
20
|
+
claude: join(env.CLAUDE_CONFIG_DIR || join(home, '.claude'), 'skills', 'harma'),
|
|
21
|
+
codex: join(env.CODEX_HOME || join(home, '.codex'), 'skills', 'harma'),
|
|
22
|
+
};
|
|
23
|
+
if (target === 'both' || !target) return all;
|
|
24
|
+
if (!all[target]) throw new HarmaError(`--target: claude | codex | both (non ${target})`);
|
|
25
|
+
return { [target]: all[target] };
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
function version() {
|
|
29
|
+
return JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8')).version;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export async function cmdInstall(flags, opts = {}) {
|
|
33
|
+
const out = opts.out ?? ((s) => process.stdout.write(s + '\n'));
|
|
34
|
+
const env = opts.env ?? process.env;
|
|
35
|
+
const lines = [];
|
|
36
|
+
for (const [host, dest] of Object.entries(skillTargets(flags.target ?? 'both', env))) {
|
|
37
|
+
if (existsSync(dest) && !existsSync(join(dest, MARKER)) && !flags.force) {
|
|
38
|
+
lines.push(`${host}: ${dest} esiste e non è stato installato da harma — saltato (usa --force per sovrascrivere)`);
|
|
39
|
+
continue;
|
|
40
|
+
}
|
|
41
|
+
rmSync(dest, { recursive: true, force: true });
|
|
42
|
+
mkdirSync(dirname(dest), { recursive: true });
|
|
43
|
+
cpSync(SKILL_SRC, dest, { recursive: true });
|
|
44
|
+
writeFileSync(join(dest, MARKER), `harma ${version()}\n`);
|
|
45
|
+
lines.push(`${host}: skill installata in ${dest}`);
|
|
46
|
+
}
|
|
47
|
+
lines.push('', 'Per la CLI: npm i -g harma-kit (comando: harma; oppure npx harma-kit <comando>)', 'Poi, nel progetto: harma init --orchestrator <harness>:<model> --effort <level>');
|
|
48
|
+
out(lines.join('\n'));
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
export async function cmdUninstall(flags, opts = {}) {
|
|
52
|
+
const out = opts.out ?? ((s) => process.stdout.write(s + '\n'));
|
|
53
|
+
const env = opts.env ?? process.env;
|
|
54
|
+
const lines = [];
|
|
55
|
+
for (const [host, dest] of Object.entries(skillTargets(flags.target ?? 'both', env))) {
|
|
56
|
+
if (!existsSync(dest)) { lines.push(`${host}: non installata`); continue; }
|
|
57
|
+
if (!existsSync(join(dest, MARKER)) && !flags.force) { lines.push(`${host}: ${dest} non è di harma — lasciata`); continue; }
|
|
58
|
+
rmSync(dest, { recursive: true, force: true });
|
|
59
|
+
lines.push(`${host}: rimossa ${dest}`);
|
|
60
|
+
}
|
|
61
|
+
out(lines.join('\n'));
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
export async function cmdDoctor(flags, opts = {}) {
|
|
65
|
+
const out = opts.out ?? ((s) => process.stdout.write(s + '\n'));
|
|
66
|
+
const env = opts.env ?? process.env;
|
|
67
|
+
const checks = [];
|
|
68
|
+
const add = (name, ok, detail, required = false) => checks.push({ name, ok, detail, required });
|
|
69
|
+
|
|
70
|
+
const major = Number(process.versions.node.split('.')[0]);
|
|
71
|
+
add('node >= 20', major >= 20, process.versions.node, true);
|
|
72
|
+
|
|
73
|
+
const cat = loadCatalog({ env });
|
|
74
|
+
add('catalogo modelli', Boolean(cat?.models && Object.keys(cat.models).length), cat ? `${Object.keys(cat.models).length} modelli, ${cat.origin} ${cat.generated_at}` : 'non leggibile', true);
|
|
75
|
+
add('file della skill', existsSync(join(SKILL_SRC, 'SKILL.md')), SKILL_SRC, true);
|
|
76
|
+
|
|
77
|
+
const herdr = await new HerdrBackend({ env }).available();
|
|
78
|
+
const hc = await new HcBackend({ env }).available();
|
|
79
|
+
add('backend herdr', herdr.ok, `${herdr.version ?? ''} ${herdr.detail}`.trim());
|
|
80
|
+
add('backend hc (herdr-core)', hc.ok, `${hc.version ?? ''} ${hc.detail}`.trim());
|
|
81
|
+
add('almeno un backend', herdr.ok || hc.ok, herdr.ok || hc.ok ? 'ok' : 'installa herdr o herdr-core per avviare agenti', true);
|
|
82
|
+
|
|
83
|
+
const agentClis = ['claude', 'codex', 'agy', 'kimi', 'grok', 'muse', 'qwen'].filter((b) => which(b, env));
|
|
84
|
+
add('CLI di agenti', agentClis.length > 0, agentClis.join(', ') || 'nessuna', true);
|
|
85
|
+
|
|
86
|
+
const cb = which('codexbar', env);
|
|
87
|
+
let cbDetail = 'non installato: crediti da budget dichiarati o stima dai log';
|
|
88
|
+
if (cb) {
|
|
89
|
+
const v = await run('codexbar', ['--version'], { env, timeout: 10_000 });
|
|
90
|
+
cbDetail = v.stdout.trim().split('\n')[0] || 'presente';
|
|
91
|
+
}
|
|
92
|
+
add('codexbar (crediti)', Boolean(cb), cbDetail);
|
|
93
|
+
add('chiave Artificial Analysis', Boolean(aaKey(env)), aaKey(env) ? 'presente (harma rank --refresh)' : 'assente: si usa lo snapshot incluso');
|
|
94
|
+
|
|
95
|
+
for (const [host, dest] of Object.entries(skillTargets('both', env))) {
|
|
96
|
+
add(`skill per ${host}`, existsSync(join(dest, 'SKILL.md')), existsSync(dest) ? dest : `non installata (npx harma-kit install --target ${host})`);
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
const failed = checks.filter((c) => c.required && !c.ok);
|
|
100
|
+
if (flags.json) out(JSON.stringify({ ok: !failed.length, checks }, null, 2));
|
|
101
|
+
else {
|
|
102
|
+
out(checks.map((c) => `${c.ok ? 'ok ' : c.required ? 'FAIL' : 'warn'} ${c.name} — ${c.detail}`).join('\n'));
|
|
103
|
+
out(failed.length ? `\n${failed.length} controlli obbligatori falliti.` : '\nharma è pronto.');
|
|
104
|
+
}
|
|
105
|
+
return { ok: !failed.length, checks, exitCode: failed.length ? 1 : 0 };
|
|
106
|
+
}
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
// What this machine can run: agent CLIs on PATH, their models, their efforts.
|
|
2
|
+
// Codex lists its models and efforts in ~/.codex/models_cache.json (machine
|
|
3
|
+
// source). The other CLIs do not list models offline, so their models come
|
|
4
|
+
// from the catalog and are reported with that source.
|
|
5
|
+
import { join } from 'node:path';
|
|
6
|
+
import { homedir } from 'node:os';
|
|
7
|
+
import { which, run, readJson, now } from './util.mjs';
|
|
8
|
+
import { harnesses } from './catalog.mjs';
|
|
9
|
+
import { meta } from './harness.mjs';
|
|
10
|
+
|
|
11
|
+
export async function inventory({ catalog, env = process.env, config = {}, versions = true } = {}) {
|
|
12
|
+
const hs = harnesses(catalog);
|
|
13
|
+
const clis = [];
|
|
14
|
+
const rows = [];
|
|
15
|
+
for (const [name, h] of Object.entries(hs)) {
|
|
16
|
+
const m = meta(name);
|
|
17
|
+
const bin = h.binary.split(' ')[0];
|
|
18
|
+
const path = which(bin, env);
|
|
19
|
+
let state = path ? 'installato' : 'assente';
|
|
20
|
+
if (path && m.variantOf && !config.harnesses?.[name]?.enabled) {
|
|
21
|
+
state = 'richiede configurazione';
|
|
22
|
+
}
|
|
23
|
+
let version = null;
|
|
24
|
+
if (path && versions && !m.variantOf) {
|
|
25
|
+
const v = await run(bin, ['--version'], { env, timeout: 10_000 });
|
|
26
|
+
version = v.ok ? v.stdout.trim().split('\n')[0].slice(0, 60) : null;
|
|
27
|
+
}
|
|
28
|
+
clis.push({ harness: name, binary: bin, state, version, billing: h.billing, effort_via: h.effort_via });
|
|
29
|
+
if (state !== 'installato') continue;
|
|
30
|
+
|
|
31
|
+
const machine = name === 'codex' ? codexModels(env) : null;
|
|
32
|
+
const models = machine ?? Object.keys(h.models ?? {}).map((id) => {
|
|
33
|
+
const def = catalog.models?.[id]?.effort_default ?? null;
|
|
34
|
+
// A CLI with no effort control runs at its own default: list only that.
|
|
35
|
+
if (!h.effort_via) {
|
|
36
|
+
return { model: id, efforts: def ? [def] : [], effort_fixed: true, default: def, source: `catalogo (${h.source}, ${h.verified_on}); effort non impostabile dalla CLI` };
|
|
37
|
+
}
|
|
38
|
+
return {
|
|
39
|
+
model: id,
|
|
40
|
+
efforts: h.models[id].effort_values ?? h.effort_values ?? catalog.models?.[id]?.efforts ?? [],
|
|
41
|
+
default: def,
|
|
42
|
+
source: `catalogo (${h.source}, ${h.verified_on})`,
|
|
43
|
+
};
|
|
44
|
+
});
|
|
45
|
+
for (const mm of models) {
|
|
46
|
+
rows.push({
|
|
47
|
+
harness: name,
|
|
48
|
+
model: mm.model,
|
|
49
|
+
efforts: mm.efforts,
|
|
50
|
+
effort_fixed: Boolean(mm.effort_fixed),
|
|
51
|
+
default_effort: mm.default ?? null,
|
|
52
|
+
in_catalog: Boolean(catalog.models?.[mm.model]),
|
|
53
|
+
source: mm.source,
|
|
54
|
+
});
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
return { fetched_at: now(), clis, models: rows };
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
function codexModels(env) {
|
|
61
|
+
const path = join(env.HOME || homedir(), '.codex', 'models_cache.json');
|
|
62
|
+
const data = readJson(path);
|
|
63
|
+
if (!Array.isArray(data?.models)) return null;
|
|
64
|
+
return data.models
|
|
65
|
+
.filter((m) => m.slug && m.visibility !== 'hidden')
|
|
66
|
+
.map((m) => ({
|
|
67
|
+
model: m.slug,
|
|
68
|
+
efforts: (m.supported_reasoning_levels ?? []).map((l) => l.effort).filter(Boolean),
|
|
69
|
+
default: m.default_reasoning_level ?? null,
|
|
70
|
+
source: `~/.codex/models_cache.json (${(data.fetched_at ?? '').slice(0, 10)})`,
|
|
71
|
+
}));
|
|
72
|
+
}
|
package/src/rank.mjs
ADDED
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
// Intelligence per model x effort: the Artificial Analysis Intelligence Index.
|
|
2
|
+
// From the catalog snapshot, or refreshed from the AA API when a key exists
|
|
3
|
+
// (AA_API_KEY, or the delegation-kit key file). Missing scores stay null and
|
|
4
|
+
// are printed as "sconosciuto"; nothing is interpolated.
|
|
5
|
+
import { readFileSync, mkdirSync, writeFileSync, existsSync } from 'node:fs';
|
|
6
|
+
import { dirname, join } from 'node:path';
|
|
7
|
+
import { homedir } from 'node:os';
|
|
8
|
+
import { aaIndex, aaCost, userCatalogPath } from './catalog.mjs';
|
|
9
|
+
import { EFFORT_ORDER, HarmaError } from './util.mjs';
|
|
10
|
+
|
|
11
|
+
export function rankRows(catalog, inventoryModels) {
|
|
12
|
+
const rows = [];
|
|
13
|
+
for (const m of inventoryModels) {
|
|
14
|
+
const model = catalog.models?.[m.model];
|
|
15
|
+
const efforts = m.efforts?.length ? m.efforts : [null];
|
|
16
|
+
for (const effort of efforts) {
|
|
17
|
+
rows.push({
|
|
18
|
+
harness: m.harness,
|
|
19
|
+
model: m.model,
|
|
20
|
+
effort,
|
|
21
|
+
index: model ? aaIndex(model, effort) : null,
|
|
22
|
+
cost_per_task: model ? aaCost(model, effort) : null,
|
|
23
|
+
provider: model?.provider ?? null,
|
|
24
|
+
aa_date: model?.aa?.date ?? null,
|
|
25
|
+
index_version: model?.aa?.index_version ?? null,
|
|
26
|
+
});
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
return rows.sort((a, b) => (b.index ?? -1) - (a.index ?? -1)
|
|
30
|
+
|| EFFORT_ORDER.indexOf(a.effort) - EFFORT_ORDER.indexOf(b.effort));
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
const VARIANT = /^(.*?)\s*\(([^()]*)\)\s*$/;
|
|
34
|
+
const VARIANT_WORDS = new Set([...EFFORT_ORDER, 'non-reasoning', 'reasoning', 'thinking']);
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* AA rows -> family slug -> variant -> index. Same rule as controller-models:
|
|
38
|
+
* the variant is the first effort word in the name's parenthetical
|
|
39
|
+
* ("Claude Opus 5.5 (Max)") and the family slug drops "-<variant>".
|
|
40
|
+
*/
|
|
41
|
+
export function aaFamilies(rows) {
|
|
42
|
+
const out = {};
|
|
43
|
+
for (const r of rows) {
|
|
44
|
+
const name = r.name ?? '';
|
|
45
|
+
const slug = r.slug ?? '';
|
|
46
|
+
const index = r.evaluations?.artificial_analysis_intelligence_index ?? null;
|
|
47
|
+
let variant = null;
|
|
48
|
+
const m = name.match(VARIANT);
|
|
49
|
+
if (m) variant = m[2].split(',').map((p) => p.trim().toLowerCase()).find((p) => VARIANT_WORDS.has(p)) ?? null;
|
|
50
|
+
const family = variant && slug.endsWith(`-${variant}`) ? slug.slice(0, -variant.length - 1) : slug;
|
|
51
|
+
(out[family] ??= {})[variant ?? 'default'] = index;
|
|
52
|
+
}
|
|
53
|
+
return out;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
export function aaKey(env = process.env) {
|
|
57
|
+
if (env.AA_API_KEY) return env.AA_API_KEY;
|
|
58
|
+
const file = join(env.HOME || homedir(), '.local/share/delegation-kit/config/artificial-analysis.env');
|
|
59
|
+
if (!existsSync(file)) return null;
|
|
60
|
+
for (const line of readFileSync(file, 'utf8').split('\n')) {
|
|
61
|
+
if (line.startsWith('AA_API_KEY=')) return line.slice(11).trim().replace(/^['"]|['"]$/g, '');
|
|
62
|
+
}
|
|
63
|
+
return null;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/** Fetch AA and write a refreshed catalog to the user config dir. Returns a change list. */
|
|
67
|
+
export async function refreshFromAA(catalog, { env = process.env, fetchImpl = fetch } = {}) {
|
|
68
|
+
const key = aaKey(env);
|
|
69
|
+
if (!key) {
|
|
70
|
+
throw new HarmaError('Nessuna chiave Artificial Analysis', { hint: 'Imposta AA_API_KEY (gratuita su artificialanalysis.ai). Senza chiave harma usa lo snapshot incluso.' });
|
|
71
|
+
}
|
|
72
|
+
let res;
|
|
73
|
+
try {
|
|
74
|
+
res = await fetchImpl(catalog.aa_api_url, { headers: { 'x-api-key': key, Accept: 'application/json', 'User-Agent': 'harma' } });
|
|
75
|
+
} catch (e) {
|
|
76
|
+
throw new HarmaError(`Artificial Analysis non raggiungibile: ${e.name}`);
|
|
77
|
+
}
|
|
78
|
+
if (!res.ok) throw new HarmaError(`Artificial Analysis ha risposto HTTP ${res.status}`);
|
|
79
|
+
const body = await res.json();
|
|
80
|
+
const rows = Array.isArray(body) ? body : body?.data;
|
|
81
|
+
if (!Array.isArray(rows)) throw new HarmaError('Risposta Artificial Analysis inattesa');
|
|
82
|
+
const fams = aaFamilies(rows);
|
|
83
|
+
const today = new Date().toISOString().slice(0, 10);
|
|
84
|
+
const next = structuredClone(catalog);
|
|
85
|
+
delete next.origin;
|
|
86
|
+
const changes = [];
|
|
87
|
+
for (const [id, m] of Object.entries(next.models)) {
|
|
88
|
+
const fam = m.aa?.slug ? fams[m.aa.slug] : null;
|
|
89
|
+
if (!fam) { changes.push({ model: id, change: m.aa?.slug ? 'non trovato su AA' : 'senza slug AA' }); continue; }
|
|
90
|
+
const index = Object.fromEntries(Object.entries(fam).filter(([, v]) => v !== null && v !== undefined));
|
|
91
|
+
if (JSON.stringify(index) !== JSON.stringify(m.aa.index)) changes.push({ model: id, change: 'indice aggiornato', old: m.aa.index, new: index });
|
|
92
|
+
m.aa.index = Object.keys(index).length ? index : null;
|
|
93
|
+
m.aa.date = today;
|
|
94
|
+
m.aa.source = 'aa-api';
|
|
95
|
+
}
|
|
96
|
+
next.generated_at = today;
|
|
97
|
+
next.source = 'Artificial Analysis API (refresh harma) su catalogo ' + (catalog.registry_updated ?? '');
|
|
98
|
+
const dest = userCatalogPath(env);
|
|
99
|
+
mkdirSync(dirname(dest), { recursive: true });
|
|
100
|
+
writeFileSync(dest, JSON.stringify(next, null, 2) + '\n');
|
|
101
|
+
return { dest, changes };
|
|
102
|
+
}
|
package/src/route.mjs
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
// Which model for which job. A score per (harness, model, effort):
|
|
2
|
+
// score = index − cost_weight × cost_per_task + credit adjustment
|
|
3
|
+
// filtered by min_index, by installed CLIs and by credit state. The profiles
|
|
4
|
+
// below are defaults; .harma/config.json "routing" overrides them per task type.
|
|
5
|
+
|
|
6
|
+
export const TASK_PROFILES = {
|
|
7
|
+
pianificazione: { min_index: 45, cost_weight: 0.5, label: 'pianificazione: massima intelligenza, il costo conta poco' },
|
|
8
|
+
sviluppo: { min_index: 40, cost_weight: 1.5, label: 'sviluppo: intelligenza alta a costo ragionevole' },
|
|
9
|
+
review: { min_index: 42, cost_weight: 1, different_vendor: true, label: 'review: vendor diverso da chi ha scritto il codice' },
|
|
10
|
+
debugging: { min_index: 45, cost_weight: 0.75, label: 'debugging: intelligenza alta, il costo conta poco' },
|
|
11
|
+
ricerca: { min_index: 35, cost_weight: 1.5, label: 'ricerca: buona intelligenza, costo contenuto' },
|
|
12
|
+
estrazione: { min_index: 30, mode: 'cheapest', label: 'estrazione: il più economico con indice ≥ soglia' },
|
|
13
|
+
};
|
|
14
|
+
|
|
15
|
+
export const TASK_ALIASES = {
|
|
16
|
+
planning: 'pianificazione', plan: 'pianificazione',
|
|
17
|
+
development: 'sviluppo', dev: 'sviluppo', build: 'sviluppo', implementazione: 'sviluppo',
|
|
18
|
+
revisione: 'review', 'code-review': 'review',
|
|
19
|
+
debug: 'debugging', 'problem-solving': 'debugging', problemi: 'debugging',
|
|
20
|
+
research: 'ricerca',
|
|
21
|
+
extraction: 'estrazione', clerk: 'estrazione',
|
|
22
|
+
};
|
|
23
|
+
|
|
24
|
+
export function taskProfile(type, config = {}) {
|
|
25
|
+
const key = TASK_PROFILES[type] ? type : TASK_ALIASES[type];
|
|
26
|
+
if (!key) return null;
|
|
27
|
+
return { type: key, ...TASK_PROFILES[key], ...(config.routing?.[key] ?? {}) };
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
const CREDIT_ADJUST = { ampio: 2, ok: 0, scarso: -8, sconosciuto: -1 };
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* rankRows: from rank.mjs. credits: rows from credits.mjs (by harness).
|
|
34
|
+
* author: {harness, model, provider} of the code under review, for review.
|
|
35
|
+
*/
|
|
36
|
+
export function route(type, { rankRows, credits = [], config = {}, author = null, top = 5 }) {
|
|
37
|
+
const p = taskProfile(type, config);
|
|
38
|
+
if (!p) return null;
|
|
39
|
+
const creditBy = new Map(credits.map((c) => [c.harness, c]));
|
|
40
|
+
// Unknown cost is never treated as cheap: assume the highest known cost.
|
|
41
|
+
const knownCosts = rankRows.map((r) => r.cost_per_task).filter((x) => x !== null);
|
|
42
|
+
const worstCost = knownCosts.length ? Math.max(...knownCosts) : 0;
|
|
43
|
+
const out = [];
|
|
44
|
+
const skipped = [];
|
|
45
|
+
for (const r of rankRows) {
|
|
46
|
+
const c = creditBy.get(r.harness);
|
|
47
|
+
const status = c?.status ?? 'sconosciuto';
|
|
48
|
+
const why = [];
|
|
49
|
+
if (r.index === null) { skipped.push({ ...r, reason: 'indice AA sconosciuto' }); continue; }
|
|
50
|
+
if (r.index < p.min_index) { skipped.push({ ...r, reason: `indice ${r.index} < ${p.min_index}` }); continue; }
|
|
51
|
+
if (status === 'esaurito') { skipped.push({ ...r, reason: `crediti ${r.harness} esauriti` }); continue; }
|
|
52
|
+
if (p.different_vendor && author && r.provider && r.provider === author.provider) {
|
|
53
|
+
skipped.push({ ...r, reason: `stesso vendor dell'autore (${author.provider})` });
|
|
54
|
+
continue;
|
|
55
|
+
}
|
|
56
|
+
const cost = r.cost_per_task ?? worstCost;
|
|
57
|
+
const adj = CREDIT_ADJUST[status] ?? 0;
|
|
58
|
+
// cheapest: order by cost; the credit adjustment only breaks ties.
|
|
59
|
+
const score = p.mode === 'cheapest'
|
|
60
|
+
? Math.round((-cost + adj / 1000) * 1000) / 1000
|
|
61
|
+
: Math.round((r.index - p.cost_weight * cost + adj) * 10) / 10;
|
|
62
|
+
why.push(`indice ${r.index}`);
|
|
63
|
+
why.push(r.cost_per_task === null ? `costo/task sconosciuto (assunto il più alto: $${worstCost})` : `costo/task $${r.cost_per_task}`);
|
|
64
|
+
why.push(`crediti ${status}${c?.remaining_pct !== null && c?.remaining_pct !== undefined ? ` (${c.remaining_pct}% residuo)` : ''}`);
|
|
65
|
+
out.push({ ...r, score, credit: status, why: why.join(' · ') });
|
|
66
|
+
}
|
|
67
|
+
out.sort((a, b) => b.score - a.score || b.index - a.index);
|
|
68
|
+
return { profile: p, candidates: out.slice(0, top), skipped };
|
|
69
|
+
}
|
package/src/state.mjs
ADDED
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
// Project state lives in <project>/.harma/:
|
|
2
|
+
// config.json orchestrator, dispatch policy, budgets, thresholds, backend
|
|
3
|
+
// agents.jsonl append-only lifecycle events (started, session, closed, ...)
|
|
4
|
+
// cache/*.json inventory, credits, rank — each with fetchedAt and source
|
|
5
|
+
import { mkdirSync, writeFileSync, appendFileSync, existsSync, readFileSync } from 'node:fs';
|
|
6
|
+
import { join, dirname, resolve } from 'node:path';
|
|
7
|
+
import { readJson, readJsonl, now, HarmaError } from './util.mjs';
|
|
8
|
+
|
|
9
|
+
export const STATE_DIR = '.harma';
|
|
10
|
+
|
|
11
|
+
export const DEFAULT_CONFIG = {
|
|
12
|
+
schema_version: 1,
|
|
13
|
+
orchestrator: null, // {harness, model, effort}
|
|
14
|
+
backend: 'auto', // auto | herdr | hc
|
|
15
|
+
dispatch_policy: 'confirm', // confirm | auto-within-budget
|
|
16
|
+
budgets: {}, // provider -> {limit, currency, period}
|
|
17
|
+
thresholds: {
|
|
18
|
+
low_remaining_pct: 20, // under this, delegate less to the provider
|
|
19
|
+
exhausted_remaining_pct: 5, // under this, do not route to it
|
|
20
|
+
high_remaining_pct: 60, // over this, the provider can take more work
|
|
21
|
+
},
|
|
22
|
+
routing: {}, // task type -> overrides, see route.mjs
|
|
23
|
+
};
|
|
24
|
+
|
|
25
|
+
/** Find the project root: the nearest ancestor holding .harma, else cwd. */
|
|
26
|
+
export function projectRoot(start = process.cwd()) {
|
|
27
|
+
let dir = resolve(start);
|
|
28
|
+
for (;;) {
|
|
29
|
+
if (existsSync(join(dir, STATE_DIR, 'config.json'))) return dir;
|
|
30
|
+
const up = dirname(dir);
|
|
31
|
+
if (up === dir) return resolve(start);
|
|
32
|
+
dir = up;
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
export function statePath(root, ...parts) {
|
|
37
|
+
return join(root, STATE_DIR, ...parts);
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
export function loadConfig(root, { required = false } = {}) {
|
|
41
|
+
const cfg = readJson(statePath(root, 'config.json'));
|
|
42
|
+
if (!cfg && required) {
|
|
43
|
+
throw new HarmaError('Nessun progetto harma qui.', { hint: 'Esegui prima: harma init --orchestrator <harness>:<model> --effort <level>' });
|
|
44
|
+
}
|
|
45
|
+
return mergeDeep(structuredClone(DEFAULT_CONFIG), cfg ?? {});
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
export function saveConfig(root, cfg) {
|
|
49
|
+
mkdirSync(statePath(root), { recursive: true });
|
|
50
|
+
writeFileSync(statePath(root, 'config.json'), JSON.stringify(cfg, null, 2) + '\n');
|
|
51
|
+
ensureGitignore(root);
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
function ensureGitignore(root) {
|
|
55
|
+
const p = statePath(root, '.gitignore');
|
|
56
|
+
if (!existsSync(p)) writeFileSync(p, 'cache/\n');
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
export function appendEvent(root, event) {
|
|
60
|
+
mkdirSync(statePath(root), { recursive: true });
|
|
61
|
+
const rec = { at: now(), ...event };
|
|
62
|
+
appendFileSync(statePath(root, 'agents.jsonl'), JSON.stringify(rec) + '\n');
|
|
63
|
+
return rec;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
export function readEvents(root) {
|
|
67
|
+
return readJsonl(statePath(root, 'agents.jsonl'));
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** Fold the event log into one record per agent name. */
|
|
71
|
+
export function agentsFromEvents(events) {
|
|
72
|
+
const agents = new Map();
|
|
73
|
+
for (const e of events) {
|
|
74
|
+
if (!e.agent) continue;
|
|
75
|
+
const cur = agents.get(e.agent) ?? { name: e.agent, history: [] };
|
|
76
|
+
cur.history.push(e.type);
|
|
77
|
+
switch (e.type) {
|
|
78
|
+
case 'started':
|
|
79
|
+
Object.assign(cur, {
|
|
80
|
+
harness: e.harness, model: e.model, effort: e.effort, task_type: e.task_type,
|
|
81
|
+
backend: e.backend, target: e.target, cwd: e.cwd, started_at: e.at,
|
|
82
|
+
session_id: e.session_id ?? cur.session_id ?? null, closed_at: null, state: 'open',
|
|
83
|
+
});
|
|
84
|
+
break;
|
|
85
|
+
case 'session':
|
|
86
|
+
cur.session_id = e.session_id;
|
|
87
|
+
cur.session_source = e.source;
|
|
88
|
+
break;
|
|
89
|
+
case 'closed':
|
|
90
|
+
cur.closed_at = e.at;
|
|
91
|
+
cur.state = 'closed';
|
|
92
|
+
cur.result = e.result ?? cur.result;
|
|
93
|
+
break;
|
|
94
|
+
case 'resumed':
|
|
95
|
+
cur.state = 'open';
|
|
96
|
+
cur.closed_at = null;
|
|
97
|
+
cur.target = e.target ?? cur.target;
|
|
98
|
+
cur.backend = e.backend ?? cur.backend;
|
|
99
|
+
break;
|
|
100
|
+
default:
|
|
101
|
+
break;
|
|
102
|
+
}
|
|
103
|
+
agents.set(e.agent, cur);
|
|
104
|
+
}
|
|
105
|
+
return [...agents.values()];
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
export function writeCache(root, name, data) {
|
|
109
|
+
mkdirSync(statePath(root, 'cache'), { recursive: true });
|
|
110
|
+
writeFileSync(statePath(root, 'cache', `${name}.json`), JSON.stringify(data, null, 2) + '\n');
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
export function readCache(root, name) {
|
|
114
|
+
return readJson(statePath(root, 'cache', `${name}.json`));
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
export function hasProject(root) {
|
|
118
|
+
return existsSync(statePath(root, 'config.json'));
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
function mergeDeep(base, extra) {
|
|
122
|
+
for (const [k, v] of Object.entries(extra)) {
|
|
123
|
+
if (v && typeof v === 'object' && !Array.isArray(v) && base[k] && typeof base[k] === 'object') {
|
|
124
|
+
base[k] = mergeDeep(base[k], v);
|
|
125
|
+
} else {
|
|
126
|
+
base[k] = v;
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
return base;
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
export function readText(path) {
|
|
133
|
+
try { return readFileSync(path, 'utf8'); } catch { return null; }
|
|
134
|
+
}
|