quoxcli 0.0.0-stage → 0.2.0

package/lib/quoxon/connect.js

@@ -0,0 +1,467 @@
+/**
+ * /connect: connections status, the secure key card's logic, the composer paste guard and the
+ * gentle "connect it now?" offer. Pure, apart from the api object passed in.
+ *
+ * Where a key goes (the path /chat/stream reads): the org's DEFAULT QuoxVault credential of the
+ * provider's integration type. The collector resolves OpenAI via auth /internal/resolve ->
+ * credentialResolver.resolveProviderKey(org, 'openai') -> getDefaultCredential(org, 'openai').
+ * The write is auth POST /api/orgs/:orgId/vault (alias of /integrations: SECRETS_WRITE gated,
+ * audited, AEE envelope carrying integration_type + label only). The label is "<Name> …last4",
+ * so the audit trail holds a fingerprint and never the key.
+ *
+ * The key itself lives only inside a secret box (closure). It is never dispatched, never put in
+ * the composer buffer or history, never sent to the chat stream, never written to a transcript.
+ */
+
+export const PROVIDERS = {
+  openai: {
+    id: 'openai', type: 'openai', name: 'OpenAI', field: 'api_key', card: true, minLen: 20,
+    why: 'Quox needs an OpenAI key to use GPT models for your org.',
+    keyUrl: 'https://platform.openai.com/api-keys'
+  },
+  anthropic: {
+    id: 'anthropic', type: 'anthropic', name: 'Claude API', field: 'api_key', card: true, minLen: 20,
+    why: 'Quox needs an Anthropic API key to call Claude models for your org.',
+    keyUrl: 'https://console.anthropic.com/settings/keys'
+  },
+  // B3: no key; a server URL. /connect ollama <url> probes it server side, then saves.
+  ollama: { id: 'ollama', type: 'ollama', name: 'Ollama', card: false, url: true },
+  // B5: hosted OpenAI-compatible presets. Same secure key card; the third-party data path is stated on it.
+  openrouter: hosted('openrouter', 'OpenRouter', 'api_key', 'https://openrouter.ai/settings/keys',
+    "OpenRouter, which passes them to the model's provider"),
+  huggingface: hosted('huggingface', 'Hugging Face', 'api_token', 'https://huggingface.co/settings/tokens',
+    "Hugging Face, which passes them to the inference provider that serves the model"),
+  groq: hosted('groq', 'Groq', 'api_key', 'https://console.groq.com/keys', 'Groq'),
+  together: hosted('together', 'Together', 'api_key', 'https://api.together.ai/settings/api-keys', 'Together AI'),
+  // B5: self-hosted OpenAI-compatible servers: no key, a URL. Probed server side, then saved.
+  lmstudio: selfHosted('lmstudio', 'LM Studio', 1234),
+  vllm: selfHosted('vllm', 'vLLM', 8000),
+  // B5: any https OpenAI-compatible base URL, key optional (asked for only when the server needs one).
+  custom: {
+    id: 'custom', type: 'openai_compatible', name: 'Custom', field: 'api_key', card: false, url: true, custom: true, minLen: 8,
+    why: 'This endpoint wants an API key. It is stored in your org vault with the base URL.',
+    keyUrl: 'the provider of that endpoint',
+    disclosure: 'Custom endpoint: your prompts and tool results leave this server for that URL. Unless it is your own server, that is a third party. Your org\'s AI data sharing consent applies.'
+  }
+};
+function hosted(id, name, field, keyUrl, who) {
+  return {
+    id, type: id, name, field, card: true, hosted: true, minLen: 20, keyUrl,
+    why: `Quox needs a ${name} key to use ${name} models for your org.`,
+    disclosure: `Hosted: your prompts and tool results leave this server for ${who}. Your org's AI data sharing consent applies.`
+  };
+}
+function selfHosted(id, name, port) {
+  return { id, type: id, name, card: false, url: true, selfHosted: true, port };
+}
+const ALIASES = {
+  'anthropic-api': 'anthropic', claude: 'anthropic', gpt: 'openai', chatgpt: 'openai',
+  hf: 'huggingface', 'lm-studio': 'lmstudio', 'openai-compatible': 'custom', openai_compatible: 'custom'
+};
+export const providerFor = (name) => PROVIDERS[ALIASES[String(name || '').toLowerCase()] || String(name || '').toLowerCase()] || null;
+
+// ---- paste guard -------------------------------------------------------------------------------
+const ANTHROPIC_RE = /\bsk-ant-[A-Za-z0-9_-]{16,}/;
+const OPENROUTER_RE = /\bsk-or-(?:v1-)?[A-Za-z0-9_-]{16,}/;
+const GROQ_RE = /\bgsk_[A-Za-z0-9]{20,}/;
+const HF_RE = /\bhf_[A-Za-z0-9]{20,}/;
+const OPENAI_RE = /\bsk-(?:proj-|svcacct-|admin-)?[A-Za-z0-9_-]{20,}/;
+
+/** -> { provider } when the text carries something API-key shaped, else null. */
+export function looksLikeKey(text) {
+  const s = String(text || '');
+  if (ANTHROPIC_RE.test(s)) return { provider: 'anthropic' };
+  if (OPENROUTER_RE.test(s)) return { provider: 'openrouter' }; // must win over the generic sk- shape
+  if (GROQ_RE.test(s)) return { provider: 'groq' };
+  if (HF_RE.test(s)) return { provider: 'huggingface' };
+  if (OPENAI_RE.test(s)) return { provider: 'openai' };
+  return null;
+}
+export const keyWarning = (hit) => `That looks like an API key. I didn't send it. Use /connect ${hit?.provider || 'openai'} to store it safely.`;
+
+// ---- masked input ------------------------------------------------------------------------------
+/** Bullets while typing; after a paste, four bullets and the last 4 (enough to recognise the key). */
+export function maskSecret(value, pasted) {
+  const v = String(value || '');
+  if (!v) return '';
+  if (pasted && v.length >= 8) return `••••${v.slice(-4)}`;
+  return '•'.repeat(Math.min(v.length, 32));
+}
+
+/** Holds the secret in a closure. Serialising the box shows nothing. */
+export function createSecretBox() {
+  let v = ''; let pasted = false;
+  const clean = (t) => String(t || '').replace(/[\s\x00-\x1f\x7f]+/g, '');
+  return {
+    type(t) { v += clean(t); },
+    paste(t) { v += clean(t); pasted = true; },
+    backspace() { v = [...v].slice(0, -1).join(''); if (!v) pasted = false; },
+    clear() { v = ''; pasted = false; },
+    length: () => v.length,
+    last4: () => v.slice(-4),
+    mask: () => maskSecret(v, pasted),
+    /** Hands the value out once and empties the box. */
+    take() { const out = v; v = ''; pasted = false; return out; },
+    toJSON: () => '[secret]',
+    toString: () => '[secret]'
+  };
+}
+
+// ---- connections status ------------------------------------------------------------------------
+const testTag = (r) => r.test_status === 'success' ? 'tested ✔' : r.test_status === 'failed' ? 'last test failed' : 'untested';
+export const pickRow = (rows, type) => {
+  const of = rows.filter(r => r.integration_type === type);
+  return { def: of.find(r => r.is_default === 1 || r.is_default === true) || null, any: of[0] || null };
+};
+
+/**
+ * -> [[text, tone?]] lines for /connect. `res` is { ok:true, rows } from the vault list, or
+ * { ok:false, error }. Only the org vault is readable by a user; anything it cannot answer is "? unknown".
+ */
+export function connectionLines(res) {
+  const STATUS_PROVIDERS = [PROVIDERS.openai, PROVIDERS.anthropic, PROVIDERS.ollama, PROVIDERS.openrouter, PROVIDERS.huggingface, PROVIDERS.groq, PROVIDERS.together, PROVIDERS.lmstudio, PROVIDERS.vllm, PROVIDERS.custom];
+  const out = [];
+  const ok = res && res.ok && Array.isArray(res.rows);
+  const rows = ok ? res.rows : [];
+  out.push(['Connections for this org:']);
+  for (const p of STATUS_PROVIDERS) {
+    const hint = p.custom ? '/connect custom https://<host>/v1' : p.card ? `/connect ${p.id}` : p.url ? `/connect ${p.id} http://<host>:${p.port || 11434}` : `quox vault create --type ${p.type}`;
+    if (!ok) { out.push([`? ${p.name}  unknown (vault not readable)`, 'warn']); continue; }
+    const { def, any } = pickRow(rows, p.type);
+    if (def) out.push([`● ${p.name}  connected · ${def.label || def.id} · ${testTag(def)}`, def.test_status === 'failed' ? 'warn' : 'ok']);
+    else if (any) out.push([`◐ ${p.name}  stored but not the default · quox vault set-default ${any.id}`, 'warn']);
+    else out.push([`○ ${p.name}  not connected · ${hint}`]);
+  }
+  out.push(['? Claude (subscription)  unknown · this server has no status route for it']);
+  if (!ok) { out.push([`  could not read the vault: ${res?.error || 'no answer'}`, 'warn']); return out; }
+  const known = new Set(Object.values(PROVIDERS).map(p => p.type));
+  const others = new Map();
+  for (const r of rows) {
+    if (known.has(r.integration_type)) continue;
+    const cur = others.get(r.integration_type);
+    if (!cur || (r.is_default && !cur.is_default)) others.set(r.integration_type, r);
+  }
+  const list = [...others.values()];
+  if (list.length) {
+    out.push(['Integrations in your vault:']);
+    for (const r of list.slice(0, 12)) out.push([`● ${r.integration_type}  ${r.label || r.id} · ${testTag(r)}`, r.test_status === 'failed' ? 'warn' : undefined]);
+    if (list.length > 12) out.push([`  +${list.length - 12} more · quox vault list`]);
+  } else {
+    out.push(['No other integrations yet. Connect Slack, GitHub, email and more with quox vault create --type <type>.']);
+  }
+  out.push(['  An instance-wide key set by your admin can also serve chat; it is not visible from here.']);
+  return out;
+}
+
+// ---- gentle offer ------------------------------------------------------------------------------
+const MISSING = [
+  [/openai[^.]*?(api key )?(not configured|not connected|missing|no api key)/i, 'openai'],
+  [/(anthropic|claude api)[^.]*?(api key )?(not configured|not connected|missing|no api key)/i, 'anthropic']
+];
+export const offerText = (p) => `Ⓠ ${p.name} isn't connected, so I can't use it yet. Connect it now? /connect ${p.id}`;
+
+/** -> the one-line offer when an event says a provider is missing, else null. */
+export function connectOfferFor(ev) {
+  if (!ev || typeof ev !== 'object') return null;
+  if (ev.available === false && ev.provider) { const p = providerFor(ev.provider); return p?.card ? offerText(p) : null; }
+  if (ev.type !== 'error' && ev.type !== 'turn.finished') return null;
+  const s = [ev.error, ev.message, ev.detail].filter(x => typeof x === 'string').join(' ');
+  for (const [re, id] of MISSING) if (re.test(s)) return offerText(PROVIDERS[id]);
+  return null;
+}
+
+// ---- save flow ---------------------------------------------------------------------------------
+const scrubOut = (s, secret) => {
+  let t = String(s || '');
+  if (secret) t = t.split(secret).join('[key]');
+  return t.replace(/\b(?:sk-|gsk_|hf_)[A-Za-z0-9_-]{6,}/g, '[key]');
+};
+
+/**
+ * Server-side live test first (nothing persisted), then the governed vault write as the org default.
+ * -> { ok, provider, last4, text } ; text is safe to show and to record.
+ */
+export async function connectFlow(api, providerId, secret, extra) {
+  const p = providerFor(providerId);
+  if (!p?.card && !p?.custom) return { ok: false, provider: providerId, text: `${providerId} cannot be connected from here.` };
+  const key = String(secret || '');
+  if (key.length < p.minLen) return { ok: false, provider: p.id, text: `That is too short to be a ${p.name} key. Paste the whole key, or Esc to cancel.` };
+  const last4 = key.slice(-4);
+  const credentials = { ...(p.custom && extra ? { base_url: extra.base_url, ...(extra.default_model ? { default_model: extra.default_model } : {}) } : {}), [p.field]: key };
+  const label = p.custom && extra?.host ? `${p.name} · ${extra.host} …${last4}` : `${p.name} …${last4}`;
+  let t;
+  try { t = await api.testProviderKey({ type: p.type, credentials }); }
+  catch (e) { t = { ok: false, unreachable: true, message: e?.message }; }
+  if (!t?.ok) {
+    const why = scrubOut(t?.message || 'no reason given', key);
+    return { ok: false, provider: p.id, last4, text: t?.unreachable || t?.status >= 500
+      ? `✖ Could not test the key (${why}). Nothing was saved.`
+      : `✖ ${p.name} rejected the key: ${why}. Nothing was saved.` };
+  }
+  let s;
+  try { s = await api.saveProviderKey({ type: p.type, label, credentials, isDefault: true }); }
+  catch (e) { s = { ok: false, status: e?.status, message: e?.message }; }
+  if (!s?.ok && s?.status === 409) return { ok: false, provider: p.id, last4, text: `This key is already in your vault as "${label}". /connect shows its status.` };
+  if (!s?.ok) {
+    const why = scrubOut(s?.message || 'failed', key);
+    const role = s?.status === 403 ? ' Storing org keys needs the secrets.write capability; ask an org admin.' : '';
+    return { ok: false, provider: p.id, last4, text: `✖ The key tested fine but was not saved (${s?.status ? `HTTP ${s.status}: ` : ''}${why}).${role}` };
+  }
+  return { ok: true, provider: p.id, last4, text: `✔ ${p.name} connected · key …${last4} · tested`, ...(p.disclosure ? { disclosure: p.disclosure } : {}) };
+}
+
+// ---- card controller ---------------------------------------------------------------------------
+/**
+ * Owns the open card and its secret box. The app routes every input event here while the card is
+ * open (onEvent returns true = consumed), and renders view(). note(text, tone) shows a line; emit(a)
+ * dispatches a transcript-visible action (only connect.started / connect.saved, provider + last4).
+ */
+export function createConnectController({ api, note, emit, refresh }) {
+  const box = createSecretBox();
+  let card = null;
+  const close = () => { box.clear(); card = null; refresh(); };
+  async function submit() {
+    if (!box.length()) { card.error = 'Paste your key first, or Esc to cancel.'; refresh(); return; }
+    card.phase = 'saving'; card.error = null; refresh();
+    const p = card.provider;
+    const extra = card.extra;
+    const r = await connectFlow(api, p.id, box.take(), extra);
+    if (!card) return;
+    if (r.ok) {
+      card = null; refresh();
+      emit({ type: 'connect.saved', provider: p.id, last4: r.last4 });
+      note(r.text, 'ok');
+      if (r.disclosure) note(r.disclosure, 'warn');
+      note('Your next turns can use it. Servers cache keys briefly, so allow up to a minute.');
+      return;
+    }
+    card.phase = 'input'; card.error = r.text; refresh();
+  }
+  return {
+    isOpen: () => Boolean(card),
+    view: () => (card ? { card: { ...card }, mask: box.mask() } : null),
+    /** -> true when a card opened. */
+    open(name) {
+      const p = providerFor(name);
+      if (!p) { note(`Nothing called "${name}" to connect. /connect lists what is available.`, 'warn'); return false; }
+      if (p.custom) { note('Custom endpoints take a URL first: /connect custom https://<host>/v1 [model]'); return false; }
+      if (!p.card) { note(p.url ? `${p.name} takes a server URL, not a key: /connect ${p.id} http://<host>:${p.port || 11434} [model]` : `${p.name} takes a server URL, not a key. Add it with: quox vault create --type ${p.type}`); return false; }
+      if (!api.testProviderKey || !api.saveProviderKey) { note('Connecting is not available in this mode.', 'warn'); return false; }
+      box.clear(); card = { provider: p, phase: 'input', error: null };
+      emit({ type: 'connect.started', provider: p.id });
+      refresh();
+      return true;
+    },
+    /** B5: open the key card for a custom endpoint that answered 401/403; extra = { base_url, host, default_model? }. */
+    openCustom(extra) {
+      if (!api.testProviderKey || !api.saveProviderKey) { note('Connecting is not available in this mode.', 'warn'); return false; }
+      box.clear(); card = { provider: PROVIDERS.custom, phase: 'input', error: null, extra, subtitle: extra.host };
+      emit({ type: 'connect.started', provider: 'custom' });
+      refresh();
+      return true;
+    },
+    onEvent(e) {
+      if (!card) return false;
+      if (card.phase === 'saving') return true;
+      if (e.type === 'paste') { box.paste(e.text); card.error = null; refresh(); return true; }
+      if (e.type === 'text') { box.type(e.text); card.error = null; refresh(); return true; }
+      if (e.type !== 'key') return true;
+      if (e.name === 'escape' || e.name === 'ctrl-c') { close(); note('Cancelled. Nothing was stored.'); return true; }
+      if (e.name === 'enter') { submit(); return true; }
+      if (e.name === 'backspace') { box.backspace(); refresh(); return true; }
+      if (e.name === 'kill-line' || e.name === 'delete-word') { box.clear(); refresh(); return true; }
+      return true; // every other key is swallowed by the card
+    }
+  };
+}
+
+// ---- Ollama (B3): a server URL, no key -----------------------------------------------------------
+/** "/connect ollama <url> [model]" rest -> { url, model } ; a bare host gets http:// and :11434. */
+export function parseOllamaArg(rest) {
+  const [rawUrl, model] = String(rest || '').trim().split(/\s+/);
+  if (!rawUrl) return { url: null, model: null };
+  let url = rawUrl;
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(url)) {
+    url = `http://${url}`;
+    try { const u = new URL(url); if (!u.port) { u.port = '11434'; url = u.toString().replace(/\/$/, ''); } } catch { /* the server says why */ }
+  }
+  return { url, model: model || null };
+}
+
+// Families whose Ollama builds accept tools (prefer one as the chat default).
+const TOOL_FAMILIES = /^(qwen2\.5|qwen3|llama3\.[123]|mistral|mistral-nemo|mistral-small|command-r|hermes3|granite3|firefunction|nemotron|gpt-oss|smollm2)/i;
+export const likelyToolCapable = (name) => TOOL_FAMILIES.test(String(name || ''));
+
+/** The chat default: the asked model, else the first likely tool-capable one, else the first. */
+export function pickOllamaDefault(models, asked) {
+  const names = (Array.isArray(models) ? models : []).map(m => (typeof m === 'string' ? m : m?.name)).filter(Boolean);
+  if (asked) {
+    if (names.includes(asked)) return asked;
+    return names.includes(`${asked}:latest`) ? `${asked}:latest` : null;
+  }
+  return names.find(likelyToolCapable) || names[0] || null;
+}
+
+const gb = (b) => (Number.isFinite(b) && b > 0 ? `${(b / 1e9).toFixed(1)} GB` : '');
+/** -> [[text, tone?]] for an installed-model list. */
+export function ollamaModelRows(models, current) {
+  const out = [];
+  for (const m of (models || []).slice(0, 20)) {
+    const facts = [m.parameter_size, gb(m.size), likelyToolCapable(m.name) ? 'tools' : null].filter(Boolean).join(' · ');
+    out.push([`${m.name === current ? '▸' : ' '} ${m.name}${facts ? `  ${facts}` : ''}`, m.name === current ? 'ok' : undefined]);
+  }
+  if ((models || []).length > 20) out.push([`  +${models.length - 20} more`]);
+  return out;
+}
+
+export const OLLAMA_REACH_HINT = [
+  'On the Ollama machine: start it listening on the network, OLLAMA_HOST=0.0.0.0 ollama serve',
+  'and allow port 11434 through its firewall. "localhost" is not reachable from the server; use the machine\'s LAN address.'
+];
+
+/**
+ * Server-side probe (GET <url>/api/tags; human org admin; nothing stored), then the governed vault
+ * write as the org default: { base_url, default_model, allow_private_origin? }. A private address is
+ * allow-listed only for the exact origin probed. -> { ok, lines: [[text, tone?]] }
+ */
+export async function connectOllamaFlow(api, rest) {
+  const { url, model } = parseOllamaArg(rest);
+  if (!url) return { ok: false, lines: [['Usage: /connect ollama http://<host>:11434 [model]', 'warn']] };
+  if (!api.ollamaProbe || !api.saveProviderKey) return { ok: false, lines: [['Connecting is not available in this mode.', 'warn']] };
+  const p = await api.ollamaProbe(url);
+  if (!p?.ok) {
+    if (p?.status === 403) return { ok: false, lines: [['✖ Connecting Ollama needs an org admin. Nothing was saved.', 'warn']] };
+    const lines = [[`✖ ${p?.message || 'Ollama could not be reached'}. Nothing was saved.`, 'warn']];
+    if (p?.error === 'ollama_unreachable' || p?.status === 502) for (const h of OLLAMA_REACH_HINT) lines.push([`  ${h}`]);
+    return { ok: false, lines };
+  }
+  const models = Array.isArray(p.models) ? p.models : [];
+  const def = pickOllamaDefault(models, model);
+  if (model && !def) {
+    return { ok: false, lines: [[`✖ ${model} is not installed on ${p.host}. On that machine run: ollama pull ${model}  Nothing was saved.`, 'warn'], ...ollamaModelRows(models)] };
+  }
+  const credentials = { base_url: p.base_url, ...(def ? { default_model: def } : {}), ...(p.private ? { allow_private_origin: p.origin } : {}) };
+  const label = `Ollama · ${p.host}`;
+  let s = await api.saveProviderKey({ type: 'ollama', label, credentials, isDefault: true });
+  if (!s?.ok && s?.status === 409 && api.connections && api.updateProviderCredential) {
+    // Same host connected before: refresh that credential (URL, default model, allowance) instead.
+    const c = await api.connections();
+    const row = c?.ok ? c.rows.find(r => r.integration_type === 'ollama' && r.label === label) : null;
+    s = row ? await api.updateProviderCredential({ id: row.id, credentials, isDefault: true }) : s;
+  }
+  if (!s?.ok) {
+    const role = s?.status === 403 ? ' Storing org connections needs the secrets.write capability; ask an org admin.' : '';
+    const lan = s?.status === 400 && /private|internal/i.test(s?.message || '') ? ' This instance does not allow LAN integration targets yet; an operator enables allow_lan_integration_targets.' : '';
+    return { ok: false, lines: [[`✖ Ollama answered but the connection was not saved (${s?.status ? `HTTP ${s.status}: ` : ''}${s?.message || 'failed'}).${role}${lan}`, 'warn']] };
+  }
+  const lines = [[`✔ Ollama connected · ${p.host} · ${models.length} model${models.length === 1 ? '' : 's'}${def ? ` · default ${def}` : ''}`, 'ok']];
+  if (p.private) lines.push([`  ${p.origin} is a private address; it is allow-listed for this org's Ollama connection only.`]);
+  if (!models.length) lines.push(['  No models installed yet. On that machine run: ollama pull qwen2.5', 'warn']);
+  else {
+    lines.push(...ollamaModelRows(models, def));
+    if (def && !likelyToolCapable(def)) lines.push([`  ${def} may not support tools; turns then run without them. qwen2.5 or llama3.1 do.`, 'warn']);
+  }
+  lines.push(['  Use it: /model ollama' + (def ? '' : ' <model>')]);
+  return { ok: true, host: p.host, model: def, lines };
+}
+
+// ---- B5: self-hosted OpenAI-compatible servers (LM Studio, vLLM) and custom endpoints ------------
+const REACH_HINTS = {
+  lmstudio: [
+    'On the LM Studio machine: in the Developer tab enable "Serve on Local Network" and start the server (port 1234).',
+    'Allow that port through its firewall. "localhost" is not reachable from the server; use the machine\'s LAN address.'
+  ],
+  vllm: [
+    'On the vLLM machine: start it listening on the network, vllm serve <model> --host 0.0.0.0 --port 8000',
+    'and allow port 8000 through its firewall. "localhost" is not reachable from the server; use the machine\'s LAN address.'
+  ],
+  custom: ['Check the URL (it usually ends in /v1) and that the endpoint is reachable from the server.']
+};
+export const SELF_HOSTED_NOTE = 'Self-hosted: your prompts stay between this server and your machine. No third party is added.';
+
+/** "/connect <lmstudio|vllm|custom> <url> [model]" rest -> { url, model, error? }. Bare host: http:// and the preset's port. */
+export function parseCompatArg(presetId, rest) {
+  const p = PROVIDERS[presetId];
+  const [rawUrl, model] = String(rest || '').trim().split(/\s+/);
+  if (!rawUrl) return { url: null, model: null };
+  let url = rawUrl;
+  if (p?.custom) {
+    if (/^http:\/\//i.test(url)) return { url: null, model: null, error: 'Custom endpoints must be https://. For a server on your own network use /connect lmstudio or /connect vllm.' };
+    if (!/^https:\/\//i.test(url)) return { url: null, model: null, error: 'Custom endpoints take a full https:// base URL, for example /connect custom https://api.example.com/v1' };
+    return { url, model: model || null };
+  }
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(url)) {
+    url = `http://${url}`;
+    try { const u = new URL(url); if (!u.port) { u.port = String(p?.port || 80); url = u.toString().replace(/\/$/, ''); } } catch { /* the server says why */ }
+  }
+  return { url, model: model || null };
+}
+
+/** Compact model rows for a compat /models list: up to 20, a tools tag when the server says so. */
+export function compatModelRows(models, current) {
+  const out = [];
+  for (const m of (models || []).slice(0, 20)) {
+    const id = typeof m === 'string' ? m : m?.id;
+    if (!id) continue;
+    out.push([`${id === current ? '▸' : ' '} ${id}${m?.tools === true ? '  tools' : ''}`, id === current ? 'ok' : undefined]);
+  }
+  if ((models || []).length > 20) out.push([`  +${models.length - 20} more`]);
+  return out;
+}
+
+/**
+ * /connect lmstudio|vllm|custom <url> [model]. Server-side probe (human org admin; nothing stored), then the
+ * governed vault write as the org default. Custom endpoints that answer 401/403 come back as
+ * { ok:false, needsKey:true, extra } so the app can open the key card carrying base_url.
+ * -> { ok, lines: [[text, tone?]], needsKey?, extra? }
+ */
+export async function connectCompatFlow(api, presetId, rest) {
+  const p = PROVIDERS[presetId];
+  if (!p?.url || p.id === 'ollama') return { ok: false, lines: [[`${presetId} cannot be connected by URL.`, 'warn']] };
+  const { url, model, error } = parseCompatArg(p.id, rest);
+  const usage = p.custom ? '/connect custom https://<host>/v1 [model]' : `/connect ${p.id} http://<host>:${p.port} [model]`;
+  if (error) return { ok: false, lines: [[`✖ ${error}`, 'warn']] };
+  if (!url) return { ok: false, lines: [[`Usage: ${usage}`, 'warn']] };
+  if (!api.compatProbe || !api.saveProviderKey) return { ok: false, lines: [['Connecting is not available in this mode.', 'warn']] };
+  const pr = await api.compatProbe(p.id, url);
+  if (!pr?.ok) {
+    if (pr?.status === 403) return { ok: false, lines: [[`✖ Connecting ${p.name} needs an org admin. Nothing was saved.`, 'warn']] };
+    const lines = [[`✖ ${pr?.message || `${p.name} could not be reached`}. Nothing was saved.`, 'warn']];
+    if (pr?.error === 'provider_unreachable' || pr?.status === 502) for (const h of REACH_HINTS[p.id] || []) lines.push([`  ${h}`]);
+    return { ok: false, lines };
+  }
+  const models = Array.isArray(pr.models) ? pr.models : [];
+  const ids = models.map(m => m.id);
+  if (pr.needs_key) {
+    if (p.custom) {
+      return { ok: false, needsKey: true, extra: { base_url: pr.base_url, host: pr.host, ...(model ? { default_model: model } : {}) },
+        lines: [[`${pr.host} answered but wants an API key. Opening the key card.`]] };
+    }
+    return { ok: false, lines: [[`✖ ${pr.host} wants an API key, which ${p.name} connections do not take here. Use /connect custom ${pr.base_url} instead. Nothing was saved.`, 'warn']] };
+  }
+  if (model && ids.length && !ids.includes(model)) {
+    return { ok: false, lines: [[`✖ ${model} is not served by ${pr.host}. Nothing was saved.`, 'warn'], ...compatModelRows(models)] };
+  }
+  const credentials = {
+    base_url: pr.base_url, ...(model ? { default_model: model } : {}),
+    ...(pr.private && !p.custom ? { allow_private_origin: pr.origin } : {})
+  };
+  const label = `${p.name} · ${pr.host}`;
+  let s = await api.saveProviderKey({ type: p.type, label, credentials, isDefault: true });
+  if (!s?.ok && s?.status === 409 && api.connections && api.updateProviderCredential) {
+    const c = await api.connections();
+    const row = c?.ok ? c.rows.find(r => r.integration_type === p.type && r.label === label) : null;
+    s = row ? await api.updateProviderCredential({ id: row.id, credentials, isDefault: true }) : s;
+  }
+  if (!s?.ok) {
+    const role = s?.status === 403 ? ' Storing org connections needs the secrets.write capability; ask an org admin.' : '';
+    const lan = s?.status === 400 && /private|internal/i.test(s?.message || '') ? ' This instance does not allow LAN integration targets yet; an operator enables allow_lan_integration_targets.' : '';
+    return { ok: false, lines: [[`✖ ${p.name} answered but the connection was not saved (${s?.status ? `HTTP ${s.status}: ` : ''}${s?.message || 'failed'}).${role}${lan}`, 'warn']] };
+  }
+  const lines = [[`✔ ${p.name} connected · ${pr.host} · ${models.length} model${models.length === 1 ? '' : 's'}${model ? ` · default ${model}` : ''}`, 'ok']];
+  if (pr.private && !p.custom) lines.push([`  ${pr.origin} is a private address; it is allow-listed for this org's ${p.name} connection only.`]);
+  lines.push(p.custom ? [`  ${p.disclosure}`, 'warn'] : [`  ${SELF_HOSTED_NOTE}`]);
+  lines.push(...compatModelRows(models, model));
+  lines.push([`  Use it: /model ${p.id}${model ? '' : ' [model]'}`]);
+  return { ok: true, host: pr.host, model: model || null, lines };
+}

package/lib/quoxon/connectCard.js

@@ -0,0 +1,28 @@
+/**
+ * The secure /connect card. Shown in place of the composer while it is open. It renders only the
+ * mask from the secret box, never the value.
+ */
+import React from 'react';
+import { Box, Text } from 'ink';
+import { c, clip } from './theme.js';
+import { Rule } from './render.js';
+
+const h = React.createElement;
+
+/** card: { provider: PROVIDERS entry, phase: 'input'|'saving', error?: string }, mask: string */
+export function ConnectCard({ card, mask, cols }) {
+  const p = card.provider;
+  const w = Math.max(10, cols - 4);
+  return h(Box, { flexDirection: 'column', width: cols, marginTop: 1 },
+    h(Rule, { cols, color: 'sky' }),
+    h(Text, { color: c('sky'), bold: true }, clip(`Ⓠ Connect ${p.name}${card.subtitle ? ` · ${card.subtitle}` : ''} · goes straight to your org vault, never into chat`, cols)),
+    h(Text, { color: c('text') }, clip(`  ${p.why}`, cols)),
+    p.disclosure ? h(Text, { color: c('warn'), wrap: 'wrap' }, `  ${p.disclosure}`) : null,
+    h(Text, { color: c('text') }, clip(`  Get a key: ${p.keyUrl}`, cols)),
+    h(Text, { color: c('text') }, clip(`  key    ${mask || ''}${card.phase === 'input' ? '▏' : ''}`, cols)),
+    card.error ? h(Text, { color: c('warn') }, clip(`  ${card.error}`, w + 2)) : null,
+    h(Text, { color: c('dim') }, card.phase === 'saving'
+      ? clip(`  ◐ testing with ${p.name}, then saving…`, cols)
+      : clip('  paste your key · Enter test and save · Esc cancel · keys typed here stay in this card', cols)),
+    h(Rule, { cols, color: 'sky' }));
+}

package/lib/quoxon/context.js

@@ -0,0 +1,68 @@
+/**
+ * Where am I: the slot this session holds and the agent attached to it, for the
+ * status line. Reads directory names and slot labels only, never token contents.
+ * Layout mirrors lib/core/callerSource.js (~/.quox/attach/sessions/claude-<pid>/<agent>/,
+ * ~/.quox/held-slots.json sessionKey claude-<pid>).
+ */
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const clean = (v, n = 32) => String(v == null ? '' : v).replace(/[^\w .:@+\-/~]/g, '').trim().slice(0, n) || null;
+
+const defaults = {
+  readName: (pid) => { try { return readFileSync(`/proc/${pid}/comm`, 'utf8').trim(); } catch { return null; } },
+  readPpid: (pid) => {
+    try {
+      const s = readFileSync(`/proc/${pid}/stat`, 'utf8');
+      const p = parseInt(s.slice(s.lastIndexOf(')') + 2).trim().split(/\s+/)[1], 10);
+      return Number.isFinite(p) ? p : null;
+    } catch { return null; }
+  },
+  attachRoot: () => join(homedir(), '.quox', 'attach', 'sessions'),
+  heldSlotsPath: () => join(homedir(), '.quox', 'held-slots.json'),
+  readdir: (d) => { try { return readdirSync(d, { withFileTypes: true }); } catch { return []; } },
+  readJson: (p) => { try { return existsSync(p) ? JSON.parse(readFileSync(p, 'utf8')) : null; } catch { return null; } },
+  exists: existsSync,
+  pid: () => process.pid
+};
+
+function claudeAncestor(d, start) {
+  let pid = start;
+  for (let hop = 0; hop < 24; hop++) {
+    if (d.readName(pid) === 'claude') return pid;
+    const pp = d.readPpid(pid);
+    if (!pp || pp === pid || pid === 1) break;
+    pid = pp;
+  }
+  return null;
+}
+
+/** -> { slot: string|null, agent: string|null } ; env wins, then the attach/slot files of the claude ancestor. */
+export function detectSlotAgent(env = process.env, overrides = {}) {
+  const d = { ...defaults, ...overrides };
+  let slot = clean(env.QUOX_SLOT);
+  let agent = clean(env.QUOX_AGENT);
+  if (slot && agent) return { slot, agent };
+  let pid = null;
+  try { pid = claudeAncestor(d, d.pid()); } catch { pid = null; }
+  if (pid) {
+    if (!agent) {
+      const dir = join(d.attachRoot(), `claude-${pid}`);
+      const found = d.readdir(dir).filter(e => e.isDirectory() && d.exists(join(dir, e.name, 'token')));
+      if (found.length) {
+        const kit = d.readJson(join(dir, found[0].name, 'kit.json'));
+        agent = clean(kit && kit.display_name) || clean(found[0].name);
+      }
+    }
+    if (!slot) {
+      const all = d.readJson(d.heldSlotsPath());
+      if (all && typeof all === 'object') {
+        for (const [name, e] of Object.entries(all)) {
+          if (e && e.sessionKey === `claude-${pid}`) { slot = clean(name); break; }
+        }
+      }
+    }
+  }
+  return { slot, agent };
+}

package/lib/quoxon/copy.js

@@ -0,0 +1,33 @@
+/** /copy helpers: pick the text and build the OSC 52 clipboard escape. */
+
+export function osc52(text, env = process.env) {
+  const seq = `\x1b]52;c;${Buffer.from(String(text), 'utf8').toString('base64')}\x07`;
+  return env.TMUX ? `\x1bPtmux;${seq.replace(/\x1b/g, '\x1b\x1b')}\x1b\\` : seq;
+}
+
+/** Fenced code blocks (``` or ~~~) of a markdown string, in order, without the fence lines. */
+export function codeBlocks(md) {
+  const out = []; let cur = null; let fence = null;
+  for (const line of String(md).split('\n')) {
+    const m = line.match(/^\s*(```+|~~~+)/);
+    if (cur === null) { if (m) { fence = m[1][0]; cur = []; } continue; }
+    if (m && m[1][0] === fence && line.trim() === m[1] ) { out.push(cur.join('\n')); cur = null; continue; }
+    cur.push(line);
+  }
+  if (cur && cur.length) out.push(cur.join('\n'));
+  return out;
+}
+
+/** arg: '' | 'N' | 'code'. -> { text } or { error } */
+export function pickCopy(answers, arg) {
+  const list = (answers || []).filter(a => a.text && a.text.trim());
+  if (!list.length) return { error: 'No answer to copy yet.' };
+  if (arg === 'code') {
+    for (let i = list.length - 1; i >= 0; i--) { const b = codeBlocks(list[i].text); if (b.length) return { text: b[b.length - 1] }; }
+    return { error: 'No code block in the answers so far.' };
+  }
+  const n = arg ? Number(arg) : 1;
+  if (!Number.isInteger(n) || n < 1) return { error: 'Usage: /copy [N|code]' };
+  if (n > list.length) return { error: `Only ${list.length} answer${list.length === 1 ? '' : 's'} so far.` };
+  return { text: list[list.length - n].text };
+}

package/lib/quoxon/demo.fixtures.js

@@ -0,0 +1,24 @@
+/** Simulated QUOXON journey for --demo, screenshots and tests. Nothing here talks to a server. */
+export const DEMO_STEPS = (turnId) => [
+  { wait: 150, ev: { type: 'turn.started', turn_id: turnId, conversation_id: 'demo-conv', agent: 'CommanderQ', provider: 'demo', model: 'demo-model', hat: 'operator' } },
+  { wait: 300, ev: { type: 'thinking', turn_id: turnId, stage: 'planning', message: 'Planning the steps' } },
+  { wait: 400, ev: { type: 'text.delta', turn_id: turnId, content: 'I will save that note, then restart the web service. ' } },
+  { wait: 300, ev: { type: 'tool.started', turn_id: turnId, call_id: 'c1', tool: 'memory_save', summary: 'save note "demo journey"' } },
+  { wait: 200, ev: { type: 'trace', turn_id: turnId, protocol: 'aee', label: 'envelope opened', ref: '01K4N8QXAB' } },
+  { wait: 700, ev: { type: 'tool.finished', turn_id: turnId, call_id: 'c1', tool: 'memory_save', status: 'ok', result_summary: 'saved', duration_ms: 640, envelope_id: 'env1', receipt: null } },
+  { wait: 300, ev: { type: 'tool.started', turn_id: turnId, call_id: 'c2', tool: 'host_restart', summary: 'restart web on edge-02' } },
+  { wait: 300, ev: { type: 'approval.requested', turn_id: turnId, call_id: 'c2', inbox_item_id: 'demo-item', approval_id: 'demo-appr', tool: 'host_restart', target: 'web on edge-02', scope: 'service restart, 1 host', risk: 'medium', dashboard_url: 'https://example.invalid/approvals/demo-item' } },
+  { gate: 'approval' },
+  { when: 'reject', wait: 200, ev: { type: 'approval.resolved', turn_id: turnId, call_id: 'c2', inbox_item_id: 'demo-item', decision: 'denied' } },
+  { when: 'reject', wait: 200, ev: { type: 'tool.finished', turn_id: turnId, call_id: 'c2', tool: 'host_restart', status: 'denied', result_summary: 'denied by you, not run', duration_ms: 0, envelope_id: null, receipt: null } },
+  { when: 'reject', wait: 300, ev: { type: 'text.delta', turn_id: turnId, content: 'Understood. The note is saved; web on edge-02 was NOT restarted because you denied it (demo data).' } },
+  { when: 'reject', wait: 200, ev: { type: 'turn.finished', turn_id: turnId, status: 'completed', conversation_id: 'demo-conv' } },
+  { when: 'approve', wait: 200, ev: { type: 'approval.resolved', turn_id: turnId, call_id: 'c2', inbox_item_id: 'demo-item', decision: 'approved' } },
+  { when: 'approve', wait: 900, ev: { type: 'tool.finished', turn_id: turnId, call_id: 'c2', tool: 'host_restart', status: 'ok', result_summary: 'restart web on edge-02', duration_ms: 2300, envelope_id: 'env2', receipt: { ward_seq: 4069513, verified: true } } },
+  { when: 'approve', wait: 100, ev: { type: 'trace', turn_id: turnId, protocol: 'aocl', label: 'ingress ok identity ok policy ok' } },
+  { when: 'approve', wait: 100, ev: { type: 'trace', turn_id: turnId, protocol: 'ward', label: 'witnessed', ref: '4069513' } },
+  { when: 'approve', wait: 300, ev: { type: 'text.delta', turn_id: turnId, content: 'Done. The note is saved and web on edge-02 restarted (demo data, nothing real ran).' } },
+  { when: 'approve', wait: 200, ev: { type: 'turn.finished', turn_id: turnId, status: 'completed', conversation_id: 'demo-conv' } }
+];
+
+export const DEMO_LABEL = 'DEMO: simulated journey, no server, nothing real runs';