@aria-framework/ask 0.1.2 → 0.2.0

package/lib/prompts.js

@@ -2,15 +2,21 @@
  * The two prompts of an Ask question, and what the model is allowed to see. The MACHINERY is shared; the WORDS are the
  * app's (D-0169 item 6) and are passed in.
  *
- *   PLAN    sees the question, the page context as a REF only (or the neutral token "@context") and the tools this person
- *           may use. It sees NO DATA, so nothing an attacker wrote can steer which look-ups run.
+ *   PLAN    sees the question, the page context as a REF only (or the neutral token "@context"), the tools this person
+ *           may use and — for a follow-up — the previous question's text and the refs its look-ups returned (0.2.0). It
+ *           sees NO DATA, so nothing an attacker wrote can steer which look-ups run.
  *   ANSWER  sees the question and the look-ups' results as ONE FENCED DOCUMENT (@aria-framework/ai `fenced` — a random
  *           per-call marker), through `modelView`: refs, names, fields and counts — never numeric ids, never hrefs, never a
  *           result's `quote` (another model's words, drawn by the app beside the answer). It has no tools.
  *
- * THE PROMPT HASH (`promptHash`) is `sha256(JSON.stringify({v:1, app, plan, answer, answerSchema, tools}))` — the hub's
- * and soc's exact document, with `app` undefined for the hub (JSON.stringify drops it) and 'soc' for Soc. So an app
- * that passes its own rule texts byte-for-byte keeps its hash, and its bench record, through adoption (test/hashes.js).
+ * THE PACKAGE'S CONTRACT (0.2.0). After the app's own rules, every planner prompt carries PLAN_CONTRACT (analyse, the
+ * reason on none, round-2 references, follow-ups) and every answer prompt ANSWER_CONTRACT (verdicts and "all/none"
+ * claims), plus ANALYSE_RULES when the plan's intent is `analyse`. They are the package's words because the check and the
+ * planner schema they describe are the package's; the app's words stay the app's.
+ *
+ * THE PROMPT HASH (`promptHash`) is `sha256(JSON.stringify({v:2, app, plan, answer, answerSchema, tools, contract}))`.
+ * 0.1's document was `{v:1, …}` with no contract; `promptHashOf` without `contract` still computes it, so an app's test
+ * can show which document a stored hash was.
  */
 
 'use strict';
@@ -31,9 +37,46 @@ const ANSWER_SCHEMA = Object.freeze({
   }
 });
 
+const PLAN_CONTRACT = [
+  'These rules come with every app and add to the rules above:',
+  '- intent "analyse" instead of "lookup" when the question asks to compare, group, rank or draw a conclusion across what',
+  '  the look-ups return ("which has the most", "what do these have in common", "is anything unusual"). Plan its',
+  '  look-ups exactly as for "lookup".',
+  '- "reason" is null, except with intent "none": then "no_tool" (no tool below covers it), "out_of_scope" (it is not',
+  '  about these records or this app) or "needs_judgement" (it asks for an opinion, a decision or advice the records',
+  '  cannot settle).',
+  '- A later look-up may take a value from an earlier look-up\'s result: write "@r1.<output>" as that argument, where r1',
+  '  is the first look-up in "calls" and <output> is one the earlier tool "gives". The app reads the value; never type a',
+  '  value you have not been given. Look-ups that take no earlier result come first, and a look-up may take only from one',
+  '  that takes none.',
+  '- A follow-up names the previous question and the references its look-ups returned. Use them only where the new',
+  '  question needs them.'
+].join('\n');
+
+const ANSWER_CONTRACT = [
+  'These rules come with every app and add to the rules above:',
+  '- Never call anything compromised, breached, malicious, benign, harmless, safe or a false positive unless a result',
+  '  you cite says so in its own fields.',
+  '- Never say that all, every or none of the rows are in a state (resolved, closed, open, healthy …) unless every row',
+  '  of the result you cite shows it.'
+].join('\n');
+
+const ANALYSE_RULES = [
+  'This question asks for an analysis. You may group, compare and conclude across the results, and only from them:',
+  '- Every sentence cites at least one result, as [r1]. A placeholder in a sentence names a result that sentence cites.',
+  '- Every count is a placeholder. Never type a number or work one out (no sums, differences, percentages, "twice as',
+  '  many"); say "more", "fewer" or "the most" instead.',
+  '- Name only the customers, people, hosts and things the cited results name. Never introduce a new one.',
+  '- Say a conclusion as coming from the results: "the results show …", "based on these results …".',
+  '- Never say anything was done, and never present advice as done.'
+].join('\n');
+
+const CONTRACT = Object.freeze({ plan: PLAN_CONTRACT, answer: ANSWER_CONTRACT, analyse: ANALYSE_RULES });
+
 /** The prompt document's hash — exported so an app's test-ask-hashes.js can pin it from its own inputs. */
-function promptHashOf({ app, plan, answer, answerSchema = ANSWER_SCHEMA, toolsHash }) {
-  const doc = JSON.stringify({ v: 1, app, plan, answer, answerSchema, tools: toolsHash });
+function promptHashOf({ app, plan, answer, answerSchema = ANSWER_SCHEMA, toolsHash, contract }) {
+  const doc = JSON.stringify(contract === undefined ? { v: 1, app, plan, answer, answerSchema, tools: toolsHash }
+    : { v: 2, app, plan, answer, answerSchema, tools: toolsHash, contract });
   return crypto.createHash('sha256').update(doc).digest('hex');
 }
 
@@ -57,6 +100,18 @@ function modelView(results) {
 const FIELDS_SENTENCE = 'The document has fields "question" and "results"; each result has "id", "look_up", "outcome", "count", '
   + '"counted", "extra_figures", "facts" and "rows".';
 
+/**
+ * The planner's follow-up sentence: the previous question AS THE PERSON TYPED IT, the tools its look-ups used and the
+ * refs they returned (the app's own public ids, from rows' `ref`) — never the model's answer, never a result's text.
+ */
+function followUpSentence(prev) {
+  if (!prev) return '';
+  const refs = (prev.refs || []).slice(0, 10);
+  return `\nThis is a follow-up. The previous question was: ${JSON.stringify(String(prev.question || '').slice(0, 500))}.`
+    + `${prev.tools && prev.tools.length ? ` Its look-ups used ${prev.tools.join(', ')}.` : ''}`
+    + `${refs.length ? ` They returned these references: ${refs.join(', ')}.` : ''}`;
+}
+
 /**
  * Prompts bound to an app's words.
  * @param {object} o
@@ -78,18 +133,20 @@ function createPrompts(o) {
   if (!o.fenced || typeof o.fenced.fencedDocument !== 'function') throw new Error('ask prompts: fenced (from @aria-framework/ai) is required');
   const { catalogue } = o;
 
-  const planSystem = (tools) => `${o.planRules}\n\nTools:\n${catalogue.describeTools(tools)}`;
-  const planUser = (question, context) => `Question: ${String(question)}${context ? String(o.contextSentence(context) || '') : ''}`;
+  const planSystem = (tools) => `${o.planRules}\n\n${PLAN_CONTRACT}\n\nTools:\n${catalogue.describeTools(tools)}`;
+  const planUser = (question, context, previous) => `Question: ${String(question)}${context ? String(o.contextSentence(context) || '') : ''}${followUpSentence(previous)}`;
 
-  function answerMessages(question, results) {
+  /** @param {{mode?: 'lookup'|'analyse'}} [opts] */
+  function answerMessages(question, results, opts = {}) {
     const { block, rule } = o.fenced.fencedDocument('the look-up results', { question: String(question), results: modelView(results) },
       { what: o.fenceWhat, onLeak: o.onLeak });
-    return { system: `${o.answerRules}\n\n${FIELDS_SENTENCE} ${rule}`, user: block };
+    const extra = opts.mode === 'analyse' ? `\n\n${ANALYSE_RULES}` : '';
+    return { system: `${o.answerRules}\n\n${ANSWER_CONTRACT}${extra}\n\n${FIELDS_SENTENCE} ${rule}`, user: block };
   }
 
-  const promptHash = () => promptHashOf({ app: o.hashApp, plan: o.planRules, answer: o.answerRules, toolsHash: catalogue.catalogueHash() });
+  const promptHash = () => promptHashOf({ app: o.hashApp, plan: o.planRules, answer: o.answerRules, toolsHash: catalogue.catalogueHash(), contract: CONTRACT });
 
-  return { EXAMPLE: o.example, PLAN_RULES: o.planRules, ANSWER_RULES: o.answerRules, ANSWER_SCHEMA, planSystem, planUser, modelView, answerMessages, promptHash };
+  return { EXAMPLE: o.example, PLAN_RULES: o.planRules, ANSWER_RULES: o.answerRules, ANSWER_SCHEMA, CONTRACT, planSystem, planUser, modelView, answerMessages, promptHash };
 }
 
-module.exports = { createPrompts, promptHashOf, modelView, ANSWER_SCHEMA, FIELDS_SENTENCE };
+module.exports = { createPrompts, promptHashOf, modelView, followUpSentence, ANSWER_SCHEMA, FIELDS_SENTENCE, PLAN_CONTRACT, ANSWER_CONTRACT, ANALYSE_RULES, CONTRACT };

package/lib/routes.js

@@ -5,10 +5,16 @@
  *     POST /ask                   ask one question; the reply is the `ask/1` NDJSON stream (lib/stream.js). Every question
  *                                 that got this far is audited `ask.asked` in a `finally`, whatever became of it.
  *     GET  /ask/history           the person's own last 20 questions, JSON
- *     GET  /ask/q/:ref            one of the person's own questions with its answer as given, JSON (stale: true)
+ *     GET  /ask/q/:ref            one of the person's own questions with its answer as given, JSON (stale: true) — 0.2.0:
+ *                                 only if the viewer still may use every tool it used, at the same reading and scope
+ *                                 (history.recheck); else { unavailable: true, text } and no answer
  *     POST /ask/q/:ref/feedback   the person's thumbs mark on their own question, JSON — audited `ask.feedback`
  *
- *   createAdminRouters → { settingsRouter at /admin/ai/ask, reviewRouter at /admin/ai/ask-review }, platform only
+ *     POST /ask takes `follow_up` (0.2.0): the ref of the person's previous question in the drawer; what it may carry is
+ *                                 history.followUp's to decide, never the body's.
+ *
+ *   createAdminRouters → { settingsRouter at /admin/ai/ask, reviewRouter at /admin/ai/ask-review (+ /none, 0.2.0: the
+ *     questions no tool could answer, with the planner's reason) }, platform only
  *     (ai_config.view to see, ai_config.edit to change). Audited `ai_config.ask_settings`, `ai_config.ask_bench`,
  *     `ai_config.ask_review` — the action names both apps already write.
  *
@@ -24,9 +30,11 @@
 'use strict';
 
 const stream = require('./stream');
+const eta = require('./eta');
 
 const s = (v) => (typeof v === 'string' ? v.trim() : '');
 const REASON_WORDS = Object.freeze({ wrong_figure: 'Wrong figure', wrong_record: 'Wrong record', no_answer: 'Didn’t answer', other: 'Other' });
+const NONE_WORDS = Object.freeze({ no_tool: 'No tool covers it', out_of_scope: 'Not about these records', needs_judgement: 'Needs a judgement' });
 const OUTCOME_WORDS = Object.freeze({ answered: 'answered', withheld: 'withheld', not_found: 'not found', refused_write: 'refused · write',
   cannot: 'could not answer', busy: 'busy', off: 'off', error: 'error', working: 'unfinished' });
 
@@ -96,7 +104,8 @@ function createAskRouter(o) {
       write(stream.start(reading));
       let answer = null;
       try {
-        answer = await A.run.ask({ req, can, question, context, settings, reading, timezone: timezoneOf(req, res),
+        const followUp = settings.enabled && typeof (req.body || {}).follow_up === 'string' ? s(req.body.follow_up).slice(0, 64) || null : null;
+        answer = await A.run.ask({ req, can, question, context, settings, reading, followUp, timezone: timezoneOf(req, res),
           onStep: (st) => write(stream.step(st)) });
       } catch (e) {
         logger.error(`Ask: the question failed before it could be answered (${e && e.stack ? e.stack : e})`);
@@ -104,7 +113,8 @@ function createAskRouter(o) {
         try {
           o.audit(req, 'ask.asked', { entity_type: 'ask_question', entity_id: null,
             detail: { ref: answer ? answer.ref : null, outcome: answer ? answer.outcome : 'error',
-              lookups: answer ? answer.lookups.map((l) => l.tool) : [], context: context ? context.kind : null } });
+              lookups: answer ? answer.lookups.map((l) => l.tool) : [], context: context ? context.kind : null,
+              ...(answer && answer.followUp ? { follow_up: answer.followUp } : {}), ...(answer && answer.noneReason ? { none_reason: answer.noneReason } : {}) } });
         } catch (e) { logger.error(`Ask: the audit line could not be written (${e && e.message ? e.message : e})`); }
       }
       write(answer ? stream.answer(answer) : stream.error(A.run.WORDS.error));
@@ -127,8 +137,12 @@ function createAskRouter(o) {
 
   router.get('/q/:ref', o.requirePermission('ai.ask'), wrap(async (req, res) => {
     if (!A.isPublicId(req.params.ref, 'ask_question')) return res.status(404).json({ error: 'not_found' });
-    const q = await A.history.one(req, canOf(res), req.params.ref);
+    const can = canOf(res);
+    const q = await A.history.one(req, can, req.params.ref);
     if (!q || !q.result) return res.status(404).json({ error: 'not_found' });
+    // THE RECHECK (0.2.0): the tools it used, the reading and the scope — as of NOW. The answer is not sent otherwise.
+    const ok = A.history.recheck(q, req, can, await o.readingOf(req, can), (await A.settings.read()).toolsOff);
+    if (!ok.ok) return res.json({ unavailable: true, text: A.run.WORDS.unavailable, question: q.question, at: q.created_at });
     res.json({ answer: q.result, at: q.created_at, rating: q.rating, stale: true });
   }));
 
@@ -157,6 +171,7 @@ function createAskRouter(o) {
  * @param {Function} o.ai           () → the app's AI facade { configFor(id), complete(opts, cfg) }
  * @param {Function} o.partners     async () → [{ id, name, is_house }]
  * @param {Function} [o.onBenchChange] the app's live hook (re-fetch the page's bench regions)
+ * @param {Function} [o.now]            the clock, in ms (default Date.now); the bench's time-left estimate reads it
  * @param {string} [o.appName]      the review list's App column
  * @param {string} [o.jobsHref]     the app's page where endpoints are assigned to routes (linked from the empty state)
  * @param {object} [o.layout]       { head, tabs, foot } partial names (default partials/staff-head, admin-tabs, staff-foot)
@@ -170,7 +185,9 @@ function createAdminRouters(o) {
   const logger = o.logger || A.logger;
   const touch = typeof o.onBenchChange === 'function' ? () => { try { o.onBenchChange(); } catch (_) { /* live is best effort */ } } : () => {};
   const layout = { head: 'partials/staff-head', tabs: 'partials/admin-tabs', foot: 'partials/staff-foot', ...(o.layout || {}) };
-  const benchState = { running: false, endpoint: null, done: 0, of: 0, startedAt: null, error: null };
+  // o.now is the clock (ms); a test fixes it. endpointSinceMs/lastCallMs/endpointIndex feed the time-left estimate (lib/eta.js).
+  const now = typeof o.now === 'function' ? o.now : Date.now;
+  const benchState = { running: false, endpoint: null, done: 0, of: 0, startedAt: null, error: null, endpointSinceMs: null, lastCallMs: null, endpointIndex: 0, endpointCount: 0 };
   const model = (fn, ...args) => A.invoke(A.modelName, fn, ...args);
 
   const kindsOf = (policy) => (policy && Array.isArray(policy.providers) && policy.providers.length ? policy.providers.join(', ') : null);
@@ -217,6 +234,8 @@ function createAdminRouters(o) {
       tools: A.catalogue.TOOLS.map((t) => ({ id: t.id, label: t.label, permission: A.gateOf(t).join(' + '), parts: t.parts || [], remote: t.kind === 'remote',
         on: !shown.toolsOff.includes(t.id) })),
       benchState: { ...benchState },
+      benchLine: benchState.running ? eta.progressLine({ done: benchState.done, of: benchState.of || A.bench.corpus().length * 3, sinceMs: benchState.endpointSinceMs,
+        nowMs: now(), startedMs: Date.parse(benchState.startedAt), endpointsLeft: Math.max(0, benchState.endpointCount - benchState.endpointIndex) }).text : null,
       corpusSize: A.bench.corpus().length,
       controlsSize: A.bench.controls().length,
       passRate: Math.round(A.bench.PASS_RATE * 100),
@@ -259,14 +278,21 @@ function createAdminRouters(o) {
     const endpoints = (await o.endpoints.forRoute('ask')) || [];
     if (!endpoints.length) return redirectWith(res, 'error', `No endpoint${kindsOf(o.routePolicy('ask')) ? ` (${kindsOf(o.routePolicy('ask'))})` : ''} is assigned to the Ask route yet — assign one first.`, back);
     const ai = o.ai();
-    Object.assign(benchState, { running: true, endpoint: null, done: 0, of: 0, startedAt: new Date().toISOString(), error: null });
+    const startMs = now();
+    Object.assign(benchState, { running: true, endpoint: null, done: 0, of: 0, startedAt: new Date(startMs).toISOString(), error: null,
+      endpointSinceMs: startMs, lastCallMs: startMs, endpointIndex: 0, endpointCount: endpoints.length });
     o.audit(req, 'ai_config.ask_bench', { entity_type: 'ai_config', detail: { route: 'ask', endpoints: endpoints.join(', '), cases: A.bench.corpus().length } });
     // IN THE BACKGROUND, in this request's async context; the record is stored at the house's installation row. Each call
     // goes to THAT endpoint's own config, the route named on the options AND the config.
     A.bench.run({
       endpoints,
       completeOn: async (id, opts) => A.bench.endpointCall(ai, await ai.configFor(id))(opts),
-      onProgress: (p) => { Object.assign(benchState, { endpoint: p.endpoint, done: p.done, of: p.of }); touch(); }
+      onProgress: (p) => {
+        const t = now();
+        if (p.endpoint !== benchState.endpoint) Object.assign(benchState, { endpointSinceMs: benchState.lastCallMs, endpointIndex: benchState.endpointIndex + 1 });
+        Object.assign(benchState, { endpoint: p.endpoint, done: p.done, of: p.of, lastCallMs: t });
+        touch();
+      }
     }).then((record) => A.bench.persistAtHouse(record))
       .catch((e) => { benchState.error = e.message; logger.error(`Ask bench failed: ${e && e.stack ? e.stack : e}`); })
       .finally(() => { benchState.running = false; touch(); });
@@ -289,6 +315,17 @@ function createAdminRouters(o) {
       askLayout: layout, adminTabStyle: 'underline' });
   }));
 
+  // THE QUESTIONS NO TOOL COULD ANSWER (0.2.0) — what people ask for that Ask has no look-up for, with the planner's reason.
+  reviewRouter.get('/none', o.requirePermission('ai_config.view'), wrap(async (req, res) => {
+    const partners = ((await o.partners()) || []).map((p) => ({ id: String(p.id), name: p.name, isHouse: Number(p.is_house) === 1 }));
+    const partner = partners.find((p) => p.id === s(req.query.partner)) ? s(req.query.partner) : null;
+    const reason = A.NONE_REASONS.includes(s(req.query.reason)) ? s(req.query.reason) : null;
+    const rows = ((await model('noneList', { reason, partner_id: partner })) || []).map((r) => ({ ...r, reasonWords: NONE_WORDS[r.none_reason] || 'Not recorded' }));
+    const base = req.baseUrl || '/admin/ai/ask-review';
+    res.render('ask/none', { title: 'AI assistance', rows, partners, partner, reason, reasons: NONE_WORDS, appName: o.appName || '', askReviewBase: base,
+      askLayout: layout, adminTabStyle: 'underline' });
+  }));
+
   reviewRouter.post('/:ref/reviewed', o.requirePermission('ai_config.edit'), wrap(async (req, res) => {
     const back = req.baseUrl || '/admin/ai/ask-review';
     if (!A.isPublicId(req.params.ref, 'ask_question')) return res.status(404).render('errors/404', { title: 'Not found' });
@@ -301,4 +338,4 @@ function createAdminRouters(o) {
   return { settingsRouter, reviewRouter, pageModel, _benchState: benchState };
 }
 
-module.exports = { createAskRouter, createAdminRouters, REASON_WORDS, OUTCOME_WORDS };
+module.exports = { createAskRouter, createAdminRouters, REASON_WORDS, OUTCOME_WORDS, NONE_WORDS };

package/lib/run.js

@@ -8,6 +8,19 @@
  *   - the page context's id goes back only into the tool of its own kind (`contextTools`), AFTER validation.
  *   - Tier 1's own words (a result's `quote`) are drawn by the app beside the answer (`quotesOf`, Soc S7).
  *
+ * 0.2.0:
+ *   - ANALYSE: a plan whose intent is `analyse` runs like a look-up; its answer gets the analyse rules and is checked in
+ *     analyse mode (check.js). The render model says which (`mode`).
+ *   - TWO ROUNDS: round-1 calls run first; only when every one is ok do the round-2 calls run, each argument that names
+ *     an earlier result ("@r1.customer_ref") RESOLVED BY THE PACKAGE (catalogue.resolveCall) and validated as a typed
+ *     argument. An unresolvable one reads as not found. The context token is put back before, and only into, the plan's
+ *     own arguments — never into a resolved value.
+ *   - NONE WITH A REASON: the fixed words are `cannot_<reason>` when the app has them, else `cannot`; the reason is in
+ *     the render model (`noneReason`), so it is stored with the row's result.
+ *   - FOLLOW-UPS: `a.followUp` (the previous question's ref) is resolved by `followUpOf` (history.js: same person,
+ *     context, reading and scope, within its minutes); what it returns goes into the planner's user message only.
+ *   - Each look-up records the refs its rows returned (`lookups[].refs`, this app's public ids) for a follow-up.
+ *
  * RUNS INSIDE THE ASKER'S OWN REQUEST — never from a job or a timer — so every look-up carries the request's tenant
  * context and its own `can`. Nothing here takes a partner, a scope or a permission from the question or the model.
  *
@@ -22,6 +35,10 @@
 const MAX_QUESTION = 500;
 const BUSY_KINDS = ['unreachable', 'timeout', 'rate_limit', 'budget', 'disabled', 'unconfigured', 'bad_response', 'unsupported', 'auth'];
 const WORD_KEYS = ['not_found', 'refused_write', 'cannot', 'cannot_plan', 'ambiguous', 'withheld', 'off', 'busy', 'error', 'nothing_to_ask'];
+/** 0.2.0, optional: a none's words by its reason (default `cannot`), and the history recheck's refusal. */
+const OPTIONAL_WORD_KEYS = ['cannot_no_tool', 'cannot_out_of_scope', 'cannot_needs_judgement', 'unavailable'];
+const UNAVAILABLE = 'This answer is no longer available to you.';
+const MAX_REFS = 10;
 
 /** The question as typed, cut and cleaned: control characters become spaces. Empty → null. */
 function cleanQuestion(q) {
@@ -49,11 +66,15 @@ const msg = (e) => (e && e.message ? e.message : String(e));
  * @param {Function} [o.openLabel]    (kind) → the refused-write link's words (default `Open the ${kind} →`)
  * @param {Function} o.principalOf    (req, can) → { id, name, acting, scope }
  * @param {object} o.gate             { endpointsFor(hash), complete(opts, usable) } — the production seam
+ * @param {Function} [o.isPublicId]   this app's id test — which row refs a look-up records for a follow-up
+ * @param {Function} [o.followUpOf]   async (req, can, ref, { context, reading }) → { ref, question, tools, refs } | null
  */
 function createRun(o) {
   for (const k of WORD_KEYS) if (typeof (o.words || {})[k] !== 'string' || !o.words[k]) throw new Error(`ask: words.${k} is required (the app's fixed wording)`);
   if (typeof o.principalOf !== 'function') throw new Error('ask: principalOf(req, can) is required');
-  const WORDS = Object.freeze({ ...o.words });
+  for (const k of OPTIONAL_WORD_KEYS) if (o.words[k] !== undefined && (typeof o.words[k] !== 'string' || !o.words[k])) throw new Error(`ask: words.${k}, when given, is the app's fixed wording`);
+  const WORDS = Object.freeze({ unavailable: UNAVAILABLE, ...o.words });
+  const isPublicId = typeof o.isPublicId === 'function' ? o.isPublicId : () => false;
   const model = o.modelName || 'AskQuestion';
   const contextTools = { ...(o.contextTools || {}) };
   const contextRef = typeof o.contextRef === 'function' ? o.contextRef : (c) => c.ref;
@@ -86,8 +107,10 @@ function createRun(o) {
     const lookups = [];
     const results = [];
     const fixed = (key, extra = {}) => ({ by: 'fixed', text: WORDS[key], chips: [], ...extra });
+    let mode = 'lookup';
+    let previous = null;
     const shape = (oc, r) => ({ ...r, outcome: oc, ref: row.public_id, question, context, lookups, provenance: prov,
-      reading: a.reading || null, at: new Date().toISOString() });
+      reading: a.reading || null, mode, followUp: previous ? previous.ref : null, at: new Date().toISOString() });
 
     /** Close the row. NEVER THROWS — three attempts, each smaller than the last (the header). */
     const finish = async (outcome, render, answerText = null) => {
@@ -121,12 +144,20 @@ function createRun(o) {
       prov.skipped = ends.skipped;
       if (!ends.usable.length) return await finish('off', fixed('off'));
 
+      // A FOLLOW-UP: what history.followUp allows to be carried, or nothing (the question is asked fresh).
+      if (a.followUp && typeof o.followUpOf === 'function') {
+        try { previous = await o.followUpOf(a.req, a.can, a.followUp, { context, reading: a.reading || null, toolsOff: a.settings.toolsOff || [] }); } catch (e) {
+          logger.warn(`Ask ${row.public_id}: the previous question could not be read for a follow-up (${msg(e)}); asked fresh`);
+          previous = null;
+        }
+      }
+
       // ── 1 PLAN ─────────────────────────────────────────────────────────────────────────────────────────────────────
       step({ n: 0, words: 'Working out what to look up…', state: 'run' });
       let t = Date.now();
       const planned = await deps.complete({
         system: prompts.planSystem(tools),
-        messages: [{ role: 'user', content: prompts.planUser(question, context) }],
+        messages: [{ role: 'user', content: prompts.planUser(question, context, previous) }],
         schema: catalogue.plannerSchema(tools),
         maxTokens: 500,
         temperature: 0
@@ -158,9 +189,15 @@ function createRun(o) {
         const link = context && context.href ? { label: openLabel(context.kind), href: context.href } : null;
         return await finish('refused_write', fixed('refused_write', { link }));
       }
-      if (plan.intent === 'none') return await finish('cannot', fixed('cannot'));
-      // THE NEUTRAL TOKEN: the record's own id goes back AFTER validation, and only into the tool of its own kind.
+      if (plan.intent === 'none') {
+        const key = plan.reason && WORDS[`cannot_${plan.reason}`] ? `cannot_${plan.reason}` : 'cannot';
+        return await finish('cannot', fixed(key, { noneReason: plan.reason || null }));
+      }
+      if (plan.intent === 'analyse') mode = 'analyse';
+      // THE NEUTRAL TOKEN: the record's own id goes back AFTER validation, only into the tool of its own kind, and only into
+      // the plan's own arguments (a round-2 argument still holds its reference here; its value is never substituted).
       for (const call of plan.calls) {
+        if (call.refs) continue;
         const kind = contextTools[call.tool];
         if (kind && call.args.ref === '@context') call.args.ref = context && context.kind === kind ? contextRef(context) : '@context';
       }
@@ -170,16 +207,29 @@ function createRun(o) {
       const ctx = { req: a.req, can: a.can, scope, principal: who, timezone: a.timezone || 'UTC' };
       for (const [i, call] of plan.calls.entries()) {
         const tool = catalogue.byId(call.tool);
-        const words = tool.describe(call.args);
+        // ROUND 2 STARTS ONLY WHEN ROUND 1 IS WHOLE: a failed, absent or ambiguous round-1 result answers on its own below.
+        if (call.refs && results.some((r) => r.outcome !== 'ok')) break;
+        let args = call.args;
+        let unresolved = null;
+        let ambiguousRef = false;
+        if (call.refs) {
+          const res = catalogue.resolveCall(call, results, tools, { isPublicId });
+          if (res.error) { unresolved = res.error; ambiguousRef = !!res.ambiguous; } else args = res.args;
+        }
+        let words;
+        try { words = tool.describe(unresolved ? Object.fromEntries(Object.keys(tool.args).map((k) => [k, call.refs[k] ? null : args[k]])) : args); } catch (_) { words = 'Looking that up'; }
         step({ n: i + 1, words: `${words}…`, state: 'run' });
         const t0 = Date.now();
         let result;
         // DEFENCE IN DEPTH: validatePlan already refused a tool outside this request's catalogue; no path into a tool
         // skips its page permissions, whatever validated the call.
         if (!catalogue.mayUse(a.can, tool)) result = { outcome: 'not_found', count: 0, rows: [], extras: [], facts: {}, words };
-        else {
+        else if (unresolved) {
+          logger.warn(`Ask ${row.public_id}: look-up ${i + 1}'s earlier result could not be read (${unresolved})`);
+          result = { outcome: ambiguousRef ? 'ambiguous' : 'not_found', count: 0, rows: [], extras: [], facts: {}, words, ...(ambiguousRef ? { candidates: [] } : {}) };
+        } else {
           try {
-            result = await tool.run(ctx, call.args);
+            result = await tool.run(ctx, args);
           } catch (e) {
             logger.error(`Ask ${row.public_id}: ${tool.id} failed — ${e && e.stack ? e.stack : e}`);
             result = { outcome: 'error', count: 0, rows: [], extras: [], facts: {}, words };
@@ -193,9 +243,10 @@ function createRun(o) {
         result.tool = tool.id;
         const ms = Date.now() - t0;
         results.push(result);
+        const refs = [...new Set((result.rows || []).map((x) => x && x.ref).filter((x) => typeof x === 'string' && isPublicId(x)))].slice(0, MAX_REFS);
         lookups.push({ n: i + 1, tool: tool.id, words: result.words, outcome: result.outcome, count: result.count,
-          href: result.href || null, ms, label: result.label || null });
-        await o.invoke(model, 'addCall', row.id, { position: i + 1, tool: tool.id, args: call.args, outcome: result.outcome,
+          href: result.href || null, ms, label: result.label || null, round: call.refs ? 2 : 1, refs });
+        await o.invoke(model, 'addCall', row.id, { position: i + 1, tool: tool.id, args, outcome: result.outcome,
           row_count: (result.rows || []).length, ms });
         step({ n: i + 1, words: `${result.words}…`, state: 'done' });
       }
@@ -215,7 +266,7 @@ function createRun(o) {
       // ── 3 ANSWER — fenced results, a strict schema, no tools ───────────────────────────────────────────────────────
       step({ n: results.length + 1, words: 'Writing the answer…', state: 'run' });
       t = Date.now();
-      const m = prompts.answerMessages(question, results);
+      const m = prompts.answerMessages(question, results, { mode });
       const answered = await deps.complete({
         system: m.system,
         messages: [{ role: 'user', content: m.user }],
@@ -230,7 +281,7 @@ function createRun(o) {
       step({ n: results.length + 1, words: 'Writing the answer…', state: 'done' });
 
       // ── 4 CHECK ────────────────────────────────────────────────────────────────────────────────────────────────────
-      const verdict = check.checkAnswer(answered.json, results);
+      const verdict = check.checkAnswer(answered.json, results, { mode, question });
       if (!verdict.ok) {
         logger.warn(`Ask ${row.public_id}: answer withheld (${verdict.reason})`);
         const raw = answered.json && typeof answered.json.answer === 'string' ? answered.json.answer : null;
@@ -263,4 +314,4 @@ function createRun(o) {
   return { ask, cleanQuestion, quotesOf, WORDS, MAX_QUESTION };
 }
 
-module.exports = { createRun, cleanQuestion, quotesOf, MAX_QUESTION, WORD_KEYS, BUSY_KINDS };
+module.exports = { createRun, cleanQuestion, quotesOf, MAX_QUESTION, WORD_KEYS, OPTIONAL_WORD_KEYS, UNAVAILABLE, BUSY_KINDS };

package/lib/store.js

@@ -33,8 +33,12 @@ 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; } };
 
+// WHY A PLAN SAID "none" (0.2.0) — stored in the `result` JSON the row already has (`noneReason`), so no column moves.
+const NONE_REASONS = Object.freeze(['no_tool', 'out_of_scope', 'needs_judgement']);
+
 function hydrate(r) {
   if (!r) return null;
+  const result = parse(r.result);
   return {
     ...r,
     id: Number(r.id),
@@ -44,7 +48,8 @@ function hydrate(r) {
     tokens: Number(r.tokens) || 0,
     ms: Number(r.ms) || 0,
     rating: r.rating == null ? null : Number(r.rating),
-    result: parse(r.result)
+    result,
+    none_reason: result && NONE_REASONS.includes(result.noneReason) ? result.noneReason : null
   };
 }
 
@@ -75,7 +80,7 @@ function createAskQuestionModel(o) {
   const WIDE = 'retention is installation-wide';
 
   return {
-    OUTCOMES, CALL_OUTCOMES, REASONS,
+    OUTCOMES, CALL_OUTCOMES, REASONS, NONE_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 }) {
@@ -197,6 +202,31 @@ function createAskQuestionModel(o) {
       return Number(r.changes || 0) > 0;
     },
 
+    /**
+     * THE QUESTIONS ASK COULD NOT PLAN (0.2.0), newest first, with the planner's reason (`none_reason`: no_tool,
+     * out_of_scope, needs_judgement; null for a row written before 0.2.0) — Admin → AI's list of what people asked that no
+     * tool answers. PLATFORM ONLY (every partner's rows). `reason` filters on the stored reason (read from `result`).
+     */
+    async noneList({ reason = null, partner_id = null, limit = 200 } = {}) {
+      platformOnly('noneList', FLEET);
+      if (reason != null && !NONE_REASONS.includes(reason)) throw new TypeError(`AskQuestion.noneList: unknown reason ${JSON.stringify(reason)}`);
+      const n = Math.min(Math.max(intOf(limit), 1), 500);
+      const where = ["q.outcome = 'cannot'"];
+      const params = [];
+      if (partner_id != null) { where.push('q.partner_id = ?'); params.push(Number(partner_id)); }
+      // PAGED AT THE DATABASE (fix round of PR #15): the reason is matched in the stored JSON text with LIKE (the run
+      // writes it with JSON.stringify, so it reads "noneReason":"<reason>"), `_` escaped; re-checked here after parsing.
+      if (reason != null) { where.push("q.result LIKE ? ESCAPE '\\'"); params.push(`%"noneReason":"${reason.replace(/_/g, '\\_')}"%`); }
+      const rows = (await d().all(
+        `SELECT q.id, q.public_id, q.partner_id, p.name AS partner_name, q.asked_by_name, q.acting, q.context_kind, q.question,
+                q.outcome, q.result, q.created_at
+           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);
+      return (reason == null ? rows : rows.filter((r) => r.none_reason === reason)).slice(0, n).map(({ result, ...r }) => r);
+    },
+
     /** RETENTION: delete every question created before `cut` (UTC), in every partner; look-ups cascade. PLATFORM ONLY. */
     async purgeBefore(cut) {
       platformOnly('purgeBefore', WIDE);
@@ -215,4 +245,4 @@ function createAskQuestionModel(o) {
   };
 }
 
-module.exports = { createAskQuestionModel, OUTCOMES, CALL_OUTCOMES, REASONS };
+module.exports = { createAskQuestionModel, OUTCOMES, CALL_OUTCOMES, REASONS, NONE_REASONS };

package/lib/text.js

@@ -0,0 +1,118 @@
+/**
+ * THE SHARED TEXT HELPER (0.2.0) for an app's search tools (a desk's tickets.search, a soc's events.search): the words of
+ * a query for AND/OR matching, a LIKE clause over the app's own columns, a capped snippet around the first match, and the
+ * path that marks snippets as ATTACKER TEXT. The app keeps its own query, its scope and its permissions; this file only
+ * turns the planner's query argument into terms and the matched text into a short, safe excerpt.
+ *
+ *   const { text } = require('@aria-framework/ask');
+ *   const q = text.searchTerms(args.query);              // { op: 'and' | 'or', terms: ['printer', 'jam'] } or null
+ *   const w = text.likeClause(['t.subject', 't.body'], q); // { sql: "(lower(t.subject) LIKE ? ESCAPE '\\' OR …) AND (…)", params }
+ *   rows.map((r) => ({ ref, title, fields: { snippet: text.snippet(r.body, q) } }))
+ *   attackerFields: text.withSnippets(['rows[].title'])   // + 'rows[].fields.snippet'
+ *
+ * A SNIPPET IS ATTACKER TEXT, ALWAYS: somebody other than the asker typed it. The check reads every path ending in
+ * `.snippet` as an attacker path whether or not the tool lists it (check.js), a snippet can never be a round-2 output
+ * (catalogue.js), and the bench plants its payloads there when the tool lists it (withSnippets).
+ */
+
+'use strict';
+
+const MAX_TERMS = 8;
+const MAX_SNIPPET = 160;
+const SNIPPET_FIELD = 'snippet';
+const SNIPPET_PATH = `rows[].fields.${SNIPPET_FIELD}`;
+// A term: letters and digits, with . _ - @ inside (an address or a host), NFKC and lower-cased.
+const TERM = /[\p{L}\p{N}](?:[\p{L}\p{N}._@-]*[\p{L}\p{N}])?/gu;
+const clean = (t) => String(t == null ? '' : t).normalize('NFKC').replace(/[\u0000-\u001f\u007f\p{Cf}]+/gu, ' ');
+
+/**
+ * The words of a query. "printer jam" is AND; "printer OR scanner" ("or" in any case, or a "|") is OR — one operator for
+ * the whole query. A mixed query ("printer jam or scanner") is AND over every term. Terms under `minLength` are dropped, duplicates once, at most
+ * `max`. Returns null for a query with no term (the tool answers not_found, never "everything").
+ * @param {string} q
+ * @param {{max?: number, minLength?: number}} [o]
+ */
+function searchTerms(q, o = {}) {
+  const max = Math.min(Math.max(Number(o.max) || MAX_TERMS, 1), 16);
+  const minLength = Math.max(Number(o.minLength) || 2, 1);
+  const raw = clean(q);
+  // "or" (any case) and "|" separate OR parts. A MIXED query ("printer jam or scanner": a part of two terms) is ANDed —
+  // the narrower reading, so a query never widens to rows matching one word of it (fix round of PR #15).
+  const parts = raw.split(/\s+or\s+|\s*\|\s*/i);
+  let op = parts.length > 1 ? 'or' : 'and';
+  if (op === 'or' && parts.some((p) => (p.toLowerCase().match(TERM) || []).filter((t) => t.length >= minLength).length > 1)) op = 'and';
+  const terms = [];
+  for (const p of parts) {
+    for (const m of p.toLowerCase().matchAll(TERM)) {
+      const t = m[0];
+      if (t.length >= minLength && !terms.includes(t)) terms.push(t);
+      if (terms.length >= max) break;
+    }
+    if (terms.length >= max) break;
+  }
+  return terms.length ? { op, terms } : null;
+}
+
+/** A term as a LIKE pattern: %, _ and \ escaped (ESCAPE '\'), wrapped in %…%. */
+const likeOf = (term) => `%${String(term).replace(/[\\%_]/g, (c) => `\\${c}`)}%`;
+
+/**
+ * A WHERE fragment over the app's own columns: each term must match (AND) — or any term (OR) — in at least one column,
+ * compared lower-cased. Column names are the APP's (validated as identifiers, never from the request). Works on SQLite and
+ * Postgres. Returns { sql, params }; an empty query is refused (throws), so a tool cannot widen to "every row".
+ * @param {string[]} columns e.g. ['t.subject', 't.body']
+ * @param {{op, terms}} q    searchTerms' result
+ */
+function likeClause(columns, q) {
+  if (!Array.isArray(columns) || !columns.length || columns.some((c) => typeof c !== 'string' || !/^[a-z_][a-z0-9_]*(?:\.[a-z_][a-z0-9_]*)?$/i.test(c))) {
+    throw new Error('ask text: likeClause needs the app\'s column names (identifiers)');
+  }
+  if (!q || !Array.isArray(q.terms) || !q.terms.length) throw new Error('ask text: likeClause needs at least one term');
+  const params = [];
+  const one = (t) => `(${columns.map((c) => { params.push(likeOf(t)); return `lower(${c}) LIKE ? ESCAPE '\\'`; }).join(' OR ')})`;
+  const sql = q.terms.map(one).join(q.op === 'or' ? ' OR ' : ' AND ');
+  return { sql: `(${sql})`, params };
+}
+
+/** Does this text match the query (in memory, the same rule as likeClause)? */
+function matches(t, q) {
+  if (!q || !q.terms || !q.terms.length) return false;
+  const s = clean(t).toLowerCase();
+  return q.op === 'or' ? q.terms.some((x) => s.includes(x)) : q.terms.every((x) => s.includes(x));
+}
+
+/**
+ * A SNIPPET: at most `max` characters (default 160, never over 500) of `t` around the first match of any term, cut at word
+ * boundaries, with "…" where it was cut, control and format characters as spaces and whitespace collapsed. No match: the
+ * start of the text. Empty → null. The result is attacker text (see the header).
+ */
+function snippet(t, q, o = {}) {
+  const max = Math.min(Math.max(Number(o.max) || MAX_SNIPPET, 20), 500);
+  const s = clean(t).replace(/\s+/g, ' ').trim();
+  if (!s) return null;
+  if (s.length <= max) return s;
+  // Found in the ORIGINAL text, case-blind, so case folding that changes a string's length (İ) never moves the index.
+  let at = -1;
+  for (const term of (q && q.terms) || []) {
+    const m = new RegExp(term.replace(/[.*+?^${}()|[\]\\]/g, (c) => `\\${c}`), 'iu').exec(s);
+    if (m && (at < 0 || m.index < at)) at = m.index;
+  }
+  if (at < 0) at = 0;
+  let start = Math.max(0, at - Math.floor(max / 3));
+  let end = Math.min(s.length, start + max - 2);
+  start = Math.max(0, end - (max - 2));
+  if (start > 0) { const sp = s.indexOf(' ', start); if (sp >= 0 && sp < at) start = sp + 1; }
+  if (end < s.length) { const sp = s.lastIndexOf(' ', end); if (sp > Math.max(start, at)) end = sp; }
+  return `${start > 0 ? '…' : ''}${s.slice(start, end).trim()}${end < s.length ? '…' : ''}`;
+}
+
+/** attackerFields with the snippet path added (once). */
+const withSnippets = (fields = [], field = SNIPPET_FIELD) => {
+  const path = `rows[].fields.${field}`;
+  return fields.includes(path) ? [...fields] : [...fields, path];
+};
+
+/** Is this result path a snippet — attacker text whatever the tool lists? */
+const isSnippetPath = (path) => /(?:^|\.)snippet$/.test(String(path));
+
+module.exports = { searchTerms, likeClause, likeOf, matches, snippet, withSnippets, isSnippetPath, SNIPPET_FIELD, SNIPPET_PATH, MAX_TERMS, MAX_SNIPPET };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aria-framework/ask",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "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,