quoxcli 0.0.0-stage → 0.2.0

package/lib/quoxon/api.js

@@ -0,0 +1,473 @@
+/**
+ * QUOXON server calls. Thin wrapper over the CLI client so the app can be
+ * driven by a fake (demo + tests). All routes per docs/QUOXON_EVENTS_v1.md.
+ */
+import { resolveEndpoint } from '../api/endpoints.js';
+import { buildStreamQuery } from '../commands/chat.js';
+import { loadBundledAssistantsRoster } from '../core/agentAlias.js';
+import { recordHeldSlot } from '../commands/slot.js';
+import { askGripe, settleGripe } from '../commands/gripe.js';
+import { fromObjective, fromExecution, fromApproval, sortRows } from './roster.js';
+import { normChoice } from './model.js';
+import { createObjectsApi } from './objects/fetch.js';
+
+const missing = (e) => e?.status === 404 || e?.status === 405 || e?.status === 501;
+/** Server steer refusal label -> client reason. Unknown labels are 'ambiguous', never "finished". */
+const steerReason = (label) => label === 'turn_finished' ? 'turn_finished' : (label === 'steer_unsupported' || label === 'unsupported') ? 'unsupported' : 'ambiguous';
+const eventsPath = (c, t) => `/api/v1/conversations/${encodeURIComponent(c)}/turns/${encodeURIComponent(t)}/events`;
+/** Reconnect backoff (ms) for a dropped durable turn; ~1 min in all, then the user is told /resume reattaches. */
+export const REATTACH_BACKOFF_MS = [250, 500, 1000, 2000, 4000, 8000, 15000, 30000];
+
+/**
+ * Drain one SSE connection of a turn into the consumer, exactly once by seq. Returns null when the turn
+ * finished (or the caller aborted), else { error } describing why the connection ended early.
+ * turn.finished arrives just after `done`: keep reading to the close, but never hang (3 s grace).
+ */
+async function* readTurn(open, cur, signal) {
+  const inner = new AbortController();
+  const relay = () => inner.abort();
+  if (signal) { if (signal.aborted) inner.abort(); else signal.addEventListener('abort', relay, { once: true }); }
+  let grace = null;
+  try {
+    for await (const ev of open(inner.signal)) {
+      if (typeof ev?.seq === 'number') { if (ev.seq <= cur.lastSeq) continue; cur.lastSeq = ev.seq; }
+      if (ev?.type === 'turn.started' && ev.conversation_id) cur.conversationId = ev.conversation_id;
+      if (ev?.type === 'turn.finished') cur.finished = true;
+      yield ev;
+      if ((ev.type === 'done' || ev.type === 'error' || ev.type === 'turn.finished') && !grace) grace = setTimeout(() => inner.abort(), 3000);
+      if (ev.type === 'turn.finished') return null;
+    }
+    return signal?.aborted || grace ? null : { error: null }; // closed without turn.finished
+  } catch (e) {
+    if (signal?.aborted) return null;
+    if (grace && inner.signal.aborted) return null; // grace timeout, not a failure
+    if (e?.status) throw e; // the server answered with an HTTP error: not a dropped connection
+    return { error: e };
+  } finally { clearTimeout(grace); signal?.removeEventListener('abort', relay); inner.abort(); } // cancels the HTTP body
+}
+const sleepFor = (ms, signal) => new Promise((r) => { if (signal?.aborted) return r(); const t = setTimeout(done, ms); function done() { clearTimeout(t); signal?.removeEventListener?.('abort', done); r(); } signal?.addEventListener?.('abort', done, { once: true }); });
+const listOf = (d, ...keys) => { for (const k of keys) if (Array.isArray(d?.[k])) return d[k]; return Array.isArray(d) ? d : null; };
+
+export function createApi({ client, config, auth, reattachBackoff = REATTACH_BACKOFF_MS }) {
+  const orgId = () => { try { return auth.getOrgId(); } catch { return null; } };
+  const userId = () => { try { return config.getAuth?.()?.user_id || null; } catch { return null; } };
+  const listApprovals = async () => {
+    const ep = resolveEndpoint('inbox.list', { orgId: orgId() });
+    const data = await client.get(ep.path, { service: ep.service, query: { status: 'open', kind: 'approval', limit: 20 } });
+    const items = data.items || data.data || data || [];
+    return Array.isArray(items) ? items : [];
+  };
+  const conv = (c, t) => `/api/v1/conversations/${encodeURIComponent(c)}/turns/${encodeURIComponent(t)}`;
+  /**
+   * After a drop: reconnect with backoff, replaying from the last seq we yielded. A 404/410 ends it with
+   * that error; running out of attempts throws err.code 'reattach_failed' (the turn may still be running).
+   */
+  async function* reattachLoop({ turnId, cur, signal, first, backoff = REATTACH_BACKOFF_MS }) {
+    let last = first;
+    for (let attempt = 1; attempt <= backoff.length; attempt++) {
+      if (signal?.aborted) return;
+      yield { type: 'reconnecting', turn_id: turnId, attempt, after: cur.lastSeq };
+      await sleepFor(backoff[attempt - 1], signal);
+      if (signal?.aborted) return;
+      let announced = false;
+      const before = cur.lastSeq;
+      let drop;
+      try {
+        drop = yield* readTurn((sig) => (async function* () {
+          for await (const ev of client.stream(eventsPath(cur.conversationId, turnId), { service: 'collector', query: { after: cur.lastSeq }, signal: sig, untilClose: true })) {
+            if (!announced) { announced = true; yield { type: 'resumed', turn_id: turnId, after: before }; }
+            yield ev;
+          }
+        })(), cur, signal);
+      } catch (e) {
+        if (e?.status === 404) { const err = new Error('The server no longer knows this turn (it may have been restarted).'); err.code = 'turn_not_found'; err.status = 404; throw err; }
+        if (e?.status === 410) { const err = new Error('This turn finished too long ago to replay; its answer is in the conversation history (/resume).'); err.code = 'turn_events_expired'; err.status = 410; throw err; }
+        if (e?.status === 401 || e?.status === 403) throw e;
+        drop = { error: e };
+      }
+      if (cur.finished || !drop || signal?.aborted) return;
+      last = drop.error || last;
+      if (cur.lastSeq > before) attempt = 0; // progress: start the backoff again
+    }
+    const err = new Error(`Lost the connection to the server${last?.message ? ` (${last.message})` : ''}. Quox keeps working on the turn; /resume reattaches.`);
+    err.code = 'reattach_failed';
+    throw err;
+  }
+  return {
+    orgId,
+    userId,
+    /** Inline object views (objects/): skill, workflow, crystal, agent, memory, rules, proof, reconcile. */
+    objects: createObjectsApi({ client, orgId }),
+    /** /model choice persisted on the active profile ({ provider, model? } only, never a key); null = auto. */
+    modelChoice() { try { return normChoice(config.getActiveProfile?.()?.chat_model); } catch { return null; } },
+    setModelChoice(choice) {
+      const prof = config.getActiveProfile?.();
+      if (!prof) return false;
+      const c = normChoice(choice);
+      if (c) prof.chat_model = c; else delete prof.chat_model;
+      config.save?.();
+      return true;
+    },
+    /** Server-side QuoxSound setting (the dashboard's `soundProfile` preference), or null when unset. */
+    async soundSettings() {
+      const ep = resolveEndpoint('auth.me.list');
+      const d = await client.get(ep.path, { service: ep.service, retries: 0 });
+      return (d?.user?.preferences ?? d?.preferences)?.soundProfile ?? null;
+    },
+    async setSoundSettings(value) {
+      const ep = resolveEndpoint('auth.me.update');
+      await client.patch(ep.path, { service: ep.service, body: { preferences: { soundProfile: value } } });
+      return true;
+    },
+    /** Local copy on the active CLI profile: offline start + fallback store. */
+    localSoundProfile() { try { return config.getActiveProfile?.()?.sound_profile || null; } catch { return null; } },
+    setLocalSoundProfile(p) { const prof = config.getActiveProfile?.(); if (!prof) return false; prof.sound_profile = p; config.save?.(); return true; },
+    /**
+     * One turn. Durable by default (events v1.1, docs/QUOXON_EVENTS_v1_1.md): the server keeps the turn running
+     * if this connection drops, every event carries a `seq`, and a drop before turn.finished is followed by an
+     * automatic reattach (GET .../turns/:tid/events?after=<last seq>) with backoff. Events are yielded exactly once
+     * by seq. While reconnecting it yields { type:'reconnecting', attempt } and, once back, { type:'resumed', after }.
+     * A server without v1.1 (no seq on its events) gets the v1 behaviour: no reattach.
+     */
+    async *stream({ turnId, message, agent, conversationId, context, provider, model, promptProfile, durable = true }, signal) {
+      const body = buildStreamQuery({ queryId: turnId, message, agent: agent || 'quox', sessionId: conversationId, context });
+      body.turn_id = turnId;
+      if (durable) body.durable = true; // the server keeps the turn running when we disconnect (v1.1)
+      if (provider) body.provider = provider; // a request: the server policy decides, turn.started says what ran
+      if (provider && model) body.model = model;
+      if (promptProfile === 'compact' || promptProfile === 'full') body.prompt_profile = promptProfile; // D3: server default when absent
+      if (conversationId) body.conversation_id = conversationId;
+      const ep = resolveEndpoint('chat.stream');
+      const cur = { lastSeq: 0, finished: false, conversationId: conversationId || null };
+      const drop = yield* readTurn((sig) => client.stream(ep.path, { service: ep.service, body, signal: sig, untilClose: true }), cur, signal);
+      if (cur.finished || !drop || !durable || signal?.aborted) return;
+      if (!cur.lastSeq || !cur.conversationId) { if (drop.error) throw drop.error; return; } // v1 server: nothing to reattach to
+      yield* reattachLoop({ turnId, cur, signal, first: drop.error, backoff: reattachBackoff });
+    },
+    /**
+     * Reattach to a running (or just finished) turn and yield its events after `after`, exactly once, until
+     * turn.finished. Same reconnect behaviour as stream(). Throws err.code 'turn_not_found' (404) or
+     * 'turn_events_expired' (410).
+     */
+    async *reattach({ conversationId, turnId, after = 0 }, signal) {
+      const cur = { lastSeq: after, finished: false, conversationId };
+      const drop = yield* readTurn((sig) => client.stream(eventsPath(conversationId, turnId), { service: 'collector', query: { after }, signal: sig, untilClose: true }), cur, signal);
+      if (cur.finished || !drop || signal?.aborted) return;
+      yield* reattachLoop({ turnId, cur, signal, first: drop.error, backoff: reattachBackoff });
+    },
+    /** -> { running:true, turnId, lastSeq } | { running:false } | null (route missing or failed: never "not running"). */
+    async runningTurn(conversationId) {
+      if (!conversationId) return { running: false };
+      try {
+        const r = await client.get(`/api/v1/conversations/${encodeURIComponent(conversationId)}/running`, { service: 'collector', retries: 0 });
+        if (r?.running === true && r.turn_id) return { running: true, turnId: r.turn_id, lastSeq: r.last_seq ?? null };
+        return r?.running === false ? { running: false } : null;
+      } catch { return null; }
+    },
+    /**
+     * -> { ok:true } | { ok:false, reason }. reason: 'unsupported' | 'turn_finished' (409, safe to queue)
+     * | 'denied' (403 steer_denied_by_policy) | 'ambiguous' (network, timeout, 5xx: may have been applied).
+     * NEVER retried automatically; steerId lets the server de-duplicate a deliberate resend.
+     */
+    async steer(conversationId, turnId, text, steerId = null) {
+      if (!conversationId) return { ok: false, reason: 'unsupported' };
+      try {
+        const body = steerId ? { text, steer_id: steerId } : { text };
+        const r = await client.post(`${conv(conversationId, turnId)}/steer`, { service: 'collector', body, retries: 0 });
+        if (r && r.queued === false) return { ok: false, reason: steerReason(r.reason) };
+        return { ok: true };
+      } catch (e) {
+        if (e?.status === 403) return { ok: false, reason: 'denied', message: e.code === 'steer_denied_by_policy' ? 'steer_denied_by_policy' : (e.message || 'forbidden') };
+        // Only say "finished" when the server says so; an unlabelled 409 may have been applied.
+        if (e?.status === 409) return { ok: false, reason: steerReason(e.code || e.detail?.code || e.detail?.reason || e.reason) };
+        if (e?.status === 404 || e?.status === 405) return { ok: false, reason: 'unsupported' };
+        return { ok: false, reason: 'ambiguous', message: e?.message || 'failed' };
+      }
+    },
+    /** -> { ok } ; ok:false means the server has no interrupt route (fall back to local abort) */
+    async interrupt(conversationId, turnId) {
+      if (!conversationId) return { ok: false };
+      try { await client.post(`${conv(conversationId, turnId)}/interrupt`, { service: 'collector', body: {} }); return { ok: true }; }
+      catch { return { ok: false }; }
+    },
+    /** -> { exists:true } | { exists:false } | { exists:null, reason } ; null = could not verify (never "not found"). */
+    async conversationExists(conversationId) {
+      try {
+        const r = await client.get(`/api/v1/conversations/${encodeURIComponent(conversationId)}/turns`, { service: 'collector', query: { limit: 1 }, retries: 0 });
+        const turns = r?.turns;
+        if (!Array.isArray(turns)) return { exists: null, reason: 'unexpected response' };
+        return { exists: turns.length > 0 };
+      } catch (e) { return { exists: null, reason: e?.status === 404 || e?.status === 405 ? 'route not available' : (e?.message || 'failed') }; }
+    },
+    /**
+     * -> [{ agent_id, name }] ; every agent id you can talk to: the live core registry (the list `quox agent attach`
+     * validates against, with display names from the bundled roster) plus your org's own agents (`quox agent list`).
+     * Throws only when no source answered at all.
+     */
+    async agents() {
+      const roster = loadBundledAssistantsRoster();
+      const nameOf = new Map(roster.map(r => [r.id, r.name || r.shortName || r.id]));
+      const out = new Map(); let ok = 0; let lastErr = null;
+      try {
+        const ep = resolveEndpoint('v1.tools.agents.list');
+        const d = await client.get(ep.path, { service: ep.service, noAuth: true, retries: 0 });
+        for (const id of Object.keys(d?.agentTools || {})) out.set(id, { agent_id: id, name: nameOf.get(id) || id });
+        ok++;
+      } catch (e) { lastErr = e; for (const r of roster) out.set(r.id, { agent_id: r.id, name: nameOf.get(r.id) }); if (roster.length) ok++; }
+      try {
+        const ep = resolveEndpoint('agents.list', { orgId: orgId() });
+        const rows = listOf(await client.get(ep.path, { service: ep.service, query: { includeTools: 'false' }, retries: 0 }), 'agents', 'data', 'items');
+        for (const r of rows || []) if (r.agent_id && !out.has(r.agent_id)) out.set(r.agent_id, { agent_id: r.agent_id, name: r.name || r.agent_id });
+        if (rows) ok++;
+      } catch (e) { lastErr = lastErr || e; }
+      if (!ok) throw lastErr || new Error('no agent list available');
+      return [...out.values()];
+    },
+    /** -> saved turns of one of YOUR conversations, oldest first [{ id, role, content }]; [] when none or not yours. */
+    async conversationTurns(conversationId) {
+      const d = await client.get(`/api/v1/conversations/${encodeURIComponent(conversationId)}/turns`, { service: 'collector', query: { limit: 200 }, retries: 0 });
+      const rows = listOf(d, 'turns');
+      if (!rows) throw new Error('unexpected response');
+      return rows;
+    },
+    /** -> the org-wide live index (GET /api/v1/sessions, QUOXON J1): { rows, groups, counts, sources }. */
+    async sessionsIndex() {
+      const d = await client.get('/api/v1/sessions', { service: 'collector', retries: 0 });
+      if (!d || !Array.isArray(d.groups)) throw new Error('unexpected response');
+      return d;
+    },
+    /** POST /api/v1/conversations/:id/compact (server-side summary; a model call, so a long timeout and never retried). */
+    async compactConversation(conversationId) {
+      return client.post(`/api/v1/conversations/${encodeURIComponent(conversationId)}/compact`, { service: 'collector', body: {}, retries: 0, timeout: 180000 });
+    },
+    /** GET /api/v1/conversations/:id/context -> { turns, compacted_turns, summary_present, summary_at, tokens, provider, model }. */
+    async conversationContext(conversationId) {
+      return client.get(`/api/v1/conversations/${encodeURIComponent(conversationId)}/context`, { service: 'collector', retries: 0 });
+    },
+    /** Persistent memory answers for this login (the same call as `quox memory stats`). -> { ok } | { ok:false, error }. */
+    async memoryStatus() {
+      try {
+        const ep = resolveEndpoint('memory.stats.list');
+        await client.get(ep.path, { service: ep.service, retries: 0 });
+        return { ok: true };
+      } catch (e) { return { ok: false, error: e?.status ? `HTTP ${e.status}` : (e?.message || 'failed') }; }
+    },
+    /** The `quox doctor` checks, run in this process. */
+    async doctorChecks() { const { runDoctorChecks } = await import('../commands/doctor.js'); return runDoctorChecks({ config }); },
+    serverUrl() { try { return new URL(config.getServiceUrl('collector')).origin; } catch { return null; } },
+    /** /config settings on the active profile. */
+    settings() { try { const q = config.getActiveProfile?.()?.quoxon; return q && typeof q === 'object' ? { ...q } : {}; } catch { return {}; } },
+    saveSetting(id, value) {
+      try { const prof = config.getActiveProfile?.(); if (!prof) return false; prof.quoxon = { ...(prof.quoxon || {}), [id]: value }; config.save?.(); return true; } catch { return false; }
+    },
+    /** -> [{ id, title, updated_at, turn_count }] ; GET /api/v1/conversations (title is server-derived, no rename route). */
+    async conversations(limit = 20) {
+      const d = await client.get('/api/v1/conversations', { service: 'collector', query: { limit }, retries: 0 });
+      const rows = listOf(d, 'conversations');
+      if (!rows) throw new Error('unexpected response');
+      return rows;
+    },
+    /**
+     * Same call as `quox slot checkout <name> --create --session <s>` (cli/lib/commands/slot.js), then the same
+     * local held-slots record. The hold keeper and slot wait loop are NOT started here.
+     * -> { ok:true, slot } | { ok:false, message }.
+     */
+    /**
+     * /gripe: the same governed path as `quox gripe --yes` (the GRIPE agent over chat, then the deterministic
+     * file when the agent did not). The client asks the user first, so the agent is told to file without asking.
+     * -> { ok:true, response, url, superseded, notes } | { ok:false, message }.
+     */
+    async gripe(text, { yes = true } = {}) {
+      try {
+        const options = { yes };
+        const data = await askGripe({ client, complaint: text, yes, orgId: orgId() });
+        const r = await settleGripe({ client, data, complaint: text, options, orgId: orgId() });
+        return { ok: true, response: r.response, url: r.url, superseded: r.superseded, notes: r.notes };
+      } catch (e) {
+        return { ok: false, message: e?.status ? `HTTP ${e.status}: ${e.message}` : (e?.message || 'failed') };
+      }
+    },
+    async checkoutSlot(name, session) {
+      const ep = resolveEndpoint('v1.slots.checkout', { name });
+      try {
+        const data = await client.post(ep.path, { service: ep.service, body: { holder_session: session, holder_kind: 'interactive', host_id: null, org_id: orgId(), force: false, create: true } });
+        recordHeldSlot(name, session);
+        return { ok: true, slot: data?.slot || data };
+      } catch (e) {
+        if (e?.status === 409) return { ok: false, message: e.detail?.assigned_to ? `slot ${name} is assigned to ${e.detail.assigned_to}` : `slot ${name} is held by ${e.detail?.holder_session || 'another session'}` };
+        return { ok: false, message: e?.message || 'failed' };
+      }
+    },
+    /** -> [{ id, name, description, edition, version, decayState }] ; the org's QSKL procedural skills (read-only list; Crystals are a separate store). */
+    async skills() {
+      const ep = resolveEndpoint('quoxflow.skills.list');
+      const data = await client.get(ep.path, { service: ep.service, query: { orgId: orgId() } });
+      const rows = data?.data || data?.records || data;
+      return Array.isArray(rows) ? rows : [];
+    },
+    /** -> the full skill record, or null when unknown (404). */
+    async skill(id) {
+      const ep = resolveEndpoint('quoxflow.skills.get', { id });
+      try { const d = await client.get(ep.path, { service: ep.service, query: { orgId: orgId() } }); return d?.data || d; }
+      catch (e) { if (e?.status === 404) return null; throw e; }
+    },
+    /**
+     * Roster of what is running for this org -> { rows, sources:[{ id, label, state:'connected'|'unavailable'|'error', count, note }] }.
+     * Each source fails on its own; a source that cannot answer adds no rows (never a placeholder).
+     */
+    async roster(now = Date.now()) {
+      const src = (id, label, fn) => fn().then(
+        (rows) => ({ id, label, state: 'connected', rows, count: rows.length }),
+        (e) => ({ id, label, rows: [], count: 0, state: missing(e) ? 'unavailable' : 'error', note: missing(e) ? 'no list endpoint on this server' : (e?.message || 'failed') }));
+      const parts = await Promise.all([
+        src('approvals', 'pending approvals (inbox)', async () => (await listApprovals()).map(i => fromApproval(i, now)).filter(Boolean)),
+        src('objectives', 'objectives and loops (tasks)', async () => {
+          const ep = resolveEndpoint('objectives.list');
+          const d = await client.get(ep.path, { service: ep.service, query: { limit: 100 }, retries: 0 });
+          const l = listOf(d, 'objectives'); if (!l) throw new Error('unexpected response');
+          return l.map(o => fromObjective(o, now)).filter(Boolean);
+        }),
+        src('executions', 'workflow executions (quoxflow)', async () => {
+          const ep = resolveEndpoint('executions.list');
+          const d = await client.get(ep.path, { service: ep.service, retries: 0 });
+          const l = listOf(d, 'data', 'items', 'executions'); if (!l) throw new Error('unexpected response');
+          return l.map(e => fromExecution(e, now, { userId: userId() })).filter(Boolean);
+        })
+      ]);
+      const unlisted = [
+        { id: 'agents', label: 'attached agents', state: 'unavailable', count: 0, note: 'no org-wide list endpoint' },
+        { id: 'devsessions', label: 'dev sessions', state: 'unavailable', count: 0, note: 'listed per host only (quox dev sessions <host>)' }
+      ];
+      return { rows: sortRows(parts.flatMap(p => p.rows)), sources: [...parts.map(({ rows, ...rest }) => rest), ...unlisted] };
+    },
+    /**
+     * Stop one roster row through the governed route that exists for it.
+     * -> { ok:true, message } | { ok:false, unavailable:true } | { ok:false, message }.
+     */
+    async stopRow(row) {
+      if (row.source === 'objectives' && row.kind === 'loop') {
+        try {
+          const ep = resolveEndpoint('objectives.halt', { id: row.id });
+          const r = await client.post(ep.path, { service: ep.service, body: { notes: 'via quoxon' }, retries: 0 });
+          return r?.status === 'halted' ? { ok: true, message: `Loop halted: ${row.name}` } : { ok: false, message: `Not halted${r?.reason ? ` (${r.reason})` : ''}` };
+        } catch (e) { return { ok: false, message: `halt refused: ${e?.message || 'failed'}` }; }
+      }
+      if (row.source === 'executions') {
+        try {
+          const ep = resolveEndpoint('runs.cancel', { orgId: orgId(), runId: row.id });
+          await client.post(ep.path, { service: ep.service, body: { reason: 'via quoxon' }, retries: 0 });
+          return { ok: true, message: `Cancel sent for ${row.name}` };
+        } catch (e) { return { ok: false, message: `cancel refused: ${e?.message || 'failed'}` }; }
+      }
+      return { ok: false, unavailable: true };
+    },
+    /** Facts for /observers, each part on its own: { lucid, learning:[{ id, label, state, text }] }. */
+    async observers() {
+      const part = async (fn) => { try { return { ok: true, v: await fn() }; } catch (e) { return { ok: false, unavailable: missing(e), error: e?.message || 'failed' }; } };
+      const stat = (id, label, name) => part(async () => {
+        const ep = resolveEndpoint(name); const d = await client.get(ep.path, { service: ep.service, retries: 0 });
+        return { id, label, text: d?.primaryMetric?.label || null, fields: d?.fields || {} };
+      });
+      const [sit, lessons, reflect, learn, insight] = await Promise.all([
+        part(async () => { const ep = resolveEndpoint('lucid.situation'); return client.get(ep.path, { service: ep.service, query: { since: 'last', surface: 'cli' }, retries: 0 }); }),
+        part(async () => { const ep = resolveEndpoint('lucid.lessons'); return client.get(ep.path, { service: ep.service, retries: 0 }); }),
+        stat('reflect', 'QuoxReflect', 'engine.reflect.stats'),
+        stat('learn', 'QuoxLearn', 'engine.learn.stats'),
+        stat('insight', 'QuoxInsight', 'engine.insight.stats')
+      ]);
+      return { situation: sit, lessons, learning: [reflect, learn, insight] };
+    },
+    async health(timeoutMs = 12000) {
+      const url = new URL('/health', config.getServiceUrl('collector'));
+      const ctrl = new AbortController();
+      const t = setTimeout(() => ctrl.abort(), timeoutMs);
+      try { const r = await fetch(url, { signal: ctrl.signal }); return { ok: r.ok, status: r.status, url: url.origin }; }
+      catch (e) {
+        const code = e.cause?.code || '';
+        return { ok: false, absent: /ECONNREFUSED|ENOTFOUND|EAI_AGAIN/.test(code), status: e.name === 'AbortError' ? 'slow to answer' : (code || e.message), url: url.origin };
+      } finally { clearTimeout(t); }
+    },
+    /** /capabilities (E1). -> { ok:true, capabilities } | { ok:false, status, missing?, error }. Never assumes. */
+    async capabilities() {
+      const ep = resolveEndpoint('v1.capabilities');
+      try {
+        const d = await client.get(ep.path, { service: ep.service, retries: 0 });
+        const caps = listOf(d, 'capabilities');
+        return caps ? { ok: true, capabilities: caps, computedAt: d?.computed_at || null } : { ok: false, error: 'unexpected response' };
+      } catch (e) {
+        return { ok: false, status: e?.status, missing: missing(e), error: e?.status ? `HTTP ${e.status} ${e.message || ''}`.trim() : (e?.message || 'failed') };
+      }
+    },
+    /** /connect status: the org vault list (the only source a user can read). -> { ok:true, rows } | { ok:false, error }. */
+    async connections() {
+      try {
+        const ep = resolveEndpoint('vault.list', { orgId: orgId() });
+        const d = await client.get(ep.path, { service: ep.service, retries: 0 });
+        const rows = listOf(d, 'credentials', 'data', 'items');
+        return rows ? { ok: true, rows } : { ok: false, error: 'unexpected response' };
+      } catch (e) { return { ok: false, error: e?.status ? `HTTP ${e.status} ${e.message || ''}`.trim() : (e?.message || 'failed') }; }
+    },
+    /**
+     * Server-side live test of a key, nothing persisted (auth test-credentials, SECRETS_WRITE).
+     * Sent once (no retries) and flagged sensitive so --debug never prints the body.
+     */
+    async testProviderKey({ type, credentials }) {
+      const ep = resolveEndpoint('vault.test-credentials', { orgId: orgId() });
+      try {
+        const r = await client.post(ep.path, { service: ep.service, body: { integration_type: type, credentials }, retries: 0, sensitive: true });
+        return { ok: r?.success === true, message: r?.message || null };
+      } catch (e) { return { ok: false, status: e?.status, message: e?.message || 'failed' }; }
+    },
+    /** The governed vault write (same route as `quox vault create`): audited, AEE envelope carries type + label only. */
+    async saveProviderKey({ type, label, credentials, isDefault }) {
+      const ep = resolveEndpoint('vault.create', { orgId: orgId() });
+      try {
+        const r = await client.post(ep.path, { service: ep.service, body: { integration_type: type, label, credentials, is_default: Boolean(isDefault) }, retries: 0, sensitive: true });
+        return { ok: Boolean(r?.id), id: r?.id || null, message: r?.id ? null : 'unexpected response' };
+      } catch (e) { return { ok: false, status: e?.status, message: e?.message || 'failed' }; }
+    },
+    /** B3: refresh an existing vault credential (same governed route as `quox vault update`). */
+    async updateProviderCredential({ id, credentials, isDefault }) {
+      const ep = resolveEndpoint('vault.update', { orgId: orgId(), id });
+      try {
+        const r = await client.put(ep.path, { service: ep.service, body: { credentials, is_default: Boolean(isDefault) }, retries: 0, sensitive: true });
+        return { ok: Boolean(r && (r.id || r.success || r.credential)), id, message: null };
+      } catch (e) { return { ok: false, status: e?.status, message: e?.message || 'failed' }; }
+    },
+    /** B3: server-side probe of an Ollama URL (GET <url>/api/tags). Nothing stored. */
+    async ollamaProbe(baseUrl) {
+      const ep = resolveEndpoint('chat.providers.ollama.probe');
+      try { return await client.post(ep.path, { service: ep.service, body: { base_url: baseUrl }, retries: 0 }); }
+      catch (e) { return { ok: false, status: e?.status, error: e?.code || null, message: e?.message || 'failed' }; }
+    },
+    /** B3: the saved Ollama connection's installed models -> { ok, host, default_model, models } | { ok:false, error, message }. */
+    async ollamaModels() {
+      const ep = resolveEndpoint('chat.providers.ollama.models');
+      try { return await client.get(ep.path, { service: ep.service, retries: 0 }); }
+      catch (e) { return { ok: false, status: e?.status, error: e?.code || null, message: e?.message || 'failed' }; }
+    },
+    /** B5: server-side probe of a self-hosted / custom OpenAI-compatible base URL (lmstudio|vllm|custom). Nothing stored. */
+    async compatProbe(preset, baseUrl) {
+      const ep = resolveEndpoint('chat.providers.compat.probe', { preset });
+      try { return await client.post(ep.path, { service: ep.service, body: { base_url: baseUrl }, retries: 0 }); }
+      catch (e) { return { ok: false, status: e?.status, error: e?.code || null, message: e?.message || 'failed' }; }
+    },
+    /** B5: the saved connection's models for a preset -> { ok, host, default_model, models:[{id,context_length,tools}] } | { ok:false, error, message }. */
+    async compatModels(preset) {
+      const ep = resolveEndpoint('chat.providers.compat.models', { preset });
+      try { return await client.get(ep.path, { service: ep.service, retries: 0 }); }
+      catch (e) { return { ok: false, status: e?.status, error: e?.code || null, message: e?.message || 'failed' }; }
+    },
+    approvals: listApprovals,
+    /** GET /api/v1/approvals/:id/result -> { status, result, executed_at } ; null when unknown (404) */
+    async approvalResult(approvalId) {
+      const ep = resolveEndpoint('v1.approvals.result', { id: approvalId });
+      try { return await client.get(ep.path, { service: ep.service, query: { org_id: orgId() || undefined } }); }
+      catch (e) { if (e?.status === 404) return null; throw e; }
+    },
+    async respond(itemId, action) {
+      const ep = resolveEndpoint('inbox.respond', { orgId: orgId(), itemId });
+      return client.post(ep.path, { service: ep.service, body: { action, comment: 'via quoxon' } });
+    }
+  };
+}