u-foo 1.9.7 → 2.1.0

package/src/providerapi/shadowDiff.js

@@ -0,0 +1,174 @@
+"use strict";
+
+// §11.6 Phase 1 shadow diff metrics: model text BLEU ≥ 0.85 and
+// tool-call sequence consistency ≥ 95%. This module provides the deterministic
+// helpers the shadow harness feeds paired (legacy, api-backed) samples into.
+
+const PHASE1_DEFAULT_BLEU_THRESHOLD = 0.85;
+const PHASE1_DEFAULT_TOOLCALL_THRESHOLD = 0.95;
+
+function tokenize(text) {
+  return String(text || "")
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s]/gu, " ")
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+function ngrams(tokens, n) {
+  if (!Array.isArray(tokens) || tokens.length < n) return [];
+  const out = [];
+  for (let i = 0; i <= tokens.length - n; i += 1) {
+    out.push(tokens.slice(i, i + n).join("\u0001"));
+  }
+  return out;
+}
+
+function countMap(list) {
+  const map = new Map();
+  for (const item of list) {
+    map.set(item, (map.get(item) || 0) + 1);
+  }
+  return map;
+}
+
+function clippedPrecision(candidateNgrams, referenceNgrams) {
+  if (candidateNgrams.length === 0) return 0;
+  const candidateCounts = countMap(candidateNgrams);
+  const referenceCounts = countMap(referenceNgrams);
+  let clipped = 0;
+  for (const [gram, count] of candidateCounts.entries()) {
+    const refCount = referenceCounts.get(gram) || 0;
+    clipped += Math.min(count, refCount);
+  }
+  return clipped / candidateNgrams.length;
+}
+
+function brevityPenalty(candidateLen, referenceLen) {
+  if (candidateLen === 0) return 0;
+  if (candidateLen >= referenceLen) return 1;
+  return Math.exp(1 - referenceLen / candidateLen);
+}
+
+function computeBleu(referenceText, candidateText, options = {}) {
+  const maxN = Number.isFinite(options.maxN) ? Math.max(1, Math.min(4, options.maxN)) : 4;
+  const weight = 1 / maxN;
+  const ref = tokenize(referenceText);
+  const cand = tokenize(candidateText);
+  if (cand.length === 0) return 0;
+  if (ref.length === 0) return 0;
+
+  let logSum = 0;
+  for (let n = 1; n <= maxN; n += 1) {
+    const precision = clippedPrecision(ngrams(cand, n), ngrams(ref, n));
+    if (precision <= 0) return 0;
+    logSum += weight * Math.log(precision);
+  }
+  const bp = brevityPenalty(cand.length, ref.length);
+  return bp * Math.exp(logSum);
+}
+
+function extractToolCallNames(events = []) {
+  return (Array.isArray(events) ? events : [])
+    .filter((event) => event && event.type === "tool_call" && event.name)
+    .map((event) => String(event.name).trim())
+    .filter(Boolean);
+}
+
+function computeToolCallSequenceConsistency(referenceSeq = [], candidateSeq = []) {
+  const ref = Array.isArray(referenceSeq) ? referenceSeq : [];
+  const cand = Array.isArray(candidateSeq) ? candidateSeq : [];
+  if (ref.length === 0 && cand.length === 0) return 1;
+
+  const m = ref.length;
+  const n = cand.length;
+  const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+  for (let i = 1; i <= m; i += 1) {
+    for (let j = 1; j <= n; j += 1) {
+      if (ref[i - 1] === cand[j - 1]) {
+        dp[i][j] = dp[i - 1][j - 1] + 1;
+      } else {
+        dp[i][j] = Math.max(dp[i - 1][j], dp[i][j - 1]);
+      }
+    }
+  }
+  const lcs = dp[m][n];
+  const denom = Math.max(m, n);
+  if (denom === 0) return 1;
+  return lcs / denom;
+}
+
+function buildPhase1ShadowDiffSample({ legacy = {}, api = {} } = {}) {
+  const bleu = computeBleu(legacy.text || "", api.text || "");
+  const toolSeqConsistency = computeToolCallSequenceConsistency(
+    extractToolCallNames(legacy.events || legacy.toolCalls || []),
+    extractToolCallNames(api.events || api.toolCalls || [])
+  );
+  return {
+    bleu,
+    toolSeqConsistency,
+  };
+}
+
+function summarizePhase1ShadowDiff(samples = [], options = {}) {
+  const bleuThreshold = Number.isFinite(options.bleuThreshold)
+    ? options.bleuThreshold
+    : PHASE1_DEFAULT_BLEU_THRESHOLD;
+  const toolCallThreshold = Number.isFinite(options.toolCallThreshold)
+    ? options.toolCallThreshold
+    : PHASE1_DEFAULT_TOOLCALL_THRESHOLD;
+
+  const list = Array.isArray(samples) ? samples : [];
+  if (list.length === 0) {
+    return {
+      sampleCount: 0,
+      meanBleu: 0,
+      meanToolSeqConsistency: 0,
+      bleuPass: false,
+      toolCallPass: false,
+      overallPass: false,
+      bleuThreshold,
+      toolCallThreshold,
+    };
+  }
+
+  let totalBleu = 0;
+  let totalTool = 0;
+  let toolCallPassCount = 0;
+  for (const sample of list) {
+    totalBleu += Number(sample.bleu || 0);
+    const consistency = Number(sample.toolSeqConsistency || 0);
+    totalTool += consistency;
+    if (consistency >= toolCallThreshold) toolCallPassCount += 1;
+  }
+
+  const meanBleu = totalBleu / list.length;
+  const meanToolSeqConsistency = totalTool / list.length;
+  const bleuPass = meanBleu >= bleuThreshold;
+  const toolCallPassRate = toolCallPassCount / list.length;
+  const toolCallPass = toolCallPassRate >= toolCallThreshold;
+
+  return {
+    sampleCount: list.length,
+    meanBleu,
+    meanToolSeqConsistency,
+    toolCallPassRate,
+    bleuPass,
+    toolCallPass,
+    overallPass: bleuPass && toolCallPass,
+    bleuThreshold,
+    toolCallThreshold,
+  };
+}
+
+module.exports = {
+  PHASE1_DEFAULT_BLEU_THRESHOLD,
+  PHASE1_DEFAULT_TOOLCALL_THRESHOLD,
+  tokenize,
+  ngrams,
+  computeBleu,
+  extractToolCallNames,
+  computeToolCallSequenceConsistency,
+  buildPhase1ShadowDiffSample,
+  summarizePhase1ShadowDiff,
+};

package/src/report/store.js

@@ -1,6 +1,7 @@
 const fs = require("fs");
 const path = require("path");
 const { getUfooPaths } = require("../ufoo/paths");
+const { redactSecrets } = require("../providerapi/redactor");
 
 const REPORT_PHASES = {
   START: "start",
@@ -100,7 +101,7 @@ function normalizeReportInput(input = {}, options = {}) {
 function appendReport(projectRoot, entry) {
   ensureReportDir(projectRoot);
   const { reportsFile } = getReportPaths(projectRoot);
-  fs.appendFileSync(reportsFile, `${JSON.stringify(entry)}\n`, "utf8");
+  fs.appendFileSync(reportsFile, `${JSON.stringify(redactSecrets(entry))}\n`, "utf8");
 }
 
 function parseJsonLines(file) {
@@ -151,7 +152,7 @@ function loadReportState(projectRoot) {
 function saveReportState(projectRoot, state) {
   ensureReportDir(projectRoot);
   const { stateFile } = getReportPaths(projectRoot);
-  fs.writeFileSync(stateFile, JSON.stringify(state, null, 2));
+  fs.writeFileSync(stateFile, JSON.stringify(redactSecrets(state), null, 2));
 }
 
 function updateReportState(projectRoot, entry) {
@@ -205,7 +206,7 @@ function getControllerInboxFile(projectRoot, controllerId = "ufoo-agent") {
 function appendControllerInboxEntry(projectRoot, controllerId, entry) {
   const file = getControllerInboxFile(projectRoot, controllerId);
   fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.appendFileSync(file, `${JSON.stringify(entry)}\n`, "utf8");
+  fs.appendFileSync(file, `${JSON.stringify(redactSecrets(entry))}\n`, "utf8");
 }
 
 function listControllerInboxEntries(projectRoot, controllerId = "ufoo-agent", options = {}) {

package/src/tools/handlers/ackBus.js

@@ -0,0 +1,26 @@
+const { buildToolError, requireSubscriber, getEventBus } = require("./common");
+
+async function ackBusHandler(ctx = {}, args = {}) {
+  const subscriber = requireSubscriber(ctx);
+  const requestedSubscriber = String(args.subscriber || subscriber).trim();
+
+  if (requestedSubscriber !== subscriber) {
+    throw buildToolError(
+      "forbidden_ack",
+      "ack_bus can only acknowledge the caller subscriber queue"
+    );
+  }
+
+  const eventBus = getEventBus(ctx);
+  const count = await eventBus.ack(subscriber);
+
+  return {
+    ok: true,
+    subscriber,
+    acknowledged: count,
+  };
+}
+
+module.exports = {
+  ackBusHandler,
+};

package/src/tools/handlers/common.js

@@ -0,0 +1,64 @@
+const EventBus = require("../../bus");
+const { CALLER_TIERS, normalizeCallerTier } = require("../types");
+
+function extractAuditFields(ctx = {}) {
+  const audit = {};
+  const turnId = ctx.turn_id || ctx.turnId;
+  const toolCallId = ctx.tool_call_id || ctx.toolCallId;
+  if (turnId) audit.turn_id = String(turnId);
+  if (toolCallId) audit.tool_call_id = String(toolCallId);
+  const callerTier = normalizeCallerTier(ctx.caller_tier || ctx.callerTier);
+  if (callerTier) audit.caller_tier = callerTier;
+  return audit;
+}
+
+function buildToolError(code, message, extra = {}) {
+  const err = new Error(String(message || "tool execution failed"));
+  err.code = String(code || "tool_error");
+  Object.assign(err, extra);
+  return err;
+}
+
+function requireSubscriber(ctx = {}) {
+  const subscriber = String(ctx.subscriber || "").trim();
+  if (!subscriber) {
+    throw buildToolError("invalid_context", "tool requires subscriber context", extractAuditFields(ctx));
+  }
+  return subscriber;
+}
+
+function getEventBus(ctx = {}) {
+  if (ctx.eventBus) return ctx.eventBus;
+  return new EventBus(ctx.projectRoot);
+}
+
+function resolveCallerTier(ctx = {}) {
+  const raw = normalizeCallerTier(ctx.caller_tier || ctx.callerTier);
+  return raw || CALLER_TIERS.CONTROLLER;
+}
+
+function assertControllerTier(ctx = {}, toolName = "") {
+  const tier = resolveCallerTier(ctx);
+  if (tier !== CALLER_TIERS.CONTROLLER) {
+    const audit = extractAuditFields(ctx);
+    audit.caller_tier = tier;
+    throw buildToolError(
+      "forbidden_caller_tier",
+      `caller_tier "${tier}" is not allowed to invoke tool "${toolName}"`,
+      {
+        tool_name: toolName,
+        allowed_tiers: [CALLER_TIERS.CONTROLLER],
+        ...audit,
+      }
+    );
+  }
+}
+
+module.exports = {
+  buildToolError,
+  requireSubscriber,
+  getEventBus,
+  resolveCallerTier,
+  assertControllerTier,
+  extractAuditFields,
+};

package/src/tools/handlers/dispatchMessage.js

@@ -0,0 +1,81 @@
+const { buildToolError, requireSubscriber, getEventBus } = require("./common");
+
+function normalizeDispatchTarget(rawTarget = "") {
+  const target = String(rawTarget || "").trim();
+  if (!target) {
+    throw buildToolError("invalid_arguments", "dispatch_message requires target");
+  }
+  if (target === "*") return "broadcast";
+  return target;
+}
+
+function normalizeDispatchMode(args = {}) {
+  const raw = String(
+    args.mode || args.injection_mode || args.injectionMode || "immediate"
+  )
+    .trim()
+    .toLowerCase();
+  if (raw === "queued") return "queued";
+  if (raw === "immediate") return "immediate";
+  throw buildToolError(
+    "invalid_arguments",
+    "dispatch_message mode must be immediate or queued"
+  );
+}
+
+async function dispatchMessageHandler(ctx = {}, args = {}) {
+  const subscriber = requireSubscriber(ctx);
+  const target = normalizeDispatchTarget(args.target);
+  const message = String(args.message || "").trim();
+  const source = String(args.source || subscriber).trim();
+  const mode = normalizeDispatchMode(args);
+
+  if (!message) {
+    throw buildToolError("invalid_arguments", "dispatch_message requires message");
+  }
+  if (source !== subscriber) {
+    throw buildToolError(
+      "forbidden_source",
+      "dispatch_message source must match caller subscriber"
+    );
+  }
+
+  const eventBus = getEventBus(ctx);
+  let result;
+  try {
+    result = target === "broadcast"
+      ? await eventBus.broadcast(message, subscriber, {
+        injectionMode: mode,
+        source: subscriber,
+        silent: true,
+      })
+      : await eventBus.send(target, message, subscriber, {
+        injectionMode: mode,
+        source: subscriber,
+        silent: true,
+      });
+  } catch (err) {
+    if (err && /not found/i.test(String(err.message || ""))) {
+      throw buildToolError(
+        "invalid_target",
+        `dispatch_message target not found: ${target}`
+      );
+    }
+    throw err;
+  }
+
+  return {
+    ok: true,
+    target,
+    source: subscriber,
+    mode,
+    delivered: mode === "immediate" ? result.targets.length : 0,
+    queued: mode === "queued" ? result.targets.length : 0,
+    targets: result.targets,
+    seq: result.seq,
+  };
+}
+
+module.exports = {
+  dispatchMessageHandler,
+};

package/src/tools/handlers/listAgents.js

@@ -0,0 +1,14 @@
+const { buildStatus } = require("../../daemon/status");
+
+function listAgentsHandler(ctx = {}) {
+  const status = buildStatus(ctx.projectRoot);
+  const agents = Array.isArray(status.active_meta) ? status.active_meta : [];
+  return {
+    count: agents.length,
+    agents,
+  };
+}
+
+module.exports = {
+  listAgentsHandler,
+};

package/src/tools/handlers/readBusSummary.js

@@ -0,0 +1,34 @@
+const { buildStatus } = require("../../daemon/status");
+
+function readBusSummaryHandler(ctx = {}) {
+  const status = buildStatus(ctx.projectRoot);
+  const activeAgents = Array.isArray(status.active_meta) ? status.active_meta : [];
+  const busyCount = activeAgents.filter((item) => {
+    const state = String((item && item.activity_state) || "").trim().toLowerCase();
+    return state === "working"
+      || state === "starting"
+      || state === "running"
+      || state === "waiting_input"
+      || state === "blocked";
+  }).length;
+
+  return {
+    project_root: ctx.projectRoot,
+    summary: {
+      active_count: activeAgents.length,
+      busy_count: busyCount,
+      ready_count: Math.max(activeAgents.length - busyCount, 0),
+      unread_total: Number(status.unread && status.unread.total ? status.unread.total : 0) || 0,
+      decisions_open: Number(status.decisions && status.decisions.open ? status.decisions.open : 0) || 0,
+      reports_pending_total: Number(status.reports && status.reports.pending_total ? status.reports.pending_total : 0) || 0,
+      controller_pending_total: Number(status.controller && status.controller.pending_total ? status.controller.pending_total : 0) || 0,
+      cron_count: Number(status.cron && status.cron.count ? status.cron.count : 0) || 0,
+      groups_active: Number(status.groups && status.groups.active ? status.groups.active : 0) || 0,
+    },
+    active_agents: activeAgents,
+  };
+}
+
+module.exports = {
+  readBusSummaryHandler,
+};

package/src/tools/handlers/readOpenDecisions.js

@@ -0,0 +1,26 @@
+const DecisionsManager = require("../../context/decisions");
+
+function readOpenDecisionsHandler(ctx = {}, args = {}) {
+  const limit = Number.isFinite(Number(args.limit)) && Number(args.limit) > 0
+    ? Math.floor(Number(args.limit))
+    : 20;
+  const manager = new DecisionsManager(ctx.projectRoot);
+  const decisions = manager.readDecisions()
+    .filter((item) => String(item.status || "open").trim().toLowerCase() === "open")
+    .slice(0, limit)
+    .map((item) => ({
+      file: item.file,
+      title: item.title,
+      status: item.status,
+      file_path: item.filePath,
+    }));
+
+  return {
+    count: decisions.length,
+    decisions,
+  };
+}
+
+module.exports = {
+  readOpenDecisionsHandler,
+};

package/src/tools/handlers/readProjectRegistry.js

@@ -0,0 +1,20 @@
+const { listProjectRuntimes } = require("../../projects/registry");
+
+function readProjectRegistryHandler(_ctx = {}, args = {}) {
+  const validate = args.validate !== false;
+  const cleanupTmp = args.cleanup_tmp !== false;
+  const projects = listProjectRuntimes({
+    validate,
+    cleanupTmp,
+    runtimeDir: args.runtimeDir,
+  });
+
+  return {
+    count: projects.length,
+    projects,
+  };
+}
+
+module.exports = {
+  readProjectRegistryHandler,
+};

package/src/tools/handlers/readPromptHistory.js

@@ -0,0 +1,123 @@
+const fs = require("fs");
+const path = require("path");
+
+const { buildStatus } = require("../../daemon/status");
+const { getUfooPaths } = require("../../ufoo/paths");
+
+function clipPromptText(value = "", maxChars = 240) {
+  const text = String(value || "").replace(/\s+/g, " ").trim();
+  if (!text) return "";
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, maxChars)}...[truncated]`;
+}
+
+function buildPromptHistory(projectRoot, activeAgents = [], args = {}) {
+  const perAgentLimit = Number.isFinite(Number(args.per_agent_limit)) && Number(args.per_agent_limit) > 0
+    ? Math.floor(Number(args.per_agent_limit))
+    : 6;
+  const maxFiles = Number.isFinite(Number(args.max_files)) && Number(args.max_files) > 0
+    ? Math.floor(Number(args.max_files))
+    : 3;
+  const target = String(args.target || "").trim();
+  const eventsDir = getUfooPaths(projectRoot).busEventsDir;
+  const activeIds = new Set(activeAgents.map((item) => String(item.id || "")).filter(Boolean));
+  const nicknames = {};
+  const rows = new Map();
+
+  for (const item of activeAgents) {
+    if (!item || !item.id) continue;
+    const id = String(item.id);
+    const nickname = String(item.nickname || "");
+    if (nickname) nicknames[nickname] = id;
+    rows.set(id, {
+      agent_id: id,
+      nickname,
+      samples: [],
+      sample_count: 0,
+      total_count: 0,
+      last_ts: "",
+    });
+  }
+
+  if (target) {
+    const resolved = activeIds.has(target) ? target : nicknames[target];
+    if (resolved) {
+      for (const id of Array.from(rows.keys())) {
+        if (id !== resolved) rows.delete(id);
+      }
+    }
+  }
+
+  let files = [];
+  try {
+    files = fs.readdirSync(eventsDir)
+      .filter((name) => name.endsWith(".jsonl"))
+      .sort()
+      .slice(-maxFiles)
+      .reverse();
+  } catch {
+    return { scanned_files: 0, matched_events: 0, per_agent: [] };
+  }
+
+  let matchedEvents = 0;
+  for (const file of files) {
+    let lines = [];
+    try {
+      lines = fs.readFileSync(path.join(eventsDir, file), "utf8")
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .reverse();
+    } catch {
+      continue;
+    }
+
+    for (const line of lines) {
+      let event = null;
+      try {
+        event = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (!event || event.event !== "message") continue;
+      const message = clipPromptText(event.data && event.data.message);
+      if (!message) continue;
+      const rawTarget = String(event.target || "").trim();
+      const agentId = rows.has(rawTarget) ? rawTarget : nicknames[rawTarget];
+      if (!agentId || !rows.has(agentId)) continue;
+
+      const row = rows.get(agentId);
+      matchedEvents += 1;
+      row.total_count += 1;
+      if (!row.last_ts) row.last_ts = String(event.timestamp || "");
+      if (row.samples.length < perAgentLimit) {
+        row.samples.push({
+          ts: String(event.timestamp || ""),
+          publisher: String(event.publisher || ""),
+          prompt: message,
+        });
+        row.sample_count = row.samples.length;
+      }
+    }
+  }
+
+  const perAgent = Array.from(rows.values())
+    .filter((row) => row.total_count > 0)
+    .sort((a, b) => String(b.last_ts || "").localeCompare(String(a.last_ts || "")));
+
+  return {
+    scanned_files: files.length,
+    matched_events: matchedEvents,
+    per_agent: perAgent,
+  };
+}
+
+function readPromptHistoryHandler(ctx = {}, args = {}) {
+  const status = buildStatus(ctx.projectRoot);
+  const activeAgents = Array.isArray(status.active_meta) ? status.active_meta : [];
+  return buildPromptHistory(ctx.projectRoot, activeAgents, args);
+}
+
+module.exports = {
+  buildPromptHistory,
+  readPromptHistoryHandler,
+};