@aria-framework/ai 0.1.0

package/browser/ai-polish.js

@@ -0,0 +1,199 @@
+/**
+ * @aria-framework/ai — browser polish widget.
+ *
+ * Data-attribute driven so it works on any surface without knowing the app. Mark a group:
+ *
+ *   <div data-ai-polish
+ *        data-ai-polish-endpoint="/admin/kb/ai/polish"
+ *        data-ai-polish-target="#kb-body"           (CSS selector for the textarea; or a <textarea> inside)
+ *        data-ai-polish-extra='{"kind":"reply"}'>   (optional extra POST fields, JSON)
+ *     <button data-polish="fix">Fix</button>
+ *     <button data-polish="rephrase" data-polish-tone="simpler">Simpler</button>
+ *     <div data-ai-polish-panel></div>              (where the proposal renders; or one inside the group)
+ *   </div>
+ *
+ * It PROPOSES: pressing a button posts the target's text and renders a word-level diff with
+ * Accept / Reject. Accept writes the target and fires input+blur (so any autosave picks it up). A
+ * rewrite the server marked `blocked` (the fact-guard tripped) cannot be accepted.
+ *
+ * Served by the consuming app like @aria-framework/theme serves theme-init.js. CSP-safe: no inline
+ * JS, and model output only ever reaches the DOM through textContent.
+ */
+(function () {
+  'use strict';
+
+  var tokenMeta = document.querySelector('meta[name="csrf-token"]');
+  var TOKEN = tokenMeta ? tokenMeta.getAttribute('content') : '';
+
+  function clear(el) { while (el.firstChild) el.removeChild(el.firstChild); }
+
+  function targetOf(group) {
+    var sel = group.getAttribute('data-ai-polish-target');
+    return (sel && document.querySelector(sel)) || group.querySelector('textarea') || null;
+  }
+  function panelOf(group) {
+    var sel = group.getAttribute('data-ai-polish-panel');
+    return (sel && document.querySelector(sel)) || group.querySelector('[data-ai-polish-panel]') || null;
+  }
+  function extraOf(group) {
+    try { return JSON.parse(group.getAttribute('data-ai-polish-extra') || '{}'); } catch (e) { return {}; }
+  }
+
+  function note(panel, text, bad) {
+    if (!panel) return;
+    clear(panel);
+    var d = document.createElement('div');
+    d.className = 'small mt-2 ' + (bad ? 'text-danger' : 'text-muted');
+    d.textContent = text;
+    panel.appendChild(d);
+  }
+
+  /** Word-level LCS diff. Char-level marks half a corrected word; sentence-level marks a paragraph. */
+  function diffWords(before, after) {
+    var a = String(before).split(/(\s+)/);
+    var b = String(after).split(/(\s+)/);
+    var n = a.length, m = b.length;
+    if (n * m > 1200000) return null;                 // guard the quadratic table on a huge rewrite
+    var lcs = [];
+    for (var i = 0; i <= n; i++) lcs.push(new Uint32Array(m + 1));
+    for (i = n - 1; i >= 0; i--) {
+      for (var j = m - 1; j >= 0; j--) {
+        lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+      }
+    }
+    var out = []; i = 0; j = 0;
+    while (i < n && j < m) {
+      if (a[i] === b[j]) { out.push({ t: 'same', v: a[i] }); i++; j++; }
+      else if (lcs[i + 1][j] >= lcs[i][j + 1]) { out.push({ t: 'del', v: a[i] }); i++; }
+      else { out.push({ t: 'ins', v: b[j] }); j++; }
+    }
+    while (i < n) { out.push({ t: 'del', v: a[i] }); i++; }
+    while (j < m) { out.push({ t: 'ins', v: b[j] }); j++; }
+    return out;
+  }
+
+  function renderDiff(before, after) {
+    var pre = document.createElement('div');
+    pre.className = 'border rounded p-2 small';
+    pre.style.whiteSpace = 'pre-wrap';
+    pre.style.maxHeight = '40vh';
+    pre.style.overflow = 'auto';
+    var parts = diffWords(before, after);
+    if (!parts) { pre.textContent = after; return pre; }
+    parts.forEach(function (p) {
+      if (p.t === 'same') { pre.appendChild(document.createTextNode(p.v)); return; }
+      var el = document.createElement(p.t === 'del' ? 'del' : 'ins');
+      el.className = p.t === 'del' ? 'polish-del' : 'polish-ins';
+      el.textContent = p.v;
+      pre.appendChild(el);
+    });
+    return pre;
+  }
+
+  function render(group, panel, data, original) {
+    var target = targetOf(group);
+    clear(panel);
+    var card = document.createElement('div');
+    card.className = 'card mt-2 border-primary';
+    var body = document.createElement('div');
+    body.className = 'card-body py-2 px-3';
+    card.appendChild(body);
+
+    var head = document.createElement('div');
+    head.className = 'd-flex flex-wrap align-items-center gap-2 mb-2';
+    var title = document.createElement('span');
+    title.className = 'small fw-semibold text-primary';
+    title.textContent = 'Proposed — ' + data.label;
+    head.appendChild(title);
+
+    var actions = document.createElement('span');
+    actions.className = 'ms-auto d-flex gap-2';
+    var accept = document.createElement('button');
+    accept.type = 'button'; accept.className = 'btn btn-sm btn-primary'; accept.textContent = 'Accept';
+    var reject = document.createElement('button');
+    reject.type = 'button'; reject.className = 'btn btn-sm btn-outline-secondary'; reject.textContent = 'Reject';
+    actions.appendChild(accept); actions.appendChild(reject);
+    head.appendChild(actions);
+    body.appendChild(head);
+
+    body.appendChild(renderDiff(original, data.rewritten));
+
+    // The guard's verdict: a blocked rewrite cannot be accepted, not merely discouraged.
+    if (data.blocked) {
+      accept.disabled = true;
+      accept.classList.remove('btn-primary');
+      accept.classList.add('btn-outline-danger');
+      var warn = document.createElement('div');
+      warn.className = 'small text-danger mt-2';
+      warn.textContent = data.blockedReason;
+      body.appendChild(warn);
+    }
+
+    var meta = document.createElement('div');
+    meta.className = 'small text-muted mt-2';
+    var bits = (data.changes || []).slice(0, 4);
+    if (!data.blocked && bits.length) bits.push('facts checked');
+    meta.textContent = bits.join(' · ') + (bits.length ? ' · ' : '') +
+      data.model + ' · ' + (data.ms / 1000).toFixed(1) + 's · ' + data.tokens + ' tokens';
+    body.appendChild(meta);
+
+    if (data.unchanged) {
+      var same = document.createElement('div');
+      same.className = 'small text-muted';
+      same.textContent = 'The model returned the same text — nothing to change.';
+      body.appendChild(same);
+    }
+
+    panel.appendChild(card);
+
+    accept.addEventListener('click', function () {
+      if (!target || accept.disabled) return;
+      target.value = data.rewritten;
+      target.dispatchEvent(new Event('input', { bubbles: true }));   // straight into any autosave
+      target.dispatchEvent(new Event('blur', { bubbles: true }));
+      clear(panel);
+      target.focus();
+    });
+    reject.addEventListener('click', function () { clear(panel); if (target) target.focus(); });
+  }
+
+  var busy = new WeakMap();
+
+  function run(group, btn) {
+    var endpoint = group.getAttribute('data-ai-polish-endpoint');
+    var target = targetOf(group);
+    var panel = panelOf(group);
+    if (!endpoint || !target || !panel) return;
+
+    var mode = btn.getAttribute('data-polish');
+    var tone = btn.getAttribute('data-polish-tone') || '';
+    var original = target.value;
+    if (!original.trim()) return note(panel, 'Write something first — there is nothing to polish yet.', true);
+    if (busy.get(group)) return;
+    busy.set(group, true);
+
+    var label = tone ? tone.charAt(0).toUpperCase() + tone.slice(1)
+      : mode.charAt(0).toUpperCase() + mode.slice(1);
+    note(panel, 'Polishing… a local model can take a few seconds.');
+
+    var fields = Object.assign({ mode: mode, tone: tone, text: original, _csrf: TOKEN }, extraOf(group));
+    fetch(endpoint, {
+      method: 'POST', credentials: 'same-origin',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'x-csrf-token': TOKEN },
+      body: new URLSearchParams(fields)
+    })
+      .then(function (r) { return r.json(); })
+      .then(function (data) {
+        if (!data.ok) return note(panel, data.error || 'The rewrite failed.', true);
+        render(group, panel, Object.assign({ label: label }, data), original);
+      })
+      .catch(function () { note(panel, 'The rewrite could not be requested.', true); })
+      .then(function () { busy.set(group, false); });
+  }
+
+  Array.prototype.forEach.call(document.querySelectorAll('[data-ai-polish]'), function (group) {
+    Array.prototype.forEach.call(group.querySelectorAll('[data-polish]'), function (btn) {
+      btn.addEventListener('click', function () { run(group, btn); });
+    });
+  });
+})();

package/error.js

@@ -0,0 +1,78 @@
+/**
+ * One error type for everything the AI layer can fail at.
+ *
+ * WHY IT EXISTS: every caller of this layer is a page render or a background job, and neither may
+ * die because a model was slow or a laptop had LM Studio closed. A typed error with a sentence
+ * somebody can act on is what lets the ticket page say "unavailable" and carry on — the same
+ * discipline the email provider already follows when SMTP is not configured.
+ *
+ * `kind` is for code, `message` is for a person. Nothing here leaks a URL, a key or a stack into
+ * the message: this text reaches an admin screen.
+ */
+
+'use strict';
+
+/** @typedef {'disabled'|'unconfigured'|'unreachable'|'timeout'|'auth'|'rate_limit'|'bad_response'|'refused'} AiErrorKind */
+
+class AiError extends Error {
+  /**
+   * @param {AiErrorKind} kind
+   * @param {string} message  written for the admin screen, not the log
+   * @param {{cause?: Error, status?: number}} [opts]
+   */
+  constructor(kind, message, opts = {}) {
+    super(message);
+    this.name = 'AiError';
+    this.kind = kind;
+    this.status = opts.status || null;
+    if (opts.cause) this.cause = opts.cause;
+  }
+
+  /** True when trying again later might work — the job runner uses this to decide on a retry. */
+  get retryable() {
+    return this.kind === 'unreachable' || this.kind === 'timeout' || this.kind === 'rate_limit';
+  }
+}
+
+/**
+ * Turn whatever fetch threw into something with a sentence in it.
+ *
+ * Node's fetch reports a refused connection as a bare `TypeError: fetch failed` with the real cause
+ * nested underneath, which is useless on a screen. The common case here — LM Studio simply not
+ * running — deserves to say so.
+ */
+function fromFetchFailure(err, { label, url }) {
+  if (err && err.name === 'AbortError') {
+    return new AiError('timeout', `${label} did not answer in time.`, { cause: err });
+  }
+  const code = (err && err.cause && err.cause.code) || (err && err.code) || '';
+  if (code === 'ECONNREFUSED' || code === 'ERR_CONNECTION_REFUSED') {
+    return new AiError('unreachable',
+      `Nothing is listening at ${url}. If this is LM Studio, check the local server is started.`,
+      { cause: err });
+  }
+  if (code === 'ENOTFOUND' || code === 'EAI_AGAIN') {
+    return new AiError('unreachable', `${url} could not be resolved.`, { cause: err });
+  }
+  return new AiError('unreachable', `${label} could not be reached: ${code || 'connection failed'}.`,
+    { cause: err });
+}
+
+/**
+ * Strip a secret out of text that is about to become a message.
+ *
+ * FOUND BY SABOTAGE. Both adapters put the provider's own error text into the message they raise,
+ * and a provider is entitled to quote your key back at you — Anthropic's 400 and 500 bodies do
+ * exactly that. Those messages are rendered on an admin screen and pasted into support threads, so
+ * the key would travel with them.
+ *
+ * Redacting at the point the message is built covers every path at once, rather than each branch
+ * being trusted to remember.
+ */
+function redact(text, secret) {
+  const t = String(text == null ? '' : text);
+  if (!secret || String(secret).length < 8) return t;
+  return t.split(String(secret)).join('***');
+}
+
+module.exports = { AiError, fromFetchFailure, redact };

package/facts.js

@@ -0,0 +1,133 @@
+/**
+ * The guard that makes rewriting safe. It is arithmetic, not a prompt.
+ *
+ * A rewrite may change every word and must change no FACT. Asking a model politely to leave figures
+ * alone is not a control — it is a hope with good manners. So the two versions are compared for the
+ * things that carry meaning on a support ticket, and anything that went missing blocks the accept
+ * and gets named.
+ *
+ * WHAT COUNTS AS A FACT here is deliberately narrow: values a customer could act on or dispute — an
+ * amount, a date, an order number, a link, an address. Prose is what the agent asked to have
+ * changed; these are not.
+ *
+ * ONE-WAY. Only losses matter. A rewrite that ADDS "Tuesday" where the original said "the 18th" is
+ * a judgement call for the reader; a rewrite that drops the 18th is a defect. Flagging additions
+ * would block almost every legitimate tidy.
+ */
+
+'use strict';
+
+/**
+ * Each kind is a name and a pattern. The name is what the agent is shown, so it is written for
+ * them: "amount", not "currency-like numeric token".
+ */
+const KINDS = [
+  // Ticket references, first — 89A0-3EYW-A4H5 and the shorter forms staff type in notes. Before
+  // the number rule, so a reference is reported as a reference rather than as three numbers.
+  { name: 'ticket reference', re: /\b[0-9A-Z]{4}(?:-[0-9A-Z]{4}){1,3}\b/g },
+  { name: 'email address', re: /\b[^\s@]+@[^\s@.]+\.[^\s@]+\b/g },
+  { name: 'link', re: /\bhttps?:\/\/[^\s<>"')]+/gi },
+  // Money with its symbol attached, so R1200 and 1200 are not treated as the same fact.
+  //
+  // BEFORE `reference`, and that order is the whole point rather than a tidy-up. `R1200` is five
+  // [A-Z0-9] characters containing both a letter and a digit, so the reference rule matched it
+  // first and blanked it — while `R1 200`, the same amount written with a space, matched the
+  // amount rule instead. The same money was classified two different ways depending only on
+  // spacing, and compare() therefore reported it as a LOST AMOUNT:
+  //
+  //     compare('Refund R1 200 to order REQ18590', 'We will refund R1200 for REQ18590')
+  //       -> { ok: false, lost: [{ kind: 'amount', value: 'R1200' }] }
+  //
+  // polish() then set blocked = true and the Accept button was disabled — on a rewrite that had
+  // kept every fact. Normalising `R1 200` to `R1200` is exactly what Tidy and Rephrase do, so the
+  // guard was most reliably blocking its own most common legitimate output.
+  //
+  // THE LOOKBEHIND IS THE FIX, NOT THE RULE ORDER. Reordering amount ahead of reference (the
+  // previous attempt) traded one wrong classification for a worse one: with /i and no boundary,
+  // the currency letter matched MID-TOKEN, so `SR12345` was consumed as the amount `R12345` and
+  // `TAGEUR2024` as `EUR2024` — and because extract() blanks its matches, compare() then WAIVED a
+  // rewrite that corrupted `SR12345` into `R12345`, which is the guard approving the exact damage
+  // it exists to block. `(?<![A-Za-z0-9])` requires the currency token to start a token.
+  //
+  // NOT `\b`, deliberately: `$`, `£` and `€` are non-word characters, so after a space there is no
+  // word boundary before them and `\b` would silently kill all three symbol currencies.
+  { name: 'amount', re: /(?<![A-Za-z0-9])(?:R|ZAR|\$|£|€|USD|EUR|GBP)\s?\d[\d\s.,]*\d|(?<![A-Za-z0-9])\d[\d\s.,]*\d\s?(?:ZAR|USD|EUR|GBP)(?![A-Za-z0-9])/gi },
+  // Any OTHER identifier: uppercase, mixing letters with digits. That is what REQ18590, 7F2C and
+  // A4H5 have in common and what ordinary words do not — so the references people actually type in
+  // notes are guarded without every capitalised word being flagged. Sits after the email, link and
+  // amount rules so it cannot bite a chunk out of any of them. This comment used to claim it sat
+  // after the link rule while the code had it before — the order now matches the description.
+  { name: 'reference', re: /\b(?=[A-Z0-9]*\d)(?=[A-Z0-9]*[A-Z])[A-Z0-9]{3,}\b/g },
+  { name: 'date', re: /\b\d{1,4}[/-]\d{1,2}[/-]\d{1,4}\b/g },
+  // Everything else numeric. Runs of digits, so "18 Aug" keeps its 18 and a version like 3.5 stays
+  // one token rather than becoming two.
+  { name: 'number', re: /\b\d+(?:\.\d+)?\b/g }
+];
+
+/**
+ * Pull the facts out of a piece of text.
+ *
+ * Matched kinds are BLANKED OUT as they are found, so a later pattern cannot re-match part of an
+ * earlier one — without that, the ticket reference 89A0-3EYW-A4H5 would also be reported as the
+ * numbers 89, 0, 3 and 4.
+ */
+function extract(text) {
+  let rest = String(text == null ? '' : text);
+  const found = [];
+  for (const kind of KINDS) {
+    rest = rest.replace(new RegExp(kind.re.source, kind.re.flags), (match) => {
+      found.push({ kind: kind.name, value: normalise(kind.name, match) });
+      return ' '.repeat(match.length);
+    });
+  }
+  return found;
+}
+
+/**
+ * Comparable form. Case and internal spacing are not facts — `R1 200` and `r1200` are the same
+ * amount, and blocking on that would train people to ignore the warning.
+ */
+function normalise(kind, value) {
+  const v = String(value).trim();
+  if (kind === 'email address' || kind === 'link') return v.toLowerCase().replace(/[.,;:)]+$/, '');
+  if (kind === 'amount') return v.toUpperCase().replace(/\s+/g, '').replace(/,/g, '');
+  return v.toUpperCase();
+}
+
+/**
+ * What the rewrite lost.
+ *
+ * MULTISET, not a set: a note that says "two 24-port switches" and comes back saying "two 24-port
+ * switches" once has lost something, and comparing unique values alone would miss it.
+ *
+ * @returns {{ok: boolean, lost: Array<{kind: string, value: string}>}}
+ */
+/** A separator that cannot occur inside a value. Written as an escape: the literal byte is
+ * invisible in an editor and makes every text tool treat this file as binary. */
+const SEP = '\u0000';
+
+function compare(before, after) {
+  const remaining = new Map();
+  for (const f of extract(after)) {
+    const key = f.kind + SEP + f.value;
+    remaining.set(key, (remaining.get(key) || 0) + 1);
+  }
+
+  const lost = [];
+  for (const f of extract(before)) {
+    const key = f.kind + SEP + f.value;
+    const left = remaining.get(key) || 0;
+    if (left > 0) remaining.set(key, left - 1);
+    else lost.push(f);
+  }
+  return { ok: lost.length === 0, lost };
+}
+
+/** "the number 24 and the ticket reference 7F2C" — for the sentence an agent reads. */
+function describe(lost) {
+  const parts = lost.map((f) => `the ${f.kind} ${f.value}`);
+  if (parts.length <= 1) return parts[0] || '';
+  return parts.slice(0, -1).join(', ') + ' and ' + parts[parts.length - 1];
+}
+
+module.exports = { extract, compare, describe, KINDS };

package/generate.js

@@ -0,0 +1,42 @@
+/**
+ * Generate — one schema-constrained JSON generation, as a thin, prompt-agnostic wrapper over
+ * complete(). This is the seam a "draft from a topic" feature sits on: the app supplies the system
+ * and user prompts and the JSON schema (all content); this handles the call, the budget and the
+ * token sizing.
+ *
+ * UNLIKE polish, there is no fact-guard here — there is no source text to preserve. A generator
+ * INVENTS, so the discipline against fabrication has to live in the caller's prompt (e.g. "leave a
+ * [specify …] placeholder rather than guess a version number").
+ */
+
+'use strict';
+
+const { AiError } = require('./error');
+
+/**
+ * @param {(opts:object, cfg?:object) => Promise<object>} complete  the client's complete()
+ * @param {{system?:string, user:string, schema:object, maxTokens?:number, temperature?:number,
+ *          ticketId?:*, signal?:AbortSignal}} opts
+ * @returns {Promise<{json:object|null, model, ms, usage, truncated:boolean}>}
+ */
+async function generate(complete, opts) {
+  if (!opts || !opts.schema) throw new AiError('refused', 'generate() requires a schema.');
+  const result = await complete({
+    system: opts.system || '',
+    messages: [{ role: 'user', content: String(opts.user == null ? '' : opts.user) }],
+    maxTokens: opts.maxTokens || 1500,
+    temperature: opts.temperature == null ? 0.3 : opts.temperature,
+    schema: opts.schema,
+    signal: opts.signal,
+    ticketId: opts.ticketId || null
+  });
+  return {
+    json: result.json || null,
+    model: result.model,
+    ms: result.ms,
+    usage: result.usage,
+    truncated: !!result.truncated
+  };
+}
+
+module.exports = { generate };

package/index.js

@@ -0,0 +1,181 @@
+/**
+ * @aria-framework/ai — the AI seam. One `complete()`, several providers behind it, plus the
+ * writing-assist engines (polish/generate) and the fact-preservation guard.
+ *
+ * DEPENDENCY-INJECTED, DATABASE-FREE. The package knows how to talk to a model; it does NOT know
+ * where an app keeps its settings, its credentials or its token ledger. The consumer builds a
+ * client with two functions of its own:
+ *
+ *   const ai = createAiClient({
+ *     resolveConfig,   // async () => resolved config (provider, baseUrl, model, apiKey, caps…)
+ *     budget,          // { assertWithinBudget(cfg, ctx), record(cfg, result, ctx) }  — optional
+ *     logger           // { info, warn, error }                                        — optional
+ *   });
+ *
+ * The provider adapters already take an explicit config and never read a database, which is what
+ * makes the seam testable: a stub adapter and a real adapter are called identically.
+ *
+ * PROMPTS ARE CONTENT AND LIVE IN THE APP. This package carries the mechanism (how to call a model,
+ * how to enforce a token ceiling, how to check a rewrite kept its facts) and generic writing
+ * operations; the words that say "you are editing a reply to a customer" belong to the app.
+ */
+
+'use strict';
+
+const facts = require('./facts');
+const { AiError, fromFetchFailure, redact } = require('./error');
+const { polish } = require('./polish');
+const { generate } = require('./generate');
+
+const PROVIDERS = {
+  // 'lmstudio' and 'openai-compatible' are the SAME adapter with different defaults — a kindness to
+  // whoever configures it: an operator running LM Studio should not have to know it speaks a shape
+  // named after somebody else.
+  lmstudio: require('./providers/openai-compatible'),
+  'openai-compatible': require('./providers/openai-compatible'),
+  anthropic: require('./providers/anthropic')
+};
+
+const DEFAULTS = {
+  lmstudio: { baseUrl: 'http://localhost:1234/v1', model: 'qwen3.5-9b', label: 'LM Studio' },
+  'openai-compatible': { baseUrl: 'http://localhost:11434/v1', model: '', label: 'The model server' },
+  anthropic: { baseUrl: 'https://api.anthropic.com/v1', model: 'claude-sonnet-4-5', label: 'Claude' }
+};
+
+const RETRY_AFTER_MS = 400;
+const RETRY_ONLY_IF_FAILED_WITHIN_MS = 5000;
+
+const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
+const NOOP_BUDGET = { async assertWithinBudget() {}, async record() {} };
+
+/**
+ * Build an AI client bound to one app's config resolution and token budget.
+ * @param {{resolveConfig: () => Promise<object>, budget?: object, logger?: object}} deps
+ */
+function createAiClient(deps = {}) {
+  const resolveConfig = deps.resolveConfig;
+  if (typeof resolveConfig !== 'function') {
+    throw new Error('createAiClient: resolveConfig must be an async function returning the resolved config');
+  }
+  const log = deps.logger || NOOP_LOGGER;
+  const meter = deps.budget || NOOP_BUDGET;
+
+  /**
+   * Try once more, but only for the failures where trying again could help — a local provider that
+   * dropped the connection while loading a model, and nothing else. A cancelled call, a timeout, a
+   * rate limit or a slow failure is never retried (see the guards below).
+   */
+  async function withOneRetry(run, opts = {}) {
+    const startedAt = Date.now();
+    try {
+      return await run();
+    } catch (err) {
+      if (opts.signal && opts.signal.aborted) throw err;
+      if (!err || !err.retryable) throw err;
+      const elapsed = Date.now() - startedAt;
+      // A TIMEOUT is the deadline itself being reached — retrying waits the whole deadline again. A
+      // RATE LIMIT is the provider asking for less pressure. A slow `unreachable` is not the
+      // sub-second dropped-connection transient this retry exists for. None of those retry.
+      if (err.kind === 'timeout' || err.kind === 'rate_limit' || elapsed > RETRY_ONLY_IF_FAILED_WITHIN_MS) {
+        log.warn(`AI: ${err.kind} after ${elapsed}ms — not retrying (${err.message})`);
+        throw err;
+      }
+      log.warn(`AI: ${err.kind} — trying once more in ${RETRY_AFTER_MS}ms (${err.message})`);
+      await new Promise((r) => setTimeout(r, RETRY_AFTER_MS));
+      return run();
+    }
+  }
+
+  /**
+   * Ask the configured model for something.
+   * @param {{system?:string, messages:Array, maxTokens?:number, temperature?:number,
+   *          schema?:object, signal?:AbortSignal, ticketId?:*, skipBudget?:boolean}} opts
+   * @param {object} [cfgOverride] the resolved config, when the caller already has it
+   */
+  async function complete(opts, cfgOverride) {
+    const cfg = cfgOverride || await resolveConfig();
+    if (!cfg.enabled) {
+      throw new AiError('disabled', 'AI assistance is switched off. An administrator can enable it in Settings.');
+    }
+    if (!cfg.model) {
+      throw new AiError('unconfigured', 'No model name is configured.');
+    }
+    const adapter = PROVIDERS[cfg.provider];
+    if (!adapter) {
+      throw new AiError('unconfigured', `No adapter is registered for provider "${cfg.provider}".`);
+    }
+
+    // The ceiling, before the call — the only place a limit can be enforced without being bypassable
+    // by whichever caller forgets. `skipBudget` is for the admin's Test connection; it still records.
+    if (!opts.skipBudget) await meter.assertWithinBudget(cfg, { ticketId: opts.ticketId });
+
+    const result = await withOneRetry(() => adapter.complete(cfg, opts), opts);
+
+    // ...and the counter after it, AWAITED: two calls in quick succession must both be counted
+    // before the second's ceiling check reads the total, or the limit is enforced against a stale one.
+    await meter.record(cfg, result, { ticketId: opts.ticketId });
+
+    log.info(`AI: ${cfg.provider}/${result.model} ${result.usage.total} tokens in ${result.ms}ms`);
+    return result;
+  }
+
+  /** Is there a provider configured at all? Callers use this to decide whether to render a control. */
+  async function isEnabled() {
+    return (await resolveConfig()).enabled;
+  }
+
+  /** A short round trip for an admin "Test connection". NEVER THROWS — it reports what is wrong. */
+  async function test(cfgOverride) {
+    const cfg = cfgOverride || await resolveConfig();
+    if (!cfg.enabled) return { ok: false, kind: 'disabled', error: 'No provider is selected.' };
+    try {
+      const r = await complete({
+        system: 'Reply with the single word: ready. Do not explain.',
+        messages: [{ role: 'user', content: 'ready?' }],
+        maxTokens: 512,
+        temperature: 0,
+        skipBudget: true            // an admin diagnosing a provider must not be blocked by a full budget
+      }, cfg);
+      return {
+        ok: true, model: r.model, ms: r.ms, reply: (r.text || '').trim().slice(0, 60), usage: r.usage,
+        finishReason: r.finishReason || null, reasoned: !!r.reasonedFor
+      };
+    } catch (err) {
+      if (err instanceof AiError) return { ok: false, kind: err.kind, error: err.message, retryable: err.retryable };
+      return { ok: false, kind: 'bad_response', error: err.message };
+    }
+  }
+
+  /** What the server has loaded, for an admin model picker. Empty when it cannot say. */
+  async function listModels(cfgOverride) {
+    const cfg = cfgOverride || await resolveConfig();
+    if (!cfg.enabled) return [];
+    try {
+      return await PROVIDERS[cfg.provider].listModels(cfg);
+    } catch (err) {
+      return [];
+    }
+  }
+
+  // The writing-assist engines are bound to this client's complete() so a caller gets config +
+  // budget + retry for free. Prompt framing is supplied per call by the app (content).
+  const boundPolish = (opts) => polish(complete, opts);
+  const boundGenerate = (opts) => generate(complete, opts);
+
+  return {
+    complete, isEnabled, test, listModels, withOneRetry,
+    polish: boundPolish, generate: boundGenerate,
+    facts, AiError, PROVIDERS, DEFAULTS
+  };
+}
+
+module.exports = {
+  createAiClient,
+  PROVIDERS, DEFAULTS,
+  AiError, fromFetchFailure, redact,
+  facts,
+  // Default writing-op catalogues, so an app can build its menus without re-declaring them.
+  POLISH_MODES: require('./polish').MODES,
+  POLISH_TONES: require('./polish').TONES,
+  RETRY_AFTER_MS
+};

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@aria-framework/ai",
+  "description": "Aria App Framework — AI module. A dependency-injected model seam (createAiClient) over several providers (LM Studio / OpenAI-compatible / Anthropic), with a fact-preservation guard, generic Polish and Generate writing engines, and a browser polish widget. Prompts and config stay in the consuming app.",
+  "version": "0.1.0",
+  "license": "UNLICENSED",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "error.js",
+    "facts.js",
+    "polish.js",
+    "generate.js",
+    "providers/openai-compatible.js",
+    "providers/anthropic.js",
+    "browser/ai-polish.js"
+  ],
+  "scripts": {
+    "test": "node test/smoke.js"
+  }
+}