@inetafrica/open-claudia 3.0.25 → 3.0.27

package/core/guardrail.js

@@ -0,0 +1,251 @@
+// Track C — dynamic owner-guardrail capture. When the OWNER states a durable
+// behavioural rule mid-chat ("from now on ...", "never ...", "stop ...ing"), a
+// deterministic post-turn detector either captures it straight into lessons.md
+// (always-loaded) or asks first, so the correction holds on the next turn with
+// no code change and no deploy.
+//
+// Invariants:
+//  - Owner-only, HARD. Rules are NEVER captured from external speakers — the
+//    caller gates on relationship.guardActive(speaker) and consider() re-checks.
+//  - Advisory-tier. A captured rule layers ABOVE lessons but can never override
+//    the code-fixed hard rules (tool-first, enforcer). Safety rails stay in code.
+//  - No model call. Detection is phrase-based and default-silent; the ambiguous
+//    tier defers to the owner (a Y/N button), not to a model that could invent
+//    a rule. Clear "from now on / never / stop" phrasings auto-capture with an
+//    announce + one-tap undo; softer imperatives ask first.
+//  - Dedupe against existing lessons (normalized text) so the same rule
+//    reinforces instead of cluttering the always-on budget.
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { atomicWriteFileSync } = require("./fsutil");
+
+const CONFIG_DIR = require("../config-dir");
+const lessons = require("./lessons");
+
+const PENDING_FILE = path.join(CONFIG_DIR, "guardrail-pending.json");
+const PENDING_TTL_MS = Number(process.env.GUARDRAIL_PENDING_TTL_MS || 24 * 60 * 60 * 1000);
+const MIN_RULE_CHARS = 10;
+const MIN_RULE_WORDS = 3;
+const MAX_RULE_CHARS = lessons.MAX_LESSON_CHARS || 240;
+
+// Operability control (mirrors pack-review's PACK_REVIEW gate). Default ON —
+// this is not a hidden kill-switch; it lets the capture path be disabled
+// without a deploy if it ever misfires, and lets tests force it off.
+function enabled() {
+  return String(process.env.GUARDRAIL_CAPTURE || "on").toLowerCase() !== "off";
+}
+
+// ── detection (pure, deterministic) ─────────────────────────────────
+
+// Explicit durable markers → high confidence (auto-capture). Matched anywhere.
+const HIGH_MARKERS = [
+  /\bfrom now on\b/i,
+  /\bfrom here on(?: out)?\b/i,
+  /\bgoing forward\b/i,
+  /\bin (?:the )?future\b/i,
+  /\bnever again\b/i,
+  /\bmake (?:it|this|that) a (?:standing )?rule\b/i,
+  /\bas a (?:standing )?rule\b/i,
+  /\balways remember to\b/i,
+];
+// Clear negative directive at the start of a (cleaned) clause → high. "stop"
+// must be followed by a gerund so "stop summarizing" captures but "stop the
+// server" (a one-off action) does not.
+const HIGH_NEG = /^(?:never\s+\w+|stop\s+\w+ing|(?:don'?t|do not) ever\b)/i;
+// Softer imperatives → medium (ask the owner first).
+const MED_OPENER = /^(?:always|don'?t|do not|make sure|be sure|remember to|prefer|avoid)\b/i;
+
+// Junk that pattern-matches a directive but is never a rule.
+const STOP_RULES = new Set(["never mind", "nevermind", "stop it", "never ever", "don't worry", "do not worry"]);
+
+function splitSentences(text) {
+  return String(text || "")
+    .split(/(?<=[.!?])\s+|\n+/)
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function endsAsQuestion(s) {
+  return /\?\s*$/.test(String(s || ""));
+}
+
+function stripOpener(s) {
+  return String(s || "").replace(/^(?:ok(?:ay)?|hey|so|and|also|well|please|now)[,:\s]+/i, "").trim();
+}
+
+// Turn a directive sentence into a clean, imperative one-line rule: drop soft
+// openers, leading durable markers, and polite lead-ins; collapse whitespace;
+// capitalize; cap length. Keeps "never/stop/always/make sure" intact — those
+// are the rule's core and drive classification.
+function cleanRule(sentence) {
+  let s = stripOpener(sentence);
+  s = s.replace(/^(?:from now on|from here on(?: out)?|going forward|in (?:the )?future)[,:\s]+/i, "");
+  s = s.replace(/^(?:can you|could you|i(?:'d| would)? (?:like|want) you to|i want you to)\s+/i, "");
+  s = s.replace(/\s+/g, " ").trim().replace(/[\s,;:]+$/g, "");
+  if (s) s = s[0].toUpperCase() + s.slice(1);
+  return s.slice(0, MAX_RULE_CHARS);
+}
+
+function ruleOk(rule) {
+  if (!rule || rule.length < MIN_RULE_CHARS) return false;
+  const low = rule.toLowerCase();
+  if (STOP_RULES.has(low)) return false;
+  if (low.split(/\s+/).length < MIN_RULE_WORDS) return false;
+  return true;
+}
+
+// Returns { isRule, confidence: "high"|"medium", rule, trigger } or { isRule:false }.
+// High short-circuits; a medium hit is remembered as the fallback.
+function detect(text) {
+  let medium = null;
+  for (const s of splitSentences(text)) {
+    if (endsAsQuestion(s)) continue;
+    const rule = cleanRule(s);
+    if (!ruleOk(rule)) continue;
+    const hasMarker = HIGH_MARKERS.some((re) => re.test(s));
+    if (hasMarker || HIGH_NEG.test(rule)) {
+      return { isRule: true, confidence: "high", rule, trigger: hasMarker ? "marker" : "directive" };
+    }
+    if (!medium && MED_OPENER.test(rule)) medium = { isRule: true, confidence: "medium", rule, trigger: "soft" };
+  }
+  return medium || { isRule: false };
+}
+
+// ── capture (dedupe against existing lessons) ───────────────────────
+
+function findDuplicate(rule) {
+  const norm = lessons.normalize(rule);
+  return lessons.readLessons().find((l) => lessons.normalize(l.text) === norm) || null;
+}
+
+// Add the rule as a lesson, or reinforce the existing twin. origin marks
+// provenance (guardrail = owner stated it in chat); lessons meta carries the date.
+function capture(rule, { origin = "guardrail" } = {}) {
+  const dup = findDuplicate(rule);
+  const target = dup ? dup.text : rule;
+  const r = lessons.addLesson({ text: target, origin });
+  return {
+    added: !!r.added,
+    reinforced: !!r.reinforced,
+    duplicate: !!dup,
+    id: r.id || (dup && dup.id) || lessons.lessonId(target),
+    text: target,
+    count: r.count,
+    overCap: !!r.overCap,
+  };
+}
+
+// ── pending store (medium-confidence Y/N confirms) ──────────────────
+
+function readPending() {
+  try { return JSON.parse(fs.readFileSync(PENDING_FILE, "utf-8")) || {}; }
+  catch (e) { return {}; }
+}
+
+function writePending(obj) {
+  fs.mkdirSync(path.dirname(PENDING_FILE), { recursive: true, mode: 0o700 });
+  atomicWriteFileSync(PENDING_FILE, JSON.stringify(obj, null, 2) + "\n", { mode: 0o600 });
+}
+
+function prunePending(obj, now) {
+  for (const [tok, rec] of Object.entries(obj)) {
+    if (!rec || now - (rec.createdAt || 0) > PENDING_TTL_MS) delete obj[tok];
+  }
+  return obj;
+}
+
+function putPending(rule, meta = {}, now = Date.now()) {
+  const obj = prunePending(readPending(), now);
+  const token = crypto.randomBytes(5).toString("hex");
+  obj[token] = { rule, channel: meta.channel || null, createdAt: now };
+  writePending(obj);
+  return token;
+}
+
+function takePending(token, now = Date.now()) {
+  const obj = prunePending(readPending(), now);
+  const rec = obj[token] || null;
+  if (rec) { delete obj[token]; }
+  writePending(obj);
+  return rec;
+}
+
+// ── render (pure) ───────────────────────────────────────────────────
+
+function clip(s) {
+  return String(s || "").replace(/\s+/g, " ").trim().slice(0, 200);
+}
+
+function renderCaptured(res) {
+  if (!res.added) return `📌 Already a standing rule — reinforced: "${clip(res.text)}"`;
+  return `📌 Got it — I'll keep this loaded as a standing rule from now on:\n"${clip(res.text)}"` +
+    `${res.overCap ? "\n(Over the lessons cap — the nightly dream will tidy.)" : ""}` +
+    `\nTap Undo if that's not what you meant.`;
+}
+
+function renderAsk(rule) {
+  return `Want me to make this a standing rule (always loaded)?\n"${clip(rule)}"`;
+}
+
+// ── orchestrator ────────────────────────────────────────────────────
+
+// Owner-gated. `announce(text, opts?)` sends to the chat (opts may carry a
+// keyboard); omit it for a dry run. Returns a small result for testability.
+async function consider({ text, speaker, announce, now = Date.now() } = {}) {
+  if (!enabled()) return { action: "disabled" };
+  const relationship = require("./relationship");
+  if (relationship.guardActive(speaker)) return { action: "external-skip" };
+
+  const d = detect(text);
+  if (!d.isRule) return { action: "silent" };
+
+  if (d.confidence === "high") {
+    const res = capture(d.rule);
+    if (typeof announce === "function") {
+      const opts = res.added
+        ? { keyboard: { inline_keyboard: [[{ text: "↩️ Undo", callback_data: `grd:undo:${res.id}` }]] } }
+        : undefined;
+      try { await announce(renderCaptured(res), opts); } catch (e) {}
+    }
+    return { action: res.added ? "captured" : "reinforced", id: res.id, rule: res.text, duplicate: res.duplicate };
+  }
+
+  const token = putPending(d.rule, { channel: speaker && speaker.channelId }, now);
+  if (typeof announce === "function") {
+    const opts = { keyboard: { inline_keyboard: [[
+      { text: "✅ Make it a rule", callback_data: `grd:save:${token}` },
+      { text: "Skip", callback_data: `grd:no:${token}` },
+    ]] } };
+    try { await announce(renderAsk(d.rule), opts); } catch (e) {}
+  }
+  return { action: "asked", token, rule: d.rule };
+}
+
+// ── callback actions (owner-gated by the caller) ────────────────────
+
+function confirmPending(token, now = Date.now()) {
+  const rec = takePending(token, now);
+  if (!rec) return { ok: false, reason: "expired" };
+  const res = capture(rec.rule);
+  return { ok: true, ...res };
+}
+
+function dropPending(token, now = Date.now()) {
+  const rec = takePending(token, now);
+  return { ok: !!rec, rule: rec ? rec.rule : "" };
+}
+
+function undo(lessonId) {
+  return { ok: !!lessons.removeLesson(lessonId) };
+}
+
+module.exports = {
+  PENDING_FILE, PENDING_TTL_MS,
+  enabled, detect, cleanRule, ruleOk, splitSentences,
+  findDuplicate, capture,
+  putPending, takePending, prunePending,
+  consider, confirmPending, dropPending, undo,
+  renderCaptured, renderAsk,
+};

package/core/handlers.js

@@ -12,7 +12,8 @@ const {
   CHAT_ID, discoverProviderExecutable, SOUL_FILE,
 } = require("./config");
 const { register } = require("./commands");
-const { send, deleteMessage } = require("./io");
+const { send, deleteMessage, typing } = require("./io");
+const { currentAdapter, currentChannelId } = require("./context");
 const {
   currentState, saveState, rootSession,
   freshUsage, getActiveProvider, getProjectKey, getProviderSession, setProviderSession, clearProviderSession,
@@ -1063,6 +1064,45 @@ register({
   },
 });
 
+register({
+  name: "agenda", aliases: ["agency"], description: "Aggregated read-only work list (tasks + Spaces + notifications)",
+  handler: async (env) => {
+    if (!authorized(env)) return;
+    const adapter = currentAdapter();
+    const channelId = currentChannelId();
+    const ledger = require("./agency/ledger");
+    try { typing(); } catch (_) {}
+    let result;
+    try {
+      result = await ledger.collect({ adapter: adapter && adapter.id, channelId });
+    } catch (e) {
+      return send(`Couldn't build the agenda: ${e.message}`);
+    }
+    send(ledger.render(result, { now: result.generatedAt, limitPerSource: 8 }));
+  },
+});
+
+register({
+  name: "next", description: "Advisory: what I'd pick to do next, and why (acts on nothing)",
+  handler: async (env) => {
+    if (!authorized(env)) return;
+    const adapter = currentAdapter();
+    const channelId = currentChannelId();
+    const ledger = require("./agency/ledger");
+    const deliberate = require("./agency/deliberate");
+    try { typing(); } catch (_) {}
+    let proposal;
+    try {
+      const result = await ledger.collect({ adapter: adapter && adapter.id, channelId });
+      proposal = await deliberate.deliberate(result, { now: result.generatedAt });
+      try { deliberate.record(proposal, { channel: adapter && adapter.id ? `${adapter.id}:${channelId}` : null }); } catch (_) {}
+    } catch (e) {
+      return send(`Couldn't deliberate: ${e.message}`);
+    }
+    send(deliberate.render(proposal));
+  },
+});
+
 register({
   name: "toolmode", description: "Tooling enforcement mode (strict = forced CLI, relaxed = scripting allowed)", args: "[strict|relaxed]", ownerOnly: true,
   handler: async (env, { tail }) => {

package/core/prompt-budget.js

@@ -0,0 +1,165 @@
+// Always-on prompt budget instrumentation (Track X0). One JSONL line per real
+// user turn plus a rolling summary, so we can baseline the fixed prompt floor
+// (soul + lessons + runtime state + slash-command list + tool headlines +
+// relationship/mandate) and watch it grow as new systems are bolted on. This
+// is read-only telemetry: it never changes what is sent to the model, it only
+// measures it. Mirrors the storage shape of core/recall/metrics.js.
+
+const fs = require("fs");
+const path = require("path");
+const CONFIG_DIR = require("../config-dir");
+
+const LOG_FILE = path.join(CONFIG_DIR, "prompt-budget.jsonl");
+const SUMMARY_FILE = path.join(CONFIG_DIR, "prompt-budget-summary.json");
+let VERSION = "";
+try { VERSION = require("../package.json").version || ""; } catch (e) {}
+
+const MAX_LOG_BYTES = 2 * 1024 * 1024; // truncate the jsonl past ~2MB so telemetry never eats disk
+
+function enabled() {
+  return String(process.env.PROMPT_BUDGET || "on").toLowerCase() !== "off";
+}
+
+// Local, network-free token estimate. Markdown/English averages ~4 chars per
+// token; this is deliberately an ESTIMATE — consistency across turns matters
+// more than matching a specific tokenizer, since X0 tracks growth over time.
+function estimateTokens(str) {
+  const chars = typeof str === "string" ? str.length : 0;
+  return Math.ceil(chars / 4);
+}
+
+function part(str) {
+  const chars = typeof str === "string" ? str.length : 0;
+  return { chars, tokens: estimateTokens(str) };
+}
+
+function addSize(a, b) {
+  return { chars: a.chars + b.chars, tokens: a.tokens + b.tokens };
+}
+
+// Which named prompt components form the fixed "always-on floor" vs the
+// variable, on-demand recall payload and the turn's own user input.
+const ALWAYS_ON_KEYS = [
+  "core",           // soul + persona + lessons + skill index + tool index + fixed boilerplate
+  "runtime",        // runtime state block
+  "speaker",        // speaker + team roster + slash-command list
+  "speakerPersona",
+  "provider",       // provider-native tools note
+  "voice",
+  "relationship",   // external-mode / mandate
+  "spacesMode",
+];
+const VARIABLE_KEYS = ["transcript", "recall"];
+
+// Break an assembled turn's named parts into sizes. `parts` keys mirror the
+// components of buildTurnPrompt(); any subset is tolerated.
+function measure(parts = {}) {
+  const components = {};
+  for (const [k, v] of Object.entries(parts)) components[k] = part(v);
+
+  let alwaysOn = { chars: 0, tokens: 0 };
+  for (const k of ALWAYS_ON_KEYS) if (components[k]) alwaysOn = addSize(alwaysOn, components[k]);
+
+  let variable = { chars: 0, tokens: 0 };
+  for (const k of VARIABLE_KEYS) if (components[k]) variable = addSize(variable, components[k]);
+
+  const recall = components.recall || { chars: 0, tokens: 0 };
+  const userPrompt = components.userPrompt || { chars: 0, tokens: 0 };
+  const total = addSize(addSize(alwaysOn, variable), userPrompt);
+
+  return { components, alwaysOn, recall, variable, userPrompt, total };
+}
+
+function readSummary() {
+  try { return JSON.parse(fs.readFileSync(SUMMARY_FILE, "utf8")) || {}; } catch (e) { return {}; }
+}
+function writeSummary(s) {
+  try { fs.writeFileSync(SUMMARY_FILE, JSON.stringify(s, null, 2)); } catch (e) {}
+}
+
+function bumpSummary(m, meta) {
+  const s = readSummary();
+  s.turns = (s.turns || 0) + 1;
+  s.alwaysOnTokensTotal = (s.alwaysOnTokensTotal || 0) + m.alwaysOn.tokens;
+  s.recallTokensTotal = (s.recallTokensTotal || 0) + m.recall.tokens;
+  s.totalTokensTotal = (s.totalTokensTotal || 0) + m.total.tokens;
+  s.alwaysOnTokensMax = Math.max(s.alwaysOnTokensMax || 0, m.alwaysOn.tokens);
+  s.componentTokensTotal = s.componentTokensTotal || {};
+  for (const [k, v] of Object.entries(m.components)) {
+    s.componentTokensTotal[k] = (s.componentTokensTotal[k] || 0) + v.tokens;
+  }
+  // Latest snapshot — the current per-component breakdown ("what is the floor
+  // right now"), distinct from the rolling averages above.
+  s.latest = {
+    ts: new Date().toISOString(),
+    v: VERSION,
+    provider: meta.provider || "",
+    alwaysOnTokens: m.alwaysOn.tokens,
+    recallTokens: m.recall.tokens,
+    totalTokens: m.total.tokens,
+    components: Object.fromEntries(Object.entries(m.components).map(([k, v]) => [k, v.tokens])),
+  };
+  s.updatedAt = new Date().toISOString();
+  writeSummary(s);
+}
+
+function appendLog(rec) {
+  try {
+    try {
+      const st = fs.statSync(LOG_FILE);
+      if (st.size > MAX_LOG_BYTES) fs.rmSync(LOG_FILE, { force: true });
+    } catch (e) {}
+    fs.appendFileSync(LOG_FILE, JSON.stringify(rec) + "\n");
+  } catch (e) {}
+}
+
+// Record one real turn's prompt budget. Best-effort; never throws.
+function record(measurement, meta = {}) {
+  if (!enabled()) return;
+  try {
+    const m = measurement && measurement.total ? measurement : null;
+    if (!m) return;
+    const rec = {
+      ts: new Date().toISOString(),
+      v: VERSION,
+      provider: meta.provider || "",
+      runId: meta.runId || null,
+      alwaysOnTokens: m.alwaysOn.tokens,
+      recallTokens: m.recall.tokens,
+      totalTokens: m.total.tokens,
+      components: Object.fromEntries(Object.entries(m.components).map(([k, v]) => [k, v.tokens])),
+    };
+    appendLog(rec);
+    bumpSummary(m, meta);
+  } catch (e) {}
+}
+
+// Human-readable rolling view (rendered by `open-claudia prompt-budget`).
+function summary() {
+  const s = readSummary();
+  const turns = s.turns || 0;
+  const avg = (total) => (turns ? Math.round((total || 0) / turns) : 0);
+  const componentAvg = {};
+  for (const [k, v] of Object.entries(s.componentTokensTotal || {})) componentAvg[k] = avg(v);
+  return {
+    turns,
+    avgAlwaysOnTokens: avg(s.alwaysOnTokensTotal),
+    maxAlwaysOnTokens: s.alwaysOnTokensMax || 0,
+    avgRecallTokens: avg(s.recallTokensTotal),
+    avgTotalTokens: avg(s.totalTokensTotal),
+    componentAvgTokens: componentAvg,
+    latest: s.latest || null,
+    updatedAt: s.updatedAt || "",
+  };
+}
+
+function _resetForTest() {
+  try { fs.rmSync(LOG_FILE, { force: true }); } catch (e) {}
+  try { fs.rmSync(SUMMARY_FILE, { force: true }); } catch (e) {}
+}
+
+module.exports = {
+  LOG_FILE, SUMMARY_FILE, VERSION, enabled,
+  ALWAYS_ON_KEYS, VARIABLE_KEYS,
+  estimateTokens, measure, record, summary, _resetForTest,
+};

package/core/runner.js

@@ -761,7 +761,7 @@ function createRunnerService(dependencies = {}) {
     let bundle;
     let invocation;
     try {
-      bundle = await promptBuilder(prompt, { runContext, provider });
+      bundle = await promptBuilder(prompt, { runContext, provider, recordBudget: !capture });
       invocation = invocationBuilder(provider, invocationContextForRun(runContext, bundle, provider));
       if (dependencies.decorateInvocation) {
         invocation = dependencies.decorateInvocation(invocation, runContext, bundle, provider);
@@ -1860,6 +1860,23 @@ async function handoffMemoryReview(result, runContext, store, state) {
   });
 }
 
+// Track C — owner-guardrail capture. After a foreground turn, a deterministic
+// detector spots durable-rule statements ("from now on / never / stop") in the
+// owner's message and captures them into lessons.md (or asks first). Owner-only
+// and best-effort: it never blocks or breaks a turn.
+async function considerGuardrail(result, runContext, store) {
+  try {
+    if (!result.ok || runContext.purpose !== "foreground") return;
+    const guardrail = require("./guardrail");
+    if (!guardrail.enabled()) return;
+    const relationship = require("./relationship");
+    const speaker = relationship.speakerFor(store?.adapter?.type, store?.channelId, store?.userId);
+    if (relationship.guardActive(speaker)) return; // external speakers never capture
+    const announce = (text, opts) => chatContext.run(store, () => send(text, opts));
+    await guardrail.consider({ text: runContext.userPrompt, speaker, announce });
+  } catch (e) { /* best-effort — a guardrail miss must never break a turn */ }
+}
+
 function deferredRunResult() {
   let resolve;
   let reject;
@@ -1920,6 +1937,7 @@ async function executeAdmittedRun(runContext, state, store, capture, ownsAdmissi
     try { service.turnObserver.onTurnSettled(!!result.ok); } catch (e) { /* best-effort */ }
   }
   if (!internalCapture) await handoffMemoryReview(result, runContext, store, state);
+  if (!internalCapture) await considerGuardrail(result, runContext, store);
   if (!internalCapture && state.settings?.backend === runContext.provider && state.settings.budget) {
     state.settings.budget = null;
     try { saveState({ strict: true }); }
@@ -1982,7 +2000,13 @@ function runAgent(prompt, cwd, replyToMsgId, opts = {}) {
     }
     const deferred = deferredRunResult();
     state.messageQueue.push({ runContext, store, deferred, queuedAt: Date.now() });
-    send(state.isCompacting ? "Compacting context, will pick this up next…" : "Queued.", { replyTo: replyToMsgId }).catch(() => {});
+    // Transient queue/compaction acks are a chat-UX affordance (Telegram/Kazee).
+    // On a Spaces task thread they'd post a throwaway "Queued." comment on the
+    // task — noise. Spaces stays quiet and just posts the real reply when its
+    // turn runs.
+    if (currentAdapter()?.type !== "spaces") {
+      send(state.isCompacting ? "Compacting context, will pick this up next…" : "Queued.", { replyTo: replyToMsgId }).catch(() => {});
+    }
     return deferred.promise;
   }
   return executeAdmittedRun(runContext, state, store, false, true);

package/core/state.js

@@ -652,6 +652,21 @@ function acquireRunLock(state = currentState()) {
   return true;
 }
 
+// True when ANY user has a turn running, admitted-and-preparing, compacting, or
+// waiting in its queue. Same busy predicate as acquireRunLock, but across every
+// user state rather than one — the Telegram poll-wedge backstop consults this
+// before a self-exit so a reboot never interrupts in-flight work. It fires on a
+// timer outside any channel context (no "current" user) and a reboot kills the
+// whole process, so it must scan all states, not just currentState().
+function anyTurnActive() {
+  for (const s of userStates.values()) {
+    if (!s) continue;
+    if (s.runningProcess || s.preparingRun || s.isCompacting) return true;
+    if (Array.isArray(s.messageQueue) && s.messageQueue.length) return true;
+  }
+  return false;
+}
+
 function migrationSources() {
   return defaultMigrationSources({
     configDir: CONFIG_DIR,
@@ -1363,6 +1378,7 @@ module.exports = {
   resetSessionUsage,
   resetSettings,
   acquireRunLock,
+  anyTurnActive,
   saveState,
   loadSessions,
   loadSessionsDocument,

package/core/system-prompt.js

@@ -15,6 +15,7 @@ const {
 const tasksStore = require("./tasks");
 const people = require("./people");
 const commandsRegistry = require("./commands");
+const promptBudget = require("./prompt-budget");
 
 function loadSoul() {
   const soul = fs.readFileSync(SOUL_FILE, "utf-8");
@@ -1068,12 +1069,40 @@ function createPromptBuilder(dependencies = {}) {
         spacesTaskMode,
       ].filter((part) => typeof part === "string" && part.trim()).join("\n\n");
 
+      // Track X0: measure the fixed always-on floor vs the variable recall
+      // payload for this turn. Pure measurement — attached to the bundle for
+      // any caller; only recorded to telemetry when the caller opts in
+      // (real user turns, never sub-agent/capture builds).
+      let budget = null;
+      try {
+        budget = promptBudget.measure({
+          core: coreInstructions,
+          transcript: transcriptContext,
+          runtime: runtimeContext,
+          speaker: speakerContext,
+          speakerPersona,
+          provider: providerContext,
+          recall: recallResult.dynamicContext,
+          voice: voiceContext,
+          relationship: relationshipContext,
+          spacesMode: spacesTaskMode,
+          userPrompt,
+        });
+        if (opts.recordBudget) {
+          promptBudget.record(budget, {
+            provider: opts.provider?.id,
+            runId: opts.runContext?.runId,
+          });
+        }
+      } catch (_) { budget = null; }
+
       return {
         coreInstructions,
         dynamicContext,
         userPrompt,
         transcriptPaths,
         recallMetadata: recallResult.metadata,
+        promptBudget: budget,
       };
     },
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inetafrica/open-claudia",
-  "version": "3.0.25",
+  "version": "3.0.27",
   "description": "An always-on, provider-agnostic coding-agent harness for Claude Code and OpenAI Codex via chat",
   "main": "bot.js",
   "bin": {
@@ -9,7 +9,7 @@
   "scripts": {
     "setup": "node setup.js",
     "start": "node bot.js",
-    "pretest": "node test-provider-fixture.js && node test-provider-core-prompt.js && node test-provider-prompt-parity.js && node test-provider-env-isolation.js && node test-provider-resume-parity.js && node test-provider-bootstrap.js && node test-provider-registry.js && node test-provider-stream-decoder.js && node test-provider-events.js && node test-provider-claude.js && node test-provider-codex.js && node test-provider-runner.js && node test-provider-run-lifecycle.js && node test-provider-gateway.js && node test-provider-side-chat.js && node test-single-runtime.js && node test-provider-migration-backup.js && node test-provider-state-migration.js && node test-provider-session-history.js && node test-provider-session-commands.js && node test-provider-compaction.js && node test-provider-scheduler.js && node test-cursor-removal.js && node test-utility-provider-policy.js && node test-provider-subagent.js && node test-provider-recall.js && node test-provider-pack-review.js && node test-memory-mutation-queue.js && node test-provider-dream.js && node test-provider-enforcer.js && node test-provider-tool-hooks.js && node test-provider-boot-matrix.js && node test-provider-capabilities.js && node test-provider-language.js && node test-provider-coupling-audit.js && node test-provider-parity-e2e.js && node test-kazee-channel-health.js",
+    "pretest": "node test-provider-fixture.js && node test-provider-core-prompt.js && node test-provider-prompt-parity.js && node test-provider-env-isolation.js && node test-provider-resume-parity.js && node test-provider-bootstrap.js && node test-provider-registry.js && node test-provider-stream-decoder.js && node test-provider-events.js && node test-provider-claude.js && node test-provider-codex.js && node test-provider-runner.js && node test-provider-run-lifecycle.js && node test-provider-gateway.js && node test-provider-side-chat.js && node test-single-runtime.js && node test-provider-migration-backup.js && node test-provider-state-migration.js && node test-provider-session-history.js && node test-provider-session-commands.js && node test-provider-compaction.js && node test-provider-scheduler.js && node test-cursor-removal.js && node test-utility-provider-policy.js && node test-provider-subagent.js && node test-provider-recall.js && node test-provider-pack-review.js && node test-memory-mutation-queue.js && node test-provider-dream.js && node test-provider-enforcer.js && node test-provider-tool-hooks.js && node test-provider-boot-matrix.js && node test-provider-capabilities.js && node test-provider-language.js && node test-provider-coupling-audit.js && node test-provider-parity-e2e.js && node test-kazee-channel-health.js && node test-prompt-budget.js && node test-agency-ledger.js && node test-agency-deliberate.js && node test-guardrail.js",
     "test": "OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node -e \"require('./vault'); console.log('OK')\" && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-runner-watchdog-static.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-usage-accounting.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-recall-engine.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-recall-graph.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-recall-discoverer.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-project-transcripts-smoke.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-abilities.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-ability-extraction.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-ability-couse.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-ability-transfer.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-ability-tiers.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-ability-merge-guard.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-learning-e2e.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-pack-nesting.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-journal-dedupe.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-read-signal.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-tools.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-tool-graph.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-tool-guard.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-tooling-mode.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-tool-manifest.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-recall-evolution.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-approval-async.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-unified-identity.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-queue-routing.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-persona-packs.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-speaker-persona.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-persona-pipeline.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-recall-relationship-gate.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-relationship.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-enforcer.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-identity-prune.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-kazee-message-id.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-delivery-contract.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-run-lock.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-web-sessions.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-telegram-poll-recovery.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-telegram-409-grace.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-telegram-conflict-heal-guard.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-single-instance.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-streaming-split.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=./test-fixtures/fake-agent-cli.js FAKE_AGENT_KIND=claude AGENT_ENV_PASSTHROUGH=FAKE_AGENT_KIND node test-spaces-autoenable.js"
   },
   "files": [
@@ -66,6 +66,10 @@
     "test-identity-prune.js",
     "test-kazee-message-id.js",
     "test-kazee-channel-health.js",
+    "test-prompt-budget.js",
+    "test-agency-ledger.js",
+    "test-agency-deliberate.js",
+    "test-guardrail.js",
     "test-delivery-contract.js",
     "test-run-lock.js",
     "test-web-sessions.js",