agentfootprint 10.2.0 → 10.3.1

package/dist/lib/moments.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * moments — PUBLIC. The five places in the loop where a rule may speak.
+ *
+ * Pattern: Closed enumeration + a mechanical name mapping, with the mapping
+ *          pinned by the compiler rather than by memory.
+ * Role:    lib/ leaf (Map). `LoopMoment` is the vocabulary `.act()` is keyed on
+ *          and the vocabulary every ledger row now stamps itself with, so a
+ *          person asking "where in the loop did this happen?" and a person
+ *          asking "where in the loop can I intervene?" are reading the same
+ *          five words.
+ * Emits:   N/A (types + one pure function).
+ *
+ * ## Why the list is here and not inside `.act()`
+ *
+ * A bundle whose keys ARE the moments is only honest while the two sets
+ * agree. Keep the list of moments in the options type and the sixth moment
+ * ships with no key and nothing notices; keep it here, derive the key names
+ * from it, and the day a moment is added the build fails inside `act.ts`
+ * naming the key nobody wrote. That is the same trick `conformSource` plays
+ * on the outside world, turned inward on ourselves.
+ *
+ * The mapping between the two spellings is mechanical — kebab in the record
+ * (`'before-tool'`, which reads as a phase), camel in the bundle
+ * (`beforeTool`, which reads as a property) — and `actKeyFor` is its runtime
+ * twin, so the validator that decides which keys `.act()` accepts is
+ * DERIVED from this list rather than typed out beside it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.actKeyFor = exports.LOOP_MOMENTS = void 0;
+/**
+ * Every moment of one agent turn where a rule may act, in the order the loop
+ * reaches them.
+ *
+ * ```
+ * input → [ window → … LLM … → before-tool → tool → after-tool ]* → output
+ * ```
+ *
+ * `watch` attends all five and more; `act` attends exactly these. The
+ * difference is what a rule may DO there — an observer reports, a rule
+ * changes what happens next.
+ */
+exports.LOOP_MOMENTS = ['input', 'before-tool', 'after-tool', 'window', 'output'];
+/**
+ * The runtime twin of {@link ActKey}. `.act()`'s accepted key set is built
+ * from this over `LOOP_MOMENTS`, so an unknown key is refused by a rule that
+ * cannot fall behind the list it is derived from.
+ */
+function actKeyFor(moment) {
+    return moment.replace(/-(.)/g, (_match, c) => c.toUpperCase());
+}
+exports.actKeyFor = actKeyFor;
+//# sourceMappingURL=moments.js.map

package/dist/lib/moments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"moments.js","sourceRoot":"","sources":["../../src/lib/moments.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;;AAEH;;;;;;;;;;;GAWG;AACU,QAAA,YAAY,GAAG,CAAC,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,CAAU,CAAC;AAehG;;;;GAIG;AACH,SAAgB,SAAS,CAAC,MAAkB;IAC1C,OAAO,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAW,CAAC;AACnF,CAAC;AAFD,8BAEC"}

package/dist/lib/plainLine.js

@@ -5,9 +5,9 @@
  *
  * Pattern: One predicate, no imports, no state.
  * Role:    Leaf. Asked by the three doors that take a short declared label:
- *          `core/agent/coverage/items.ts` (a coverage item's `short`, at the
+ *          `semantics/coverage/items.ts` (a coverage item's `short`, at the
  *          `absent()` / `coverage()` mint AND at the dispatch reader) and
- *          `lib/injection-engine/factories/defineSkill.ts` (a skill's
+ *          `injection-engine/factories/defineSkill.ts` (a skill's
  *          `title`). One rule, so the three cannot disagree.
  * Emits:   N/A.
  *

package/dist/lib/saidByPerson.js

@@ -71,7 +71,7 @@
  * rule fires on it. Adding one means adding it to
  * {@link LIBRARY_AUTHORED_PREFIXES}, and every reader is fixed at once —
  * which is why the count is no longer asserted in prose alone:
- * `test/lib/injection-engine/userTurnProducers.test.ts` WALKS the tree for
+ * `test/injection-engine/userTurnProducers.test.ts` WALKS the tree for
  * every `role: 'user'` construction site and fails, with the file and line, on
  * one that is neither registered here, nor a person's own turn, nor
  * wire-only.
@@ -160,7 +160,7 @@ function isCompactedSummary(msg) {
 exports.isCompactedSummary = isCompactedSummary;
 // FOLD · the one owner of which role:'user' message a PERSON wrote, as opposed to the ones this library writes in a person's voice
 // consumers read this and never re-derive it: core/agent/window/currentRequest.ts, injection-engine/types.ts's
-// saidByPerson(ctx) (lib/injection-engine/types.ts · saidByPerson), and src/index.ts (published)
+// saidByPerson(ctx) (injection-engine/types.ts · saidByPerson), and src/index.ts (published)
 // detached: yes — a boolean over one message; the writers import the prefixes the recogniser matches on.
 /**
  * THE rule: true when this message is something a PERSON said.

package/dist/lib/saidByPerson.js.map

@@ -1 +1 @@
-{"version":3,"file":"saidByPerson.js","sourceRoot":"","sources":["../../src/lib/saidByPerson.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;;;AAmBH;yDACyD;AAC5C,QAAA,kBAAkB,GAAG,kBAAkB,CAAC;AAErD;6DAC6D;AAChD,QAAA,sBAAsB,GAAG,oBAAoB,CAAC;AAE3D;uEACuE;AAC1D,QAAA,yBAAyB,GAAG,eAAe,CAAC;AAEzD;0EAC0E;AAC7D,QAAA,2BAA2B,GAAG,iBAAiB,CAAC;AAE7D;;+BAE+B;AAClB,QAAA,oBAAoB,GAAG,mBAAmB,CAAC;AAExD;;gCAEgC;AACnB,QAAA,uBAAuB,GAAG,cAAc,CAAC;AAEtD;;;;;;;;;GASG;AACU,QAAA,oBAAoB,GAC/B,6LAA6L,CAAC;AAEhM;4EAC4E;AAC/D,QAAA,wBAAwB,GAAG,cAAc,CAAC;AAEvD;;;;;;;;;;;;;;;;;;GAkBG;AACU,QAAA,yBAAyB,GAAsB,MAAM,CAAC,MAAM,CAAC;IACxE,0BAAkB;IAClB,8BAAsB;IACtB,iCAAyB;IACzB,mCAA2B;IAC3B,4BAAoB;IACpB,+BAAuB;IACvB,4BAAoB;IACpB,gCAAwB;CACzB,CAAC,CAAC;AAEH,iFAAiF;AACjF,SAAgB,sBAAsB,CAAC,GAAgC;IACrE,OAAO,CACL,GAAG,KAAK,SAAS;QACjB,GAAG,CAAC,IAAI,KAAK,MAAM;QACnB,iCAAyB,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAC3E,CAAC;AACJ,CAAC;AAND,wDAMC;AAED,gEAAgE;AAChE,SAAgB,YAAY,CAAC,GAAgC;IAC3D,OAAO,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,0BAAkB,CAAC,CAAC;AAChG,CAAC;AAFD,oCAEC;AAED,+DAA+D;AAC/D,SAAgB,kBAAkB,CAAC,GAAgC;IACjE,OAAO,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,8BAAsB,CAAC,CAAC;AACpG,CAAC;AAFD,gDAEC;AAED,mIAAmI;AACnI,+GAA+G;AAC/G,iGAAiG;AACjG,yGAAyG;AACzG;;;;;;;;;;;;GAYG;AACH,SAAgB,cAAc,CAAC,GAAgC;IAC7D,OAAO,CACL,GAAG,KAAK,SAAS;QACjB,GAAG,CAAC,IAAI,KAAK,MAAM;QACnB,GAAG,CAAC,UAAU,KAAK,SAAS;QAC5B,GAAG,CAAC,SAAS,KAAK,IAAI;QACtB,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAC7B,CAAC;AACJ,CAAC;AARD,wCAQC"}
+{"version":3,"file":"saidByPerson.js","sourceRoot":"","sources":["../../src/lib/saidByPerson.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;;;AAmBH;yDACyD;AAC5C,QAAA,kBAAkB,GAAG,kBAAkB,CAAC;AAErD;6DAC6D;AAChD,QAAA,sBAAsB,GAAG,oBAAoB,CAAC;AAE3D;uEACuE;AAC1D,QAAA,yBAAyB,GAAG,eAAe,CAAC;AAEzD;0EAC0E;AAC7D,QAAA,2BAA2B,GAAG,iBAAiB,CAAC;AAE7D;;+BAE+B;AAClB,QAAA,oBAAoB,GAAG,mBAAmB,CAAC;AAExD;;gCAEgC;AACnB,QAAA,uBAAuB,GAAG,cAAc,CAAC;AAEtD;;;;;;;;;GASG;AACU,QAAA,oBAAoB,GAC/B,6LAA6L,CAAC;AAEhM;4EAC4E;AAC/D,QAAA,wBAAwB,GAAG,cAAc,CAAC;AAEvD;;;;;;;;;;;;;;;;;;GAkBG;AACU,QAAA,yBAAyB,GAAsB,MAAM,CAAC,MAAM,CAAC;IACxE,0BAAkB;IAClB,8BAAsB;IACtB,iCAAyB;IACzB,mCAA2B;IAC3B,4BAAoB;IACpB,+BAAuB;IACvB,4BAAoB;IACpB,gCAAwB;CACzB,CAAC,CAAC;AAEH,iFAAiF;AACjF,SAAgB,sBAAsB,CAAC,GAAgC;IACrE,OAAO,CACL,GAAG,KAAK,SAAS;QACjB,GAAG,CAAC,IAAI,KAAK,MAAM;QACnB,iCAAyB,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAC3E,CAAC;AACJ,CAAC;AAND,wDAMC;AAED,gEAAgE;AAChE,SAAgB,YAAY,CAAC,GAAgC;IAC3D,OAAO,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,0BAAkB,CAAC,CAAC;AAChG,CAAC;AAFD,oCAEC;AAED,+DAA+D;AAC/D,SAAgB,kBAAkB,CAAC,GAAgC;IACjE,OAAO,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,8BAAsB,CAAC,CAAC;AACpG,CAAC;AAFD,gDAEC;AAED,mIAAmI;AACnI,+GAA+G;AAC/G,6FAA6F;AAC7F,yGAAyG;AACzG;;;;;;;;;;;;GAYG;AACH,SAAgB,cAAc,CAAC,GAAgC;IAC7D,OAAO,CACL,GAAG,KAAK,SAAS;QACjB,GAAG,CAAC,IAAI,KAAK,MAAM;QACnB,GAAG,CAAC,UAAU,KAAK,SAAS;QAC5B,GAAG,CAAC,SAAS,KAAK,IAAI;QACtB,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAC7B,CAAC;AACJ,CAAC;AARD,wCAQC"}

package/dist/lib/sha256.js

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * sha256Hex — FIPS 180-4 SHA-256 over a JS string, with no platform edge.
+ *
+ * Role:  Fold. A leaf function. It reads nothing, writes nothing and emits
+ *        nothing; the receipt calls it to fingerprint content it must not
+ *        keep.
+ * Reads: its argument.
+ * Emits: N/A.
+ *
+ * WHY NOT `rag/hash.ts` · `sha256`. That one reaches `node:crypto` through
+ * `lazyRequire`, which is right where it lives: indexing a corpus is a Node
+ * job that runs once, off any hot path. This one is called on EVERY LLM call,
+ * including from an agent running in a browser through the `browser*`
+ * providers — a `node:crypto` edge there would throw at request assembly and
+ * take the run with it. `crypto.subtle.digest` is the browser answer and it is
+ * asynchronous, which request assembly is not.
+ *
+ * So the algorithm is here, in about seventy lines, and
+ * `test/time-travel/receipt-conformance.test.ts` checks it against
+ * `node:crypto` on every input the suite hashes. A vendored primitive that is
+ * never compared against the reference is a second truth waiting to happen.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sha256Hex = void 0;
+/** Round constants — the first 32 bits of the fractional parts of the cube
+ *  roots of the first 64 primes (FIPS 180-4 §4.2.2). */
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+function rotr(x, n) {
+    return ((x >>> n) | (x << (32 - n))) >>> 0;
+}
+/** Hex SHA-256 of a string's UTF-8 bytes. 64 lowercase hex characters. */
+function sha256Hex(input) {
+    const message = new TextEncoder().encode(input);
+    const bitLength = message.length * 8;
+    // One 0x80 byte, then zeroes, then the 64-bit big-endian length: pad to the
+    // next whole 64-byte block that leaves room for all nine of those bytes.
+    const padded = ((message.length + 9 + 63) >> 6) << 6;
+    const buffer = new Uint8Array(padded);
+    buffer.set(message);
+    buffer[message.length] = 0x80;
+    const view = new DataView(buffer.buffer);
+    view.setUint32(padded - 8, Math.floor(bitLength / 0x100000000));
+    view.setUint32(padded - 4, bitLength >>> 0);
+    const h = new Uint32Array([
+        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+    ]);
+    const w = new Uint32Array(64);
+    for (let offset = 0; offset < padded; offset += 64) {
+        for (let i = 0; i < 16; i++)
+            w[i] = view.getUint32(offset + i * 4);
+        for (let i = 16; i < 64; i++) {
+            const a = w[i - 15];
+            const b = w[i - 2];
+            const s0 = (rotr(a, 7) ^ rotr(a, 18) ^ (a >>> 3)) >>> 0;
+            const s1 = (rotr(b, 17) ^ rotr(b, 19) ^ (b >>> 10)) >>> 0;
+            w[i] = (w[i - 16] + s0 + w[i - 7] + s1) >>> 0;
+        }
+        let a = h[0];
+        let b = h[1];
+        let c = h[2];
+        let d = h[3];
+        let e = h[4];
+        let f = h[5];
+        let g = h[6];
+        let hh = h[7];
+        for (let i = 0; i < 64; i++) {
+            const s1 = (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) >>> 0;
+            const ch = ((e & f) ^ (~e & g)) >>> 0;
+            const t1 = (hh + s1 + ch + K[i] + w[i]) >>> 0;
+            const s0 = (rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) >>> 0;
+            const maj = ((a & b) ^ (a & c) ^ (b & c)) >>> 0;
+            const t2 = (s0 + maj) >>> 0;
+            hh = g;
+            g = f;
+            f = e;
+            e = (d + t1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) >>> 0;
+        }
+        h[0] = (h[0] + a) >>> 0;
+        h[1] = (h[1] + b) >>> 0;
+        h[2] = (h[2] + c) >>> 0;
+        h[3] = (h[3] + d) >>> 0;
+        h[4] = (h[4] + e) >>> 0;
+        h[5] = (h[5] + f) >>> 0;
+        h[6] = (h[6] + g) >>> 0;
+        h[7] = (h[7] + hh) >>> 0;
+    }
+    let out = '';
+    for (const word of h)
+        out += word.toString(16).padStart(8, '0');
+    return out;
+}
+exports.sha256Hex = sha256Hex;
+//# sourceMappingURL=sha256.js.map

package/dist/lib/sha256.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sha256.js","sourceRoot":"","sources":["../../src/lib/sha256.ts"],"names":[],"mappings":"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"}

package/dist/lib/stableJson.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * stableJson — the one sorted-key JSON spelling every fingerprint in this
+ * library hashes: the receipt's digests (`core/agent/receipt/receipt.ts`), the
+ * ontology's hash (`ontology/define.ts` · `ontologyHash`). A leaf so that the
+ * layers that hash a value and cannot import each other spell it the same way.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stableJson = void 0;
+/**
+ * JSON with object keys in sorted order, at every depth — so two structurally
+ * equal values hash the same however they were built. Property order survives
+ * `structuredClone`, but it does NOT survive every path a value takes through
+ * a delta-encoded commit log and back, and a fingerprint that depends on
+ * insertion order is a fingerprint that reports a change nobody made.
+ *
+ * Returns `undefined` — never `''` — for anything JSON cannot express (a
+ * cycle, a `BigInt`, a value whose `toJSON` throws). It does not throw,
+ * because a receipt is bookkeeping and must never be able to stop a run; and
+ * it does not collapse, because `''` made every unreadable value equal to
+ * every other one. Two requests that both failed to serialize compared EQUAL,
+ * and the receipt wrote `transformHash: null` — "the cache strategy changed
+ * nothing" — about a pair it had not read. Callers substitute
+ * `core/agent/receipt/receipt.ts` · `UNSERIALIZABLE` where a digest needs bytes, and
+ * branch where a comparison needs truth.
+ */
+function stableJson(value) {
+    const canonical = (input) => {
+        if (Array.isArray(input))
+            return input.map(canonical);
+        if (input !== null && typeof input === 'object') {
+            const source = input;
+            const out = {};
+            for (const key of Object.keys(source).sort()) {
+                const next = canonical(source[key]);
+                if (next === undefined)
+                    continue;
+                out[key] = next;
+            }
+            return out;
+        }
+        return input;
+    };
+    try {
+        return JSON.stringify(canonical(value)) ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+exports.stableJson = stableJson;
+//# sourceMappingURL=stableJson.js.map

package/dist/lib/stableJson.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stableJson.js","sourceRoot":"","sources":["../../src/lib/stableJson.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,UAAU,CAAC,KAAc;IACvC,MAAM,SAAS,GAAG,CAAC,KAAc,EAAW,EAAE;QAC5C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACtD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAChD,MAAM,MAAM,GAAG,KAAgC,CAAC;YAChD,MAAM,GAAG,GAA4B,EAAE,CAAC;YACxC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;gBAC7C,MAAM,IAAI,GAAG,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;gBACpC,IAAI,IAAI,KAAK,SAAS;oBAAE,SAAS;gBACjC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;YAClB,CAAC;YACD,OAAO,GAAG,CAAC;QACb,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IACF,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,IAAI,SAAS,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AApBD,gCAoBC"}

package/dist/lib/toolBytes.js

@@ -4,7 +4,7 @@
  *
  * Pattern: One pure function. No imports, no state, no clock.
  * Role:    Leaf. The one owner of the tool-bytes boundary — the `toolChars`
- *          field of `adapters/types.ts` · `LLMMessage` (honesty layer 2).
+ *          field of `provider-contract/types.ts` · `LLMMessage` (honesty layer 2).
  * Emits:   N/A.
  *
  * ## Why this is a leaf and not a helper beside its first reader
@@ -22,7 +22,7 @@
  *   answer as if the tool had said it;
  * - the answer's standing (`core/agent/assessment/assess.ts` · `assessAnswer`)
  *   and the answer account's in-view results
- *   (`lib/answer-account/facts/inView.ts` · `readInView`) — the one emptiness
+ *   (`answer-account/facts/inView.ts` · `readInView`) — the one emptiness
  *   reader parses the tool's bytes, and a note after a `[]` made the parse
  *   fail, so a filled call's empty result stopped reading `empty-undeclared`
  *   and its absence stopped reading `declared-absent`;
@@ -48,7 +48,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.toolBytesOf = void 0;
 // FOLD · the one owner of where a tool's own words end in a result message
 // consumers read this and never re-derive it: core/agent/evidence/evidenceIndex.ts · evidenceFromHistory,
-// core/agent/assessment/assess.ts · turnResults, lib/answer-account/facts/inView.ts · readInView,
+// core/agent/assessment/assess.ts · turnResults, answer-account/facts/inView.ts · readInView,
 // core/agent/stages/callLLM.ts · groundedTextOf, core/agent/stages/toolCalls.ts · producerCorpusOf
 // detached: yes — a string cut from the content (or the content as given when it is not a string).
 /**

package/dist/lib/toolBytes.js.map

@@ -1 +1 @@
-{"version":3,"file":"toolBytes.js","sourceRoot":"","sources":["../../src/lib/toolBytes.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;;;AAEH,2EAA2E;AAC3E,0GAA0G;AAC1G,kGAAkG;AAClG,mGAAmG;AACnG,mGAAmG;AACnG;;;;;;;GAOG;AACH,SAAgB,WAAW,CAAI,OAG9B;IACC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;IAC5C,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IAChD,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,GAAG,IAAI,OAAO,CAAC,MAAM;QAC1F,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;QACvB,CAAC,CAAC,OAAO,CAAC;AACd,CAAC;AATD,kCASC"}
+{"version":3,"file":"toolBytes.js","sourceRoot":"","sources":["../../src/lib/toolBytes.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;;;AAEH,2EAA2E;AAC3E,0GAA0G;AAC1G,8FAA8F;AAC9F,mGAAmG;AACnG,mGAAmG;AACnG;;;;;;;GAOG;AACH,SAAgB,WAAW,CAAI,OAG9B;IACC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;IAC5C,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IAChD,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,GAAG,IAAI,OAAO,CAAC,MAAM;QAC1F,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;QACvB,CAAC,CAAC,OAAO,CAAC;AACd,CAAC;AATD,kCASC"}

package/dist/lib/toolName.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * toolName — the LLM tool-name law: the charset every major provider enforces,
+ * the strict check (`assertValidToolName`) and the dev-mode warning
+ * (`warnIfInvalidToolName`) that `defineTool` runs. A leaf so that every
+ * layer that mints a tool name — `tools/tools.ts` · `defineTool`, the tool
+ * registry, the coverage result's `tryInstead` — asks the same rule.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.warnIfInvalidToolName = exports.assertValidToolName = void 0;
+const footprintjs_1 = require("footprintjs");
+/**
+ * The tool-name charset every major LLM provider enforces (OpenAI, Azure OpenAI,
+ * and Anthropic all require `^[a-zA-Z0-9_-]{1,64}$`). A name with a dot, space,
+ * slash, colon, or >64 chars makes the provider 400-REJECT the WHOLE request — so
+ * EVERY tool vanishes, not just the bad one, and it looks like "my tool isn't
+ * visible." We validate at `defineTool` so a bad name fails LOUD here, naming the
+ * offending tool, instead of as an opaque provider 400 at run time.
+ */
+const LLM_TOOL_NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/;
+/**
+ * STRICT validation — throws a clear, actionable error if a tool name can't be
+ * sent to an LLM. Exposed for consumers who want to fail hard (e.g. in a build
+ * step or a test). The library itself only WARNS (see `warnIfInvalidToolName`),
+ * because a name is provider-specific: a mock or a name-sanitizing custom provider
+ * may accept dotted/namespaced names that OpenAI/Anthropic reject.
+ */
+function assertValidToolName(name) {
+    if (typeof name !== 'string' || name.length === 0) {
+        throw new Error(`defineTool: tool name must be a non-empty string (got ${JSON.stringify(name)}).`);
+    }
+    if (!LLM_TOOL_NAME_RE.test(name)) {
+        const reason = name.length > 64
+            ? `it is ${name.length} chars (max 64)`
+            : `it contains characters outside [a-zA-Z0-9_-] (e.g. a dot, space, slash, or colon)`;
+        throw new Error(`tool name ${JSON.stringify(name)} — ${reason}. ` +
+            `LLM tool names must match /^[a-zA-Z0-9_-]{1,64}$/ (OpenAI, Azure, and Anthropic all ` +
+            `400-reject the whole request otherwise, making every tool disappear). ` +
+            `Rename it — e.g. replace '.', ':', '/', or ' ' with '_'.`);
+    }
+}
+exports.assertValidToolName = assertValidToolName;
+/**
+ * DEV-MODE heads-up (never throws): warns once-per-call if a tool name will be
+ * rejected by OpenAI/Anthropic. Production and non-dev runs pay nothing. This is
+ * the library's default guard (Convention: dev diagnostics warn, they don't throw)
+ * — keeping mock/custom-provider + namespaced-name setups working. Reach for
+ * `assertValidToolName` when you want a hard failure.
+ */
+function warnIfInvalidToolName(name) {
+    if (!(0, footprintjs_1.isDevMode)())
+        return;
+    try {
+        assertValidToolName(name);
+    }
+    catch (e) {
+        // eslint-disable-next-line no-console
+        console.warn(`[agentfootprint] invalid ${e.message}`);
+    }
+}
+exports.warnIfInvalidToolName = warnIfInvalidToolName;
+//# sourceMappingURL=toolName.js.map

package/dist/lib/toolName.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolName.js","sourceRoot":"","sources":["../../src/lib/toolName.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAEH,6CAAwC;AAExC;;;;;;;GAOG;AACH,MAAM,gBAAgB,GAAG,uBAAuB,CAAC;AAEjD;;;;;;GAMG;AACH,SAAgB,mBAAmB,CAAC,IAAa;IAC/C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CACb,yDAAyD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAClF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,MAAM,MAAM,GACV,IAAI,CAAC,MAAM,GAAG,EAAE;YACd,CAAC,CAAC,SAAS,IAAI,CAAC,MAAM,iBAAiB;YACvC,CAAC,CAAC,mFAAmF,CAAC;QAC1F,MAAM,IAAI,KAAK,CACb,aAAa,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,MAAM,IAAI;YAC/C,sFAAsF;YACtF,wEAAwE;YACxE,0DAA0D,CAC7D,CAAC;IACJ,CAAC;AACH,CAAC;AAlBD,kDAkBC;AAED;;;;;;GAMG;AACH,SAAgB,qBAAqB,CAAC,IAAa;IACjD,IAAI,CAAC,IAAA,uBAAS,GAAE;QAAE,OAAO;IACzB,IAAI,CAAC;QACH,mBAAmB,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,sCAAsC;QACtC,OAAO,CAAC,IAAI,CAAC,4BAA6B,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC;IACnE,CAAC;AACH,CAAC;AARD,sDAQC"}

package/dist/lib/traceToolNames.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * traceToolNames — the two facts about the trace toolpack that are needed
+ * BEFORE the pack is loaded.
+ *
+ * `.selfExplain()` mounts the pack lazily (9.94.0): the toolpack module —
+ * eleven tools over a finished trace, the largest single module on the
+ * library's default graph — is reached through `import()` the first time
+ * the self-explain skill is active on an iteration, never at build time and
+ * never for an agent that did not enable it (see `selfExplain.ts` ·
+ * `buildSelfExplainToolProvider`). Two things the builder needs cannot wait
+ * for that load, and they live here so that reading them costs nothing:
+ *
+ *   - `TRACE_TOOL_NAMES` — the names the pack can mount, which `build()`
+ *     reserves synchronously (a consumer tool sharing a name would silently
+ *     shadow the trace tool);
+ *   - `NO_COMPLETED_RUN_MESSAGE` — the model-visible answer every trace tool
+ *     gives before a turn has finished, which the delegate-mode `explain_run`
+ *     tool returns without loading the pack at all.
+ *
+ * `traceToolpack.ts` re-exports `TRACE_TOOL_NAMES` and `lazyToolpack.ts`
+ * re-exports `NO_COMPLETED_RUN_MESSAGE`, so every existing import path still
+ * resolves — this module only changes what a static import of them COSTS.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_COMPLETED_RUN_MESSAGE = exports.TRACE_TOOL_NAMES = void 0;
+/**
+ * The tool names this pack can mount. The Agent builder reserves these at
+ * `.selfExplain()` build time — the tools slot dedupes by name with
+ * first-occurrence-wins, so a consumer tool sharing a name would silently
+ * shadow the trace tool AND the skill body would instruct the model into
+ * the wrong one. Exported so the reservation list is DERIVED from the pack
+ * rather than typed out beside it (a second list is a list that drifts).
+ *
+ * The pack itself asserts, at test time, that what it mounts is exactly
+ * this list (test/trace-toolpack/selfExplainAgent.test.ts).
+ */
+exports.TRACE_TOOL_NAMES = [
+    'run_overview',
+    'find_context_errors',
+    'find_in_trace',
+    'trace_node',
+    'trace_slice',
+    'backtrack',
+    'who_wrote',
+    'get_value',
+    'inspect_tool_call',
+    'inspect_tool_run',
+    'inspect_subflow',
+    'read_narrative',
+];
+/** Model-visible answer when no completed run is available yet. */
+exports.NO_COMPLETED_RUN_MESSAGE = 'No completed run is available yet — the trace exists only after a turn finishes. ' +
+    'Tell the user there is nothing to explain yet.';
+//# sourceMappingURL=traceToolNames.js.map

package/dist/lib/traceToolNames.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceToolNames.js","sourceRoot":"","sources":["../../src/lib/traceToolNames.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;;;AAEH;;;;;;;;;;GAUG;AACU,QAAA,gBAAgB,GAAG;IAC9B,cAAc;IACd,qBAAqB;IACrB,eAAe;IACf,YAAY;IACZ,aAAa;IACb,WAAW;IACX,WAAW;IACX,WAAW;IACX,mBAAmB;IACnB,kBAAkB;IAClB,iBAAiB;IACjB,gBAAgB;CACR,CAAC;AAEX,mEAAmE;AACtD,QAAA,wBAAwB,GACnC,mFAAmF;IACnF,gDAAgD,CAAC"}

package/dist/locales/timeAsk.js

@@ -3,7 +3,7 @@
  * locales/timeAsk — the time ask's sentences, for the PERSON answering it
  * (time design § 6.2, TQ7).
  *
- * The library validates a time field's answer (`core/time/ask.ts` ·
+ * The library validates a time field's answer (`time/ask.ts` ·
  * `checkTimeAnswer`), so a refused answer needs a reason — and the reason is a
  * sentence a person reads on the re-ask (`InputRefusal.reason`), never text
  * for the model. It lives here, as data, so an app can translate or reword

package/dist/mcp/connectionRefusals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connectionRefusals.js","sourceRoot":"","sources":["../../src/mcp/connectionRefusals.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG;;;AAIH,0EAA0E;AAC1E,MAAM,kBAAkB,GAAG,CAAC,WAAW,EAAE,UAAU,EAAE,OAAO,CAAU,CAAC;AAEvE;;;;;;;GAOG;AACH,SAAgB,wBAAwB,CACtC,IAA6C,EAC7C,IAAY;IAEZ,MAAM,EAAE,GAAG,aAAa,IAAI,GAAG,CAAC;IAChC,6EAA6E;IAC7E,6EAA6E;IAC7E,8EAA8E;IAC9E,iCAAiC;IACjC,MAAM,KAAK,GAAG,IAAoD,CAAC;IAEnE,IAAI,KAAK,CAAC,YAAY,CAAC,KAAK,SAAS,EAAE,CAAC;QACtC,IAAI,KAAK,CAAC,WAAW,CAAC,KAAK,SAAS,IAAI,KAAK,CAAC,SAAS,CAAC,KAAK,SAAS,EAAE,CAAC;YACvE,MAAM,IAAI,KAAK,CACb,GAAG,EAAE,kFAAkF;gBACrF,oDAAoD,CACvD,CAAC;QACJ,CAAC;QACD,OAAO;IACT,CAAC;IAED,sDAAsD;IACtD,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,sBAAsB,EAAE,CAAC;QACrD,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,SAAS,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CACb,GAAG,EAAE,0BAA0B,MAAM,6BAA6B;gBAChE,oEAAoE,MAAM,QAAQ;gBAClF,6DAA6D,KAAK,EAAE,CACvE,CAAC;QACJ,CAAC;IACH,CAAC;IACD,gBAAgB,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,EAAE,CAAC,CAAC;AAC5C,CAAC;AAhCD,4DAgCC;AAED;;;;;GAKG;AACH,MAAM,sBAAsB,GAExB;IACF;QACE,iBAAiB;QACjB,gFAAgF;YAC9E,+EAA+E;YAC/E,6CAA6C;KAChD;IACD;QACE,YAAY;QACZ,kGAAkG;KACnG;IACD;QACE,WAAW;QACX,gGAAgG;KACjG;IACD;QACE,KAAK;QACL,+EAA+E;YAC7E,wCAAwC;KAC3C;IACD;QACE,SAAS;QACT,uFAAuF;KACxF;CACF,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,SAAS,gBAAgB,CAAC,UAAmB,EAAE,EAAU;IACvD,MAAM,OAAO,GAAG,CAAC,UAAU,IAAI,EAAE,CAAsC,CAAC;IACxE,KAAK,MAAM,MAAM,IAAI,kBAAkB,EAAE,CAAC;QACxC,IAAI,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,UAAU,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CACb,GAAG,EAAE,6BAA6B,MAAM,yCAAyC;gBAC/E,oFAAoF;gBACpF,kFAAkF;gBAClF,uDAAuD,CAC1D,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/mcp/elicitation.js

@@ -0,0 +1,186 @@
+"use strict";
+/**
+ * mcp/elicitation — a typed ask carried as an MCP elicitation, and the
+ * elicitation's answer carried back (time design § 6.1).
+ *
+ * Pattern: Adapter, pure, both directions in one file so they cannot drift.
+ *          `elicitationOf` maps a pending `AwaitingInput` onto the MCP
+ *          elicitation request (`message` + a flat `requestedSchema` of
+ *          primitive properties, the MCP specification revision of
+ *          2025-06-18); `answerFromElicitation` maps the client's `content`
+ *          back to the `InputResponse` `agent.resume` takes. Nothing is
+ *          checked here that the resume door checks: the answer goes through
+ *          `tools/inputRequest.ts` · `applyInputResponse` like any other, and a
+ *          refused time answer comes back as a re-ask to elicit again.
+ * Role:    mcp (the transport). Reads `tools/inputRequest.ts` types only.
+ * Emits:   N/A.
+ *
+ * ## The mapping
+ *
+ * MCP's elicitation schema holds strings (with a `format` of `date-time`
+ * among a few), numbers, booleans and string choices (`enum` + `enumNames`).
+ * It has no range, so a time field becomes the properties a person can fill:
+ *
+ * | Field | Properties |
+ * |-------|------------|
+ * | `string` / `number` / `boolean` | `<id>`, as typed; a string's `enum` with its `labels` as `enumNames` |
+ * | `format: 'instant'` | `<id>`: `{ type: 'string', format: 'date-time' }` |
+ * | `format: 'zone'` | `<id>`: a string |
+ * | `format: 'time-range'` | `<id>.from` and `<id>.to`: two `date-time` strings, joined back as `from/to` |
+ * | a `format` field with choices | `<id>`: the choices, labelled; unless `strict`, ALSO the free-entry properties above (`<id>.other` for an instant or a zone) — answer one or the other |
+ *
+ * Only the fields still open are asked (a supplied value is known). A
+ * property is `required` only when it is the one way to answer a missing
+ * field. A number or boolean with `enum` has no MCP spelling and is refused,
+ * never widened; so is a field id that collides with a generated name.
+ *
+ * @example
+ * ```ts
+ * const out = await agent.run({ message });
+ * if (isInputPause(out)) {
+ *   const request = elicitationOf(out.awaitingInput);
+ *   const reply = await mcpClientSession.elicit(request); // { action: 'accept', content }
+ *   if (reply.action === 'accept')
+ *     await agent.resume(out.checkpoint, answerFromElicitation(out.awaitingInput, reply.content));
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.answerFromElicitation = exports.elicitationOf = void 0;
+const inputRequest_js_1 = require("../tools/inputRequest.js");
+const own = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+function fail(reason) {
+    throw new inputRequest_js_1.InputRequestError(reason);
+}
+function carriageOf(field) {
+    const id = field.id;
+    if (field.enum === undefined) {
+        return { entry: field.format === 'time-range' ? [`${id}.from`, `${id}.to`] : [id] };
+    }
+    if (field.format === undefined || field.strict === true)
+        return { choice: id, entry: [] };
+    // A time field's choices keep free entry open (time design § 6.1): both ways travel.
+    return {
+        choice: id,
+        entry: field.format === 'time-range' ? [`${id}.from`, `${id}.to`] : [`${id}.other`],
+    };
+}
+function entryProperty(field) {
+    const description = field.description !== undefined ? { description: field.description } : {};
+    if (field.type === 'number')
+        return { type: 'number', ...description };
+    if (field.type === 'boolean')
+        return { type: 'boolean', ...description };
+    if (field.format === 'instant' || field.format === 'time-range')
+        return { type: 'string', format: 'date-time', ...description };
+    return { type: 'string', ...description };
+}
+function choiceProperty(field) {
+    if (field.type !== 'string') {
+        fail(`field '${field.id}': an MCP elicitation carries choices of strings only`);
+    }
+    return {
+        type: 'string',
+        ...(field.description !== undefined && { description: field.description }),
+        enum: (field.enum ?? []).map(String),
+        ...(field.labels !== undefined && { enumNames: [...field.labels] }),
+    };
+}
+/** The fields still open — a supplied value is known and not asked again. */
+const openFields = (awaiting) => awaiting.fields.filter((f) => !own(awaiting.supplied, f.id));
+/**
+ * The MCP elicitation for a pending typed ask: its question (after the
+ * refusal's reason, on a re-ask) and one property per way to answer each open
+ * field. Throws `InputRequestError` on a field MCP cannot carry.
+ */
+function elicitationOf(awaiting) {
+    const properties = {};
+    const required = [];
+    const ids = new Set(awaiting.fields.map((f) => f.id));
+    const place = (name, property, owner) => {
+        if (own(properties, name) || (name !== owner && ids.has(name))) {
+            fail(`field '${owner}': the elicitation property '${name}' collides with another field`);
+        }
+        properties[name] = property;
+    };
+    for (const field of openFields(awaiting)) {
+        const carriage = carriageOf(field);
+        if (carriage.choice !== undefined)
+            place(carriage.choice, choiceProperty(field), field.id);
+        for (const name of carriage.entry)
+            place(name, entryProperty(field), field.id);
+        // Required only when there is ONE way to answer: a choice with free entry is either-or.
+        if (awaiting.missing.includes(field.id) &&
+            (carriage.choice === undefined) !== (carriage.entry.length === 0)) {
+            required.push(...(carriage.choice !== undefined ? [carriage.choice] : carriage.entry));
+        }
+    }
+    const message = awaiting.refused !== undefined
+        ? `${awaiting.refused.reason}\n\n${awaiting.question}`
+        : awaiting.question;
+    return {
+        message,
+        requestedSchema: {
+            type: 'object',
+            properties,
+            ...(required.length > 0 && { required }),
+        },
+    };
+}
+exports.elicitationOf = elicitationOf;
+function primitive(name, value) {
+    if (typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    return fail(`the elicitation's '${name}' is not a string, number or boolean`);
+}
+/**
+ * The `InputResponse` an accepted elicitation's `content` names — each open
+ * field's value, a time range's two properties joined as `from/to`. Throws
+ * `InputRequestError` on a property the elicitation did not ask, on a choice
+ * AND a free entry for one field, and on half a range. The values are judged
+ * by `agent.resume`, as any answer is.
+ */
+function answerFromElicitation(awaiting, content) {
+    if (typeof content !== 'object' || content === null || Array.isArray(content)) {
+        fail("the elicitation's content must be an object");
+    }
+    const given = content;
+    const asked = new Set();
+    const values = {};
+    for (const field of openFields(awaiting)) {
+        const carriage = carriageOf(field);
+        const names = [...(carriage.choice !== undefined ? [carriage.choice] : []), ...carriage.entry];
+        names.forEach((n) => asked.add(n));
+        const chosen = carriage.choice !== undefined && own(given, carriage.choice);
+        const entered = carriage.entry.filter((n) => own(given, n));
+        if (chosen && entered.length > 0) {
+            fail(`field '${field.id}': answer with a choice or your own value, not both`);
+        }
+        let value;
+        if (chosen)
+            value = primitive(carriage.choice, given[carriage.choice]);
+        else if (field.format === 'time-range' && entered.length > 0) {
+            if (entered.length !== 2)
+                fail(`field '${field.id}': a time range needs its start and its end`);
+            value = `${primitive(`${field.id}.from`, given[`${field.id}.from`])}/${primitive(`${field.id}.to`, given[`${field.id}.to`])}`;
+        }
+        else if (entered.length === 1)
+            value = primitive(entered[0], given[entered[0]]);
+        if (value !== undefined) {
+            Object.defineProperty(values, field.id, {
+                value,
+                enumerable: true,
+                writable: true,
+                configurable: true,
+            });
+        }
+    }
+    const unasked = Object.keys(given).filter((k) => !asked.has(k));
+    if (unasked.length > 0)
+        fail(`the elicitation's content names properties it did not ask: ${unasked.join(', ')}`);
+    return { requestId: awaiting.requestId, values };
+}
+exports.answerFromElicitation = answerFromElicitation;
+//# sourceMappingURL=elicitation.js.map