trodo-cli 0.0.0-stage → 0.3.0

package/lib/commands/evals.js

@@ -0,0 +1,138 @@
+'use strict';
+
+const config = require('../config');
+const { client } = require('../http');
+const { print } = require('../output');
+const { usage, pick, int, unitVerdicts } = require('../common');
+
+/** trodo evals list: the names --eval takes, and each eval's steps (STEP.FIELD). */
+async function listEvals(_args, flags) {
+  const { evals } = await client(config.resolve(flags)).get('/evals');
+  const rows = (evals || []).map((e) => ({
+    ...e,
+    step_fields: (e.steps || []).flatMap((s) => (s.fields || []).map((f) => `${s.name}.${f.name} (${f.type === 'enum' ? (f.values || []).join('|') : f.type})`)).join('; '),
+  }));
+  print(flags.table ? rows : evals, flags, [['name', 'Eval', 44], ['target', 'Target', 12], ['enabled', 'On', 5], ['step_fields', 'Steps (STEP.FIELD)', 70]]);
+}
+
+async function resolveEval(api, ref) {
+  const { evals } = await api.get('/evals');
+  return pick(evals || [], ref, { kind: 'eval', listCmd: 'trodo evals list' });
+}
+
+/** trodo evals get EVAL: the eval, its production version's graph and its 30-day stats. */
+async function getEval([ref], flags) {
+  const api = client(config.resolve(flags));
+  const e = await resolveEval(api, ref);
+  const [lineage, stats] = await Promise.all([
+    api.get(`/eval3/definitions/${e.id}`),
+    api.get(`/eval3/definitions/${e.id}/stats`).catch(() => null),
+  ]);
+  print({ ...lineage, steps: e.steps, stats: stats || undefined }, flags);
+}
+
+/** "7d" / "48h" / "30" → whole days for the verdict list (1-365). */
+function daysOf(since) {
+  if (since == null || since === true) return undefined;
+  const m = /^(\d+)\s*([hd]?)$/.exec(String(since).trim());
+  if (!m) throw usage('--since takes days or hours here: 7d, 48h, 30.');
+  const n = Number(m[1]);
+  return Math.min(365, Math.max(1, m[2] === 'h' ? Math.ceil(n / 24) : n));
+}
+
+/**
+ * trodo evals verdicts EVAL [--failed | --passed] [--since 7d] [--version N] [--limit 50] [--offset N]
+ * trodo evals verdicts --run RUN_ID | --span SPAN_ID | --conversation ID
+ * The eval's verdicts, newest first; or every eval's newest verdict on one unit.
+ */
+async function verdicts([ref], flags) {
+  const api = client(config.resolve(flags));
+  const unit = ['run', 'span', 'conversation'].find((k) => flags[k] && flags[k] !== true);
+  const cols = [['id', 'Verdict', 36], ['lineage_name', 'Eval', 34], ['passed', 'Passed', 6], ['score', 'Score', 6], ['reason_code', 'Reason', 22], ['created_at', 'At', 24]];
+  if (unit) {
+    const out = await api.get(`/eval3/units/${unit}/${encodeURIComponent(String(flags[unit]))}/verdicts`);
+    print(unitVerdicts(out), flags, cols);
+    return;
+  }
+  if (flags.failed && flags.passed) throw usage('Give --failed or --passed, not both.');
+  const e = await resolveEval(api, ref);
+  const q = {
+    limit: int(flags.limit, 50, 200),
+    offset: flags.offset,
+    days: daysOf(flags.since),
+    version: flags.version,
+    ...(flags.failed ? { passed: 'false' } : flags.passed ? { passed: 'true' } : {}),
+  };
+  const out = await api.get(`/eval3/definitions/${e.id}/runs`, q);
+  const rows = (out.runs || out.verdicts || []).map((r) => ({ lineage_name: e.name, ...r }));
+  print(flags.table ? rows : { eval: e.name, ...out }, flags, cols);
+}
+
+/** trodo evals verdict VERDICT_ID: one verdict, every step it took and why. */
+async function verdict([id], flags) {
+  if (!id) throw usage('Usage: trodo evals verdict VERDICT_ID');
+  print(await client(config.resolve(flags)).get(`/eval3/runs/${encodeURIComponent(id)}`), flags);
+}
+
+/**
+ * trodo evals mark VERDICT_ID --right
+ * trodo evals mark VERDICT_ID --wrong --should pass|fail --reason TEXT
+ * A person's thumbs on a verdict. A thumbs-down says what it should have been and
+ * why; it becomes that verdict row's Expected and feeds the eval's improvement.
+ */
+async function mark([id], flags) {
+  if (!id) throw usage('Usage: trodo evals mark VERDICT_ID --right | --wrong --should pass|fail --reason TEXT');
+  if (Boolean(flags.right) === Boolean(flags.wrong)) throw usage('Give --right or --wrong.');
+  const body = { source: 'v3', eval_run_id: String(id), thumbs: flags.right ? 'up' : 'down' };
+  if (flags.wrong) {
+    const should = String(flags.should || '');
+    if (!['pass', 'fail'].includes(should)) throw usage('--wrong needs --should pass or --should fail.');
+    if (!flags.reason || flags.reason === true) throw usage('--wrong needs --reason "why".');
+    body.corrected_passed = should === 'pass';
+    body.reason_text = String(flags.reason);
+  } else if (flags.reason && flags.reason !== true) body.reason_text = String(flags.reason);
+  print(await client(config.resolve(flags)).post('/eval3/feedback', body), flags);
+}
+
+/**
+ * trodo evals queue [--eval EVAL] [--graded] [--limit 50]
+ * Verdicts waiting on a person: an eval's human step stops there until someone
+ * picks one of its choices.
+ */
+async function queue(_a, flags) {
+  const api = client(config.resolve(flags));
+  const lineageId = flags.eval && flags.eval !== true ? (await resolveEval(api, flags.eval)).id : undefined;
+  const out = await api.get('/eval3/queue', { status: flags.graded ? 'graded' : 'open', lineage_id: lineageId, limit: int(flags.limit, 50, 200), offset: flags.offset });
+  print(out.items || out, flags, [['id', 'Item', 36], ['lineage_name', 'Eval', 34], ['node_id', 'Step', 22], ['status', 'Status', 8], ['created_at', 'Waiting since', 24]]);
+}
+
+/** trodo evals review ITEM_ID: one waiting item with the path the eval took to it. */
+async function review([id], flags) {
+  if (!id) throw usage('Usage: trodo evals review ITEM_ID');
+  print(await client(config.resolve(flags)).get(`/eval3/queue/${encodeURIComponent(id)}`), flags);
+}
+
+/** trodo evals grade ITEM_ID CHOICE: answer the human step; the eval carries on from there. */
+async function grade([id, choice], flags) {
+  if (!id || !choice) throw usage('Usage: trodo evals grade ITEM_ID CHOICE  (`trodo evals review ITEM_ID` lists the choices)');
+  print(await client(config.resolve(flags)).post(`/eval3/queue/${encodeURIComponent(id)}/grade`, { choice: String(choice) }), flags);
+}
+
+/**
+ * trodo evals steps EVAL [--since 30d] [--version N]
+ * The paths verdicts took through the eval's steps (its nodes), each with how
+ * many runs took it and how they came out: which step decides most failures.
+ */
+async function steps([ref], flags) {
+  const api = client(config.resolve(flags));
+  const e = await resolveEval(api, ref);
+  const out = await api.get(`/eval3/definitions/${e.id}/steps`, { days: daysOf(flags.since) || 30, version: flags.version });
+  if (flags.table) {
+    const rows = (out.paths || []).map((p) => ({ path: (p.names || p.path || []).join(' → '), runs: p.runs, share: p.share, passed: p.passed, failed: p.failed, errored: p.errored }));
+    print(rows, flags, [['path', 'Path through the steps', 90], ['runs', 'Runs', 6], ['share', 'Share', 6], ['passed', 'Passed', 6], ['failed', 'Failed', 6], ['errored', 'Errored', 7]]);
+    return;
+  }
+  print({ eval: e.name, steps: e.steps, ...out }, flags);
+}
+
+module.exports = { list: listEvals, get: getEval, verdicts, verdict, mark, queue, review, grade, steps, daysOf };

package/lib/commands/issues.js

@@ -0,0 +1,40 @@
+'use strict';
+
+const config = require('../config');
+const { client } = require('../http');
+const { print } = require('../output');
+const { usage, int } = require('../common');
+
+const csv = (v) => (v === undefined || v === true ? undefined : [].concat(v).join(','));
+
+/** trodo issues list [--status open,regression,closed] [--agent NAME] [--search TEXT] [--limit 50] */
+async function list(_a, flags) {
+  const out = await client(config.resolve(flags)).get('/issues', {
+    status: csv(flags.status), agent: csv(flags.agent), search: flags.search !== true ? flags.search : undefined,
+    limit: int(flags.limit, 50, 200), offset: flags.offset,
+  });
+  print(out.issues || out, flags, [['id', 'Id', 6], ['status', 'Status', 10], ['agent_name', 'Agent', 28], ['title', 'Issue', 60], ['evidence_count', 'Evidence', 8], ['last_seen_at', 'Last seen', 24]]);
+}
+
+/** trodo issues get ID: the issue, its evidence (runs, spans, conversations) and its timeline. */
+async function get([id], flags) {
+  if (!id) throw usage('Usage: trodo issues get ISSUE_ID');
+  print(await client(config.resolve(flags)).get(`/issues/${encodeURIComponent(id)}`), flags);
+}
+
+/** trodo issues failures ID: the recorded inputs of every failure, to replay against a fix. */
+async function failures([id], flags) {
+  if (!id) throw usage('Usage: trodo issues failures ISSUE_ID');
+  print(await client(config.resolve(flags)).get(`/issues/${encodeURIComponent(id)}/failures`, { limit: flags.limit, cursor: flags.cursor !== true ? flags.cursor : undefined }), flags);
+}
+
+async function setStatus(id, status, flags) {
+  if (!id) throw usage(`Usage: trodo issues ${status === 'closed' ? 'close' : 'reopen'} ISSUE_ID`);
+  print(await client(config.resolve(flags)).post(`/issues/${encodeURIComponent(id)}/status`, { status }), flags);
+}
+
+/** trodo issues close ID: closed; a new failure of the same kind reopens it as a regression. */
+const close = ([id], flags) => setStatus(id, 'closed', flags);
+const reopen = ([id], flags) => setStatus(id, 'open', flags);
+
+module.exports = { list, get, failures, close, reopen };

package/lib/commands/prompts.js

@@ -0,0 +1,125 @@
+'use strict';
+
+const fs = require('fs');
+const config = require('../config');
+const { client } = require('../http');
+const { print } = require('../output');
+const { usage, pick } = require('../common');
+
+/** What a prompt version is, without who saved it: what `pull` writes and `push` reads. */
+const CONTENT_KEYS = ['messages', 'model', 'tools', 'response_format', 'variables'];
+
+/** A refusal to edit, said as what to do about it. */
+async function editing(prompt, fn) {
+  try { return await fn(); } catch (e) {
+    if (e && e.status === 403 && e.body && e.body.error === 'forbidden_edit') {
+      throw Object.assign(new Error(`You can't change "${prompt}": only its owner and the editors they add can. Ask the owner to add you (prompt page → Editors).`), { exitCode: 1 });
+    }
+    throw e;
+  }
+}
+
+async function resolvePrompt(api, ref) {
+  const { prompts } = await api.get('/prompts');
+  const hit = pick(prompts || [], ref, { kind: 'prompt', listCmd: 'trodo prompts list' });
+  const { prompt } = await api.get(`/prompts/${hit.id}`);
+  return prompt;
+}
+
+/** The version a --version N or --label L names; the newest one otherwise. */
+function versionOf(prompt, flags) {
+  const versions = prompt.versions || [];
+  if (flags.version !== undefined && flags.version !== true) {
+    const v = versions.find((x) => String(x.version_no) === String(flags.version));
+    if (!v) throw usage(`"${prompt.name}" has no version ${flags.version}. \`trodo prompts versions "${prompt.name}"\` lists them.`);
+    return v;
+  }
+  if (flags.label !== undefined && flags.label !== true) {
+    const v = versions.find((x) => (x.labels || []).includes(String(flags.label)));
+    if (!v) throw usage(`No version of "${prompt.name}" has the label "${flags.label}".`);
+    return v;
+  }
+  return versions.reduce((a, b) => (!a || Number(b.version_no) > Number(a.version_no) ? b : a), null);
+}
+
+async function list(_a, flags) {
+  const { prompts } = await client(config.resolve(flags)).get('/prompts', { label: flags.label !== true ? flags.label : undefined, tag: flags.tag !== true ? flags.tag : undefined });
+  print(prompts || [], flags, [['name', 'Prompt', 36], ['current_version', 'Version', 8], ['labels', 'Labels', 24], ['id', 'Id', 36], ['updated_at', 'Updated', 24]]);
+}
+
+/** trodo prompts get PROMPT [--version N | --label production]: one version, whole. */
+async function get([ref], flags) {
+  const prompt = await resolvePrompt(client(config.resolve(flags)), ref);
+  const v = versionOf(prompt, flags);
+  print({ id: prompt.id, name: prompt.name, description: prompt.description, tags: prompt.tags, version: v }, flags);
+}
+
+async function versions([ref], flags) {
+  const prompt = await resolvePrompt(client(config.resolve(flags)), ref);
+  const rows = (prompt.versions || []).map((v) => ({ version_no: v.version_no, labels: v.labels, commit_message: v.commit_message, created_by: v.created_by_email, created_at: v.created_at, content_hash: v.content_hash }));
+  print(rows, flags, [['version_no', 'v', 4], ['labels', 'Labels', 22], ['commit_message', 'Message', 44], ['created_by', 'By', 24], ['created_at', 'At', 24]]);
+}
+
+/** trodo prompts pull PROMPT [--version N | --label L] [-o prompt.json]: the content to edit and push back. */
+async function pull([ref], flags) {
+  const prompt = await resolvePrompt(client(config.resolve(flags)), ref);
+  const v = versionOf(prompt, flags);
+  const out = { name: prompt.name, version_no: v.version_no };
+  for (const k of CONTENT_KEYS) out[k] = v[k];
+  if (flags.out && flags.out !== true) {
+    fs.writeFileSync(String(flags.out), `${JSON.stringify(out, null, 2)}\n`);
+    process.stderr.write(`${prompt.name} v${v.version_no} → ${flags.out}\n`);
+    return;
+  }
+  print(out, flags);
+}
+
+/**
+ * trodo prompts push PROMPT -f prompt.json [--message "why"] [--label staging]
+ * A new version from a file `pull` wrote (or any { messages, model?, tools?,
+ * variables? }). The prompt is made when no prompt has that name. Content equal
+ * to the newest version cuts no version.
+ */
+async function push([ref], flags) {
+  const file = flags.file;
+  if (!file || file === true) throw usage('Usage: trodo prompts push PROMPT -f prompt.json [--message "why"] [--label staging]');
+  let content;
+  try { content = JSON.parse(fs.readFileSync(String(file), 'utf8')); } catch (e) { throw usage(`${file} is not a JSON prompt: ${e.message}`); }
+  if (!Array.isArray(content.messages) || !content.messages.length) throw usage(`${file} has no messages.`);
+  const api = client(config.resolve(flags));
+  const name = ref && ref !== true ? String(ref) : content.name;
+  if (!name) throw usage('Name the prompt.');
+  const { prompts } = await api.get('/prompts');
+  let target = (prompts || []).find((p) => p.id === name || p.name === name);
+  let created = false;
+  if (!target) {
+    const made = await api.post('/prompts', { name, ...(content.description ? { description: content.description } : {}) });
+    target = made.prompt || made;
+    created = true;
+  }
+  const body = { messages: content.messages };
+  for (const k of ['model', 'tools', 'response_format', 'variables']) if (content[k] !== undefined) body[k] = content[k];
+  if (flags.message && flags.message !== true) body.commit_message = String(flags.message);
+  if (flags.label && flags.label !== true) body.labels = [].concat(flags.label).map(String);
+  const out = await editing(name, () => api.post(`/prompts/${target.id}/versions`, body));
+  const v = out.version || {};
+  print({ prompt: name, id: target.id, created, version_no: v.version_no, labels: v.labels, unchanged: Boolean(out.unchanged) }, flags);
+}
+
+/**
+ * trodo prompts label PROMPT VERSION LABEL [--remove]
+ * Moves LABEL (say production) to VERSION. Agents that fetch the prompt by that
+ * label run the new version from their next call.
+ */
+async function label([ref, versionNo, name], flags) {
+  if (!ref || !versionNo || !name) throw usage('Usage: trodo prompts label PROMPT VERSION LABEL [--remove]');
+  const api = client(config.resolve(flags));
+  const prompt = await resolvePrompt(api, ref);
+  const v = versionOf(prompt, { version: versionNo });
+  const out = await editing(prompt.name, () => (flags.remove
+    ? api.del(`/prompts/${prompt.id}/versions/${v.version_no}/label/${encodeURIComponent(String(name))}`)
+    : api.post(`/prompts/${prompt.id}/versions/${v.version_no}/label`, { label: String(name) })));
+  print({ prompt: prompt.name, version_no: v.version_no, ...(out.version ? { labels: out.version.labels } : out) }, flags);
+}
+
+module.exports = { list, get, versions, pull, push, label };

package/lib/commands/runs.js

@@ -0,0 +1,118 @@
+'use strict';
+
+const config = require('../config');
+const { client } = require('../http');
+const { print } = require('../output');
+const { buildSpec } = require('./traces');
+const { usage, listQuery, pages, unitVerdicts, int } = require('../common');
+
+const DAY = 86400e3;
+/** A filter's time → { time_start, time_end } for the lists. */
+function windowOf(time, now = Date.now()) {
+  if (time.from || time.to) return { time_start: time.from || new Date(now - 7 * DAY).toISOString(), time_end: time.to || new Date(now).toISOString() };
+  const p = String(time.preset || '7d');
+  const start = new Date(now); start.setHours(0, 0, 0, 0);
+  if (p === 'today') return { time_start: start.toISOString(), time_end: new Date(now).toISOString() };
+  if (p === 'yesterday') return { time_start: new Date(start.getTime() - DAY).toISOString(), time_end: new Date(start.getTime() - 1).toISOString() };
+  const m = /^(\d+)([mhd])$/.exec(p);
+  const n = m ? Number(m[1]) : 7;
+  const unit = !m ? DAY : m[2] === 'h' ? 3600e3 : m[2] === 'd' ? DAY : (['3m', '6m', '12m'].includes(p) ? 30 * DAY : 60e3);
+  return { time_start: new Date(now - n * unit).toISOString(), time_end: new Date(now).toISOString() };
+}
+
+/** trodo runs list [filter flags] [--limit 50] [--offset N] */
+async function listRuns(_args, flags) {
+  const api = client(config.resolve(flags));
+  const spec = await buildSpec(api, flags, 'runs');
+  const q = listQuery(spec, windowOf);
+  const rows = await pages(flags, async (limit, offset) => { const out = await api.get('/runs', { ...q, limit, offset }); return out.runs || []; }, { max: 100 });
+  print(rows, flags, [['run_id', 'Run', 36], ['agent_name', 'Agent', 30], ['status', 'Status', 8], ['started_at', 'Started', 24], ['duration_ms', 'ms', 8]]);
+}
+
+/** The spans of a run as an indented tree, one line each: what a person reads first. */
+function spanTree(spans) {
+  const byId = new Map(spans.map((s) => [s.span_id, s]));
+  const kids = new Map();
+  const roots = [];
+  const order = (a, b) => String(a.started_at || '').localeCompare(String(b.started_at || ''));
+  for (const s of [...spans].sort(order)) {
+    if (s.parent_span_id && byId.has(s.parent_span_id)) {
+      if (!kids.has(s.parent_span_id)) kids.set(s.parent_span_id, []);
+      kids.get(s.parent_span_id).push(s);
+    } else roots.push(s);
+  }
+  const lines = [];
+  const label = (s) => {
+    const bits = [`${s.name || s.tool_name || s.kind}`, `[${s.kind || 'span'}]`];
+    if (s.model) bits.push(s.model);
+    if (s.duration_ms != null) bits.push(`${(Number(s.duration_ms) / 1000).toFixed(2)}s`);
+    const tok = (Number(s.input_tokens) || 0) + (Number(s.output_tokens) || 0);
+    if (tok) bits.push(`${tok} tok`);
+    if (s.status && s.status !== 'ok') bits.push(`✗ ${s.status}${s.error_message ? `: ${String(s.error_message).slice(0, 80)}` : ''}`);
+    bits.push(s.span_id);
+    return bits.join('  ');
+  };
+  const walk = (s, prefix, last, depth) => {
+    lines.push(`${depth ? `${prefix}${last ? '└─ ' : '├─ '}` : ''}${label(s)}`);
+    const c = kids.get(s.span_id) || [];
+    c.forEach((k, i) => walk(k, depth ? `${prefix}${last ? '   ' : '│  '}` : '', i === c.length - 1, depth + 1));
+  };
+  roots.forEach((r, i) => walk(r, '', i === roots.length - 1, 0));
+  return lines.join('\n');
+}
+
+/**
+ * trodo runs get RUN_ID [--tree]: the run, its spans, messages, feedback and
+ * evaluations. --tree prints the span tree instead of JSON.
+ */
+async function getRun([id], flags) {
+  if (!id) throw usage('Usage: trodo runs get RUN_ID [--tree]');
+  const api = client(config.resolve(flags));
+  const [detail, verdicts] = await Promise.all([
+    api.get(`/runs/${encodeURIComponent(id)}`, { include: 'spans,messages' }),
+    api.get(`/eval3/units/run/${encodeURIComponent(id)}/verdicts`).catch(() => null),
+  ]);
+  if (flags.tree) {
+    const r = detail.run || {};
+    const head = `${r.agent_name || 'run'}  ${r.status || ''}  ${r.started_at || ''}  ${r.duration_ms != null ? `${(r.duration_ms / 1000).toFixed(2)}s` : ''}  ${r.run_id || id}`;
+    process.stdout.write(`${head}\n${spanTree(detail.spans || [])}\n`);
+    return;
+  }
+  print({ ...detail, evaluations: unitVerdicts(verdicts) }, flags);
+}
+
+/** trodo runs tree RUN_ID: the span tree alone. */
+const tree = (args, flags) => getRun(args, { ...flags, tree: true });
+
+/**
+ * trodo runs feedback RUN_ID [--thumbs up|down] [--rating 1-5] [--comment TEXT] [--user DISTINCT_ID]
+ * A person's feedback on the run, as the SDK and the run page record it.
+ */
+async function feedback([id], flags) {
+  if (!id) throw usage('Usage: trodo runs feedback RUN_ID --thumbs up|down [--rating 1-5] [--comment TEXT]');
+  const body = {};
+  if (flags.thumbs !== undefined) {
+    const t = String(flags.thumbs);
+    if (!['up', 'down'].includes(t)) throw usage('--thumbs is up or down.');
+    body.satisfaction = t === 'up' ? 'positive' : 'negative';
+  }
+  if (flags.rating !== undefined) {
+    const n = Number(flags.rating);
+    if (!Number.isInteger(n) || n < 1 || n > 5) throw usage('--rating is a whole number from 1 to 5.');
+    body.rating = n;
+  }
+  if (flags.comment !== undefined && flags.comment !== true) body.comment = String(flags.comment);
+  if (flags.user !== undefined && flags.user !== true) body.distinct_id = String(flags.user);
+  if (!Object.keys(body).some((k) => ['satisfaction', 'rating', 'comment'].includes(k))) throw usage('Give --thumbs, --rating or --comment.');
+  print(await client(config.resolve(flags)).post(`/runs/${encodeURIComponent(id)}/feedback`, body), flags);
+}
+
+/** trodo runs search TEXT [--limit 50]: runs whose input, output or spans mention TEXT. */
+async function search(words, flags) {
+  const q = words.join(' ').trim();
+  if (!q) throw usage('Usage: trodo runs search TEXT [--limit 50]');
+  const out = await client(config.resolve(flags)).get('/runs/search', { q, limit: int(flags.limit, 50, 200) });
+  print(out.runs || out, flags, [['run_id', 'Run', 36], ['agent_name', 'Agent', 30], ['status', 'Status', 8], ['started_at', 'Started', 24], ['distinct_id', 'User', 26]]);
+}
+
+module.exports = { list: listRuns, get: getRun, tree, feedback, search, windowOf, spanTree };

package/lib/commands/setup.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { print } = require('../output');
+const { usage } = require('../common');
+
+const SKILLS_DIR = path.join(__dirname, '..', '..', 'skills');
+
+/**
+ * trodo setup claude [--global] | trodo setup --dir DIR
+ * Installs the skills this CLI ships (trodo: read and act on traces; trodo-datasets:
+ * training data) where a coding agent finds them: ./.claude/skills (this project),
+ * ~/.claude/skills with --global, or any folder with --dir.
+ */
+async function setup([agent], flags) {
+  let root;
+  if (flags.dir && flags.dir !== true) root = path.resolve(String(flags.dir));
+  else if (agent === 'claude') root = flags.global ? path.join(os.homedir(), '.claude', 'skills') : path.resolve('.claude', 'skills');
+  else throw usage('Usage: trodo setup claude [--global]   or   trodo setup --dir SKILLS_DIR');
+  const installed = [];
+  for (const name of fs.readdirSync(SKILLS_DIR)) {
+    const src = path.join(SKILLS_DIR, name, 'SKILL.md');
+    if (!fs.existsSync(src)) continue;
+    const dest = path.join(root, name);
+    fs.mkdirSync(dest, { recursive: true });
+    fs.copyFileSync(src, path.join(dest, 'SKILL.md'));
+    installed.push(path.join(dest, 'SKILL.md'));
+  }
+  print({ installed }, flags);
+}
+
+module.exports = { setup };

package/lib/commands/spans.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const config = require('../config');
+const { client } = require('../http');
+const { print } = require('../output');
+const { buildSpec } = require('./traces');
+const { windowOf } = require('./runs');
+const { usage, listQuery, pages, unitVerdicts, int } = require('../common');
+
+/** trodo spans list [filter flags] [--limit 50] [--offset N]: newest first. */
+async function list(_args, flags) {
+  const api = client(config.resolve(flags));
+  const spec = await buildSpec(api, flags, 'spans');
+  const q = listQuery(spec, windowOf);
+  const rows = await pages(flags, async (limit, offset) => { const out = await api.get('/spans', { ...q, limit, offset }); return out.spans || []; });
+  print(rows, flags, [['span_id', 'Span', 36], ['name', 'Name', 28], ['kind', 'Kind', 8], ['model', 'Model', 22], ['status', 'Status', 8], ['duration_ms', 'ms', 8], ['run_id', 'Run', 36]]);
+}
+
+/** trodo spans get SPAN_ID: the span with its full input and output, and its evaluations. */
+async function get([id], flags) {
+  if (!id) throw usage('Usage: trodo spans get SPAN_ID');
+  const api = client(config.resolve(flags));
+  const [detail, verdicts] = await Promise.all([
+    api.get(`/spans/${encodeURIComponent(id)}`),
+    api.get(`/eval3/units/span/${encodeURIComponent(id)}/verdicts`).catch(() => null),
+  ]);
+  print({ ...detail, evaluations: unitVerdicts(verdicts) }, flags);
+}
+
+/** trodo spans search TEXT [--limit 50]: spans whose name, input or output mention TEXT. */
+async function search(words, flags) {
+  const q = words.join(' ').trim();
+  if (!q) throw usage('Usage: trodo spans search TEXT [--limit 50]');
+  const out = await client(config.resolve(flags)).get('/spans/search', { q, limit: int(flags.limit, 50, 200) });
+  print(out.spans || out, flags, [['span_id', 'Span', 36], ['name', 'Name', 28], ['kind', 'Kind', 8], ['started_at', 'Started', 24], ['run_id', 'Run', 36]]);
+}
+
+module.exports = { list, get, search };

package/lib/commands/traces.js

@@ -0,0 +1,112 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const config = require('../config');
+const { client } = require('../http');
+const { print, sink } = require('../output');
+const { specFromFlags, needsEvals } = require('../filters');
+
+async function evalsIfNeeded(api, flags) {
+  return needsEvals(flags) ? (await api.get('/evals')).evals || [] : [];
+}
+
+async function buildSpec(api, flags, kind) {
+  return specFromFlags(flags, { kind, evals: await evalsIfNeeded(api, flags) });
+}
+
+/** trodo traces count [filter flags] */
+async function count(_args, flags) {
+  const api = client(config.resolve(flags));
+  const spec = await buildSpec(api, flags, flags.kind || 'runs');
+  const out = await api.post('/traces/count', spec);
+  print({ kind: spec.kind, matched: out.matched, capped: out.capped, window: out.window, sample: out.sample }, flags);
+}
+
+/**
+ * trodo traces export [filter flags] [--include-trace] [--format trodo|openai|dpo] [--target output|expected] [-o file]
+ * One JSON line per unit (the row a dataset would hold, with its evaluations),
+ * or one fine-tuning example per line. The summary goes to stderr.
+ */
+async function exportTraces(_args, flags) {
+  const api = client(config.resolve(flags));
+  const spec = await buildSpec(api, flags, flags.kind || 'runs');
+  const body = { ...spec };
+  if (flags.format) body.format = String(flags.format);
+  if (flags.target) body.target = String(flags.target);
+  const dir = flags.dir && flags.dir !== true ? String(flags.dir) : null;
+  if (dir && flags.out) throw Object.assign(new Error('Give -o FILE or --dir DIR, not both.'), { exitCode: 2 });
+  if (dir) fs.mkdirSync(dir, { recursive: true });
+  const out = dir ? null : sink(flags.out && flags.out !== true ? String(flags.out) : null);
+  let summary = null;
+  let n = 0;
+  for await (const line of api.lines('POST', '/traces/export', { body })) {
+    if (line && line._trodo) { summary = line._trodo; continue; }
+    n += 1;
+    if (dir) {
+      // One file per unit, named by what it is: run-<id>.json, span-<id>.json, conversation-<id>.json.
+      const src = line.source || {};
+      const kind = line.unit_kind || (spec.kind === 'eval_results' ? 'verdict' : spec.kind.replace(/s$/, ''));
+      const md = line.metadata || {};
+      const byKind = { span: src.span_id || md.span_id, conversation: src.conversation_id || md.conversation_id, verdict: md.eval_run_id || src.eval_run_id, run: src.run_id || md.run_id };
+      const id = byKind[kind] || src.span_id || src.run_id || src.conversation_id || String(n).padStart(5, '0');
+      fs.writeFileSync(path.join(dir, `${kind}-${String(id).replace(/[^\w.-]/g, '_')}.json`), `${JSON.stringify(line, null, 2)}\n`);
+      continue;
+    }
+    // eslint-disable-next-line no-await-in-loop
+    await out.write(line);
+  }
+  if (out) await out.close();
+  if (summary) process.stderr.write(`${summary.rows} ${spec.kind}${summary.skipped ? `, ${summary.skipped} skipped (no input or no target)` : ''}${flags.out ? ` → ${flags.out}` : dir ? ` → ${dir}/` : ''}\n`);
+}
+
+/**
+ * trodo traces stats [filter flags] [--compare]
+ * Count, error rate, latency p50/p95/p99, tokens, cost, feedback, eval
+ * outcomes and the busiest agents for what the filter matches. --compare puts
+ * the window just before it beside it (the last 7 days against the 7 before).
+ */
+async function stats(_args, flags) {
+  const api = client(config.resolve(flags));
+  const spec = await buildSpec(api, flags, flags.kind || 'runs');
+  const current = await api.post('/traces/stats', spec);
+  if (!flags.compare) { print(current, flags); return; }
+  const from = new Date(current.window.from).getTime();
+  const to = new Date(current.window.to).getTime();
+  const prevSpec = { ...spec, filter: { ...spec.filter, time: { from: new Date(from - (to - from)).toISOString(), to: new Date(from).toISOString() } } };
+  const previous = await api.post('/traces/stats', prevSpec);
+  const pct = (a, b) => (b ? Number((((a - b) / b) * 100).toFixed(1)) : null);
+  print({
+    current,
+    previous,
+    change_pct: {
+      units: pct(current.units, previous.units),
+      error_rate: current.error_rate != null && previous.error_rate != null ? Number(((current.error_rate - previous.error_rate) * 100).toFixed(2)) : null,
+      p50_ms: pct(current.latency_ms.p50, previous.latency_ms.p50),
+      p95_ms: pct(current.latency_ms.p95, previous.latency_ms.p95),
+      cost: pct(current.cost, previous.cost),
+    },
+  }, flags);
+}
+
+/** trodo traces agents: the agent names traces carry (what --agent takes), with run counts. */
+async function agents(_a, flags) {
+  const out = await client(config.resolve(flags)).get('/runs/agents');
+  print(out.agents || out, flags, [['agent_name', 'Agent', 40], ['run_count', 'Runs', 8], ['error_count', 'Errors', 8], ['total_cost', 'Cost', 12], ['last_seen_at', 'Last seen', 24]]);
+}
+
+/** trodo traces fields [--agent NAME]: the properties --where can name, run and span, fixed and custom. */
+async function fields(_a, flags) {
+  const agent = flags.agent && flags.agent !== true ? [].concat(flags.agent)[0] : undefined;
+  print(await client(config.resolve(flags)).get('/runs/property-keys', { agent_name: agent }), flags);
+}
+
+/** trodo traces values FIELD [--search TEXT] [--limit 50]: the values one property takes, most common first. */
+async function values([field], flags) {
+  if (!field) throw Object.assign(new Error('Usage: trodo traces values FIELD [--search TEXT]  (trodo traces fields lists them)'), { exitCode: 2 });
+  const agent = flags.agent && flags.agent !== true ? [].concat(flags.agent)[0] : undefined;
+  const out = await client(config.resolve(flags)).get('/runs/property-values', { field, q: flags.search !== true ? flags.search : undefined, agent_name: agent, limit: flags.limit });
+  print(out.values || out, flags, [['value', 'Value', 50], ['count', 'Count', 10]]);
+}
+
+module.exports = { count, export: exportTraces, stats, agents, fields, values, buildSpec };

package/lib/commands/users.js

@@ -0,0 +1,14 @@
+'use strict';
+
+const config = require('../config');
+const { client } = require('../http');
+const { print } = require('../output');
+const { usage } = require('../common');
+
+/** trodo users get DISTINCT_ID [--since 30d]: one user's runs, conversations, cost, evals and feedback, as the user drawer shows. */
+async function get([id], flags) {
+  if (!id) throw usage('Usage: trodo users get DISTINCT_ID');
+  print(await client(config.resolve(flags)).get(`/runs/users/${encodeURIComponent(id)}/profile`, { period: flags.since !== true ? flags.since : undefined }), flags);
+}
+
+module.exports = { get };