@bongos/core 1.19.710 → 1.19.711

package/modules/agents/lib/answer-hold.js

@@ -0,0 +1,91 @@
+'use strict';
+
+// modules/agents/lib/answer-hold.js — where a server-side fire's answer waits for
+// the caller who asked for it (task 1002493).
+//
+// THE PROBLEM. `POST /agents/:name/invoke` takes 60-120 seconds and costs about a
+// dollar, so it cannot be a synchronous request — the edge proxy times out around
+// 100s and the caller would pay for an answer nobody receives. So it returns 202
+// with a run id and the fire continues behind it. That leaves one question: where
+// does the answer go?
+//
+// NOT THE LEDGER. `agents_runs.output_ref` is a POINTER by the schema's own rule,
+// never the output — agent text rendered to whoever reads the ledger would make
+// that table a delivery path for whatever the agent read. And there is no blob
+// store in this project to point AT.
+//
+// SO: THE ANSWER IS HELD, NOT STORED. In memory, bounded, for a few minutes,
+// keyed by run id, and handed to the first caller who asks for it. The honest
+// reading of this is a pickup counter, not a database:
+//
+//   - it does not survive a restart, and nothing pretends otherwise — the LEDGER
+//     survives, so "the fire happened, cost this, and succeeded" is durable even
+//     when the text is gone;
+//   - it is capped at MAX_HELD entries and evicts the oldest, so a loop of
+//     invocations cannot grow the process;
+//   - it expires, because an answer nobody collected is a copy of whatever the
+//     agent read sitting in memory for no one.
+//
+// A caller that needs the answer durably passes `--out` to
+// `scripts/gds/agent-invoke.js` and owns the file. That is the deliberate split:
+// the CLI delivers to the operator's disk, the route delivers to the operator's
+// next request, and neither writes agent prose into a table.
+//
+// Requires nothing (ADR 0083). The clock is injected so the expiry is testable
+// without waiting for it.
+
+const MAX_HELD = 50;
+const TTL_MS = 15 * 60 * 1000;
+
+function createAnswerHold({ maxHeld = MAX_HELD, ttlMs = TTL_MS, now = () => Date.now() } = {}) {
+  // Insertion-ordered, which is what makes "evict the oldest" a first key rather
+  // than a sort.
+  const held = new Map();
+
+  function sweep() {
+    const cutoff = now() - ttlMs;
+    for (const [key, entry] of held) {
+      if (entry.at <= cutoff) held.delete(key);
+    }
+  }
+
+  return {
+    /** Hold one answer for the caller who asked for it. */
+    put(runId, answer) {
+      const key = String(runId);
+      if (key === 'null' || key === 'undefined' || key === '') return false;
+      sweep();
+      // Delete-then-set so a re-put moves the entry to the END of the insertion
+      // order; without it a refreshed entry would keep its original eviction
+      // position and could be dropped while it was the newest thing here.
+      held.delete(key);
+      held.set(key, { answer, at: now() });
+      while (held.size > maxHeld) {
+        const oldest = held.keys().next().value;
+        held.delete(oldest);
+      }
+      return true;
+    },
+
+    /**
+     * Collect an answer. Returns null when it was never held, has expired, or was
+     * evicted — three different histories with the same remedy, and the LEDGER is
+     * where a caller finds out which.
+     */
+    take(runId) {
+      sweep();
+      const key = String(runId);
+      const entry = held.get(key);
+      if (!entry) return null;
+      // Reading does NOT remove it: a caller polling while the fire is still in
+      // flight would otherwise consume the answer with its first successful poll
+      // and see nothing on the next. Expiry is what removes things here.
+      return entry.answer;
+    },
+
+    /** For the tests and for a future /status: what is waiting to be collected. */
+    size() { sweep(); return held.size; },
+  };
+}
+
+module.exports = { createAnswerHold, MAX_HELD, TTL_MS };

package/modules/agents/lib/authoring.js

@@ -0,0 +1,155 @@
+'use strict';
+
+// modules/agents/lib/authoring.js — the decisions behind the agent WRITE surface
+// (task 1002493, goal 1000038 Phase 2a).
+//
+// The routes do HTTP; this does the thinking, so every rule below is testable
+// without a server, a database or a session. Requires nothing, for the reason
+// validate.js and gate.js require nothing: `modules/**` may import only
+// src/module-api.js (ADR 0083), and importing nothing clears that bar outright.
+//
+// FOUR RULES, and each is a way an authoring surface turns into an escalation.
+//
+//  1. AUTHORITY FIELDS ARE NEVER READ FROM THE REQUEST. `author_rank`, `source`,
+//     `provenance`, `enabled`, `scope_violation` and the file-provenance columns
+//     are decided by the server or by a dedicated route, never by a body key. A
+//     request that names one is REFUSED rather than quietly stripped: silently
+//     ignoring a field called `author_rank` teaches the next caller that it
+//     worked, and the difference only surfaces as an authority bug much later.
+//
+//  2. THE STAMPED RANK IS THE AUTHOR'S LIVE RANK, so it can never exceed it.
+//     That is the declaration clamp: a builder may declare a scope, a trigger
+//     and a tier, and may not declare the authority those are judged against.
+//     Editing re-stamps to the EDITOR's live rank, which can only move the row
+//     down the ladder or leave it — the safe direction — and the scope wall then
+//     re-runs against the new, lower rank.
+//
+//     WHAT IT IS NOT: a grant of runtime authority. An agent's authority is its
+//     tool set intersected with its (absent, in v1) service principal — the
+//     spawn path is fixed read-only. author_rank clamps what may be DECLARED.
+//
+//  3. A DB-AUTHORED DEFINITION MAY NOT REACH A PROTECTED SURFACE AT ALL —
+//     not at Metic, not at Archon. This is deliberately STRICTER than
+//     validate.js's Metic+ floor, and the asymmetry is the point: a committed
+//     definition reached the registry through a branch, a grader panel and CI,
+//     while one authored here reached it through a single HTTP call. The rank
+//     floor is the right wall for the reviewed path; for the unreviewed one the
+//     answer is no.
+//
+//  4. THE SYNC OWNS ITS OWN ROWS. A `source='file'` definition is rewritten from
+//     the committed file on every deploy, so editing or deleting one here would
+//     be undone by the next reconcile — a write that silently reverts is worse
+//     than a refusal. Arming is the exception, and the only one: `enabled` is
+//     explicitly an operator decision that agents-sync carries forward
+//     untouched (its rule 4), which is what makes enable/disable the act that
+//     turns a committed definition on.
+
+// Body keys a caller may set. Anything else is refused — see rule 1.
+const AUTHORABLE_FIELDS = Object.freeze([
+  'name', 'title', 'persona', 'trigger_type', 'trigger_spec', 'model_tier',
+  'scope_modules', 'scope_paths',
+]);
+
+// Keys that would be an escalation if they were honoured, named explicitly so a
+// refusal can say WHICH one and why rather than "unknown field".
+const SERVER_OWNED_FIELDS = Object.freeze({
+  author_rank: 'the author rank is taken from your live DB rank, never from the request (ADR 0016)',
+  author_builder_id: 'the author is taken from your session, never from the request',
+  source: "'db' for anything authored here; only agents-sync writes 'file' rows",
+  provenance: "'instance' for anything authored here",
+  enabled: 'use POST /agents/:name/enable or /disable — arming is its own act, with its own audit line',
+  scope_violation: 'set by the scope wall, never declared',
+  source_path: 'file provenance belongs to agents-sync',
+  source_sha256: 'file provenance belongs to agents-sync',
+  last_synced_at: 'file provenance belongs to agents-sync',
+  id: 'assigned by the database',
+});
+
+function isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Rule 1. Which forbidden keys did this body name?
+ *
+ * @returns {Array<{field: string, reason: string}>} empty when the body is clean.
+ */
+function forbiddenFields(body) {
+  if (!isPlainObject(body)) return [];
+  return Object.keys(body)
+    .filter((k) => Object.prototype.hasOwnProperty.call(SERVER_OWNED_FIELDS, k))
+    .map((field) => ({ field, reason: SERVER_OWNED_FIELDS[field] }));
+}
+
+/**
+ * Rule 3. Does this candidate's declared scope reach a protected surface?
+ *
+ * Fail-closed in the same three places the validator's wall is (task 1002492):
+ * a missing matcher counts as protected, a throwing matcher counts as protected,
+ * and only an explicit `false` clears a path. Ambiguity reads as protected here
+ * too — loud and fixable beats silent and admitted.
+ *
+ * @returns {{protected: boolean, modules: string[], paths: string[]}}
+ */
+function protectedScopeHits(candidate, { protectedModules = [], isProtectedPath = null } = {}) {
+  const declaredModules = Array.isArray(candidate && candidate.scope_modules) ? candidate.scope_modules : [];
+  const declaredPaths = Array.isArray(candidate && candidate.scope_paths) ? candidate.scope_paths : [];
+  const modules = declaredModules.filter((m) => protectedModules.includes(m));
+  let paths = [];
+  if (declaredPaths.length > 0) {
+    if (typeof isProtectedPath !== 'function') {
+      paths = [...declaredPaths];
+    } else {
+      paths = declaredPaths.filter((p) => {
+        try { return isProtectedPath(p) !== false; } catch { return true; }
+      });
+    }
+  }
+  return { protected: modules.length > 0 || paths.length > 0, modules, paths };
+}
+
+/**
+ * Rule 4. May this existing row be edited or deleted through the API?
+ *
+ * @returns {{ok: boolean, reason: string|null}}
+ */
+function writableByApi(row) {
+  if (!row) return { ok: false, reason: 'no such agent in the registry' };
+  if (row.source === 'file') {
+    return {
+      ok: false,
+      reason: `this definition is owned by ${row.source_path || 'a committed file'} — agents-sync rewrites it on every deploy, so an edit here would be silently undone. Change the file. Arming is the exception: enable/disable work on a file-sourced definition and the sync carries your choice forward.`,
+    };
+  }
+  return { ok: true, reason: null };
+}
+
+/**
+ * Merge a PATCH over the row it edits, so the validator judges the WHOLE
+ * definition rather than the delta.
+ *
+ * A partial update that only validated its own keys is how a definition ends up
+ * in a state no single request ever asked for: switch `trigger_type` to 'event'
+ * in one call and the missing `trigger_spec.event` is never noticed, because the
+ * call that would have noticed did not send that field.
+ */
+function mergeForValidation(row, patch) {
+  const base = {};
+  for (const f of AUTHORABLE_FIELDS) {
+    if (row && row[f] !== undefined && row[f] !== null) base[f] = row[f];
+  }
+  const over = isPlainObject(patch) ? patch : {};
+  for (const f of AUTHORABLE_FIELDS) {
+    if (Object.prototype.hasOwnProperty.call(over, f)) base[f] = over[f];
+  }
+  return base;
+}
+
+module.exports = {
+  AUTHORABLE_FIELDS,
+  SERVER_OWNED_FIELDS,
+  forbiddenFields,
+  protectedScopeHits,
+  writableByApi,
+  mergeForValidation,
+};

package/modules/agents/lib/fire-budget.js

@@ -0,0 +1,109 @@
+'use strict';
+
+// modules/agents/lib/fire-budget.js — the per-builder ceiling on how often an
+// agent can be fired (task 1002493).
+//
+// WHY. `POST /agents/:name/invoke` is self-gated at requireBuilder, deliberately:
+// which agents exist at all is an operator decision, and a v1 agent is
+// hard-read-only. What that reasoning does NOT bound is SPEND. A fire costs real
+// money — roughly $0.90 and 60-120 seconds for a historian question — and the
+// only thing between a builder and a loop of them was that they had to type it.
+// An async 202 made that worse, not better: the caller does not even wait.
+//
+// So: a sliding window per BUILDER, not per IP. The existing limiters in
+// src/bongos/middleware/rate-limit.js key on `req.ip` because they guard surfaces
+// reachable before anyone is identified; every fire is attributable by
+// construction (ADR 0016, and the ledger's whole point), and a builder's IP is
+// incidental — two builders behind one office NAT must not share a spend ceiling,
+// and one builder on two machines must not get two.
+//
+// A CEILING, NOT A BUDGET. This bounds the blast radius of a loop; it does not
+// decide what agents may cost. The real accounting is `agents_runs.cost_usd`
+// billed through the shared LLM cost cache, and a per-instance $/month cap reads
+// from there. Do not grow this into a budget — a ceiling that silently became the
+// accounting would be a second, wrong answer to "what did agents cost".
+//
+// ONE INSTANCE, module-level, for the reason ADR 0209 gives about
+// `publicProjectFeedRateLimit`: two call sites that each build their own from
+// matching config get two budgets, which looks identical in review and hands a
+// caller double the rate. (The answer hold is per-router on purpose and that is
+// not a contradiction — a delivery buffer splitting just means an answer is
+// collected from the router that produced it, while a ceiling splitting means
+// there is no ceiling.)
+//
+// Requires nothing (ADR 0083). The clock is injected so the window is testable
+// without waiting for it.
+
+// Deliberately generous: a builder working through a question genuinely asks
+// several in a session, and a limit that bites during ordinary use gets raised by
+// whoever hits it rather than respected. Ten an hour is ~$9/hour/builder worst
+// case, which is a bad afternoon rather than a bad month.
+const DEFAULT_LIMIT = 10;
+const DEFAULT_WINDOW_MS = 60 * 60 * 1000;
+
+// Bounded so a large instance's bucket map cannot grow without limit. Eviction is
+// safe here in a way it would not be for a security check: dropping the OLDEST
+// bucket forgives the least recent spender, never the busiest one.
+const MAX_TRACKED_BUILDERS = 5000;
+
+function envInt(name, fallback) {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  const n = Number(raw);
+  return Number.isInteger(n) && n > 0 ? n : fallback;
+}
+
+function createFireBudget({
+  limit = envInt('BONGOS_AGENTS_FIRE_LIMIT', DEFAULT_LIMIT),
+  windowMs = envInt('BONGOS_AGENTS_FIRE_WINDOW_MS', DEFAULT_WINDOW_MS),
+  now = () => Date.now(),
+} = {}) {
+  const buckets = new Map();
+
+  return {
+    limit,
+    windowMs,
+
+    /**
+     * May this builder fire right now? Records the fire when the answer is yes,
+     * so the caller cannot forget to.
+     *
+     * FAIL-CLOSED ON AN UNIDENTIFIED CALLER: no builder id means no bucket to
+     * spend from, and an unattributable fire is exactly what the ledger exists to
+     * prevent — so it is refused rather than admitted under a shared 'unknown'
+     * key, which one caller could exhaust for everyone.
+     *
+     * @returns {{ok: boolean, remaining: number, retryAfterSeconds: number}}
+     */
+    check(builderId) {
+      const key = builderId === null || builderId === undefined ? '' : String(builderId);
+      if (key === '') return { ok: false, remaining: 0, retryAfterSeconds: 0 };
+      const at = now();
+      const cutoff = at - windowMs;
+      const bucket = (buckets.get(key) || []).filter((t) => t > cutoff);
+      if (bucket.length >= limit) {
+        buckets.set(key, bucket);
+        return {
+          ok: false,
+          remaining: 0,
+          retryAfterSeconds: Math.max(1, Math.ceil((bucket[0] + windowMs - at) / 1000)),
+        };
+      }
+      bucket.push(at);
+      // Delete-then-set keeps insertion order meaningful, so the eviction below
+      // drops the builder who has been quiet longest rather than an arbitrary one.
+      buckets.delete(key);
+      buckets.set(key, bucket);
+      while (buckets.size > MAX_TRACKED_BUILDERS) {
+        buckets.delete(buckets.keys().next().value);
+      }
+      return { ok: true, remaining: limit - bucket.length, retryAfterSeconds: 0 };
+    },
+
+    /** Test seam — a module-level singleton otherwise carries state between cases. */
+    reset() { buckets.clear(); },
+    size() { return buckets.size; },
+  };
+}
+
+module.exports = { createFireBudget, DEFAULT_LIMIT, DEFAULT_WINDOW_MS, MAX_TRACKED_BUILDERS };

package/modules/agents/lib/gate.js

@@ -0,0 +1,64 @@
+'use strict';
+
+// modules/agents/lib/gate.js — may this definition be fired ON DEMAND, and if
+// not, what does the ledger row say (task 1002493).
+//
+// WHY IT IS ITS OWN FILE. Two callers ask the same question from opposite sides
+// of the trust boundary: `scripts/gds/agent-invoke.js` (task 1002491) runs where
+// the operator is, and `POST /agents/:name/invoke` runs on the server. A gate
+// with two implementations is a gate with two behaviours the day one of them is
+// edited — and the interesting half of this answer is the REASON, which is the
+// entire content of the no-go row a refusal writes. One rule, one wording, one
+// place to change it.
+//
+// Requires NOTHING, for the same reason validate.js does: `modules/**` may import
+// only src/module-api.js (ADR 0083), and importing nothing clears that bar by
+// construction while letting the CLI require it directly.
+//
+// THE VERDICT IS ALWAYS A FULL SENTENCE, never a code. A caller that wants a code
+// has `decision`; the reason is written to be read by whoever is wondering why
+// the agent they asked for did not answer.
+
+// Mirrors agents_definitions_trigger_type_chk. Spelled here rather than imported
+// from validate.js only to keep this file dependency-free; the routes test pins
+// the two against each other so they cannot drift.
+const ON_DEMAND = 'on-demand';
+
+function isNonEmptyString(v) {
+  return typeof v === 'string' && v.trim().length > 0;
+}
+
+/**
+ * Decide whether a registry row may be invoked on demand.
+ *
+ * PURE and total: a missing row, a hostile row and a well-formed row all return
+ * the same shape, and nothing here throws into a caller that was only asking.
+ *
+ * @param {object|null} row  the agents_definitions row as read from the registry.
+ * @returns {{decision: 'go'|'no-go', reason: string|null}}
+ */
+function gateFor(row) {
+  if (!row) return { decision: 'no-go', reason: 'no such agent in the registry' };
+  if (row.trigger_type !== ON_DEMAND) {
+    return {
+      decision: 'no-go',
+      reason: `trigger_type is '${row.trigger_type}', not '${ON_DEMAND}' — this agent is dispatched by an event, not asked a question`,
+    };
+  }
+  // Checked before `enabled` even though agents_definitions_flagged_not_armed_chk
+  // makes a flagged row necessarily disabled: the two states share a verdict and
+  // have completely different fixes, and the reason is what the caller acts on.
+  if (isNonEmptyString(row.scope_violation)) {
+    return { decision: 'no-go', reason: `disarmed by the scope wall: ${row.scope_violation}` };
+  }
+  // THE HALF THAT MAKES `disable` MEAN SOMETHING. The dispatch index is partial
+  // (`WHERE enabled`), so an event agent switched off is simply never selected;
+  // on demand there is no selection step, so the check has to be here or
+  // disabling would stop autonomous firing and leave the agent askable.
+  if (row.enabled !== true) {
+    return { decision: 'no-go', reason: 'the definition is present in the registry but not enabled' };
+  }
+  return { decision: 'go', reason: null };
+}
+
+module.exports = { gateFor, ON_DEMAND };