@aria-framework/ask 0.1.1 → 0.2.0

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.1",
+  "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,

package/views/ask/admin.ejs

@@ -51,7 +51,7 @@
         </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>
+        <p class="small mb-2"><span class="tagpill sm">Running</span> <%= benchState.endpoint || 'starting' %> · <span data-bench-eta><%= benchLine %></span> (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>
@@ -79,7 +79,7 @@
               <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>
+                  <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.reached) { %> · <span class="text-danger"><%= e.bench.reached %> attacker-planted addresses reached the person</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>
                   <% } %>

package/views/ask/none.ejs

@@ -0,0 +1,56 @@
+<% 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) %>
+
+  <%# QUESTIONS ASK COULD NOT ANSWER (@aria-framework/ask 0.2.0): every question whose plan said "none", with the planner's
+      reason — no tool covers it, it is not about these records, or it asks for a judgement. For the platform
+      (ai_config.view): every partner's rows, with a Partner filter. Question text AS TYPED, escaped, as data. Rows go when
+      the question's retention ends. App locals used: whenTag; askLayout and askReviewBase are optional. %>
+
+  <div class="card mb-3"><div class="card-body">
+    <h6 class="card-title">Questions Ask could not answer <span class="cnt"><%= rows.length %></span></h6>
+    <p class="small text-body-secondary">What people asked that no look-up answers, and why the planner said so. <a href="<%= _base %>">Answers marked not helpful →</a></p>
+    <form method="GET" action="<%= _base %>/none" class="row g-2 align-items-end mb-3">
+      <div class="col-auto">
+        <label class="form-label small" for="nn-partner">Partner</label>
+        <select class="form-select form-select-sm" id="nn-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="nn-reason">Reason</label>
+        <select class="form-select form-select-sm" id="nn-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"><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 questions Ask could not answer<%= reason ? ' for this reason' : '' %>.</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>Page</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><%= r.question %></td>
+            <td class="small"><%= r.context_kind || '—' %></td>
+            <td class="small" data-none-reason="<%= r.none_reason || '' %>"><%= r.reasonWords %></td>
+          </tr>
+        <% }) %>
+        </tbody>
+      </table></div>
+    <% } %>
+  </div></div>
+
+<%- include(_L.foot) %>

package/views/ask/review.ejs

@@ -12,6 +12,7 @@
 
   <div class="card mb-3"><div class="card-body">
     <h6 class="card-title">Questions marked not helpful <span class="cnt"><%= rows.length %></span></h6>
+    <p class="small text-body-secondary"><a href="<%= _base %>/none">Questions Ask could not answer, and why →</a></p>
     <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>