quoxcli 0.3.1 → 0.5.0

package/lib/commands/x.js

@@ -389,6 +389,56 @@ export function registerXCommands(program, ctx) {
       }
     });
 
+  // ── x whoami / accounts ───────────────────────────────────────────────────
+  // quox#867: a focused read of the connected social account (platform, handle,
+  // connection status), without the posting-budget half of `x status`. Backs the
+  // chat read-parity lane (an agent/CLI asking "which X account am I connected as?").
+  x
+    .command('whoami')
+    .alias('accounts')
+    .description('Show the connected X account: platform, handle and connection status')
+    .action(async () => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('v1.tools.execute');
+
+      let cred = null;
+      let credError = null;
+      try {
+        const credData = await client.post(ep.path, {
+          service: ep.service,
+          body: { tool_name: 'twitter_verify_credentials', input: {}, org_id: orgId },
+        });
+        if (credData && credData.success === false) {
+          credError = credData.error || 'unknown error';
+        } else {
+          cred = credData && credData.result ? credData.result : credData;
+        }
+      } catch (err) {
+        credError = err.message;
+      }
+
+      const account = {
+        platform: 'x',
+        connected: !credError && !!cred,
+        handle: cred && cred.username ? `@${cred.username}` : null,
+        name: (cred && cred.name) || null,
+        id: (cred && cred.id) || null,
+        error: credError,
+      };
+
+      if (program.opts().output === 'json') {
+        formatDetail({ accounts: [account] }, { format: 'json' });
+        return;
+      }
+
+      if (credError) {
+        printWarning(`X: not connected (twitter_verify_credentials via POST ${ep.path}): ${credError}`);
+      } else {
+        printSuccess(`X: connected as ${account.handle}${account.name ? ` (${account.name})` : ''}`);
+      }
+    });
+
   // ── x media-root ────────────────────────────────────────────────────────
 
   x

package/lib/commands/youtube.js

@@ -0,0 +1,172 @@
+/**
+ * `quox youtube` — YouTube plugin verbs, YT-O-6 (tiktok/linkedin CLI parity).
+ *
+ * quox youtube upload "<title>" --file <path-in-media-root> [--description t] [--privacy private|unlisted|public] [--thumbnail <image-path>]
+ * quox youtube thumbnail <videoId> --image <path-in-media-root>
+ * quox youtube videos [--limit <n>]
+ * quox youtube channel
+ * quox youtube analytics [--metrics a,b,c] [--video <id>]
+ * quox youtube comment <commentId> "<text>"
+ *
+ * The write verbs (upload, thumbnail, comment) execute the youtube connector
+ * tool through the governed collector endpoint (POST /api/v1/tools/execute ->
+ * connector bridge). The bridge gates them on requiresApproval: it files an
+ * owner approval card and returns { pending:true, status:'awaiting_approval',
+ * approvalId, inbox_item_id }. The YouTube API write only happens once an
+ * approver says yes (dashboard inbox or `quox inbox respond <id> --action approve`).
+ *
+ * Honest limit on --thumbnail: YouTube assigns the video id only when the
+ * upload actually executes, i.e. AFTER approval. While the upload card is
+ * pending there is no id to attach a thumbnail to, so the chained
+ * set_thumbnail step runs only if the upload came back executed with a
+ * video id; otherwise the CLI says so and names the follow-up verb.
+ */
+
+import { formatDetail, printSuccess, printInfo, printWarning } from '../core/output.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { resolveOrgId } from './helpers.js';
+
+const PRIVACY = ['private', 'unlisted', 'public'];
+
+async function executeYouTubeTool({ client, auth, program }, toolName, input) {
+  auth.requireAuth();
+  const orgId = resolveOrgId(auth, program);
+  const ep = resolveEndpoint('v1.tools.execute');
+  const body = { tool_name: toolName, input, org_id: orgId };
+  const data = await client.post(ep.path, { service: ep.service, body });
+  if (data && data.success === false && !data.pending) {
+    throw new Error(`${toolName} via POST ${ep.path} returned success:false: ${data.error || 'unknown error'}`);
+  }
+  return data;
+}
+
+function printAwaitingApproval(action, data) {
+  const itemRef = data.inbox_item_id || data.approvalId || 'unknown';
+  printSuccess(`${action} filed for owner approval - inbox item ${itemRef} (awaiting approval). Nothing is sent to YouTube until an approver says yes.`);
+  if (data.inbox_item_id) {
+    printInfo(`Review and approve: quox inbox get ${data.inbox_item_id}  (or: quox inbox respond ${data.inbox_item_id} --action approve)`);
+  }
+}
+
+export function registerYouTubeCommands(program, ctx) {
+  const { client, auth } = ctx;
+  const run = (tool, input) => executeYouTubeTool({ client, auth, program }, tool, input);
+  const asJson = () => program.opts().output === 'json';
+
+  const youtube = program
+    .command('youtube')
+    .description('YouTube uploads, thumbnails, comments and reads: writes are governed and HITL-approved via HITL Inbox, on your own vaulted Google credential');
+
+  youtube
+    .command('upload')
+    .description('Upload a video from a file under the org media root. Files an owner approval card and returns immediately; never uploads directly.')
+    .argument('<title>', 'video title (max 100 characters)')
+    .requiredOption('--file <path>', 'video file path, relative to the org media root')
+    .option('--description <text>', 'video description')
+    .option('--privacy <status>', `privacy status: ${PRIVACY.join('|')} (default private)`, 'private')
+    .option('--thumbnail <path>', 'thumbnail image path (media root); chained set_thumbnail, only possible once the upload has a video id')
+    .action(async (title, options) => {
+      const privacy = options.privacy || 'private';
+      if (!PRIVACY.includes(privacy)) {
+        throw new Error(`--privacy must be one of ${PRIVACY.join(', ')} (got ${privacy})`);
+      }
+      const input = { title, file_path: options.file, privacy_status: privacy };
+      if (options.description) input.description = options.description;
+
+      const data = await run('youtube_upload_video', input);
+      const videoId = data?.result?.video_id || data?.video_id || null;
+      let thumb = null;
+      if (options.thumbnail && videoId && !data.pending) {
+        thumb = await run('youtube_set_thumbnail', { video_id: videoId, image_path: options.thumbnail });
+      }
+
+      if (asJson()) {
+        formatDetail(thumb ? { upload: data, thumbnail: thumb } : data, { format: 'json' });
+        return;
+      }
+      if (data.pending) {
+        printAwaitingApproval('Upload', data);
+        if (options.thumbnail) {
+          printWarning(`Thumbnail not filed: the video id does not exist until the upload is approved and runs. After approval run: quox youtube thumbnail <videoId> --image ${options.thumbnail}  (that files a second, separate approval).`);
+        }
+        return;
+      }
+      printSuccess(`Upload executed${videoId ? ` - video ${videoId}` : ''}.`);
+      if (thumb) {
+        if (thumb.pending) printAwaitingApproval('Thumbnail', thumb);
+        else printSuccess('Thumbnail set.');
+      } else if (options.thumbnail) {
+        printWarning(`Upload returned no video id, so the thumbnail was not set. Run: quox youtube thumbnail <videoId> --image ${options.thumbnail}`);
+      }
+    });
+
+  youtube
+    .command('thumbnail')
+    .description('Set a custom thumbnail on an existing video from an image under the org media root. Files an owner approval card; never sets it directly.')
+    .argument('<videoId>', 'YouTube video id')
+    .requiredOption('--image <path>', 'image path (.jpg/.jpeg/.png, max 2MB), relative to the org media root')
+    .action(async (videoId, options) => {
+      const data = await run('youtube_set_thumbnail', { video_id: videoId, image_path: options.image });
+      if (asJson()) { formatDetail(data, { format: 'json' }); return; }
+      printAwaitingApproval('Thumbnail', data);
+    });
+
+  youtube
+    .command('videos')
+    .description('List the connected channel\'s recent videos (read-only, no approval needed).')
+    .option('--limit <n>', 'max videos to return (max 50)', '20')
+    .action(async (options) => {
+      const count = Math.min(parseInt(options.limit, 10) || 20, 50);
+      const data = await run('youtube_list_videos', { count });
+      if (asJson()) { formatDetail(data, { format: 'json' }); return; }
+      const videos = data.result?.videos || [];
+      if (videos.length === 0) { printInfo('No videos returned.'); return; }
+      for (const v of videos) {
+        console.log(`${v.video_id}  ${v.title || '(no title)'}  [${v.privacy_status || 'unknown'}]`);
+        console.log(`  views: ${v.view_count ?? 0}  likes: ${v.like_count ?? 0}  comments: ${v.comment_count ?? 0}`);
+      }
+    });
+
+  youtube
+    .command('channel')
+    .description('Show the connected YouTube channel (also the cheapest live credential check).')
+    .action(async () => {
+      const data = await run('youtube_get_channel', {});
+      if (asJson()) { formatDetail(data, { format: 'json' }); return; }
+      const ch = data.result || {};
+      if (!ch.channel_id && !ch.title) { printInfo('No channel returned.'); return; }
+      console.log(`${ch.title || 'unknown'}  (${ch.channel_id || 'unknown'})`);
+      console.log(`  subscribers: ${ch.subscriber_count ?? 'unknown'}  videos: ${ch.video_count ?? 'unknown'}  views: ${ch.view_count ?? 'unknown'}`);
+    });
+
+  youtube
+    .command('analytics')
+    .description('Channel (or single video) analytics totals for the last 28 days.')
+    .option('--metrics <list>', 'comma-separated YouTube Analytics metric names (default views,estimatedMinutesWatched,averageViewDuration,likes,subscribersGained)')
+    .option('--video <id>', 'restrict to one video id')
+    .action(async (options) => {
+      const input = {};
+      if (options.metrics) input.metrics = options.metrics;
+      if (options.video) input.video_id = options.video;
+      const data = await run('youtube_get_analytics', input);
+      if (asJson()) { formatDetail(data, { format: 'json' }); return; }
+      const r = data.result || {};
+      const metrics = r.metrics || {};
+      const keys = Object.keys(metrics);
+      if (keys.length === 0) { printInfo('No analytics returned.'); return; }
+      console.log(`${r.start_date || '?'} to ${r.end_date || '?'}${r.video_id ? `  video ${r.video_id}` : ''}`);
+      for (const k of keys) console.log(`  ${k}: ${metrics[k]}`);
+      if (r.missing_metrics?.length) printWarning(`Not returned by YouTube: ${r.missing_metrics.join(', ')}`);
+    });
+
+  youtube
+    .command('comment')
+    .description('Reply to a comment thread. Files an owner approval card and returns immediately; never posts directly.')
+    .argument('<commentId>', 'comment thread id to reply to (the id of the top-level comment)')
+    .argument('<text>', 'reply text')
+    .action(async (parentId, text) => {
+      const data = await run('youtube_reply_comment', { parent_id: parentId, text });
+      if (asJson()) { formatDetail(data, { format: 'json' }); return; }
+      printAwaitingApproval('Comment reply', data);
+    });
+}

package/lib/core/actionItems.js

@@ -0,0 +1,115 @@
+/**
+ * Action Tracker item writes and open-item reads, shared by `quox actions
+ * add|done` and the Quox TUI /todo and /todos. One core, so chat, CLI and TUI
+ * create the same item through the same collector route
+ * (POST /api/v1/actions, PATCH /api/v1/actions/:id), as the logged-in user.
+ */
+
+import { resolveEndpoint } from '../api/endpoints.js';
+import { QuoxError } from './errors.js';
+
+export const PRIORITIES = ['low', 'medium', 'high', 'urgent'];
+const ISO_DAY = /^\d{4}-\d{2}-\d{2}$/;
+
+const pad = (n) => String(n).padStart(2, '0');
+const dayOf = (d) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+
+/** "today", "tomorrow" or YYYY-MM-DD -> YYYY-MM-DD. Anything else is a usage error, never guessed. */
+export function parseDue(value, now = new Date()) {
+  if (value === undefined || value === null || value === '') return null;
+  const v = String(value).trim().toLowerCase();
+  if (v === 'today') return dayOf(now);
+  if (v === 'tomorrow') return dayOf(new Date(now.getFullYear(), now.getMonth(), now.getDate() + 1));
+  if (ISO_DAY.test(v) && !Number.isNaN(Date.parse(`${v}T00:00:00Z`))) return v;
+  throw new QuoxError(`--due must be YYYY-MM-DD, today or tomorrow (got "${value}")`, 2);
+}
+
+/** Words typed after the verb -> a title. Empty or blank is a usage error. */
+export function titleFromWords(words) {
+  const title = (Array.isArray(words) ? words.join(' ') : String(words || '')).trim();
+  if (!title) throw new QuoxError('Usage: quox actions add <text...> [--due <date>] [--priority low|medium|high|urgent]', 2);
+  return title;
+}
+
+/** Throw unless the response carries an item with an id: an error body is never a created item. */
+function itemOf(res, what) {
+  const item = res && res.item;
+  if (!item || !item.id || res.success === false) {
+    throw new QuoxError(`${what} failed: ${(res && (res.error || res.message)) || 'the server returned no item'}`);
+  }
+  return item;
+}
+
+/** Create one Action Tracker item (status todo) as the logged-in user. -> the item. */
+export async function addActionItem(client, { title, due, priority, description } = {}) {
+  const t = titleFromWords(title);
+  if (priority && !PRIORITIES.includes(priority)) {
+    throw new QuoxError(`--priority must be one of ${PRIORITIES.join(', ')}`, 2);
+  }
+  const body = { title: t };
+  const dueDate = parseDue(due);
+  if (dueDate) body.due_date = dueDate;
+  if (priority) body.priority = priority;
+  if (description) body.description = description;
+  const ep = resolveEndpoint('actions.create');
+  return itemOf(await client.post(ep.path, { service: ep.service, body }), 'Adding the action item');
+}
+
+export const STATUS_COLUMNS = ['todo', 'doing', 'done'];
+
+/** Move one item to todo, doing or done. -> the item. */
+export async function moveActionItem(client, id, status) {
+  const clean = String(id || '').trim();
+  if (!clean) throw new QuoxError('Usage: quox actions move <id> <todo|doing|done>', 2);
+  if (!STATUS_COLUMNS.includes(status)) throw new QuoxError(`status must be one of ${STATUS_COLUMNS.join(', ')}`, 2);
+  const ep = resolveEndpoint('actions.update', { id: clean });
+  return itemOf(await client.patch(ep.path, { service: ep.service, body: { status } }), 'Moving the action item');
+}
+
+/** Mark one item done. -> the item. */
+export async function completeActionItem(client, id) {
+  if (!String(id || '').trim()) throw new QuoxError('Usage: quox actions done <id>', 2);
+  return moveActionItem(client, id, 'done');
+}
+
+/** Every item in one column (or all), paged to the end; never a silent cap. -> [{id,title,status,priority,due_date}]. */
+export async function listActionItems(client, status = 'all', { pageSize = 100, maxPages = 50 } = {}) {
+  const ep = resolveEndpoint('actions.list');
+  const out = [];
+  for (let page = 1; page <= maxPages; page++) {
+    const query = { limit: pageSize, page };
+    if (status !== 'all') query.status = status;
+    const res = await client.get(ep.path, { service: ep.service, query, retries: 0 });
+    if (!res || !Array.isArray(res.items)) {
+      throw new QuoxError(`Listing action items failed: ${(res && (res.error || res.message)) || 'unexpected response'}`);
+    }
+    out.push(...res.items);
+    if (!(res.pagination && res.pagination.has_more)) return out;
+  }
+  throw new QuoxError(`More than ${maxPages * pageSize} action items; narrow with quox actions list --status.`);
+}
+
+/** The board by column. -> { backlog (status todo), doing, done } each a full list. */
+export async function listBoard(client) {
+  const backlog = await listActionItems(client, 'todo');
+  const doing = await listActionItems(client, 'doing');
+  const done = await listActionItems(client, 'done');
+  return { backlog, doing, done };
+}
+
+/** Open items (todo then doing), all of them. */
+export async function listOpenActionItems(client) {
+  return [...(await listActionItems(client, 'todo')), ...(await listActionItems(client, 'doing'))];
+}
+
+/** Delete one item (server soft-deletes; creator or admin only). Checks the status before trusting the body. -> { id, title }. */
+export async function deleteActionItem(client, id) {
+  const clean = String(id || '').trim();
+  if (!clean) throw new QuoxError('Usage: quox actions delete <id> --yes', 2);
+  const ep = resolveEndpoint('actions.delete', { id: clean });
+  const res = await client.delete(ep.path, { service: ep.service });
+  if (!res || res.success === false || res.deleted !== true) {
+    throw new QuoxError(`Deleting the action item failed: ${(res && (res.error || res.message)) || 'the server did not confirm the delete'}`);
+  }
+  return { id: clean, title: res.title || '' };
+}

package/lib/core/agentAlias.js

@@ -58,6 +58,8 @@ export function loadBundledAssistantsRoster(dir = DEFAULT_ASSISTANTS_DIR) {
           id: raw.id,
           name: raw.identity?.name || null,
           shortName: raw.identity?.shortName || null,
+          // AGENT-TAXONOMY: present only when the file declares one.
+          ...(raw.family ? { family: raw.family } : {}),
         });
       }
     } catch {

package/lib/core/agentFamilies.js

@@ -0,0 +1,7 @@
+// Agent family ids, mirrored from src/config/agentFamilies.js (the authority).
+// The published CLI does not ship src/config, so it keeps this copy;
+// cli/test/core/agentFamilies.test.js fails if the two drift.
+export const AGENT_FAMILY_IDS = [
+  'command', 'devops', 'monitoring', 'secops', 'development',
+  'assistantq', 'knowledge', 'marketing', 'voice', 'governance',
+];

package/lib/core/announce.js

@@ -0,0 +1,86 @@
+/**
+ * announce: the ONE renderer CLI verbs use to say "Quox did something".
+ *
+ * Owner order 2026-10-29: if anything Quox happens, it announces. A verb that
+ * writes or governs prints exactly one QuoxGlyph line:
+ *   <icon> NAME │ <verb object> │ <result>[ · <duration>] <status>
+ * built on core/quoxglyph.js (the canonical grammar), never hand-typed.
+ *
+ * Output rules:
+ *  - stderr, not stdout: scripted stdout (tables, ids, --json) is byte-for-byte unchanged;
+ *  - silent under --json / --quiet;
+ *  - brand-gradient name only when stderr is a TTY, plain when piped or redirected.
+ */
+
+import { line } from './quoxglyph.js';
+import { getOutputFormat } from './output.js';
+
+// eslint-disable-next-line no-control-regex
+const ANSI = /\x1b\[[0-9;]*m/g;
+
+function errMessage(err) {
+  if (!err) return 'failed';
+  const body = err.body && (err.body.message || err.body.error);
+  return String(body || err.message || err).replace(/\s+/g, ' ').trim();
+}
+
+/** Render without printing. opts: {result, ms, status} (status defaults to ok). */
+export function renderAnnounce(surface, verb, opts = {}) {
+  let s = line(surface, verb, { status: 'ok', ...opts });
+  if (!(process.stderr && process.stderr.isTTY)) s = s.replace(ANSI, '');
+  return tidy(s);
+}
+
+// No result: the grammar's third field is just the status glyph (avoid a double space after the separator).
+const tidy = (s) => s.replace(/│ {2}(?=\S)/, '│ ');
+
+export function announceMuted() { return muted(); }
+function muted() {
+  const f = getOutputFormat();
+  return f === 'json' || f === 'quiet';
+}
+
+/** Print one announce line to stderr. Returns the rendered line (or null when muted). */
+export function announce(surface, verb, opts = {}) {
+  if (muted()) return null;
+  const s = renderAnnounce(surface, verb, opts);
+  process.stderr.write(`${s}\n`);
+  return s;
+}
+
+/** The failure twin: one line, status fail, reason as the result. */
+export function announceFailure(surface, verb, err) {
+  if (err && typeof err === 'object') { try { Object.defineProperty(err, 'quoxAnnounced', { value: true, configurable: true }); } catch { /* frozen */ } }
+  return announce(surface, verb, { result: errMessage(err), status: 'fail' });
+}
+
+/**
+ * Command-level wrapper: a verb whose SUCCESS announces itself inline gets its FAILURE exit announced here, once, so
+ * every exit (return or throw) of the verb prints exactly one QuoxGlyph line. `verb` is a string, or a function of the
+ * action's arguments. An error already announced (by an inner announceFailure) is not announced twice.
+ */
+export function announceOnFail(surface, verb, fn) {
+  return async (...args) => {
+    try { return await fn(...args); } catch (err) {
+      if (err && typeof err === 'object' && !err.quoxAnnounced) {
+        announceFailure(surface, typeof verb === 'function' ? verb(...args) : verb, err);
+      } else if (!err || typeof err !== 'object') announceFailure(surface, typeof verb === 'function' ? verb(...args) : verb, err);
+      throw err;
+    }
+  };
+}
+
+// quox_event statuses arrive as QuoxGlyph status names (ok fail busy warn block).
+const EVENT_STATUS = new Set(['ok', 'fail', 'busy', 'warn', 'block']);
+
+/**
+ * The plain (no ANSI) QuoxGlyph line for a collector `quox_event` frame, so the TUI transcript
+ * and `--print` render a turn's Quox effects with the SAME renderer the verbs use.
+ * Returns null for a frame with nothing to say.
+ */
+export function eventLine(ev) {
+  if (!ev || typeof ev !== 'object' || !ev.verb) return null;
+  const surface = String(ev.surface || 'quox').toLowerCase().replace(/[^a-z0-9_-]/g, '') || 'quox';
+  const status = EVENT_STATUS.has(ev.status) ? ev.status : 'ok';
+  return tidy(line(surface, String(ev.verb), { status, ...(ev.result ? { result: String(ev.result) } : {}) }).replace(ANSI, ''));
+}

package/lib/core/auth.js

@@ -7,6 +7,7 @@
 
 import { readFileSync, statSync, openSync, closeSync, unlinkSync } from 'node:fs';
 import { QuoxAuthError, QuoxApiError, QuoxTransientAuthError } from './errors.js';
+import { rateLimitHint, retryAfterMsFrom } from './loginGuard.js';
 import { loadResidentProfile, residentLogin, resolveResidentBaseUrl } from './residentAuth.js';
 
 // A resident agent has no refresh token: its expired-access-token seam is
@@ -159,6 +160,17 @@ async function acquireRefreshLock(file, { staleMs = 20000, waitMs = 20000 } = {}
   }
 }
 
+// H4: tag a failed bare fetch with the server and profile so the central error mapping can name the exact
+// `quox connect` command when the cause is a certificate this machine does not trust.
+async function fetchTagged(config, baseUrl, url, opts) {
+  try { return await fetch(url, opts); } catch (e) {
+    if (e && typeof e === 'object') {
+      try { e.quoxUrl = baseUrl; e.quoxProfile = config?.getActiveProfileName?.(); } catch { /* tagging is best effort */ }
+    }
+    throw e;
+  }
+}
+
 export function createAuth(config) {
   return {
     async login(baseUrl, email, password, orgId) {
@@ -170,7 +182,7 @@ export function createAuth(config) {
       const body = { email, password, client: 'cli' };
       if (orgId) body.org_id = orgId;
 
-      const res = await fetch(url, {
+      const res = await fetchTagged(config, baseUrl, url, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify(body),
@@ -179,6 +191,12 @@ export function createAuth(config) {
       const data = await res.json();
 
       if (!res.ok) {
+        if (res.status === 429) {
+          const retryAfterMs = retryAfterMsFrom(res, data);
+          const err = new QuoxApiError(429, data.error, rateLimitHint({ retryAfterMs }));
+          err.retryAfterMs = retryAfterMs;
+          throw err;
+        }
         throw new QuoxApiError(res.status, data.error, data.message || 'Login failed');
       }
 
@@ -204,7 +222,7 @@ export function createAuth(config) {
 
     async verifyMfa(baseUrl, token, code) {
       const url = `${baseUrl}/api/mfa/verify`;
-      const res = await fetch(url, {
+      const res = await fetchTagged(config, baseUrl, url, {
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',

package/lib/core/callMe.js

@@ -0,0 +1,118 @@
+/**
+ * callMe: the shared core behind `quox approvals call-me` and the TUI
+ * /callmeforapprovals. It reads and flips the ApprovalsQ call-me policy (the
+ * switch for the watcher that phones a human when a high-risk approval sits
+ * unanswered). The server route is human-org-admin only; agent identities and
+ * service keys are refused there, and every write is audited (AEE).
+ *
+ * It NEVER approves or denies anything. on/off flip `enabled` only (plus the
+ * optional --after / --quiet knobs); every other stored field is preserved.
+ */
+
+import { resolveEndpoint } from '../api/endpoints.js';
+import { QuoxUserError } from './errors.js';
+
+const HHMM = /^(\d{1,2}):(\d{2})$/;
+const ok = (s) => { const m = HHMM.exec(s); return Boolean(m && Number(m[1]) <= 23 && Number(m[2]) <= 59); };
+
+/** "22:00-08:00" -> { start, end }, or throws a QuoxUserError naming the fix. */
+export function parseQuiet(text) {
+  const m = /^(\d{1,2}:\d{2})\s*-\s*(\d{1,2}:\d{2})$/.exec(String(text || '').trim());
+  if (!m || !ok(m[1]) || !ok(m[2])) {
+    throw new QuoxUserError(`--quiet must look like 22:00-08:00 (got "${text}")`, { code: 'bad_quiet_hours' });
+  }
+  return { start: m[1], end: m[2] };
+}
+
+/** --after <minutes>: integer 1-1440, or throws. */
+export function parseAfter(text) {
+  const n = Number(text);
+  if (!Number.isInteger(n) || n < 1 || n > 1440) {
+    throw new QuoxUserError(`--after must be whole minutes between 1 and 1440 (got "${text}")`, { code: 'bad_after' });
+  }
+  return n;
+}
+
+/** Build the PUT body for an action (on|off) plus options { after, quiet }. */
+export function buildChange(action, { after, quiet } = {}) {
+  if (action !== 'on' && action !== 'off') {
+    throw new QuoxUserError(`Unknown action "${action}". Use status, on or off.`, { code: 'bad_action' });
+  }
+  const body = { enabled: action === 'on' };
+  if (after !== undefined && after !== null && after !== '') body.age_threshold_minutes = parseAfter(after);
+  if (quiet) body.quiet_hours = parseQuiet(quiet);
+  return body;
+}
+
+/** One honest line about the watcher. Unknown is said as unknown, never guessed as alive. */
+export function watcherLine(w) {
+  if (!w || typeof w !== 'object') return 'watcher: unknown (the server did not report it)';
+  if (w.running === false) {
+    return w.reason === 'env_flag_off'
+      ? 'watcher: NOT RUNNING (QUOX_APPROVALSQ_WATCHER is off on the collector, so no call will be placed)'
+      : 'watcher: NOT RUNNING (it did not start, so no call will be placed)';
+  }
+  if (w.running === true) {
+    if (!w.last_tick_at) return 'watcher: started, no check completed yet';
+    const tail = w.stale ? ' STALE, it has stopped checking' : (w.last_tick_ok === false ? ' (last check had errors)' : '');
+    return `watcher: alive, last check ${w.last_tick_at}${tail}`;
+  }
+  return 'watcher: unknown (the server did not report it)';
+}
+
+/** Human-readable status lines from a { policy, watcher } response. */
+export function statusLines(data) {
+  const p = (data && data.policy) || {};
+  const q = p.quiet_hours || {};
+  const lines = [
+    `call me for approvals: ${p.enabled ? 'ON' : 'OFF'}`,
+    `rings after: ${p.age_threshold_minutes} min unanswered`,
+    `quiet hours: ${q.start}-${q.end} ${q.timezone || ''}`.trimEnd(),
+    `min tier: ${p.min_tier}`,
+    watcherLine(data && data.watcher),
+  ];
+  if (p.enabled && p.destination_configured === false) lines.push('calls go to: the owner mobile (QuoxVoice default; no destination number set on this policy)');
+  return lines;
+}
+
+/** Plain-words refusal for a 401/403 from the server. */
+function refusal(e) {
+  if (e && e.status === 402) {
+    return new QuoxUserError('QuoxVoice is not licensed for this org, so call-me for approvals is unavailable.', { code: 'license_required', status: 402 });
+  }
+  if (e && (e.status === 403 || e.status === 401)) {
+    return new QuoxUserError('Only a signed-in human org admin can change or read the call-me policy. Agent identities and service keys are refused.', { code: 'admin_only', status: e.status });
+  }
+  return e;
+}
+
+export async function getCallMe(client) {
+  const ep = resolveEndpoint('v1.approvals.call-me.get');
+  try { return await client.get(ep.path, { service: ep.service, retries: 0 }); } catch (e) { throw refusal(e); }
+}
+
+export async function setCallMe(client, change) {
+  const ep = resolveEndpoint('v1.approvals.call-me.put');
+  try { return await client.put(ep.path, { service: ep.service, body: change, retries: 0 }); } catch (e) { throw refusal(e); }
+}
+
+/** Parse TUI args: "[on|off|status] [--after N] [--quiet HH:MM-HH:MM]" -> { action, after, quiet }. */
+export function parseSlashArgs(text) {
+  const toks = String(text || '').trim().split(/\s+/).filter(Boolean);
+  const out = { action: 'status' };
+  for (let i = 0; i < toks.length; i++) {
+    const t = toks[i];
+    if (t === 'on' || t === 'off' || t === 'status') out.action = t;
+    else if (t === '--after') out.after = toks[++i];
+    else if (t === '--quiet') out.quiet = toks[++i];
+    else throw new QuoxUserError(`Unknown argument "${t}". Usage: /callmeforapprovals [on|off|status] [--after <minutes>] [--quiet HH:MM-HH:MM]`, { code: 'bad_args' });
+  }
+  return out;
+}
+
+/** Run an action end to end -> { data, changed }. status reads; on/off write. */
+export async function runCallMe(client, { action = 'status', after, quiet } = {}) {
+  if (action === 'status') return { data: await getCallMe(client), changed: false };
+  const body = buildChange(action, { after, quiet });
+  return { data: await setCallMe(client, body), changed: true };
+}