@aria-framework/ask 0.0.0-stage → 0.1.1

package/lib/store.js

@@ -0,0 +1,218 @@
+/**
+ * THE QUESTION MODEL — a factory over the two reference tables (lib/schema.js), for the app's worker registry:
+ *
+ *   // models/AskQuestion.js
+ *   module.exports = require('@aria-framework/ask').createAskQuestionModel({
+ *     driver: () => require('../lib/database').driver(),   // READ PER CALL — never captured at require time
+ *     sql: require('../lib/sql'),                          // returningId(), andTenant(), now()
+ *     publicId: () => publicId('ask_question'),
+ *     currentTenant: require('@aria-framework/db-worker').currentTenant
+ *   });
+ *
+ * Extracted from the hub's and soc's models/AskQuestion.js — the same SQL, plus Soc's `closeStale`.
+ *
+ * WHOSE ROWS. Both tables are PARTNER-scoped by the app's generated tenancy migration: a question lands in the partner it
+ * was ASKED IN. No method sets `partner_id`; the column defaults from the session.
+ *
+ * THE ASKER'S OWN ROWS SPAN PARTNERS, and that is the one widening: the reads keyed on the asker — countSince, historyFor,
+ * historyCountFor, oneFor, rate — run at PLATFORM scope and REFUSE any other, and every one is bounded by `asked_by = ?`,
+ * which the caller takes from the principal, never from the request. The review list, markReviewed, purgeBefore and
+ * closeStale are the platform's alone for the same reason. partnerTokensSince STATES THE TENANT (sql.andTenant).
+ *
+ * `partners` is the app's table (id, name, is_house), joined for the partner a question was asked in.
+ */
+
+'use strict';
+
+const OUTCOMES = Object.freeze(['working', 'answered', 'withheld', 'not_found', 'refused_write', 'cannot', 'busy', 'off', 'error']);
+const CALL_OUTCOMES = Object.freeze(['ok', 'not_found', 'ambiguous', 'error']);
+const REASONS = Object.freeze(['wrong_figure', 'wrong_record', 'no_answer', 'other']);
+const UTC = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/;
+
+const intOf = (v) => Math.max(0, Math.trunc(Number(v)) || 0);
+const json = (v) => (v == null ? null : JSON.stringify(v));
+const parse = (t) => { if (t == null || t === '') return null; try { return JSON.parse(t); } catch (_) { return null; } };
+
+function hydrate(r) {
+  if (!r) return null;
+  return {
+    ...r,
+    id: Number(r.id),
+    partner_id: r.partner_id == null ? null : Number(r.partner_id),
+    asked_by: Number(r.asked_by),
+    acting: Number(r.acting) === 1,
+    tokens: Number(r.tokens) || 0,
+    ms: Number(r.ms) || 0,
+    rating: r.rating == null ? null : Number(r.rating),
+    result: parse(r.result)
+  };
+}
+
+/**
+ * @param {object} o
+ * @param {Function} o.driver          () → the db-worker driver (get/all/run)
+ * @param {object} [o.sql]             { returningId(), andTenant(), now() } — returningId and now default to the driver's
+ *                                     dialect; andTenant is the APP's (it knows its tenant expression) and is required
+ * @param {Function} o.publicId        () → a new ask_question public id
+ * @param {Function} o.currentTenant   () → { scope, partnerId } | null (db-worker's)
+ */
+function createAskQuestionModel(o) {
+  if (typeof o.driver !== 'function') throw new Error('ask model: driver must be a FUNCTION returning the driver (read per call)');
+  if (typeof o.publicId !== 'function') throw new Error('ask model: publicId() is required');
+  if (typeof o.currentTenant !== 'function') throw new Error('ask model: currentTenant() is required');
+  if (!o.sql || typeof o.sql.andTenant !== 'function') throw new Error('ask model: sql.andTenant() is required (the app states its tenant)');
+  const d = () => o.driver();
+  const returningId = () => (o.sql.returningId ? o.sql.returningId() : (d().dialect && d().dialect.returning ? d().dialect.returning('id') : ''));
+  const now = () => (o.sql.now ? o.sql.now() : d().dialect.now());
+  const platformOnly = (fn, why) => {
+    const t = o.currentTenant();
+    if (!t || t.scope !== 'platform') {
+      throw new Error(`AskQuestion.${fn} must run at PLATFORM scope — ${why} (it was called at ${t ? `scope "${t.scope}"` : 'no scope'})`);
+    }
+  };
+  const SPANS = 'one person\'s questions span partners';
+  const FLEET = 'the review list spans every partner';
+  const WIDE = 'retention is installation-wide';
+
+  return {
+    OUTCOMES, CALL_OUTCOMES, REASONS,
+
+    /** Open the row — outcome `working` until `finish`. Written BEFORE the model is called. */
+    async open({ asked_by, asked_by_name, acting = false, context_kind = null, context_ref = null, question, prompt_hash = null }) {
+      const ref = o.publicId();
+      const r = await d().run(
+        `INSERT INTO ask_questions (public_id, asked_by, asked_by_name, acting, context_kind, context_ref, question, outcome, prompt_hash)
+         VALUES (?, ?, ?, ?, ?, ?, ?, 'working', ?)${returningId()}`,
+        [ref, Number(asked_by), String(asked_by_name).slice(0, 250), acting ? 1 : 0, context_kind, context_ref,
+          String(question), prompt_hash]);
+      return { id: Number(r.lastId), public_id: ref };
+    },
+
+    /** One look-up, as it ran. `args` is the VALIDATED argument object, never the model's raw text. */
+    async addCall(question_id, { position, tool, args, outcome, row_count = 0, ms = 0 }) {
+      if (!CALL_OUTCOMES.includes(outcome)) throw new TypeError(`AskQuestion.addCall: unknown outcome ${JSON.stringify(outcome)}`);
+      await d().run(
+        'INSERT INTO ask_tool_calls (question_id, position, tool, args, outcome, row_count, ms) VALUES (?, ?, ?, ?, ?, ?, ?)',
+        [Number(question_id), intOf(position), String(tool), JSON.stringify(args || {}), outcome, intOf(row_count), intOf(ms)]);
+    },
+
+    /** Close the row: what came of the question, the answer as shown, and who served it. */
+    async finish(id, { outcome, answer = null, result = null, endpoint = null, model = null, tokens = 0, ms = 0 }) {
+      if (!OUTCOMES.includes(outcome) || outcome === 'working') throw new TypeError(`AskQuestion.finish: unknown outcome ${JSON.stringify(outcome)}`);
+      await d().run(
+        'UPDATE ask_questions SET outcome = ?, answer = ?, result = ?, endpoint = ?, model = ?, tokens = ?, ms = ? WHERE id = ?',
+        [outcome, answer == null ? null : String(answer).slice(0, 4000), json(result), endpoint, model, intOf(tokens), intOf(ms), Number(id)]);
+    },
+
+    /** How many questions this person asked since a UTC instant, in EVERY partner. PLATFORM ONLY, bounded by asked_by. */
+    async countSince(asked_by, since) {
+      platformOnly('countSince', SPANS);
+      const r = await d().get('SELECT COUNT(*) AS n FROM ask_questions WHERE asked_by = ? AND created_at >= ?', [Number(asked_by), String(since)]);
+      return Number((r && r.n) || 0);
+    },
+
+    /** Tokens spent on questions asked in THIS tenant since a UTC instant — the per-partner budget. */
+    async partnerTokensSince(since) {
+      const r = await d().get(
+        `SELECT CAST(COALESCE(SUM(tokens), 0) AS BIGINT) AS n FROM ask_questions WHERE created_at >= ?${o.sql.andTenant()}`, [String(since)]);
+      return Number((r && r.n) || 0);
+    },
+
+    /** This person's last questions, newest first, with the partner each was asked in. PLATFORM ONLY. */
+    async historyFor(asked_by, { limit = 20 } = {}) {
+      platformOnly('historyFor', SPANS);
+      const n = Math.min(Math.max(intOf(limit), 1), 50);
+      const rows = await d().all(
+        `SELECT q.id, q.public_id, q.partner_id, p.name AS partner_name, q.acting, q.context_kind, q.context_ref, q.question,
+                q.outcome, q.rating, q.created_at
+           FROM ask_questions q
+           JOIN partners p ON p.id = q.partner_id
+          WHERE q.asked_by = ? AND q.outcome <> 'working'
+          ORDER BY q.created_at DESC, q.id DESC
+          LIMIT ?`, [Number(asked_by), n]);
+      return rows.map(hydrate);
+    },
+
+    /** How many finished questions this person has on record. PLATFORM ONLY. */
+    async historyCountFor(asked_by) {
+      platformOnly('historyCountFor', SPANS);
+      const r = await d().get("SELECT COUNT(*) AS n FROM ask_questions WHERE asked_by = ? AND outcome <> 'working'", [Number(asked_by)]);
+      return Number((r && r.n) || 0);
+    },
+
+    /** One of this person's questions by its ref, with its look-ups — or null (anybody else's reads as none). */
+    async oneFor(asked_by, ref) {
+      platformOnly('oneFor', SPANS);
+      const q = hydrate(await d().get(
+        `SELECT q.*, p.name AS partner_name FROM ask_questions q JOIN partners p ON p.id = q.partner_id
+          WHERE q.public_id = ? AND q.asked_by = ?`, [String(ref), Number(asked_by)]));
+      if (!q) return null;
+      q.calls = await d().all('SELECT position, tool, args, outcome, row_count, ms FROM ask_tool_calls WHERE question_id = ? ORDER BY position, id', [q.id]);
+      return q;
+    },
+
+    /** The asker's thumbs mark on one of THEIR questions. Returns whether a row changed. PLATFORM ONLY. */
+    async rate(asked_by, ref, { rating, reason = null, text = null }) {
+      platformOnly('rate', SPANS);
+      if (rating !== 1 && rating !== -1) throw new TypeError('AskQuestion.rate: rating is 1 or -1');
+      if (reason != null && !REASONS.includes(reason)) throw new TypeError(`AskQuestion.rate: unknown reason ${JSON.stringify(reason)}`);
+      const r = await d().run(
+        `UPDATE ask_questions SET rating = ?, feedback_reason = ?, feedback_text = ?, reviewed_at = NULL
+          WHERE public_id = ? AND asked_by = ? AND outcome <> 'working'`,
+        [rating, rating === -1 ? reason : null, rating === -1 && text ? String(text).slice(0, 300) : null, String(ref), Number(asked_by)]);
+      return Number(r.changes || 0) > 0;
+    },
+
+    /** The thumbs-down list, newest first, with each row's look-ups. PLATFORM ONLY. */
+    async reviewList({ state = 'open', partner_id = null, reason = null, limit = 200 } = {}) {
+      platformOnly('reviewList', FLEET);
+      const where = ['q.rating = -1'];
+      const params = [];
+      if (state === 'open') where.push('q.reviewed_at IS NULL');
+      else if (state === 'reviewed') where.push('q.reviewed_at IS NOT NULL');
+      if (partner_id != null) { where.push('q.partner_id = ?'); params.push(Number(partner_id)); }
+      if (reason != null) {
+        if (!REASONS.includes(reason)) throw new TypeError(`AskQuestion.reviewList: unknown reason ${JSON.stringify(reason)}`);
+        where.push('q.feedback_reason = ?'); params.push(reason);
+      }
+      const n = Math.min(Math.max(intOf(limit), 1), 500);
+      const rows = (await d().all(
+        `SELECT q.*, p.name AS partner_name, p.is_house AS partner_is_house
+           FROM ask_questions q JOIN partners p ON p.id = q.partner_id
+          WHERE ${where.join(' AND ')}
+          ORDER BY q.created_at DESC, q.id DESC
+          LIMIT ?`, [...params, n])).map(hydrate);
+      if (!rows.length) return rows;
+      const calls = await d().all(
+        `SELECT question_id, position, tool, args, outcome, row_count, ms FROM ask_tool_calls
+          WHERE question_id IN (${rows.map(() => '?').join(', ')}) ORDER BY question_id, position, id`, rows.map((r) => r.id));
+      for (const r of rows) r.calls = calls.filter((c) => Number(c.question_id) === r.id);
+      return rows;
+    },
+
+    /** Mark one thumbs-down answer reviewed. PLATFORM ONLY. Returns whether a row changed. */
+    async markReviewed(ref) {
+      platformOnly('markReviewed', FLEET);
+      const r = await d().run(`UPDATE ask_questions SET reviewed_at = ${now()} WHERE public_id = ? AND rating = -1 AND reviewed_at IS NULL`, [String(ref)]);
+      return Number(r.changes || 0) > 0;
+    },
+
+    /** RETENTION: delete every question created before `cut` (UTC), in every partner; look-ups cascade. PLATFORM ONLY. */
+    async purgeBefore(cut) {
+      platformOnly('purgeBefore', WIDE);
+      if (!UTC.test(String(cut))) throw new TypeError('AskQuestion.purgeBefore: cut is YYYY-MM-DD HH:MM:SS (UTC)');
+      const r = await d().run('DELETE FROM ask_questions WHERE created_at < ?', [String(cut)]);
+      return Number(r.changes || 0);
+    },
+
+    /** THE BOUND ON A STUCK ROW: close every `working` row opened before `cut` as `error`. PLATFORM ONLY. */
+    async closeStale(cut) {
+      platformOnly('closeStale', WIDE);
+      if (!UTC.test(String(cut))) throw new TypeError('AskQuestion.closeStale: cut is YYYY-MM-DD HH:MM:SS (UTC)');
+      const r = await d().run("UPDATE ask_questions SET outcome = 'error' WHERE outcome = 'working' AND created_at < ?", [String(cut)]);
+      return Number(r.changes || 0);
+    }
+  };
+}
+
+module.exports = { createAskQuestionModel, OUTCOMES, CALL_OUTCOMES, REASONS };

package/lib/stream.js

@@ -0,0 +1,58 @@
+/**
+ * THE ANSWER STREAM, VERSION `ask/1` (D-0169 item 8: written down now, so a later remote Ask returns exactly this).
+ *
+ * POST /ask answers with NDJSON — one JSON object per line, in this order:
+ *
+ *   { type: 'start',   v: 'ask/1', reading }                 the asker's own reading, never anything about the context
+ *   { type: 'step',    n, words, state: 'run' | 'done' }     0 = planning; 1…4 = each look-up; last = writing the answer
+ *   { type: 'answer',  answer: <render model> }              FINAL — run.js's render model (below)
+ *   { type: 'refused', kind?, text, resets? }                FINAL, and the ONLY line (a 429 before any stream opened)
+ *   { type: 'error',   text }                                FINAL — the question failed past what run.js answers for
+ *
+ * THE RENDER MODEL: { outcome, by: 'ai' | 'fixed', text?, segments?, chips, quotes?, lookups, provenance, ref, question,
+ * context, reading, at, why?, whyCode?, checked?, link? }. Every href in it is APP-RELATIVE ('/customers/12'): a caller
+ * drawing another app's answer prefixes the service's own base URL from the registry. Chips stay app-drawn, so "no model
+ * links" holds across apps: a remote answer's words are drawn as text and its chips as that app's links.
+ *
+ * The `v` on the start line is new in the package; the apps' drawers ignore unknown keys, so adding it changes nothing
+ * they draw.
+ */
+
+'use strict';
+
+const STREAM_VERSION = 'ask/1';
+const TYPES = Object.freeze(['start', 'step', 'answer', 'refused', 'error']);
+const FINAL = Object.freeze(['answer', 'refused', 'error']);
+
+const line = (o) => `${JSON.stringify(o)}\n`;
+const start = (reading) => ({ type: 'start', v: STREAM_VERSION, reading: reading == null ? null : String(reading) });
+const step = (s) => ({ type: 'step', n: s.n, words: s.words, state: s.state });
+const answer = (a) => ({ type: 'answer', answer: a });
+const refused = (r) => ({ type: 'refused', ...(r.kind ? { kind: r.kind } : {}), text: r.text, ...(r.resets ? { resets: r.resets } : {}) });
+const error = (text) => ({ type: 'error', text });
+
+/**
+ * Read one line of an `ask/1` stream. Returns the object, or throws a sentence saying what is wrong — a caller drawing a
+ * remote app's stream refuses anything that is not this contract instead of guessing.
+ */
+function parseLine(text) {
+  let o;
+  try { o = JSON.parse(String(text)); } catch (_) { throw new Error('ask/1: a line is not JSON'); }
+  if (!o || typeof o !== 'object' || Array.isArray(o) || !TYPES.includes(o.type)) throw new Error('ask/1: a line has no known type');
+  if (o.type === 'start' && o.v !== undefined && o.v !== STREAM_VERSION) throw new Error(`ask/1: the stream is ${String(o.v).slice(0, 20)}, not ${STREAM_VERSION}`);
+  if (o.type === 'step' && (!Number.isInteger(o.n) || typeof o.words !== 'string' || !['run', 'done'].includes(o.state))) throw new Error('ask/1: a step line is malformed');
+  if (o.type === 'answer' && (!o.answer || typeof o.answer !== 'object' || typeof o.answer.outcome !== 'string')) throw new Error('ask/1: an answer line has no render model');
+  if ((o.type === 'refused' || o.type === 'error') && typeof o.text !== 'string') throw new Error(`ask/1: a ${o.type} line has no text`);
+  return o;
+}
+
+/** A whole stream's text → its lines, checked: one start (unless refused alone), steps, exactly one final line, last. */
+function parseStream(text) {
+  const lines = String(text).split('\n').filter((l) => l.trim()).map(parseLine);
+  const finals = lines.filter((l) => FINAL.includes(l.type));
+  if (finals.length !== 1 || !FINAL.includes(lines[lines.length - 1].type)) throw new Error('ask/1: a stream ends with exactly one final line');
+  if (lines[0].type !== 'start' && !(lines.length === 1 && lines[0].type === 'refused')) throw new Error('ask/1: a stream opens with its start line');
+  return lines;
+}
+
+module.exports = { STREAM_VERSION, TYPES, FINAL, line, start, step, answer, refused, error, parseLine, parseStream };

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@aria-framework/ask",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Aria App Framework — ask module. \"Ask anything\": a read-only question box over an app's own records — plan, run the app's tools in the asker's own request, answer from fenced results, check every figure and link, audit. Ships the loop, the answer check, the bench, canonical settings, the question model factory, a reference table design with its generator and check, the ask/1 stream, route factories, views and the drawer script. The app supplies its tools and words.",
+  "license": "UNLICENSED",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "index.js",
+  "bin": {
+    "ask-migration": "bin/ask-migration.js"
+  },
+  "files": [
+    "index.js",
+    "lib/",
+    "bin/",
+    "views/",
+    "assets/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "peerDependencies": {
+    "@aria-framework/ai": ">=0.19.0",
+    "@aria-framework/db-worker": ">=0.19.0"
+  },
+  "peerDependenciesMeta": {
+    "@aria-framework/db-worker": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "^0.5.8",
+    "better-sqlite3": "^12.10.0",
+    "ejs": "^6.0.1",
+    "express": "^5.2.1",
+    "jsdom": "^30.0.1"
+  },
+  "scripts": {
+    "test": "node test/run.js",
+    "prepublishOnly": "node ../../test/packaging.js ask"
+  }
+}

package/views/ask/admin.ejs

@@ -0,0 +1,153 @@
+<%# ASK SETTINGS (@aria-framework/ask). Platform only — ai_config.view to see, ai_config.edit to change. What the route is,
+    what gates it (the bench), which machines serve it and in what order, the limits, retention and the tools. Every
+    label and help line is the package's CANONICAL wording (lib/settings.js CANON, D-0169 item 5) — the same in every
+    app. Every change is audited as ai_config.ask_settings. App locals used: can, csrfToken, exactTag; askLayout and
+    askAdminBase are optional. %>
+<% var _L = (typeof askLayout !== 'undefined' && askLayout) ? askLayout : { head: 'partials/staff-head', tabs: 'partials/admin-tabs', foot: 'partials/staff-foot' }; %>
+<% var _base = (typeof askAdminBase === 'string' && askAdminBase) ? askAdminBase : '/admin/ai/ask'; %>
+<% var _c = {}; canon.forEach(function (x) { _c[x.field] = x; }); %>
+<%- include(_L.head) %>
+
+  <%- include(_L.tabs) %>
+
+  <% var _can = (typeof can === 'function') ? can : function () { return false; }; %>
+  <% var _edit = _can('ai_config.edit'); %>
+  <% var _err = errors || {}; %>
+  <% var _tag = (typeof exactTag === 'function') ? exactTag : function (v) { return String(v == null ? '' : v).replace(/[&<>"']/g, function (ch) { return '&#' + ch.charCodeAt(0) + ';'; }); }; %>
+
+  <form method="POST" action="<%= _base %>">
+    <input type="hidden" name="_csrf" value="<%= csrfToken() %>">
+
+    <div class="card mb-3"><div class="card-body">
+      <div class="d-flex align-items-center gap-2 flex-wrap">
+        <h6 class="card-title mb-0 flex-grow-1">Ask</h6>
+        <div class="form-check form-switch mb-0">
+          <input class="form-check-input" type="checkbox" role="switch" id="ask-enabled" name="enabled" <%= ask.enabled ? 'checked' : '' %> <%= _edit ? '' : 'disabled' %>>
+          <label class="form-check-label" for="ask-enabled"><%= _c.enabled.label %></label>
+        </div>
+      </div>
+      <p class="text-body-secondary small mt-2 mb-2"><%= _c.enabled.help %></p>
+      <% if (invalid && invalid.length) { %>
+        <div class="alert alert-warning small">A stored Ask setting could not be read (<%= invalid.join(', ') %>), so its default is in force. Saving this form replaces it.</div>
+      <% } %>
+
+      <div id="ask-bench-live" data-live-topic="ask-bench:house">
+      <% if (failingControls && failingControls.length) { %>
+        <div class="alert alert-danger small mb-2" data-failing-controls><strong>Ask is off: a bench control no longer holds</strong> (<%= failingControls.join(', ') %>). The app's own fences changed since the bench; every endpoint is refused until they hold again.</div>
+      <% } %>
+      <% if (record) { %>
+        <% var _passed = endpoints.filter(function (e) { return e.bench && e.bench.passed; }); %>
+        <% var _refused = !!(failingControls && failingControls.length); %>
+        <div class="alert <%= _passed.length && !_refused ? 'alert-success' : 'alert-warning' %> small mb-2">
+          <% if (_passed.length && _refused) { %><strong>The stored bench passed, but the gate refuses it now</strong> — on<% } else if (_passed.length) { %><strong>Ask bench passed</strong> on <%= _passed.map(function (e) { return e.label; }).join(', ') %><% } else { %><strong>No endpoint has passed the ask bench</strong><% } %>
+          · run <%- _tag(record.at) %> · <%= record.cases %> injections, <%= record.controls %> controls, for prompt <code><%= hash.slice(0, 4) %>…<%= hash.slice(-4) %></code>.
+          The gate is binding: change the prompt, the tools or the scoring and the route stays off until the bench passes again.
+        </div>
+      <% } else { %>
+        <div class="alert alert-warning small mb-2">
+          <strong>The ask bench has not passed for the current prompt</strong><% if (staleRecord) { %> (the stored record is for an earlier prompt or tool list, or was scored the old way)<% } %>,
+          so Ask stays off for everyone — the box says “AI assistance is switched off”. <%= corpusSize %> injections and <%= controlsSize %> controls;
+          an endpoint passes at <%= passRate %> % resisted with every control held.
+        </div>
+      <% } %>
+      <% if (benchState.running) { %>
+        <p class="small mb-2"><span class="tagpill sm">Running</span> <%= benchState.endpoint || 'starting' %> · <%= benchState.done %> of <%= benchState.of || corpusSize * 3 %> calls (each case runs three times: twice without its payload, once with it).</p>
+        <progress class="d-block w-100 mb-2" data-bench-progress max="<%= benchState.of || corpusSize * 3 %>" value="<%= benchState.done %>"><%= benchState.done %> of <%= benchState.of || corpusSize * 3 %></progress>
+      <% } else if (benchState.error) { %>
+        <p class="small text-danger mb-2">The last bench run failed: <%= benchState.error %></p>
+      <% } %>
+      <% if (_edit) { %>
+        <button type="submit" class="btn btn-outline-primary btn-sm" formaction="<%= _base %>/bench" <%= benchState.running ? 'disabled' : '' %>>Run the bench now</button>
+      <% } %>
+      </div>
+    </div></div>
+
+    <div class="card mb-3"><div class="card-body" id="ask-endpoints-live" data-live-topic="ask-bench:house">
+      <h6 class="card-title">Endpoints for route ask <span class="cnt"><%= endpoints.length %></span></h6>
+      <p class="text-body-secondary small">Walked in this order. <% if (providerKinds) { %>Only endpoints of the kinds this route may use (<%= providerKinds %>) are used, and only<% } else { %>Only<% } %> ones chosen for this route — there is no default list. An endpoint without a passing ask bench is skipped and the answer says so. If every endpoint is skipped the person is told the AI is busy; nothing moves quietly to another model.</p>
+      <% if (!endpoints.length) { %>
+        <p class="small mb-0">No endpoint is assigned to Ask, so it is off.<% if (jobsHref) { %> Assign one<%= providerKinds ? ' (' + providerKinds + ')' : '' %> under <a href="<%= jobsHref %>">Jobs</a>.<% } %></p>
+      <% } else { %>
+        <div class="table-responsive"><table class="table table-sm align-middle mb-0">
+          <thead><tr><th>Order</th><th>Endpoint</th><th>Engine</th><th>Ask bench</th><th>Now</th></tr></thead>
+          <tbody>
+          <% endpoints.forEach(function (e) { %>
+            <tr>
+              <td><%= e.order %></td>
+              <td><%= e.label %> <span class="text-body-secondary small"><%= e.provider %></span></td>
+              <td class="small"><%= (e.bench && e.bench.model) || e.model || '—' %></td>
+              <td class="small"><% if (e.bench) { %>
+                <span class="tagpill sm <%= e.bench.passed ? 'ok' : 'warn' %>"><%= e.bench.passed ? 'passed' : 'not passed' %></span>
+                <% if (e.bench.injectionRate != null) { %>
+                  <div>Injection resisted <strong><%= e.bench.injectionRate %> %</strong> · format followed <%= e.bench.formatRate %> % · <%= e.bench.controlsHeld %> of <%= e.bench.controlsTotal %> controls<% if (e.bench.counts && e.bench.counts.error) { %> · <span class="text-danger"><%= e.bench.counts.error %> cases unanswered (<%= e.bench.errorRate %> %)</span><% } %><% if (e.bench.changedDuringRun) { %> · <span class="text-danger">configuration changed during the run</span><% } %></div>
+                  <% if (e.bench.topReasons && e.bench.topReasons.length) { %>
+                    <div class="text-body-secondary">Top reasons: <%= e.bench.topReasons.map(function (x) { return x.code + ' ×' + x.n; }).join(', ') %></div>
+                  <% } %>
+                <% } else { %>
+                  <%= e.bench.rate %> % · <%= e.bench.controlsHeld %> of <%= e.bench.controlsTotal %> controls
+                <% } %>
+              <% } else { %>not run<% } %></td>
+              <td class="small"><%= e.now %></td>
+            </tr>
+          <% }) %>
+          </tbody>
+        </table></div>
+      <% } %>
+    </div></div>
+
+    <div class="card mb-3"><div class="card-body">
+      <h6 class="card-title">Limits</h6>
+      <p class="text-body-secondary small">Over a limit, the person gets a plain line saying which one and when it resets.</p>
+      <div class="row g-3">
+        <% [['limitHour', 'ask-lh'], ['limitDay', 'ask-ld'], ['partnerTokensDay', 'ask-pt']].forEach(function (f) { var x = _c[f[0]]; %>
+        <div class="col-sm-4">
+          <label class="form-label" for="<%= f[1] %>"><%= x.label %></label>
+          <input class="form-control <%= _err[x.form] ? 'is-invalid' : '' %>" id="<%= f[1] %>" name="<%= x.form %>" inputmode="numeric" value="<%= ask[x.field] %>" <%= _edit ? '' : 'disabled' %>>
+          <% if (x.help) { %><div class="form-text"><%= x.help %></div><% } %>
+          <% if (_err[x.form]) { %><div class="invalid-feedback"><%= _err[x.form] %></div><% } %>
+        </div>
+        <% }) %>
+      </div>
+      <p class="small mt-2 mb-0">Questions at a time: <strong>1 per person</strong> · fixed.</p>
+    </div></div>
+
+    <div class="card mb-3"><div class="card-body">
+      <h6 class="card-title"><%= _c.retention.label %></h6>
+      <p class="text-body-secondary small"><%= _c.retention.help %></p>
+      <% _c.retention.options.forEach(function (r) { %>
+        <div class="form-check form-check-inline">
+          <input class="form-check-input" type="radio" name="retention" id="ask-ret-<%= r[0] %>" value="<%= r[0] %>" <%= String(ask.retention) === r[0] ? 'checked' : '' %> <%= _edit ? '' : 'disabled' %>>
+          <label class="form-check-label" for="ask-ret-<%= r[0] %>"><%= r[1] %></label>
+        </div>
+      <% }) %>
+      <% if (_err.retention) { %><div class="text-danger small"><%= _err.retention %></div><% } %>
+      <p class="small mt-2 mb-0">Each person’s history follows this setting.</p>
+    </div></div>
+
+    <div class="card mb-3"><div class="card-body">
+      <h6 class="card-title"><%= _c.toolsOff.label %> <span class="cnt"><%= tools.length %></span></h6>
+      <p class="text-body-secondary small"><%= _c.toolsOff.help %></p>
+      <div class="table-responsive"><table class="table table-sm align-middle mb-0">
+        <thead><tr><th>On</th><th>Tool</th><th>Needs the user’s permission</th></tr></thead>
+        <tbody>
+        <% tools.forEach(function (t) { %>
+          <tr<%= t.remote ? ' class="text-body-secondary"' : '' %>>
+            <td><input class="form-check-input" type="checkbox" name="tools" value="<%= t.id %>" id="ask-tool-<%= t.id %>" <%= t.on && !t.remote ? 'checked' : '' %> <%= _edit && !t.remote ? '' : 'disabled' %>></td>
+            <td><label for="ask-tool-<%= t.id %>"><%= t.label %></label> <code class="small"><%= t.id %></code><% if (t.remote) { %> <span class="small">another app’s Ask — not offered yet</span><% } %></td>
+            <td class="small"><code><%= t.permission %></code><% if (t.parts.length) { %> (+ parts: <%= t.parts.join(', ') %>)<% } %></td>
+          </tr>
+        <% }) %>
+        </tbody>
+      </table></div>
+    </div></div>
+
+    <% if (_edit) { %>
+      <div class="d-flex gap-2 align-items-center">
+        <button type="submit" class="btn btn-primary">Save Ask settings</button>
+        <a class="btn btn-link" href="<%= _base %>">Discard</a>
+        <span class="small text-body-secondary">Changes are recorded in the audit log.</span>
+      </div>
+    <% } %>
+  </form>
+
+<%- include(_L.foot) %>

package/views/ask/drawer.ejs

@@ -0,0 +1,59 @@
+<%#
+  ASK ANYTHING — the drawer (@aria-framework/ask). Included by the app's staff-foot — include('ask/drawer', { askWords,
+  askSuggestions }) — and only for a viewer holding ai.ask, beside /js/ask/ask.css and /js/ask/ask.js (assetsDir).
+
+  Everything inside the conversation is drawn by assets/ask.js from the `ask/1` stream, as TEXT (textContent) — no model
+  words ever become HTML, and the only links are the app's own hrefs from the look-ups (chips) and the page context.
+
+  LOCALS (the app's words, D-0169 item 6):
+    askContext      { kind, ref, name } set by a page — its ref and name, never page text; the route resolves it again
+    askWords        { heading, intro }                           (default 'Ask' and a generic line)
+    askSuggestions  { <context kind>: [{ title, items: [..] }], '*': [...] } — '{name}' in a title is the context's name
+%>
+<% var _ctx = (typeof askContext !== 'undefined' && askContext) ? askContext : null; %>
+<% var _w = (typeof askWords !== 'undefined' && askWords) ? askWords : {}; %>
+<% var _s = (typeof askSuggestions !== 'undefined' && askSuggestions) ? askSuggestions : {}; %>
+<% var _groups = (_ctx && _s[_ctx.kind]) ? _s[_ctx.kind] : (_s['*'] || []); %>
+<aside id="ask-drawer" class="ask-drawer" role="dialog" aria-modal="false" aria-labelledby="ask-title" hidden
+  data-context-kind="<%= _ctx ? _ctx.kind : '' %>" data-context-ref="<%= _ctx ? _ctx.ref : '' %>" data-context-name="<%= _ctx ? _ctx.name : '' %>"
+  data-history-note="<%= _w.historyNote || 'Your last 20 questions here · kept per the retention setting · only you see them.' %>" data-ask-base="<%= _w.base || '/ask' %>">
+  <div class="ask-head">
+    <h2 id="ask-title" class="ask-title"><i class="bi bi-stars" aria-hidden="true"></i> <span data-ask-heading><%= _w.heading || 'Ask' %></span></h2>
+    <div class="ask-tools">
+      <button type="button" class="btn btn-sm btn-link" data-ask-history>History</button>
+      <button type="button" class="btn btn-sm btn-link" data-ask-new>New question</button>
+      <button type="button" class="btn-close" data-ask-close aria-label="Close"></button>
+    </div>
+  </div>
+  <p class="ask-scope small text-body-secondary mb-0"><span data-ask-reading></span><span data-ask-reading-sep hidden> · </span>Answers use only what you can open. It can’t change anything.</p>
+  <div class="ask-acting small" data-ask-acting hidden></div>
+
+  <div class="ask-body" data-ask-body aria-live="polite" aria-busy="false">
+    <div class="ask-empty" data-ask-empty>
+      <p class="small text-body-secondary"><%= _w.intro || 'Ask about what you can open here.' %></p>
+      <div class="ask-sugg" data-ask-suggestions>
+        <% _groups.forEach(function (g) { %>
+          <h3><%= String(g.title || '').replace('{name}', _ctx ? _ctx.name : '') %></h3>
+          <ul>
+            <% (g.items || []).forEach(function (q) { %><li><button type="button" data-ask-suggest><%= q %></button></li><% }) %>
+          </ul>
+        <% }) %>
+      </div>
+    </div>
+    <ol class="ask-conv" data-ask-conv></ol>
+    <div class="ask-history" data-ask-history-panel hidden></div>
+  </div>
+
+  <form class="ask-form" data-ask-form autocomplete="off">
+    <% if (_ctx) { %>
+      <span class="ask-ctx" data-ask-ctx>About: <span><%= _ctx.name %></span>
+        <button type="button" class="cx" data-ask-ctx-clear aria-label="Ask without this page’s context">×</button></span>
+    <% } %>
+    <div class="ask-row">
+      <label for="ask-q" class="visually-hidden">Your question</label>
+      <textarea id="ask-q" name="question" rows="2" maxlength="500" placeholder="Your question" data-ask-input></textarea>
+      <button type="submit" class="btn btn-primary" data-ask-send>Ask</button>
+    </div>
+    <p class="small text-body-secondary mb-0" data-ask-hint>Enter sends · Shift+Enter for a new line · Esc closes</p>
+  </form>
+</aside>

package/views/ask/review.ejs

@@ -0,0 +1,90 @@
+<% var _L = (typeof askLayout !== 'undefined' && askLayout) ? askLayout : { head: 'partials/staff-head', tabs: 'partials/admin-tabs', foot: 'partials/staff-foot' }; %>
+<% var _base = (typeof askReviewBase === 'string' && askReviewBase) ? askReviewBase : '/admin/ai/ask-review'; %>
+<%- include(_L.head) %>
+
+  <%- include(_L.tabs) %>
+
+  <%# ASK REVIEW (@aria-framework/ask): answers marked not helpful, for the platform (ai_config.view — partner admins do not
+      see this list). Every partner's rows, with a Partner filter. Question and feedback text are shown AS TYPED, escaped,
+      as data. Rows go when the question's retention ends. App locals used: can, csrfToken, whenTag; askLayout and
+      askReviewBase are optional. %>
+  <% var _can = (typeof can === 'function') ? can : function () { return false; }; %>
+
+  <div class="card mb-3"><div class="card-body">
+    <h6 class="card-title">Questions marked not helpful <span class="cnt"><%= rows.length %></span></h6>
+    <form method="GET" action="<%= _base %>" class="row g-2 align-items-end mb-3">
+      <div class="col-auto">
+        <label class="form-label small" for="rv-partner">Partner</label>
+        <select class="form-select form-select-sm" id="rv-partner" name="partner">
+          <option value="">All partners</option>
+          <% partners.forEach(function (p) { %><option value="<%= p.id %>" <%= partner === p.id ? 'selected' : '' %>><%= p.name %><%= p.isHouse ? ' (house)' : '' %></option><% }) %>
+        </select>
+      </div>
+      <div class="col-auto">
+        <label class="form-label small" for="rv-reason">Reason</label>
+        <select class="form-select form-select-sm" id="rv-reason" name="reason">
+          <option value="">Any reason</option>
+          <% Object.keys(reasons).forEach(function (k) { %><option value="<%= k %>" <%= reason === k ? 'selected' : '' %>><%= reasons[k] %></option><% }) %>
+        </select>
+      </div>
+      <div class="col-auto">
+        <label class="form-label small" for="rv-state">State</label>
+        <select class="form-select form-select-sm" id="rv-state" name="state">
+          <option value="open" <%= state === 'open' ? 'selected' : '' %>>Not reviewed</option>
+          <option value="reviewed" <%= state === 'reviewed' ? 'selected' : '' %>>Reviewed</option>
+          <option value="all" <%= state === 'all' ? 'selected' : '' %>>All</option>
+        </select>
+      </div>
+      <div class="col-auto"><button type="submit" class="btn btn-sm btn-outline-primary">Filter</button></div>
+      <div class="col-auto small text-body-secondary">Kept as long as the Ask retention setting — older questions are deleted.</div>
+    </form>
+
+    <% if (!rows.length) { %>
+      <p class="small mb-0">No answers marked not helpful<%= state === 'open' ? ' are waiting for review' : '' %>.</p>
+    <% } else { %>
+      <div class="table-responsive"><table class="table table-sm align-top mb-0">
+        <thead><tr><th>Time</th><th>User</th><th>Partner</th><th>App</th><th>Question</th><th>Tools</th><th>Outcome</th><th>Reason</th></tr></thead>
+        <tbody>
+        <% rows.forEach(function (r) { %>
+          <tr>
+            <td class="small text-nowrap"><%- whenTag(r.created_at) %></td>
+            <td class="small"><%= r.asked_by_name %><%= r.acting ? ' (working inside)' : '' %></td>
+            <td class="small"><%= r.partner_name %></td>
+            <td class="small"><%= typeof appName !== 'undefined' ? appName : '' %></td>
+            <td>
+              <details>
+                <summary><%= r.question %></summary>
+                <div class="small mt-2">
+                  <div class="fw-semibold">Look-ups</div>
+                  <% if (!r.calls.length) { %><div class="text-body-secondary">none ran</div><% } %>
+                  <ol class="mb-2">
+                    <% r.calls.forEach(function (c) { %>
+                      <li><code><%= c.tool %></code> · <%= c.row_count %> row<%= Number(c.row_count) === 1 ? '' : 's' %> · <%= c.ms %> ms · <%= c.outcome %> <code class="d-block text-wrap"><%= c.args %></code></li>
+                    <% }) %>
+                  </ol>
+                  <div class="fw-semibold">Answer and feedback</div>
+                  <% if (r.answer) { %><p class="mb-1">“<%= r.answer %>”</p><% } else { %><p class="mb-1 text-body-secondary">Fixed wording (no AI answer).</p><% } %>
+                  <p class="mb-1">Reason: <%= r.reasonWords || '—' %><% if (r.feedback_text) { %> · Their words: “<%= r.feedback_text %>”<% } %></p>
+                  <p class="mb-2 text-body-secondary">Model <%= r.endpoint || '—' %> <%= r.model || '' %> · <%= (Number(r.ms) / 1000).toFixed(1) %> s · <%= Number(r.tokens).toLocaleString() %> tokens</p>
+                  <% if (!r.reviewed_at && _can('ai_config.edit')) { %>
+                    <form method="POST" action="<%= _base %>/<%= r.public_id %>/reviewed">
+                      <input type="hidden" name="_csrf" value="<%= csrfToken() %>">
+                      <button type="submit" class="btn btn-sm btn-outline-primary">Mark reviewed</button>
+                    </form>
+                  <% } else if (r.reviewed_at) { %>
+                    <span class="tagpill sm ok">Reviewed</span>
+                  <% } %>
+                </div>
+              </details>
+            </td>
+            <td class="small"><%= r.calls.length %></td>
+            <td class="small"><%= r.outcomeWords %></td>
+            <td class="small"><%= r.reasonWords || '—' %></td>
+          </tr>
+        <% }) %>
+        </tbody>
+      </table></div>
+    <% } %>
+  </div></div>
+
+<%- include(_L.foot) %>