@aria-framework/ask 0.1.1 → 0.2.0

package/lib/catalogue.js

@@ -11,9 +11,19 @@
  * request holds (`can`, the request's own) and that the platform has not switched off. A tool the person lacks is NOT IN
  * THE SCHEMA, so it cannot be emitted, and a call to it that arrives anyway is refused by `validatePlan` — never run.
  *
- * THE SCHEMA IS STRICT AND CLOSED (`plannerSchema`): `intent` is lookup | write | none; `calls` is at most MAX_CALLS of
- * `{tool, args}` with exactly that tool's declared arguments (nullable where optional), enums for every closed value and a
- * length bound on every string. THE REPLY IS VALIDATED AGAIN (`validatePlan`), whatever the provider claims.
+ * THE SCHEMA IS STRICT AND CLOSED (`plannerSchema`): `intent` is lookup | analyse | write | none; `reason` is null or,
+ * for none, no_tool | out_of_scope | needs_judgement; `calls` is at most MAX_CALLS of `{tool, args}` with exactly that
+ * tool's declared arguments (nullable where optional), enums for every closed value and a length bound on every string.
+ * THE REPLY IS VALIDATED AGAIN (`validatePlan`), whatever the provider claims.
+ *
+ * TWO ROUNDS (0.2.0). The planner still sees NO DATA. It may plan a second round in the same reply: a later call may take
+ * a text argument from an earlier call's result by REFERENCE — "@r1.customer_ref" — naming an OUTPUT the earlier tool
+ * declares (`outputs: { customer_ref: { path: 'facts.customer_ref', describe } }`). The PACKAGE reads the value at that
+ * path from the result after round 1 ran (`resolveCall`) and validates it with the argument's own spec, as if the model
+ * had typed it; the model never supplies the value. Rules: every round-1 call comes first; a reference names an earlier
+ * round-1 call, never a round-2 one (so at most two rounds); an output read from one of the tool's attackerFields must be
+ * marked `safe: true` by the app (assertToolShape refuses it otherwise); a snippet is never an output; the total stays at
+ * most MAX_CALLS (ask_tool_calls.position is 1–4).
  *
  * REMOTE TOOLS (D-0169 item 8, interface only): a tool may be declared `{ id, kind: 'remote', service, ... }` — another
  * app's own Ask, answering for the same person. 0.1.0 VALIDATES the shape and NEVER OFFERS it (`catalogueFor` leaves it
@@ -26,8 +36,18 @@
 const crypto = require('crypto');
 
 const MAX_CALLS = 4;
-const INTENTS = ['lookup', 'write', 'none'];
+// 0.2.0: `analyse` (the answer may group, compare and conclude across rows — the answer check holds it to the analyse
+// rules) and a REASON on `none`.
+const INTENTS = ['lookup', 'analyse', 'write', 'none'];
+const NONE_REASONS = Object.freeze(['no_tool', 'out_of_scope', 'needs_judgement']);
 const ID = /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/;
+// A ROUND-2 REFERENCE (0.2.0): "@r1.customer_ref" — result r1 (the FIRST call) and the output its tool declared.
+const REF_ARG = /^@r([1-4])\.([a-z][a-z0-9_]{0,39})$/;
+// Anything that starts like a reference and is not a valid one is refused, never passed on as text.
+const REFISH = /^@r\d/i;
+// Where an output may be read from: a fact, or a row's ref or field. A list path ('rows[].…') must hold ONE value.
+const OUTPUT_PATH = /^(?:facts\.[a-z0-9_]+|rows\[\]\.(?:ref|fields\.[a-z0-9_]+))$/;
+const SNIPPET_PATH = /(?:^|\.)snippet$/;
 
 /** The permissions a tool's page is gated by, as a list — `permission: 'x'` is `['x']`. */
 function gateOf(tool) {
@@ -60,6 +80,47 @@ function assertToolShape(tool) {
   }
   if (!Array.isArray(tool.attackerFields)) fail('has no attackerFields list (an empty list must be said)');
   if (typeof tool.describe !== 'function') fail('has no describe(args)');
+  // STATE FIELDS (0.2.0): which row field holds a state an "all / none of them are <state>" answer may claim, and the
+  // values that mean it — { open: { field: 'is_open', values: [true] }, resolved: { field: 'status', values: ['resolved', 'closed'] } }.
+  // A closed list of values, so even a field other people can write only ever matches or does not.
+  if (tool.stateFields !== undefined) {
+    if (!tool.stateFields || typeof tool.stateFields !== 'object' || Array.isArray(tool.stateFields)) fail('stateFields is an object { state: { field, values } }');
+    for (const [state, def] of Object.entries(tool.stateFields)) {
+      if (!/^[a-z]+$/.test(state)) fail(`state ${state} is not a lower-case word`);
+      if (!def || typeof def.field !== 'string' || !/^[a-z0-9_]{1,40}$/.test(def.field)) fail(`state ${state}: field is a row field name`);
+      if (!Array.isArray(def.values) || !def.values.length || def.values.some((v) => !(typeof v === 'boolean' || (typeof v === 'string' && v)))) fail(`state ${state}: values is a list of strings or booleans`);
+      if (def.synonyms !== undefined && (!Array.isArray(def.synonyms) || def.synonyms.some((w) => typeof w !== 'string' || !/^[a-z]+$/.test(w)))) fail(`state ${state}: synonyms is a list of lower-case words`);
+    }
+  }
+  // ROW NAME (review round 3 of PR #14): the field(s) a sentence may name a row by, besides its ref — 'title' or a row field.
+  if (tool.rowName !== undefined) {
+    const names = [].concat(tool.rowName);
+    if (!names.length || names.some((n) => typeof n !== 'string' || !/^[a-z0-9_]{1,40}$/.test(n))) fail('rowName is \'title\' or a row field name (or a list of them)');
+  }
+  // GROUP BY (review round 3 of PR #14): a breakdown may mark an extra `enum: true` (its label app-written) only for a
+  // group-by key it declares here with the closed list of labels — never for a key a free-text argument chooses.
+  if (tool.groupBy !== undefined) {
+    if (!tool.groupBy || typeof tool.groupBy !== 'object' || Array.isArray(tool.groupBy)) fail('groupBy is an object { key: { enum: [labels] } }');
+    for (const [key, def] of Object.entries(tool.groupBy)) {
+      if (!/^[a-z][a-z0-9_]{0,39}$/.test(key)) fail(`groupBy ${key} is not a lower-case name`);
+      if (!def || !Array.isArray(def.enum) || !def.enum.length || def.enum.some((v) => typeof v !== 'string' || !v)) fail(`groupBy ${key}: enum is the closed list of its group labels`);
+      if (tool.args[key] && tool.args[key].type !== 'enum') fail(`groupBy ${key} is a free-text argument; only an enum may group app-written labels`);
+    }
+  }
+  if (tool.outputs !== undefined) {
+    if (!tool.outputs || typeof tool.outputs !== 'object' || Array.isArray(tool.outputs)) fail('outputs is an object { name: { path, describe, safe? } }');
+    for (const [name, out] of Object.entries(tool.outputs)) {
+      if (!/^[a-z][a-z0-9_]{0,39}$/.test(name)) fail(`output ${name} is not a lower-case name`);
+      if (!out || typeof out !== 'object' || typeof out.path !== 'string' || !OUTPUT_PATH.test(out.path)) fail(`output ${name}: its path is 'facts.<key>', 'rows[].ref' or 'rows[].fields.<key>'`);
+      if (typeof out.describe !== 'string' || !out.describe) fail(`output ${name} has no describe text`);
+      if (out.safe !== undefined && out.safe !== true) fail(`output ${name}: safe is true or absent`);
+      if (out.kind !== undefined && (typeof out.kind !== 'string' || !/^[a-z][a-z_]{0,39}$/.test(out.kind))) fail(`output ${name}: kind is a lower-case id kind ('customer')`);
+      // ATTACKER TEXT NEVER STEERS A LOOK-UP unless the app says, for this one output, that it may (`safe: true`): a value
+      // other people typed would otherwise choose what round 2 reads. A snippet is attacker text whatever is declared.
+      if (SNIPPET_PATH.test(out.path)) fail(`output ${name} reads a snippet, which is attacker text and never an output`);
+      if (tool.attackerFields.includes(out.path) && out.safe !== true) fail(`output ${name} reads ${out.path}, an attacker field — mark it safe: true only if a value other people typed may choose what a later look-up reads`);
+    }
+  }
   if (tool.kind === 'remote') {
     if (typeof tool.service !== 'string' || !tool.service) fail('a remote tool names its service');
   } else if (typeof tool.run !== 'function') fail('has no run(ctx, args)');
@@ -105,9 +166,10 @@ function plannerSchema(tools) {
     schema: {
       type: 'object',
       additionalProperties: false,
-      required: ['intent', 'calls'],
+      required: ['intent', 'calls', 'reason'],
       properties: {
         intent: { type: 'string', enum: INTENTS },
+        reason: { type: ['string', 'null'], enum: [...NONE_REASONS, null] },
         calls: variants.length
           ? { type: 'array', maxItems: MAX_CALLS, items: variants.length === 1 ? variants[0] : { anyOf: variants } }
           : { type: 'array', maxItems: 0 }
@@ -136,25 +198,46 @@ function checkArg(name, spec, value) {
   return v;
 }
 
+/** The round-2 references in a call's raw args: { argName: { from: index, output } }, or throws a reason. */
+function refsOf(c, tool, i) {
+  const refs = {};
+  for (const [name, spec] of Object.entries(tool.args)) {
+    const v = c.args[name];
+    if (typeof v !== 'string' || !REFISH.test(v.trim())) continue;
+    const m = REF_ARG.exec(v.trim());
+    if (!m) throw new Error(`look-up ${i + 1}: ${name} looks like a reference to an earlier result and is not one`);
+    if (spec.type === 'enum') throw new Error(`look-up ${i + 1}: ${name} is a closed list and cannot take an earlier result`);
+    refs[name] = { from: Number(m[1]) - 1, output: m[2] };
+  }
+  return refs;
+}
+
 /**
- * The planner's reply, validated against the tools THIS request may use. Returns { intent, calls: [{tool, args}] } with
- * every argument normalised, or { error, code?, index? } naming the first thing wrong — nothing from a refused reply runs.
- * A `write` or `none` intent carries no calls. A duplicate call is dropped, not run twice.
+ * The planner's reply, validated against the tools THIS request may use. Returns { intent, reason, calls: [{tool, args,
+ * refs?}] } with every argument normalised — a round-2 argument keeps its reference ("@r1.customer_ref") and `refs`
+ * names it — or { error, code?, index? } naming the first thing wrong; nothing from a refused reply runs.
+ * A `write` or `none` intent carries no calls; `reason` is only a none's (absent reads as null — a 0.1 plan). A
+ * duplicate call is dropped, not run twice, and a reference to it follows to the call that is kept.
  */
 function validatePlan(reply, tools) {
   if (!isPlain(reply)) return { error: 'the plan is not an object' };
-  const extra = Object.keys(reply).filter((k) => !['intent', 'calls'].includes(k));
+  const extra = Object.keys(reply).filter((k) => !['intent', 'calls', 'reason'].includes(k));
   if (extra.length) return { error: `the plan has unexpected fields (${extra.join(', ')})` };
   if (!INTENTS.includes(reply.intent)) return { error: 'the plan has no valid intent' };
   if (!Array.isArray(reply.calls)) return { error: 'the plan has no calls list' };
-  if (reply.intent !== 'lookup') {
-    return reply.calls.length ? { error: `a ${reply.intent} plan may not name look-ups` } : { intent: reply.intent, calls: [] };
+  const reason = reply.reason === undefined ? null : reply.reason;
+  if (reason !== null && !NONE_REASONS.includes(reason)) return { error: 'the plan\'s reason is not one of its values' };
+  if (reason !== null && reply.intent !== 'none') return { error: `a ${reply.intent} plan carries no reason` };
+  if (reply.intent === 'write' || reply.intent === 'none') {
+    return reply.calls.length ? { error: `a ${reply.intent} plan may not name look-ups` } : { intent: reply.intent, reason, calls: [] };
   }
   if (!reply.calls.length) return { error: 'a look-up plan names no look-ups' };
   if (reply.calls.length > MAX_CALLS) return { error: `the plan names more than ${MAX_CALLS} look-ups` };
   const allowed = new Map(tools.map((t) => [t.id, t]));
   const calls = [];
-  const seen = new Set();
+  const seen = new Map();
+  const kept = [];   // the reply's index → the kept call's index
+  let roundTwo = false;
   for (const [i, c] of reply.calls.entries()) {
     if (!isPlain(c)) return { error: `look-up ${i + 1} is not an object` };
     const keys = Object.keys(c).filter((k) => !['tool', 'args'].includes(k));
@@ -166,25 +249,89 @@ function validatePlan(reply, tools) {
     if (!isPlain(c.args)) return { error: `look-up ${i + 1} has no arguments object` };
     const unknown = Object.keys(c.args).filter((k) => !Object.prototype.hasOwnProperty.call(tool.args, k));
     if (unknown.length) return { error: `look-up ${i + 1} has arguments its tool does not take` };
+    let refs;
+    try { refs = refsOf(c, tool, i); } catch (e) { return { error: e.message }; }
     const args = {};
     try {
-      for (const [name, spec] of Object.entries(tool.args)) args[name] = checkArg(name, spec, c.args[name]);
+      for (const [name, spec] of Object.entries(tool.args)) {
+        if (refs[name]) {
+          const r = refs[name];
+          // EARLIER, ROUND 1, AND A DECLARED OUTPUT: the reference names a call before this one that takes no reference
+          // itself (so there are never three rounds) and an output its tool declares.
+          if (r.from >= i) throw new Error(`${name} names a result that is not an earlier look-up`);
+          const src = reply.calls[r.from];
+          const srcTool = allowed.get(src && src.tool);
+          if (!calls[kept[r.from]] || calls[kept[r.from]].refs) throw new Error(`${name} names a result of the second round (at most two rounds)`);
+          if (!srcTool.outputs || !Object.prototype.hasOwnProperty.call(srcTool.outputs, r.output)) throw new Error(`${name} names an output ${srcTool.id} does not give`);
+          r.from = kept[r.from];
+          args[name] = `@r${r.from + 1}.${r.output}`;
+        } else args[name] = checkArg(name, spec, c.args[name]);
+      }
     } catch (e) {
       return { error: `look-up ${i + 1}: ${e.message}` };
     }
+    const two = Object.keys(refs).length > 0;
+    // A round-2 call takes its context from round 1, never from the page as well (fix round of PR #15).
+    if (two && Object.values(args).includes('@context')) return { error: `look-up ${i + 1} mixes "@context" with an earlier result` };
+    if (!two && roundTwo) return { error: `look-up ${i + 1} takes no earlier result and comes after one that does (round-1 look-ups come first)` };
+    roundTwo = roundTwo || two;
     const key = JSON.stringify([tool.id, args]);
-    if (seen.has(key)) continue;
-    seen.add(key);
-    calls.push({ tool: tool.id, args });
+    if (seen.has(key)) { kept[i] = seen.get(key); continue; }
+    seen.set(key, calls.length);
+    kept[i] = calls.length;
+    calls.push(two ? { tool: tool.id, args, refs } : { tool: tool.id, args });
   }
-  return { intent: 'lookup', calls };
+  return { intent: reply.intent, reason: null, calls };
 }
 
-/** What the planner reads about each tool: its id, what it does, and its arguments in words. */
+/** Every string value at an output path of a result ('facts.x', 'rows[].ref', 'rows[].fields.x'). */
+function valuesAt(result, path) {
+  const out = [];
+  const take = (v) => { if (typeof v === 'string') out.push(v); else if (typeof v === 'number' && Number.isFinite(v)) out.push(String(v)); };
+  const [head, ...rest] = path.split('.');
+  if (head === 'facts') take((result.facts || {})[rest[0]]);
+  else for (const row of result.rows || []) take(rest[0] === 'ref' ? row.ref : (row.fields || {})[rest[1]]);
+  return out;
+}
+
+/**
+ * A ROUND-2 CALL'S ARGUMENTS, RESOLVED BY THE PACKAGE: each reference's value read from its result at the output's
+ * declared path — exactly ONE distinct value, from a result whose outcome is ok — then validated by the argument's own spec
+ * (control characters, length, nullability) as a typed value would be. A value shaped like a reference or the context
+ * token is refused: it is never substituted again. Returns { args } or { error }.
+ */
+function resolveCall(call, results, tools, o = {}) {
+  const isPublicId = typeof o.isPublicId === 'function' ? o.isPublicId : () => false;
+  const tool = tools.find((t) => t.id === call.tool);
+  if (!tool) return { error: 'the tool is not offered' };
+  const args = { ...call.args };
+  for (const [name, r] of Object.entries(call.refs || {})) {
+    const res = results[r.from];
+    if (!res || res.outcome !== 'ok') return { error: `${name}: result r${r.from + 1} is not an ok result` };
+    const srcTool = tools.find((t) => t.id === res.tool);
+    const out = srcTool && srcTool.outputs && srcTool.outputs[r.output];
+    if (!out) return { error: `${name}: ${res.tool} gives no output ${r.output}` };
+    const values = [...new Set(valuesAt(res, out.path).map((v) => v.trim()).filter(Boolean))];
+    // SEVERAL VALUES is a choice the person has to make (ambiguous), not an absence (fix round of PR #15).
+    if (values.length > 1) return { error: `${name}: r${r.from + 1}.${r.output} holds ${values.length} values, not one`, ambiguous: true };
+    if (values.length !== 1) return { error: `${name}: r${r.from + 1}.${r.output} holds no value` };
+    if (REFISH.test(values[0]) || values[0] === '@context') return { error: `${name}: the value read is shaped like a reference` };
+    // ONLY THIS APP'S OWN IDS PASS unless the app marked the output safe (fix round of PR #15): an attacker field the tool
+    // forgot to list cannot steer round 2 with free text.
+    // OF ITS KIND (re-review of PR #15): an output declaring `kind` passes only an id of that kind — a usr_ id never reaches
+    // a customer argument.
+    if (out.safe !== true && !isPublicId(values[0], out.kind)) return { error: `${name}: r${r.from + 1}.${r.output} is not ${out.kind ? `a ${out.kind} id` : 'an id'} of this app (mark the output safe to pass other text)` };
+    try { args[name] = checkArg(name, tool.args[name], values[0]); } catch (e) { return { error: e.message }; }
+  }
+  return { args };
+}
+
+/** What the planner reads about each tool: its id, what it does, its arguments in words, and what a later look-up may take from it. */
 function describeTools(tools) {
   return tools.map((t) => {
     const args = Object.entries(t.args).map(([k, spec]) => `    - ${k}: ${spec.describe}${spec.type === 'enum' ? ` (one of: ${spec.values.join(', ')}${spec.nullable ? ', or null' : ''})` : ''}`);
-    return `- ${t.id}: ${t.description}\n${args.join('\n')}`;
+    const outs = Object.entries(t.outputs || {}).map(([k, o]) => `    - gives ${k}: ${o.describe}`);
+    return `- ${t.id}: ${t.description}\n${[...args, ...outs].join('\n')}`;
   }).join('\n');
 }
 
@@ -195,18 +342,33 @@ function describeTools(tools) {
  * BYTE-IDENTICAL TO BOTH APPS' COPIES: the hub serialised `{id, permission, description, args, attackerFields}`, Soc
  * `{id, permissions, …}`. Both keys are written here in that order; JSON.stringify drops the one a tool does not declare,
  * so each app's string — and so its prompt hash — is unchanged by adopting the package (test/hashes.js proves it on
- * copies of both apps' documents). A REMOTE tool adds `kind` and `service` after the rest (no app has one yet).
+ * copies of both apps' documents). A REMOTE tool adds `kind` and `service` after the rest (no app has one yet); a tool
+ * with STATE FIELDS or OUTPUTS (0.2.0) adds `stateFields` / `outputs` last, so a tool without them hashes as before.
  */
 function catalogueHashOf(tools) {
   const doc = tools.map((t) => ({ id: t.id, permission: t.permission, permissions: t.permissions, description: t.description, args: t.args,
-    attackerFields: t.attackerFields, kind: t.kind === 'remote' ? 'remote' : undefined, service: t.kind === 'remote' ? t.service : undefined }));
+    attackerFields: t.attackerFields, kind: t.kind === 'remote' ? 'remote' : undefined, service: t.kind === 'remote' ? t.service : undefined,
+    stateFields: t.stateFields, rowName: t.rowName, groupBy: t.groupBy, outputs: t.outputs }));
   return crypto.createHash('sha256').update(JSON.stringify(doc)).digest('hex');
 }
 
 /** A catalogue over an app's tools, in the order registered. */
-function createCatalogue(tools) {
+/**
+ * @param {object[]} tools
+ * @param {{idKinds?: string[]}} [o] the id kinds this app's isPublicId(v, kind) knows — required when an output declares
+ *   a kind, and every declared kind must be one of them (checked at boot).
+ */
+function createCatalogue(tools, o = {}) {
   if (!Array.isArray(tools) || !tools.length) throw new Error('ask: createAsk needs a non-empty tools list');
   const TOOLS = Object.freeze(tools.map(assertToolShape));
+  const kinds = Array.isArray(o.idKinds) ? new Set(o.idKinds) : null;
+  for (const t of TOOLS) {
+    for (const [name, out] of Object.entries(t.outputs || {})) {
+      if (out.kind === undefined) continue;
+      if (!kinds) throw new Error(`ask tool ${JSON.stringify(t.id)}: output ${name} declares kind ${out.kind}; pass createAsk idKinds (the kinds isPublicId knows)`);
+      if (!kinds.has(out.kind)) throw new Error(`ask tool ${JSON.stringify(t.id)}: output ${name} declares kind ${out.kind}, which is not one of idKinds (${[...kinds].join(', ')})`);
+    }
+  }
   const BY_ID = new Map();
   for (const t of TOOLS) {
     if (BY_ID.has(t.id)) throw new Error(`ask tool ${JSON.stringify(t.id)} is registered twice`);
@@ -214,7 +376,7 @@ function createCatalogue(tools) {
   }
   const TOOL_IDS = Object.freeze(TOOLS.map((t) => t.id));
   return {
-    TOOLS, TOOL_IDS, MAX_CALLS, INTENTS,
+    TOOLS, TOOL_IDS, MAX_CALLS, INTENTS, NONE_REASONS,
     byId: (id) => BY_ID.get(String(id)) || null,
     mayUse,
     /** The tools this request may plan: every permission held, not switched off, and not remote (0.1.0). */
@@ -222,9 +384,10 @@ function createCatalogue(tools) {
       const off = new Set(Array.isArray(toolsOff) ? toolsOff : []);
       return TOOLS.filter((t) => t.kind !== 'remote' && !off.has(t.id) && mayUse(can, t));
     },
-    plannerSchema, validatePlan, describeTools,
+    plannerSchema, validatePlan, resolveCall, describeTools,
     catalogueHash: () => catalogueHashOf(TOOLS)
   };
 }
 
-module.exports = { createCatalogue, assertToolShape, mayUse, gateOf, plannerSchema, validatePlan, describeTools, catalogueHashOf, MAX_CALLS, INTENTS };
+module.exports = { createCatalogue, assertToolShape, mayUse, gateOf, plannerSchema, validatePlan, resolveCall, valuesAt, describeTools, catalogueHashOf,
+  MAX_CALLS, INTENTS, NONE_REASONS, REF_ARG };