@the-open-engine/zeroshot 5.4.0

package/src/agent/agent-trigger-evaluator.js

@@ -0,0 +1,67 @@
+/**
+ * AgentTriggerEvaluator - Trigger matching and logic evaluation
+ *
+ * Provides:
+ * - Trigger matching based on message topics
+ * - Logic evaluation via LogicEngine
+ * - Trigger action determination
+ */
+
+/**
+ * Find trigger matching the message topic
+ * @param {Object} params - Evaluation parameters
+ * @param {Array} params.triggers - Agent triggers configuration
+ * @param {Object} params.message - Message to match against
+ * @returns {Object|null} Matching trigger or null
+ */
+function findMatchingTrigger({ triggers, message }) {
+  if (!triggers) {
+    return null;
+  }
+
+  return triggers.find((trigger) => {
+    // Match exact topic or wildcard
+    if (trigger.topic === '*' || trigger.topic === message.topic) {
+      return true;
+    }
+    // Match topic prefix (e.g., "VALIDATION_*")
+    if (trigger.topic.endsWith('*')) {
+      const prefix = trigger.topic.slice(0, -1);
+      return message.topic.startsWith(prefix);
+    }
+    return false;
+  });
+}
+
+/**
+ * Evaluate trigger logic
+ * @param {Object} params - Evaluation parameters
+ * @param {Object} params.trigger - Trigger to evaluate
+ * @param {Object} params.message - Triggering message
+ * @param {Object} params.agent - Agent context (id, role, iteration, cluster_id)
+ * @param {Object} params.logicEngine - LogicEngine instance
+ * @returns {boolean} Whether trigger logic passed
+ */
+function evaluateTrigger({ trigger, message, agent, logicEngine }) {
+  if (!trigger.logic || !trigger.logic.script) {
+    return true; // No logic = always true
+  }
+
+  // NO TRY/CATCH - let errors propagate and crash
+  return logicEngine.evaluate(trigger.logic.script, agent, message);
+}
+
+/**
+ * Get trigger action type
+ * @param {Object} trigger - Trigger object
+ * @returns {string} Action type ('execute_task' or 'stop_cluster')
+ */
+function getTriggerAction(trigger) {
+  return trigger.action || 'execute_task';
+}
+
+module.exports = {
+  findMatchingTrigger,
+  evaluateTrigger,
+  getTriggerAction,
+};

package/src/agent/context-metrics.js

@@ -0,0 +1,160 @@
+const TOKENS_PER_CHAR_ESTIMATE = 4;
+
+function estimateTokensFromChars(chars) {
+  if (!Number.isFinite(chars) || chars <= 0) {
+    return 0;
+  }
+
+  return Math.ceil(chars / TOKENS_PER_CHAR_ESTIMATE);
+}
+
+function buildSectionMetrics(sections) {
+  const sectionMetrics = {};
+  let totalChars = 0;
+
+  for (const [sectionName, text] of Object.entries(sections)) {
+    const safeText = typeof text === 'string' ? text : '';
+    const chars = safeText.length;
+    const estimatedTokens = estimateTokensFromChars(chars);
+    sectionMetrics[sectionName] = { chars, estimatedTokens };
+    totalChars += chars;
+  }
+
+  return { sectionMetrics, totalChars };
+}
+
+function buildSectionMetricsFromPacks(packs) {
+  const sectionMetrics = {};
+  let totalChars = 0;
+
+  for (const pack of packs) {
+    if (pack.status !== 'included') continue;
+    const sectionName = pack.section || pack.id || 'unknown';
+    const chars = Number.isFinite(pack.chars) ? pack.chars : 0;
+    if (!sectionMetrics[sectionName]) {
+      sectionMetrics[sectionName] = { chars: 0, estimatedTokens: 0 };
+    }
+    sectionMetrics[sectionName].chars += chars;
+    totalChars += chars;
+  }
+
+  for (const section of Object.values(sectionMetrics)) {
+    section.estimatedTokens = estimateTokensFromChars(section.chars);
+  }
+
+  return { sectionMetrics, totalChars };
+}
+
+function resolveLegacyMaxTokens(strategy) {
+  if (!strategy) {
+    return 100000;
+  }
+
+  return strategy.maxTokens || 100000;
+}
+
+function buildContextMetrics({
+  clusterId,
+  agentId,
+  role,
+  iteration,
+  triggeringMessage,
+  strategy,
+  sections,
+  packs,
+  budget,
+  truncation,
+}) {
+  const maxTokens = resolveLegacyMaxTokens(strategy);
+  const sourcesCount = Array.isArray(strategy?.sources) ? strategy.sources.length : 0;
+  const packMetrics = Array.isArray(packs) ? packs : [];
+
+  let sectionMetrics = {};
+  let totalChars = 0;
+  if (packMetrics.length > 0) {
+    const packTotals = buildSectionMetricsFromPacks(packMetrics);
+    sectionMetrics = packTotals.sectionMetrics;
+    totalChars = packTotals.totalChars;
+  } else if (sections) {
+    const sectionTotals = buildSectionMetrics(sections);
+    sectionMetrics = sectionTotals.sectionMetrics;
+    totalChars = sectionTotals.totalChars;
+  }
+
+  return {
+    clusterId,
+    agentId,
+    role,
+    iteration,
+    triggeredBy: triggeringMessage?.topic || null,
+    triggerFrom: triggeringMessage?.sender || null,
+    strategy: {
+      maxTokens,
+      sourcesCount,
+    },
+    budget: {
+      maxTokens: budget?.maxTokens ?? maxTokens,
+      remainingTokens: budget?.remainingTokens === undefined ? null : budget?.remainingTokens,
+      overBudgetTokens: budget?.overBudgetTokens ?? 0,
+      finalTokens: budget?.finalTokens ?? estimateTokensFromChars(totalChars),
+    },
+    packs: packMetrics,
+    sections: sectionMetrics,
+    total: {
+      chars: totalChars,
+      estimatedTokens: estimateTokensFromChars(totalChars),
+    },
+    truncation: {
+      maxContextChars: truncation?.maxContextChars || {
+        applied: false,
+        beforeChars: totalChars,
+        afterChars: totalChars,
+      },
+    },
+  };
+}
+
+function updateTotalMetrics(metrics, chars) {
+  if (!metrics || !Number.isFinite(chars)) {
+    return;
+  }
+
+  metrics.total = {
+    chars,
+    estimatedTokens: estimateTokensFromChars(chars),
+  };
+
+  if (metrics.budget) {
+    metrics.budget.finalTokens = estimateTokensFromChars(chars);
+  }
+
+  if (metrics.truncation?.maxContextChars) {
+    metrics.truncation.maxContextChars.afterChars = chars;
+  }
+}
+
+function emitContextMetrics(metrics, { messageBus, clusterId, agentId }) {
+  if (process.env.ZEROSHOT_CONTEXT_METRICS === '1') {
+    console.log('[ContextMetrics]', JSON.stringify(metrics));
+  }
+
+  if (process.env.ZEROSHOT_CONTEXT_METRICS_LEDGER === '1' && messageBus?.publish) {
+    messageBus.publish({
+      cluster_id: clusterId,
+      topic: 'CONTEXT_METRICS',
+      sender: agentId,
+      receiver: 'system',
+      content: {
+        data: metrics,
+      },
+    });
+  }
+}
+
+module.exports = {
+  estimateTokensFromChars,
+  resolveLegacyMaxTokens,
+  buildContextMetrics,
+  updateTotalMetrics,
+  emitContextMetrics,
+};

package/src/agent/context-pack-builder.js

@@ -0,0 +1,367 @@
+const { estimateTokensFromChars } = require('./context-metrics');
+
+const PRIORITY_RANK = {
+  required: 0,
+  high: 1,
+  medium: 2,
+  low: 3,
+};
+
+const DEFAULT_PRIORITY = 'medium';
+const TRUNCATION_SUFFIX = '\n\n[Context truncated to fit limit]\n';
+
+function normalizePriority(priority, required) {
+  if (required) return 'required';
+  if (priority && PRIORITY_RANK[priority] !== undefined) return priority;
+  return DEFAULT_PRIORITY;
+}
+
+function normalizePack(pack, index) {
+  const priority = normalizePriority(pack.priority, pack.required);
+  return {
+    ...pack,
+    priority,
+    required: pack.required || priority === 'required',
+    order: pack.order ?? index,
+  };
+}
+
+function renderVariant(pack, variant, cache) {
+  const cacheKey = `${pack.id}:${variant}`;
+  if (cache.has(cacheKey)) return cache.get(cacheKey);
+
+  let text = '';
+  if (variant === 'full') {
+    text = typeof pack.render === 'function' ? pack.render() : '';
+  } else if (variant === 'compact') {
+    text = typeof pack.compact === 'function' ? pack.compact() : '';
+  }
+
+  if (typeof text !== 'string') {
+    text = '';
+  }
+
+  const chars = text.length;
+  const estimatedTokens = estimateTokensFromChars(chars);
+  const rendered = { text, chars, estimatedTokens };
+  cache.set(cacheKey, rendered);
+  return rendered;
+}
+
+function sortByPriorityThenOrder(a, b) {
+  const priorityDelta = PRIORITY_RANK[a.priority] - PRIORITY_RANK[b.priority];
+  if (priorityDelta !== 0) return priorityDelta;
+  return a.order - b.order;
+}
+
+function sortByOrder(a, b) {
+  return a.order - b.order;
+}
+
+function sortByPriorityDescThenOrderDesc(a, b) {
+  const priorityDelta = PRIORITY_RANK[b.priority] - PRIORITY_RANK[a.priority];
+  if (priorityDelta !== 0) return priorityDelta;
+  return b.order - a.order;
+}
+
+function selectVariant(pack, remainingTokens, cache) {
+  const full = renderVariant(pack, 'full', cache);
+  const compact = pack.compact ? renderVariant(pack, 'compact', cache) : null;
+
+  const hasFull = full.chars > 0;
+  const hasCompact = compact && compact.chars > 0;
+
+  if (!hasFull && !hasCompact) {
+    return {
+      status: 'skipped',
+      variant: null,
+      reason: 'empty',
+      chars: 0,
+      estimatedTokens: 0,
+    };
+  }
+
+  if (pack.required) {
+    let chosen = full;
+    let variant = 'full';
+
+    if (!hasFull && hasCompact) {
+      chosen = compact;
+      variant = 'compact';
+    } else if (
+      Number.isFinite(remainingTokens) &&
+      hasCompact &&
+      full.estimatedTokens > remainingTokens
+    ) {
+      if (
+        compact.estimatedTokens <= remainingTokens ||
+        compact.estimatedTokens < full.estimatedTokens
+      ) {
+        chosen = compact;
+        variant = 'compact';
+      }
+    }
+
+    return {
+      status: 'included',
+      variant,
+      chars: chosen.chars,
+      estimatedTokens: chosen.estimatedTokens,
+      text: chosen.text,
+    };
+  }
+
+  if (!Number.isFinite(remainingTokens) || full.estimatedTokens <= remainingTokens) {
+    return {
+      status: 'included',
+      variant: 'full',
+      chars: full.chars,
+      estimatedTokens: full.estimatedTokens,
+      text: full.text,
+    };
+  }
+
+  if (hasCompact && compact.estimatedTokens <= remainingTokens) {
+    return {
+      status: 'included',
+      variant: 'compact',
+      chars: compact.chars,
+      estimatedTokens: compact.estimatedTokens,
+      text: compact.text,
+    };
+  }
+
+  return {
+    status: 'skipped',
+    variant: null,
+    reason: 'budget',
+    chars: 0,
+    estimatedTokens: 0,
+  };
+}
+
+function truncateText(text, targetChars) {
+  if (text.length <= targetChars) {
+    return { text, truncated: false };
+  }
+
+  if (targetChars <= 0) {
+    return { text: '', truncated: true };
+  }
+
+  if (targetChars <= TRUNCATION_SUFFIX.length) {
+    return { text: text.slice(0, targetChars), truncated: true };
+  }
+
+  const sliceLength = targetChars - TRUNCATION_SUFFIX.length;
+  return { text: text.slice(0, sliceLength) + TRUNCATION_SUFFIX, truncated: true };
+}
+
+function applyMaxCharsGuard({ packs, selected, decisions, cache, maxChars, totalChars }) {
+  let currentChars = totalChars;
+  if (!Number.isFinite(maxChars) || currentChars <= maxChars) {
+    return { applied: false, beforeChars: totalChars, afterChars: totalChars };
+  }
+
+  const includedOptional = packs
+    .filter((pack) => selected.has(pack.id) && !pack.required)
+    .sort(sortByPriorityDescThenOrderDesc);
+
+  for (const pack of includedOptional) {
+    if (currentChars <= maxChars) break;
+    const decision = decisions.get(pack.id);
+    if (!decision || decision.variant === 'compact' || !pack.compact) continue;
+
+    const compact = renderVariant(pack, 'compact', cache);
+    if (compact.chars === 0 || compact.chars >= decision.chars) continue;
+
+    const previousChars = decision.chars;
+    selected.set(pack.id, { ...compact, variant: 'compact' });
+    decision.variant = 'compact';
+    decision.chars = compact.chars;
+    decision.estimatedTokens = compact.estimatedTokens;
+    decision.reason = decision.reason || 'max_chars';
+
+    currentChars -= previousChars - compact.chars;
+    currentChars = Math.max(0, currentChars);
+  }
+
+  for (const pack of includedOptional) {
+    if (currentChars <= maxChars) break;
+    if (!selected.has(pack.id)) continue;
+
+    const decision = decisions.get(pack.id);
+    currentChars -= decision?.chars || 0;
+    selected.delete(pack.id);
+    if (decision) {
+      decision.status = 'skipped';
+      decision.reason = decision.reason || 'max_chars';
+      decision.chars = 0;
+      decision.estimatedTokens = 0;
+    }
+  }
+
+  if (currentChars > maxChars) {
+    let overage = currentChars - maxChars;
+    const requiredCandidates = packs
+      .filter((pack) => selected.has(pack.id) && pack.required)
+      .sort((a, b) => {
+        const preserveDelta = (a.preserve ? 1 : 0) - (b.preserve ? 1 : 0);
+        if (preserveDelta !== 0) return preserveDelta;
+        const sizeDelta = (selected.get(b.id)?.chars || 0) - (selected.get(a.id)?.chars || 0);
+        if (sizeDelta !== 0) return sizeDelta;
+        return b.order - a.order;
+      });
+
+    for (const pack of requiredCandidates) {
+      if (overage <= 0) break;
+      const decision = decisions.get(pack.id);
+      const selectedPack = selected.get(pack.id);
+      if (!decision || !selectedPack) continue;
+
+      const targetChars = Math.max(0, selectedPack.chars - overage);
+      const truncated = truncateText(selectedPack.text, targetChars);
+      if (truncated.text.length === selectedPack.chars) continue;
+
+      const newChars = truncated.text.length;
+      const reduced = selectedPack.chars - newChars;
+      overage -= reduced;
+
+      selected.set(pack.id, {
+        text: truncated.text,
+        chars: newChars,
+        estimatedTokens: estimateTokensFromChars(newChars),
+        variant: selectedPack.variant,
+      });
+
+      decision.chars = newChars;
+      decision.estimatedTokens = estimateTokensFromChars(newChars);
+      decision.truncated = true;
+      decision.reason = decision.reason || 'max_chars';
+    }
+  }
+
+  const afterChars = Array.from(selected.values()).reduce((sum, item) => sum + item.chars, 0);
+  return { applied: true, beforeChars: totalChars, afterChars };
+}
+
+function buildContextPacks({ packs, maxTokens, maxChars }) {
+  const normalized = packs.map(normalizePack);
+  const selectionOrder = normalized.slice().sort(sortByPriorityThenOrder);
+  const renderCache = new Map();
+  const decisions = new Map();
+  const selected = new Map();
+
+  let remainingTokens = Number.isFinite(maxTokens) ? maxTokens : Infinity;
+  let overBudgetTokens = 0;
+
+  for (const pack of selectionOrder) {
+    const selection = selectVariant(pack, remainingTokens, renderCache);
+    const decision = {
+      id: pack.id,
+      section: pack.section || null,
+      priority: pack.priority,
+      required: pack.required,
+      status: selection.status,
+      variant: selection.variant,
+      chars: selection.chars,
+      estimatedTokens: selection.estimatedTokens,
+      order: pack.order,
+      reason: selection.reason || null,
+    };
+
+    decisions.set(pack.id, decision);
+
+    if (selection.status !== 'included') {
+      continue;
+    }
+
+    selected.set(pack.id, {
+      text: selection.text,
+      chars: selection.chars,
+      estimatedTokens: selection.estimatedTokens,
+      variant: selection.variant,
+    });
+
+    if (!Number.isFinite(remainingTokens)) {
+      continue;
+    }
+
+    if (selection.estimatedTokens > remainingTokens) {
+      overBudgetTokens += selection.estimatedTokens - remainingTokens;
+      remainingTokens = 0;
+    } else {
+      remainingTokens -= selection.estimatedTokens;
+    }
+  }
+
+  const ordered = normalized.slice().sort(sortByOrder);
+  let context = '';
+  for (const pack of ordered) {
+    const selectedPack = selected.get(pack.id);
+    if (selectedPack) {
+      context += selectedPack.text;
+    }
+  }
+
+  const totalChars = context.length;
+  const truncation = applyMaxCharsGuard({
+    packs: ordered,
+    selected,
+    decisions,
+    cache: renderCache,
+    maxChars,
+    totalChars,
+  });
+
+  if (truncation.applied) {
+    context = '';
+    for (const pack of ordered) {
+      const selectedPack = selected.get(pack.id);
+      if (selectedPack) {
+        context += selectedPack.text;
+      }
+    }
+  }
+
+  const finalChars = context.length;
+  const finalTokens = estimateTokensFromChars(finalChars);
+  const packDecisions = ordered.map((pack) => {
+    const decision = decisions.get(pack.id);
+    return {
+      id: decision.id,
+      section: decision.section,
+      priority: decision.priority,
+      required: decision.required,
+      status: decision.status,
+      variant: decision.variant,
+      chars: decision.chars,
+      estimatedTokens: decision.estimatedTokens,
+      order: decision.order,
+      reason: decision.reason,
+      truncated: decision.truncated || false,
+    };
+  });
+
+  return {
+    context,
+    packDecisions,
+    budget: {
+      maxTokens,
+      remainingTokens: Number.isFinite(remainingTokens) ? remainingTokens : null,
+      overBudgetTokens,
+      finalTokens,
+    },
+    truncation: {
+      maxContextChars: {
+        applied: truncation.applied,
+        beforeChars: truncation.beforeChars,
+        afterChars: truncation.afterChars,
+      },
+    },
+  };
+}
+
+module.exports = {
+  buildContextPacks,
+};

package/src/agent/context-replay-policy.js

@@ -0,0 +1,51 @@
+const RAW_LOG_ONLY_REPLAY_POLICY = 'raw_log_only';
+const CONTEXT_REPLAY_POLICY = 'context';
+
+function buildRawLogOnlyMetadata(extra = {}) {
+  return {
+    ...extra,
+    contextSafe: false,
+    replayPolicy: RAW_LOG_ONLY_REPLAY_POLICY,
+  };
+}
+
+function getReplayPolicy(message) {
+  return message?.metadata?.replayPolicy ?? message?.content?.data?.replayPolicy;
+}
+
+function getContextSafe(message) {
+  if (typeof message?.metadata?.contextSafe === 'boolean') {
+    return message.metadata.contextSafe;
+  }
+
+  if (typeof message?.content?.data?.contextSafe === 'boolean') {
+    return message.content.data.contextSafe;
+  }
+
+  return null;
+}
+
+function isReplayableMessage(message) {
+  const contextSafe = getContextSafe(message);
+  if (contextSafe !== null) {
+    return contextSafe;
+  }
+
+  const replayPolicy = getReplayPolicy(message);
+  if (replayPolicy === RAW_LOG_ONLY_REPLAY_POLICY) {
+    return false;
+  }
+
+  if (replayPolicy === CONTEXT_REPLAY_POLICY) {
+    return true;
+  }
+
+  return message?.topic !== 'AGENT_OUTPUT';
+}
+
+module.exports = {
+  RAW_LOG_ONLY_REPLAY_POLICY,
+  CONTEXT_REPLAY_POLICY,
+  buildRawLogOnlyMetadata,
+  isReplayableMessage,
+};