quoxcli 0.4.0 → 0.6.0

package/lib/quoxon/dragonMoments.js

@@ -5,6 +5,8 @@
  * dragon shows itself. The controller (dragonCompanion.js) runs the engine on every stream fact and owns the routing: while a
  * companion owns the moments the Q dragon stays quiet, so a moment is never two dragons.
  */
+import { dragonForAgent } from '../dragon/select.js';
+
 export const MOMENTS = Object.freeze({
   approval: Object.freeze({ mood: 'waiting', companion: true }),
   failure: Object.freeze({ mood: 'failure', companion: true }),
@@ -80,3 +82,79 @@ export function createRosterWatch() {
     },
   };
 }
+
+// ---- sender moments: a named session or agent speaks to the owner, so its own dragon appears (companion mode `on` only) ---------
+/** The same sender cannot call its dragon again for this long once it has shown (a chatty session is one dragon, not a parade). */
+export const SENDER_COOLDOWN_MS = 5 * 60 * 1000;
+/** Only a message this recent is a moment: a backlog replayed on (re)connect is history, not news. */
+export const SLOT_FRESH_MS = 2 * 60 * 1000;
+
+const head = (s) => String(s).split(/[\s\-_.:/]+/)[0];
+/** One name -> a dragon id: the whole name, its first word, or that word without trailing digits (quoxperticus-126). */
+function dragonForName(name) {
+  const s = String(name ?? '').trim();
+  if (!s) return null;
+  return dragonForAgent(s) || dragonForAgent(head(s)) || dragonForAgent(head(s).replace(/\d+$/, ''));
+}
+/**
+ * A slot message sender -> its agent's dragon, or null. `from` is "slot (display)" or a bare name. The speaker (the display name
+ * in brackets) wins, then the bare name, then the slot it holds. Only approved dragons (select.js AGENT_DRAGON) can match.
+ */
+export function dragonForSender(m) {
+  if (!m) return null;
+  const from = String(m.from ?? '').trim();
+  const inner = (from.match(/\(([^)]*)\)\s*$/) || [])[1];
+  const bare = from.replace(/\s*\(.*$/, '');
+  for (const n of [inner, bare, m.from_slot]) { const d = dragonForName(n); if (d) return d; }
+  return null;
+}
+const senderKey = (m) => String(m?.from_slot || m?.from || '').replace(/\s*\(.*$/, '').trim().toLowerCase();
+
+/** A fresh slot message from a dragon session -> { dragon, sender, caption } | null. The caption says who and what kind, never the content. */
+export function slotMessageMoment(m, { now = Date.now(), broadcast = false, run = false } = {}) {
+  const dragon = dragonForSender(m);
+  if (!dragon) return null;
+  const t = Date.parse(m.created_at ?? m.createdAt ?? '');
+  if (!Number.isFinite(t) || now - t > SLOT_FRESH_MS) return null;
+  const who = String(m.from).trim();
+  const caption = run ? `${who} asks you to run a command.` : broadcast ? `Broadcast from ${who}.` : `Message from ${who}.`;
+  return { dragon, sender: senderKey(m), caption };
+}
+
+/** Another session's approval card newly waiting, asked by an agent with a dragon -> { dragon, sender, key, caption } | null. */
+export function waitingCardMoment(prev, next) {
+  const before = new Set((prev?.waiting || []).map(c => c.inboxItemId));
+  for (const c of next?.waiting || []) {
+    if (!c || before.has(c.inboxItemId)) continue;
+    const who = c.origin || c.askedBy;
+    const dragon = dragonForName(who) || dragonForName(c.askedBy);
+    if (!dragon) continue;
+    return { dragon, sender: String(who).toLowerCase(), key: c.inboxItemId, caption: `${who} wants your approval${c.tool ? ` (${c.tool})` : ''}.` };
+  }
+  return null;
+}
+
+/**
+ * Dedupe + per-sender cooldown for sender moments. observe() remembers the message id at once (a re-delivery is never a second
+ * moment); shown() starts the sender's cooldown, so a moment refused because the owner was typing does not silence that sender.
+ */
+export function createSenderWatch({ now = Date.now, cooldownMs = SENDER_COOLDOWN_MS } = {}) {
+  const seen = new Set(), last = new Map();
+  const remember = (k) => { seen.add(k); if (seen.size > 500) seen.delete(seen.values().next().value); };
+  const cool = (sender) => { const t = last.get(sender); return t != null && now() - t < cooldownMs; };
+  return {
+    observe(m, opts = {}) {
+      const id = m?.event_id || m?.id || (m?.created_at ? `${m.created_at}|${m.seq ?? ''}|${m.from ?? ''}` : null);
+      if (id != null) { if (seen.has(String(id))) return null; remember(String(id)); }
+      const mo = slotMessageMoment(m, { ...opts, now: now() });
+      return mo && !cool(mo.sender) ? mo : null;
+    },
+    card(prev, next) {
+      const mo = waitingCardMoment(prev, next);
+      if (!mo || seen.has(`card:${mo.key}`)) return null;
+      remember(`card:${mo.key}`);
+      return cool(mo.sender) ? null : mo;
+    },
+    shown(sender) { last.set(sender, now()); },
+  };
+}

package/lib/quoxon/echo.js

@@ -10,6 +10,7 @@ export const ECHO_CAP = 2000;
 export function echoLine(text, { cols = 100 } = {}) {
   let t = String(text ?? '').trim();
   if (PIN_CMD.test(t)) t = t.split(/\s+/)[0]; // a stray argument may be a PIN: never shown
+  if (/^\/verify-email(\s|$)/i.test(t) && /(^|\D)\d{6}(\D|$)/.test(t)) t = '/verify-email'; // a 6-digit run may be a PIN typed by mistake: never shown
   const full = redactSecrets(t).text;
   return { shown: clip(full.replace(/\s*\n\s*/g, ' '), ECHO_CAP), full };
 }

package/lib/quoxon/events.js

@@ -11,6 +11,9 @@
  *   turn     : null | { id, status: running|interrupting, startedAt, stage, activity }
  */
 
+import { eventLine } from '../core/announce.js';
+import { isDestructive, isDestructiveTool, destructiveObject } from './destructive.js';
+import { heldReason } from './bulkRisk.js';
 import { approvalSentence } from './approvalSentence.js';
 import { dividerStep } from './dividerAocl.js';
 import { approvalFacts } from './approvalFacts.js';
@@ -80,6 +83,15 @@ export function textGate(st, ev) {
 
 const tms = (v) => { const t = typeof v === 'number' ? v : Date.parse(v); return Number.isFinite(t) ? t : null; };
 
+/** A machine source key (`devsuite_pack_install:<host>:<pack>:<ver>`) is never shown as a requester: it names a human-readable origin instead. */
+const SOURCE_KEY = /^[A-Za-z][\w.-]*(:[^:\s]+){2,}$/;
+const SOURCE_NAMES = [[/^devsuite_/i, 'DevSuite (skill-pack sync)']];
+export function humanRequester(v) {
+  const t = String(v ?? '').trim(); if (!t || !SOURCE_KEY.test(t)) return t || null;
+  const hit = SOURCE_NAMES.find(([re]) => re.test(t)); if (hit) return hit[1];
+  const head = t.split(':')[0].replace(/[_-]+/g, ' ').trim();
+  return head ? head.charAt(0).toUpperCase() + head.slice(1) : 'plugin or workflow';
+}
 const short = (v, n = 120) => { const t = typeof v === 'string' ? v : (v == null ? '' : JSON.stringify(v)); return t.length > n ? t.slice(0, n - 1) + '…' : t; };
 const argText = (a) => a && typeof a === 'object' && !Array.isArray(a) && (a.argv || a.command) ? argText(a.argv ?? a.command) : Array.isArray(a) ? a.join(' ') : (a && typeof a === 'object' ? Object.entries(a).filter(([, v]) => v != null && typeof v !== 'object').slice(0, 4).map(([k, v]) => `${k}=${v}`).join(' ') : (a == null ? '' : String(a)));
 
@@ -97,7 +109,7 @@ export function describeInboxItem(it) {
   const argv = m.argv ?? m.args ?? c.argv ?? c.args ?? p.argv ?? p.args ?? m.command ?? c.command ?? p.command ?? null;
   const cmd = short([m.leaf || c.leaf || p.leaf, argText(argv)].filter(Boolean).join(' ').trim() || null);
   const target = w.target || m.target || c.target || p.target || cmd || w.target_none || c.target_org || c.org_name || p.org_name || c.org_id || p.org_id || null;
-  const by = ob.agent || ob.agent_id || ob.session_name || ob.session || c.requested_by?.agent_label || c.source_label || p.source || it?.source || null;
+  const by = humanRequester(ob.agent || ob.agent_id || ob.session_name || ob.session || c.requested_by?.agent_label || c.source_label || p.source || it?.source || null);
   const what = w.summary ? String(w.summary) : (it?.title ? short(String(it.title), 160) : null);
   return { tool, target: target ? short(target, 200) : null, title: what, by: by ? String(by) : null, at: it?.created_at ?? it?.createdAt ?? null };
 }
@@ -107,6 +119,13 @@ export function describeInboxItem(it) {
  * Qualifies when created after `since` (the turn start, else app start), or raised on behalf of this
  * user, or in this conversation. The inbox list is already scoped to the signed-in user and org.
  */
+/** The contact-consent proposal on an inbox item (proposeOptin.js), or null. It has no executor: the TUI records the grant. */
+export function consentOf(it) {
+  const p = it?.payload || {};
+  if (p.kind_detail !== 'contactability_optin' || !p.recipient || !p.channel) return null;
+  return { recipient: String(p.recipient), channel: String(p.channel), proposed: p.proposed && typeof p.proposed === 'object' ? p.proposed : {} };
+}
+
 export function cardFromInboxItem(it, { since = 0, userId = null, conversationId = null, now = 0 } = {}) {
   if (!it || !it.id) return null;
   if (it.payload?.type === 'decision') return null; // quox ask: answered with /answer N key from /approvals, never a y/n key card
@@ -126,9 +145,13 @@ export function cardFromInboxItem(it, { since = 0, userId = null, conversationId
   const tool = d.tool || String(it.title || it.id);
   return {
     callId: `inbox:${it.id}`, inboxItemId: it.id, approvalId,
+    consent: consentOf(it), // a contact-consent proposal: approving records nothing until the person gives the lawful basis
     tool, target: d.target, what: d.title, askedBy: d.by, askedAt: d.at, scope: null, risk: c.risk || null,
     url: it.dashboard_url || null, shownAt: now, undescribable: !d.tool && !d.target && !it._plan,
     plan: it._plan ? { lines: planLines(it._plan.steps), loaded: it._plan.loaded !== false, orgId: it._plan.orgId || null, orgName: it._plan.orgName || null } : null, // the plan's steps + the item's own org
+    destructive: isDestructive(it) ? destructiveObject(it) : null, // typed-name confirm before a y approves it
+    disruptive: [it, it.payload, c, m, it.payload?.what].some(o => o && o.disruptive === true), // server-marked: never batched
+    held: heldReason(it), // a risky ask is never part of a batch card
     facts: approvalFacts(it), // APPROVAL-WWWH: the exact command, hosts, chain, reason, time and read-only class
     // only an item that names THIS conversation is ours; anything else came from another session and must not take the keyboard
     foreign: !here,
@@ -140,7 +163,7 @@ export function cardFromInboxItem(it, { since = 0, userId = null, conversationId
 /** Where an inbox approval came from: its source label, else the payload source, else its type. */
 export function approvalSourceLabel(it) {
   const c = it?.payload?.approval_context || {};
-  return String(c.source_label || it?.payload?.source || it?.source || (c.requested_by && c.requested_by.agent_label) || it?.payload?.type || 'plugin or workflow');
+  return humanRequester(c.source_label || it?.payload?.source || it?.source || (c.requested_by && c.requested_by.agent_label) || it?.payload?.type || 'plugin or workflow');
 }
 
 /**
@@ -245,7 +268,7 @@ export function delegateInfo(ev) {
   if (ev.tool !== 'delegate_to_agent') return {};
   const id = ev.agent_id || (String(ev.summary || '').match(/\bagent_id=(\S+)/) || [])[1] || null;
   if (!id) return {};
-  return { agentId: id, agentName: ev.agent_name || id, ...(ev.task_gist ? { taskGist: ev.task_gist } : {}) };
+  return { agentId: id, agentName: ev.agent_name || id, ...(ev.task_gist ? { taskGist: ev.task_gist } : {}), ...(ev.dragon === true ? { dragon: true } : {}) };
 }
 
 function upsertTool(s, ev, patch) {
@@ -377,7 +400,7 @@ function reduceInner(s, a) {
     case 'help':
       return { ...s, history: [...s.history, { id: nid(), kind: 'help', model: a.model }] };
     case 'object': // inline object view (objects/): pure data, rebuilt at render width
-      return { ...s, history: [...s.history, { id: nid(), kind: 'object', obj: a.obj }] };
+      return { ...s, notify: scopeNotify(s.notify, a.obj), history: [...s.history, { id: nid(), kind: 'object', obj: a.obj }] };
     case 'error':
       return flush(addBlock(s, { kind: 'error', text: a.text }), false);
     case 'verbose':
@@ -435,11 +458,11 @@ function reduceInner(s, a) {
       const card = cardFromInboxItem(a.item, { since: s.turn?.startedAt ?? a.since ?? 0, userId: a.userId, conversationId: s.ctx.conversationId, now: a.now || 0 });
       if (card && card.approvalId) { // an event card raised without an inbox id learns it from the poll (else y answers a null id: 404)
         const j = s.approvals.findIndex(x => !x.inboxItemId && x.approvalId === card.approvalId);
-        if (j >= 0) { const approvals = s.approvals.slice(); approvals[j] = { ...approvals[j], inboxItemId: card.inboxItemId, url: approvals[j].url || card.url, facts: approvals[j].facts || card.facts }; return { ...s, approvals, seenInbox: { ...s.seenInbox, [card.inboxItemId]: true } }; }
+        if (j >= 0) { const approvals = s.approvals.slice(); approvals[j] = { ...approvals[j], inboxItemId: card.inboxItemId, url: approvals[j].url || card.url, facts: approvals[j].facts || card.facts, destructive: approvals[j].destructive || card.destructive }; return { ...s, approvals, seenInbox: { ...s.seenInbox, [card.inboxItemId]: true } }; }
       }
       if (card && card.approvalId) { // an event stub that could not be described learns its description from the inbox item
         const j = s.approvals.findIndex(x => x.undescribable && (x.inboxItemId === card.inboxItemId || x.approvalId === card.approvalId));
-        if (j >= 0 && !card.undescribable) { const approvals = s.approvals.slice(); approvals[j] = { ...approvals[j], tool: card.tool, target: card.target, what: card.what, askedBy: card.askedBy, askedAt: card.askedAt, facts: card.facts, undescribable: false }; return { ...s, approvals }; }
+        if (j >= 0 && !card.undescribable) { const approvals = s.approvals.slice(); approvals[j] = { ...approvals[j], tool: card.tool, target: card.target, what: card.what, askedBy: card.askedBy, askedAt: card.askedAt, facts: card.facts, destructive: approvals[j].destructive || card.destructive, undescribable: false }; return { ...s, approvals }; }
       }
       if (!card || s.seenInbox[card.inboxItemId] || s.approvals.some(x => x.inboxItemId === card.inboxItemId || (card.approvalId && x.approvalId === card.approvalId))) return s;
       if (card.foreign) { // another conversation's card: a compact notice, never the focused card
@@ -458,9 +481,15 @@ function reduceInner(s, a) {
       return { ...s, approvals: s.approvals.filter(x => x.callId !== a.callId) };
     case 'approval.sent': { // the human answered from this terminal
       const rest = { ...s, inbox: (s.inbox || []).filter(x => x.id !== a.inboxItemId), seenInbox: a.inboxItemId ? { ...s.seenInbox, [a.inboxItemId]: true } : s.seenInbox, approvals: s.approvals.filter(x => x.callId !== a.callId && !(a.inboxItemId && x.inboxItemId === a.inboxItemId)), waiting: s.waiting.filter(x => x.callId !== a.callId && x.inboxItemId !== a.callId) };
+      if (a.notRecorded) return note(rest, a.notRecorded, 'warn'); // the server answered 2xx but did not record the yes
+      if (a.consent && a.action === 'approve') return note(rest, `approved, but no consent is recorded yet: ${a.consent.recipient} via ${a.consent.channel} needs the lawful basis. Type it now (one line), or n to leave it unrecorded.`, 'warn');
       if (a.batch) return rest; // /approve N prints its own one-line summary
       if (a.quiet && a.action === 'approve') return rest;
       if (a.action !== 'approve') return note(rest, approvalSentence(a, false), 'warn');
+      if (a.foreign && a.approvalId) { // tracked: the poll adds one follow-up line with the outcome
+        const run = { callId: a.callId, approvalId: a.approvalId, tool: a.tool, target: a.target };
+        return note({ ...rest, running: [...rest.running.filter(x => x.callId !== a.callId), run] }, approvalSentence(a, true), 'ok');
+      }
       if (a.foreign) return note(rest, approvalSentence(a, true), 'ok');
       if (a.tool === 'hat.switch') { // applied server-side by the inbox approve; nothing to wait for
         const to = String(a.target || '').split('\u2192').pop().replace(/\(privileged\)/, '').trim() || 'the new hat';
@@ -475,8 +504,9 @@ function reduceInner(s, a) {
       const n = { ...s, running: s.running.filter(x => x.callId !== a.callId) };
       const what = run ? `${run.tool || 'approval'}${run.target ? ` on ${run.target}` : ''}` : 'approval';
       if (a.outcome === 'done') return note(n, `result: ${what}: ${a.text || 'completed'}`, 'ok');
-      if (a.outcome === 'failed') return note(n, `failed: ${what}: ${a.text || 'error'}`, 'warn');
+      if (a.outcome === 'failed') return note(n, `${Number.isInteger(a.exit) && a.exit >= 1 ? `ran, exit ${a.exit}` : 'failed'}: ${what}: ${a.text || 'error'}`, 'warn');
       if (a.outcome === 'denied') return note(n, `denied: ${what}`, 'warn');
+      if (a.outcome === 'unrecorded') return note(n, `not run: ${what}. Your yes was saved in your inbox but never reached the tool runner: the server still shows the approval pending, with nobody recorded as deciding. Nothing ran. Ask the agent again for a fresh approval. Check: quox approvals result ${run && run.approvalId ? run.approvalId : '(no id)'}`, 'warn');
       // FW4: never silent and never a guess. Say what is unknown and where the authoritative answer is.
       const check = run && run.approvalId ? `quox approvals result ${run.approvalId} (or /approvals)` : '/approvals (no approval id was returned, so it cannot be tracked from here)';
       return note(n, `result not known yet: ${what}; approved, but the server has not said whether it ran. It may still be running or may have run. Check: ${check}`, 'warn');
@@ -495,6 +525,15 @@ function reduceInner(s, a) {
 }
 
 /** The first card is armed from the moment it is actually SHOWN, not from when it was received. */
+/** An away/sitrep card that lists older items or a source it cannot see: the approvals bar must not say all-clear next to it. */
+function scopeNotify(n, obj) {
+  const d = obj?.data;
+  if (!d || (obj.type !== 'away' && obj.type !== 'sitrep')) return n;
+  const outstanding = obj.type === 'away' ? (d.standing?.count || 0) : (d.needs || []).length;
+  const blind = Array.isArray(d.blind) ? d.blind.length : 0;
+  return { ...n, outstanding, blind };
+}
+
 export function reduce(s, a) {
   let n = reduceInner(s, a);
   // TUI-DIVIDER: the bottom-rule AOCL strip, moved only by real turn events (dividerAocl.js).
@@ -593,7 +632,8 @@ function reduceEvent(s, ev, now) {
         target: ev.target, scope: ev.scope, risk: ev.risk, url: ev.dashboard_url, shownAt: now,
         undescribable: ev.describable === false || !ev.target,
         turnId: s.turn?.id ?? ev.turn_id ?? null, // the turn this card arrived in (a stream event is always this conversation)
-        privileged: isPrivileged({ tool: ev.tool, risk: ev.risk, flag: ev.privileged === true || ev.elevated === true })
+        privileged: isPrivileged({ tool: ev.tool, risk: ev.risk, flag: ev.privileged === true || ev.elevated === true }),
+        destructive: ev.destructive === true || ev.irreversible === true || isDestructiveTool(ev.tool) ? (() => { const v = String(ev.object_name || ev.target || ev.inbox_item_id || ev.tool || 'item').slice(0, 80); return { label: v, name: v }; })() : null
       };
       if (s.approvals.some(x => x.callId === card.callId)) return s;
       const dup = s.approvals.findIndex(x => (card.inboxItemId && x.inboxItemId === card.inboxItemId) || (card.approvalId && x.approvalId === card.approvalId));
@@ -611,6 +651,13 @@ function reduceEvent(s, ev, now) {
       const n = { ...s, approvals: s.approvals.filter(x => x.callId !== ev.call_id) };
       return card || ev.decision ? note(n, `${ev.decision === 'approved' ? '✔ approved by you' : `approval ${ev.decision || 'resolved'}`}${card ? `: ${card.tool} on ${card.target}` : ''}`, ev.decision === 'approved' ? 'ok' : 'warn') : n;
     }
+    // QUOX-ANNOUNCE A2: a Quox effect of this turn (memory saved, approval held, delegation ...), one line, same renderer as the CLI verbs.
+    case 'quox_event': {
+      const text = eventLine(ev);
+      if (!text) return s;
+      if (ev.status === 'fail') return addBlock(s, { kind: 'error', text });
+      return addBlock(s, { kind: 'note', text, tone: ev.status === 'ok' ? 'ok' : ev.status === 'busy' ? 'accent' : 'warn' });
+    }
     case 'steer.accepted': {
       const i = s.steering.findIndex(x => x.text === ev.text);
       const steering = i >= 0 ? s.steering.filter((_, k) => k !== i) : s.steering.slice(1);