@the-open-engine/zeroshot 6.38.0 → 6.39.0

package/src/agent/context-pack-core.ts

@@ -0,0 +1,96 @@
+import contextMetrics = require('./context-metrics');
+
+import type {
+  ContextPack,
+  ContextPackPriority,
+  ContextPackVariant,
+  NormalizedContextPack,
+  RenderedVariant,
+} from './context-pack-types';
+
+const { estimateTokensFromChars } = contextMetrics;
+
+const PRIORITY_RANK: Readonly<Record<ContextPackPriority, number>> = {
+  required: 0,
+  high: 1,
+  medium: 2,
+  low: 3,
+};
+
+const DEFAULT_PRIORITY: ContextPackPriority = 'medium';
+
+function isContextPackPriority(priority: string): priority is ContextPackPriority {
+  return (
+    priority === 'required' || priority === 'high' || priority === 'medium' || priority === 'low'
+  );
+}
+
+function normalizePriority(
+  priority: string | undefined,
+  required: boolean | undefined
+): ContextPackPriority {
+  if (required) return 'required';
+  if (priority && isContextPackPriority(priority)) return priority;
+  return DEFAULT_PRIORITY;
+}
+
+function normalizePack(pack: ContextPack, index: number): NormalizedContextPack {
+  const priority = normalizePriority(pack.priority, pack.required);
+  return {
+    ...pack,
+    priority,
+    required: pack.required || priority === 'required',
+    order: pack.order ?? index,
+  };
+}
+
+function renderVariant(
+  pack: NormalizedContextPack,
+  variant: ContextPackVariant,
+  cache: Map<string, RenderedVariant>
+): RenderedVariant {
+  const cacheKey = `${pack.id}:${variant}`;
+  const cached = cache.get(cacheKey);
+  if (cached) return cached;
+
+  let text: unknown = '';
+  if (variant === 'full') {
+    text = typeof pack.render === 'function' ? pack.render() : '';
+  } else if (variant === 'compact') {
+    text = typeof pack.compact === 'function' ? pack.compact() : '';
+  }
+
+  const safeText = typeof text === 'string' ? text : '';
+  const chars = safeText.length;
+  const estimatedTokens = estimateTokensFromChars(chars);
+  const rendered = { text: safeText, chars, estimatedTokens };
+  cache.set(cacheKey, rendered);
+  return rendered;
+}
+
+function sortByPriorityThenOrder(a: NormalizedContextPack, b: NormalizedContextPack): number {
+  const priorityDelta = PRIORITY_RANK[a.priority] - PRIORITY_RANK[b.priority];
+  if (priorityDelta !== 0) return priorityDelta;
+  return a.order - b.order;
+}
+
+function sortByOrder(a: NormalizedContextPack, b: NormalizedContextPack): number {
+  return a.order - b.order;
+}
+
+function sortByPriorityDescThenOrderDesc(
+  a: NormalizedContextPack,
+  b: NormalizedContextPack
+): number {
+  const priorityDelta = PRIORITY_RANK[b.priority] - PRIORITY_RANK[a.priority];
+  if (priorityDelta !== 0) return priorityDelta;
+  return b.order - a.order;
+}
+
+export = {
+  normalizePack,
+  renderVariant,
+  sortByPriorityThenOrder,
+  sortByOrder,
+  sortByPriorityDescThenOrderDesc,
+};

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

@@ -0,0 +1,119 @@
+"use strict";
+const contextPackCore = require("./context-pack-core");
+const { renderVariant, sortByPriorityThenOrder } = contextPackCore;
+function includedSelection(variant, rendered) {
+    return {
+        status: 'included',
+        variant,
+        chars: rendered.chars,
+        estimatedTokens: rendered.estimatedTokens,
+        text: rendered.text,
+    };
+}
+function skippedSelection(reason) {
+    return {
+        status: 'skipped',
+        variant: null,
+        reason,
+        chars: 0,
+        estimatedTokens: 0,
+    };
+}
+function shouldCompactRequired(full, compact, remainingTokens) {
+    return (Number.isFinite(remainingTokens) &&
+        compact !== null &&
+        compact.chars > 0 &&
+        full.estimatedTokens > remainingTokens &&
+        (compact.estimatedTokens <= remainingTokens || compact.estimatedTokens < full.estimatedTokens));
+}
+function selectRequiredVariant(full, compact, remainingTokens) {
+    if (full.chars === 0 && compact && compact.chars > 0) {
+        return includedSelection('compact', compact);
+    }
+    if (shouldCompactRequired(full, compact, remainingTokens)) {
+        return includedSelection('compact', compact);
+    }
+    return includedSelection('full', full);
+}
+function selectOptionalVariant(full, compact, remainingTokens) {
+    if (!Number.isFinite(remainingTokens) || full.estimatedTokens <= remainingTokens) {
+        return includedSelection('full', full);
+    }
+    if (compact && compact.chars > 0 && compact.estimatedTokens <= remainingTokens) {
+        return includedSelection('compact', compact);
+    }
+    return skippedSelection('budget');
+}
+function selectVariant(pack, remainingTokens, cache) {
+    const full = renderVariant(pack, 'full', cache);
+    const compact = pack.compact ? renderVariant(pack, 'compact', cache) : null;
+    if (full.chars === 0 && (!compact || compact.chars === 0)) {
+        return skippedSelection('empty');
+    }
+    return pack.required
+        ? selectRequiredVariant(full, compact, remainingTokens)
+        : selectOptionalVariant(full, compact, remainingTokens);
+}
+function buildDecision(pack, selection) {
+    return {
+        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: 'reason' in selection ? selection.reason : null,
+    };
+}
+function consumeSelectionBudget(selection, budget) {
+    if (!Number.isFinite(budget.remainingTokens)) {
+        return budget;
+    }
+    if (selection.estimatedTokens > budget.remainingTokens) {
+        return {
+            remainingTokens: 0,
+            overBudgetTokens: budget.overBudgetTokens + selection.estimatedTokens - budget.remainingTokens,
+        };
+    }
+    return {
+        remainingTokens: budget.remainingTokens - selection.estimatedTokens,
+        overBudgetTokens: budget.overBudgetTokens,
+    };
+}
+function selectPacks(normalized, maxTokens) {
+    const renderCache = new Map();
+    const decisions = new Map();
+    const selected = new Map();
+    let budget = {
+        remainingTokens: typeof maxTokens === 'number' && Number.isFinite(maxTokens) ? maxTokens : Infinity,
+        overBudgetTokens: 0,
+    };
+    const selectionOrder = normalized.slice().sort(sortByPriorityThenOrder);
+    for (const pack of selectionOrder) {
+        const selection = selectVariant(pack, budget.remainingTokens, renderCache);
+        decisions.set(pack.id, buildDecision(pack, selection));
+        if (selection.status !== 'included') {
+            continue;
+        }
+        selected.set(pack.id, {
+            text: selection.text,
+            chars: selection.chars,
+            estimatedTokens: selection.estimatedTokens,
+            variant: selection.variant,
+        });
+        budget = consumeSelectionBudget(selection, budget);
+    }
+    return {
+        renderCache,
+        decisions,
+        selected,
+        remainingTokens: budget.remainingTokens,
+        overBudgetTokens: budget.overBudgetTokens,
+    };
+}
+module.exports = {
+    selectPacks,
+};

package/src/agent/context-pack-selection.ts

@@ -0,0 +1,187 @@
+import contextPackCore = require('./context-pack-core');
+
+import type {
+  IncludedSelection,
+  MutableContextPackDecision,
+  NormalizedContextPack,
+  PackSelection,
+  PackSelectionState,
+  RenderedVariant,
+  SelectedVariant,
+} from './context-pack-types';
+
+type SkippedSelection = Extract<PackSelection, { status: 'skipped' }>;
+
+interface TokenBudgetState {
+  remainingTokens: number;
+  overBudgetTokens: number;
+}
+
+const { renderVariant, sortByPriorityThenOrder } = contextPackCore;
+
+function includedSelection(
+  variant: IncludedSelection['variant'],
+  rendered: RenderedVariant
+): IncludedSelection {
+  return {
+    status: 'included',
+    variant,
+    chars: rendered.chars,
+    estimatedTokens: rendered.estimatedTokens,
+    text: rendered.text,
+  };
+}
+
+function skippedSelection(reason: SkippedSelection['reason']): SkippedSelection {
+  return {
+    status: 'skipped',
+    variant: null,
+    reason,
+    chars: 0,
+    estimatedTokens: 0,
+  };
+}
+
+function shouldCompactRequired(
+  full: RenderedVariant,
+  compact: RenderedVariant | null,
+  remainingTokens: number
+): compact is RenderedVariant {
+  return (
+    Number.isFinite(remainingTokens) &&
+    compact !== null &&
+    compact.chars > 0 &&
+    full.estimatedTokens > remainingTokens &&
+    (compact.estimatedTokens <= remainingTokens || compact.estimatedTokens < full.estimatedTokens)
+  );
+}
+
+function selectRequiredVariant(
+  full: RenderedVariant,
+  compact: RenderedVariant | null,
+  remainingTokens: number
+): IncludedSelection {
+  if (full.chars === 0 && compact && compact.chars > 0) {
+    return includedSelection('compact', compact);
+  }
+
+  if (shouldCompactRequired(full, compact, remainingTokens)) {
+    return includedSelection('compact', compact);
+  }
+
+  return includedSelection('full', full);
+}
+
+function selectOptionalVariant(
+  full: RenderedVariant,
+  compact: RenderedVariant | null,
+  remainingTokens: number
+): PackSelection {
+  if (!Number.isFinite(remainingTokens) || full.estimatedTokens <= remainingTokens) {
+    return includedSelection('full', full);
+  }
+
+  if (compact && compact.chars > 0 && compact.estimatedTokens <= remainingTokens) {
+    return includedSelection('compact', compact);
+  }
+
+  return skippedSelection('budget');
+}
+
+function selectVariant(
+  pack: NormalizedContextPack,
+  remainingTokens: number,
+  cache: Map<string, RenderedVariant>
+): PackSelection {
+  const full = renderVariant(pack, 'full', cache);
+  const compact = pack.compact ? renderVariant(pack, 'compact', cache) : null;
+
+  if (full.chars === 0 && (!compact || compact.chars === 0)) {
+    return skippedSelection('empty');
+  }
+
+  return pack.required
+    ? selectRequiredVariant(full, compact, remainingTokens)
+    : selectOptionalVariant(full, compact, remainingTokens);
+}
+
+function buildDecision(
+  pack: NormalizedContextPack,
+  selection: PackSelection
+): MutableContextPackDecision {
+  return {
+    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: 'reason' in selection ? selection.reason : null,
+  };
+}
+
+function consumeSelectionBudget(
+  selection: IncludedSelection,
+  budget: TokenBudgetState
+): TokenBudgetState {
+  if (!Number.isFinite(budget.remainingTokens)) {
+    return budget;
+  }
+
+  if (selection.estimatedTokens > budget.remainingTokens) {
+    return {
+      remainingTokens: 0,
+      overBudgetTokens:
+        budget.overBudgetTokens + selection.estimatedTokens - budget.remainingTokens,
+    };
+  }
+
+  return {
+    remainingTokens: budget.remainingTokens - selection.estimatedTokens,
+    overBudgetTokens: budget.overBudgetTokens,
+  };
+}
+
+function selectPacks(
+  normalized: readonly NormalizedContextPack[],
+  maxTokens: number | undefined
+): PackSelectionState {
+  const renderCache = new Map<string, RenderedVariant>();
+  const decisions = new Map<string, MutableContextPackDecision>();
+  const selected = new Map<string, SelectedVariant>();
+  let budget: TokenBudgetState = {
+    remainingTokens:
+      typeof maxTokens === 'number' && Number.isFinite(maxTokens) ? maxTokens : Infinity,
+    overBudgetTokens: 0,
+  };
+  const selectionOrder = normalized.slice().sort(sortByPriorityThenOrder);
+  for (const pack of selectionOrder) {
+    const selection = selectVariant(pack, budget.remainingTokens, renderCache);
+    decisions.set(pack.id, buildDecision(pack, selection));
+    if (selection.status !== 'included') {
+      continue;
+    }
+    selected.set(pack.id, {
+      text: selection.text,
+      chars: selection.chars,
+      estimatedTokens: selection.estimatedTokens,
+      variant: selection.variant,
+    });
+    budget = consumeSelectionBudget(selection, budget);
+  }
+
+  return {
+    renderCache,
+    decisions,
+    selected,
+    remainingTokens: budget.remainingTokens,
+    overBudgetTokens: budget.overBudgetTokens,
+  };
+}
+
+export = {
+  selectPacks,
+};

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

@@ -0,0 +1,139 @@
+"use strict";
+const contextMetrics = require("./context-metrics");
+const contextPackCore = require("./context-pack-core");
+const { estimateTokensFromChars } = contextMetrics;
+const { renderVariant, sortByPriorityDescThenOrderDesc } = contextPackCore;
+const TRUNCATION_SUFFIX = '\n\n[Context truncated to fit limit]\n';
+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 compactOptionalPacks(packs, { selected, decisions, cache, maxChars }, startingChars) {
+    let currentChars = startingChars;
+    for (const pack of packs) {
+        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);
+    }
+    return currentChars;
+}
+function dropOptionalPacks(packs, { selected, decisions, maxChars }, startingChars) {
+    let currentChars = startingChars;
+    for (const pack of packs) {
+        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;
+        }
+    }
+    return currentChars;
+}
+function sortRequiredTruncationCandidates(packs, selected) {
+    return 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;
+    });
+}
+function truncateRequiredPacks({ packs, selected, decisions, currentChars, maxChars, }) {
+    let overage = currentChars - maxChars;
+    const requiredCandidates = sortRequiredTruncationCandidates(packs, selected);
+    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;
+        overage -= selectedPack.chars - newChars;
+        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';
+    }
+}
+function selectedChars(selected) {
+    return Array.from(selected.values()).reduce((sum, item) => sum + item.chars, 0);
+}
+function applyMaxCharsGuard({ packs, selected, decisions, cache, maxChars, totalChars, }) {
+    if (typeof maxChars !== 'number' || !Number.isFinite(maxChars) || totalChars <= maxChars) {
+        return {
+            applied: false,
+            beforeChars: totalChars,
+            afterChars: totalChars,
+        };
+    }
+    const includedOptional = packs
+        .filter((pack) => selected.has(pack.id) && !pack.required)
+        .sort(sortByPriorityDescThenOrderDesc);
+    const mutationParams = { selected, decisions, cache, maxChars };
+    let currentChars = compactOptionalPacks(includedOptional, mutationParams, totalChars);
+    currentChars = dropOptionalPacks(includedOptional, mutationParams, currentChars);
+    if (currentChars > maxChars) {
+        truncateRequiredPacks({
+            packs,
+            selected,
+            decisions,
+            currentChars,
+            maxChars,
+        });
+    }
+    return {
+        applied: true,
+        beforeChars: totalChars,
+        afterChars: selectedChars(selected),
+    };
+}
+module.exports = {
+    applyMaxCharsGuard,
+};