@dogpile/sdk 0.2.2 → 0.3.0

package/src/runtime/wrap-up.ts

@@ -0,0 +1,257 @@
+import type {
+  BudgetCaps,
+  BudgetTier,
+  EngineOptions,
+  JsonObject,
+  ModelMessage,
+  Protocol,
+  ProtocolConfig,
+  RunEvent,
+  TerminationCondition,
+  TerminationEvaluationContext,
+  TranscriptEntry,
+  WrapUpHintConfig
+} from "../types.js";
+
+interface WrapUpControllerOptions {
+  readonly protocol: ProtocolConfig;
+  readonly tier: BudgetTier;
+  readonly budget?: BudgetCaps;
+  readonly terminate?: TerminationCondition;
+  readonly wrapUpHint?: WrapUpHintConfig;
+}
+
+interface WrapUpContextOptions {
+  readonly runId: string;
+  readonly protocol: Protocol;
+  readonly protocolConfig?: ProtocolConfig;
+  readonly cost: TerminationEvaluationContext["cost"];
+  readonly events: readonly RunEvent[];
+  readonly transcript: readonly TranscriptEntry[];
+  readonly iteration?: number;
+  readonly protocolIteration?: number;
+  readonly elapsedMs?: number;
+  readonly metadata?: JsonObject;
+}
+
+export function createWrapUpHintController(options: WrapUpControllerOptions) {
+  const hint = options.wrapUpHint;
+  const effectiveBudget = effectiveWrapUpBudget(options.budget, options.terminate);
+  let emitted = false;
+
+  return {
+    context(context: WrapUpContextOptions): TerminationEvaluationContext {
+      return wrapUpEvaluationContext({
+        ...context,
+        tier: options.tier,
+        ...(effectiveBudget !== undefined ? { budget: effectiveBudget } : {})
+      });
+    },
+
+    inject(messages: readonly ModelMessage[], context: WrapUpContextOptions): readonly ModelMessage[] {
+      if (!hint || emitted) {
+        return messages;
+      }
+
+      const evaluationContext = wrapUpEvaluationContext({
+        ...context,
+        tier: options.tier,
+        ...(effectiveBudget !== undefined ? { budget: effectiveBudget } : {})
+      });
+
+      if (!shouldInjectWrapUpHint(hint, evaluationContext)) {
+        return messages;
+      }
+
+      const content = (hint.inject ?? defaultWrapUpHint)(evaluationContext);
+      emitted = true;
+
+      return [
+        messages[0] ?? { role: "system", content: "" },
+        { role: "system", content },
+        ...messages.slice(1)
+      ];
+    }
+  };
+}
+
+function wrapUpEvaluationContext(
+  options: WrapUpContextOptions & { readonly tier: BudgetTier; readonly budget?: BudgetCaps }
+): TerminationEvaluationContext {
+  const iteration = options.iteration ?? options.transcript.length;
+  const elapsedMs = options.elapsedMs;
+
+  return {
+    runId: options.runId,
+    protocol: options.protocol,
+    tier: options.tier,
+    cost: options.cost,
+    events: options.events,
+    transcript: options.transcript,
+    ...(options.protocolConfig !== undefined ? { protocolConfig: options.protocolConfig } : {}),
+    ...(iteration !== undefined ? { iteration } : {}),
+    ...(options.protocolIteration !== undefined ? { protocolIteration: options.protocolIteration } : {}),
+    ...(elapsedMs !== undefined ? { elapsedMs } : {}),
+    ...(options.budget !== undefined ? { budget: options.budget } : {}),
+    ...(options.budget !== undefined
+      ? {
+          remainingBudget: remainingBudget(options.budget, {
+            cost: options.cost,
+            iteration,
+            elapsedMs
+          })
+        }
+      : {}),
+    ...(options.metadata !== undefined ? { metadata: options.metadata } : {})
+  };
+}
+
+function shouldInjectWrapUpHint(hint: WrapUpHintConfig, context: TerminationEvaluationContext): boolean {
+  const iteration = context.iteration ?? context.transcript.length;
+
+  if (hint.atIteration !== undefined && iteration >= hint.atIteration) {
+    return true;
+  }
+
+  if (hint.atFraction === undefined || context.budget === undefined) {
+    return false;
+  }
+
+  const fraction = hint.atFraction;
+  return (
+    capFractionReached(iteration, context.budget.maxIterations, fraction) ||
+    capFractionReached(context.elapsedMs, context.budget.timeoutMs, fraction)
+  );
+}
+
+function capFractionReached(current: number | undefined, limit: number | undefined, fraction: number): boolean {
+  if (current === undefined || limit === undefined || limit <= 0) {
+    return false;
+  }
+
+  return current / limit >= fraction;
+}
+
+function remainingBudget(
+  budget: BudgetCaps,
+  current: {
+    readonly cost: TerminationEvaluationContext["cost"];
+    readonly iteration: number | undefined;
+    readonly elapsedMs: number | undefined;
+  }
+): NonNullable<TerminationEvaluationContext["remainingBudget"]> {
+  return {
+    ...(budget.maxIterations !== undefined && current.iteration !== undefined
+      ? { iterations: Math.max(0, budget.maxIterations - current.iteration) }
+      : {}),
+    ...(budget.timeoutMs !== undefined && current.elapsedMs !== undefined
+      ? { timeoutMs: Math.max(0, budget.timeoutMs - current.elapsedMs) }
+      : {}),
+    ...(budget.maxUsd !== undefined ? { usd: Math.max(0, budget.maxUsd - current.cost.usd) } : {}),
+    ...(budget.maxTokens !== undefined ? { tokens: Math.max(0, budget.maxTokens - current.cost.totalTokens) } : {})
+  };
+}
+
+function defaultWrapUpHint(context: TerminationEvaluationContext): string {
+  const parts: string[] = [];
+  const remaining = context.remainingBudget;
+
+  if (remaining?.iterations !== undefined) {
+    const label = remaining.iterations === 1 ? "turn" : "turns";
+    parts.push(`${remaining.iterations} ${label} remaining`);
+  }
+  if (remaining?.timeoutMs !== undefined) {
+    parts.push(`${formatRemainingTime(remaining.timeoutMs)} remaining`);
+  }
+
+  const remainingText =
+    parts.length === 0 ? "You are approaching a configured hard limit." : `You are approaching a hard limit with ${parts.join(" and ")}.`;
+  return `[wrap-up] ${remainingText} If you have enough context, package your work now and return a final-ready answer.`;
+}
+
+function formatRemainingTime(timeoutMs: number): string {
+  if (timeoutMs >= 1_000) {
+    return `${(timeoutMs / 1_000).toFixed(1)}s`;
+  }
+
+  return `${timeoutMs}ms`;
+}
+
+function effectiveWrapUpBudget(
+  budget: BudgetCaps | undefined,
+  terminate: EngineOptions["terminate"]
+): BudgetCaps | undefined {
+  const terminationBudget = budgetCapsFromTermination(terminate);
+  if (!budget && !terminationBudget) {
+    return undefined;
+  }
+
+  const maxUsd = minCap(budget?.maxUsd, terminationBudget?.maxUsd);
+  const maxTokens = minCap(budget?.maxTokens, terminationBudget?.maxTokens);
+  const maxIterations = minCap(budget?.maxIterations, terminationBudget?.maxIterations);
+  const timeoutMs = minCap(budget?.timeoutMs, terminationBudget?.timeoutMs);
+
+  return {
+    ...(maxUsd !== undefined ? { maxUsd } : {}),
+    ...(maxTokens !== undefined ? { maxTokens } : {}),
+    ...(maxIterations !== undefined ? { maxIterations } : {}),
+    ...(timeoutMs !== undefined ? { timeoutMs } : {})
+  };
+}
+
+function budgetCapsFromTermination(condition: TerminationCondition | undefined): BudgetCaps | undefined {
+  if (!condition) {
+    return undefined;
+  }
+
+  switch (condition.kind) {
+    case "budget":
+      return {
+        ...(condition.maxUsd !== undefined ? { maxUsd: condition.maxUsd } : {}),
+        ...(condition.maxTokens !== undefined ? { maxTokens: condition.maxTokens } : {}),
+        ...(condition.maxIterations !== undefined ? { maxIterations: condition.maxIterations } : {}),
+        ...(condition.timeoutMs !== undefined ? { timeoutMs: condition.timeoutMs } : {})
+      };
+    case "firstOf": {
+      let merged: BudgetCaps | undefined;
+      for (const child of condition.conditions) {
+        merged = mergeBudgetCaps(merged, budgetCapsFromTermination(child));
+      }
+      return merged;
+    }
+    case "convergence":
+    case "judge":
+      return undefined;
+  }
+}
+
+function mergeBudgetCaps(left: BudgetCaps | undefined, right: BudgetCaps | undefined): BudgetCaps | undefined {
+  if (!left) {
+    return right;
+  }
+  if (!right) {
+    return left;
+  }
+
+  const maxUsd = minCap(left.maxUsd, right.maxUsd);
+  const maxTokens = minCap(left.maxTokens, right.maxTokens);
+  const maxIterations = minCap(left.maxIterations, right.maxIterations);
+  const timeoutMs = minCap(left.timeoutMs, right.timeoutMs);
+
+  return {
+    ...(maxUsd !== undefined ? { maxUsd } : {}),
+    ...(maxTokens !== undefined ? { maxTokens } : {}),
+    ...(maxIterations !== undefined ? { maxIterations } : {}),
+    ...(timeoutMs !== undefined ? { timeoutMs } : {})
+  };
+}
+
+function minCap(left: number | undefined, right: number | undefined): number | undefined {
+  if (left === undefined) {
+    return right;
+  }
+  if (right === undefined) {
+    return left;
+  }
+  return Math.min(left, right);
+}

package/src/types.ts

@@ -260,6 +260,12 @@ export interface SequentialProtocolConfig {
   readonly kind: "sequential";
   /** Maximum number of agent turns to execute; defaults to `3` for named protocols. */
   readonly maxTurns?: number;
+  /**
+   * Floor for convergence and judge termination checks.
+   *
+   * Budget caps still apply immediately. Defaults to `0` when omitted.
+   */
+  readonly minTurns?: number;
 }
 
 /**
@@ -274,6 +280,12 @@ export interface CoordinatorProtocolConfig {
   readonly kind: "coordinator";
   /** Maximum number of coordinator-managed turns to execute; defaults to `3` for named protocols. */
   readonly maxTurns?: number;
+  /**
+   * Floor for convergence and judge termination checks.
+   *
+   * Budget caps still apply immediately. Defaults to `0` when omitted.
+   */
+  readonly minTurns?: number;
 }
 
 /**
@@ -288,6 +300,12 @@ export interface BroadcastProtocolConfig {
   readonly kind: "broadcast";
   /** Maximum number of broadcast/merge rounds to execute; defaults to `2` for named protocols. */
   readonly maxRounds?: number;
+  /**
+   * Floor for convergence and judge termination checks.
+   *
+   * Budget caps still apply immediately. Defaults to `0` when omitted.
+   */
+  readonly minRounds?: number;
 }
 
 /**
@@ -302,6 +320,12 @@ export interface SharedProtocolConfig {
   readonly kind: "shared";
   /** Maximum number of shared-state turns to execute; defaults to `3` for named protocols. */
   readonly maxTurns?: number;
+  /**
+   * Floor for convergence and judge termination checks.
+   *
+   * Budget caps still apply immediately. Defaults to `0` when omitted.
+   */
+  readonly minTurns?: number;
   /** Optional organizational memory snapshot visible to every shared agent. */
   readonly organizationalMemory?: string;
 }
@@ -526,6 +550,8 @@ export interface TerminationEvaluationContext {
   readonly runId: string;
   /** Protocol currently executing. */
   readonly protocol: Protocol;
+  /** Exact normalized protocol configuration when the evaluator needs protocol-specific limits. */
+  readonly protocolConfig?: ProtocolConfig;
   /** Cost/quality tier selected for the run. */
   readonly tier: BudgetTier;
   /** Current accumulated cost and token usage. */
@@ -536,8 +562,14 @@ export interface TerminationEvaluationContext {
   readonly transcript: readonly TranscriptEntry[];
   /** Completed model-turn iterations at the evaluation point. */
   readonly iteration?: number;
+  /** Protocol-native progress count: turns for sequential/coordinator/shared, rounds for broadcast. */
+  readonly protocolIteration?: number;
   /** Elapsed runtime in milliseconds at the evaluation point. */
   readonly elapsedMs?: number;
+  /** Effective hard caps visible to this evaluation point. */
+  readonly budget?: BudgetCaps;
+  /** Remaining headroom computed from the effective hard caps at this evaluation point. */
+  readonly remainingBudget?: RemainingBudget;
   /** Optional normalized judge or quality score in the inclusive range `0..1`. */
   readonly quality?: NormalizedQualityScore;
   /** Optional caller-owned judge decision for judge termination checks. */
@@ -546,6 +578,20 @@ export interface TerminationEvaluationContext {
   readonly metadata?: JsonObject;
 }
 
+/**
+ * Remaining budget headroom derived from the current evaluation context.
+ */
+export interface RemainingBudget {
+  /** Remaining turn iterations before an iteration cap is reached. */
+  readonly iterations?: number;
+  /** Remaining elapsed milliseconds before a timeout cap is reached. */
+  readonly timeoutMs?: number;
+  /** Remaining spend in US dollars before a cost cap is reached. */
+  readonly usd?: number;
+  /** Remaining total tokens before a token cap is reached. */
+  readonly tokens?: number;
+}
+
 /**
  * Decision returned by a termination condition evaluator.
  */
@@ -2547,6 +2593,26 @@ export interface BudgetCostTierOptions {
   readonly budget?: BudgetCaps;
 }
 
+/**
+ * Advisory wrap-up hint injected into the next model turn near a hard cap.
+ */
+export interface WrapUpHintConfig {
+  /** Absolute completed model-turn iteration at which to inject the hint once. */
+  readonly atIteration?: number;
+  /**
+   * Fraction of `maxIterations` or `timeoutMs` at which to inject the hint once.
+   *
+   * `0.8` means the next turn after reaching 80% of a supported cap receives
+   * the wrap-up hint.
+   */
+  readonly atFraction?: number;
+  /**
+   * Optional custom hint builder. When omitted, the SDK injects a default
+   * message that describes the remaining turn and/or time budget.
+   */
+  readonly inject?: (context: TerminationEvaluationContext) => string;
+}
+
 /**
  * Options accepted by the high-level single-call workflow APIs.
  *
@@ -2576,6 +2642,8 @@ export interface DogpileOptions extends BudgetCostTierOptions {
   readonly temperature?: number;
   /** Optional composable termination policy for budget, convergence, judge, or firstOf stop conditions. */
   readonly terminate?: TerminationCondition;
+  /** Optional one-shot advisory hint injected into the next model turn near a hard cap. */
+  readonly wrapUpHint?: WrapUpHintConfig;
   /** Optional caller-owned evaluator that supplies quality and evaluation data. */
   readonly evaluate?: RunEvaluator;
   /** Optional deterministic seed recorded in the replay trace. */
@@ -2638,6 +2706,8 @@ export interface EngineOptions {
   readonly budget?: Omit<Budget, "tier">;
   /** Optional composable termination policy for budget, convergence, judge, or firstOf stop conditions. */
   readonly terminate?: TerminationCondition;
+  /** Optional one-shot advisory hint injected into the next model turn near a hard cap. */
+  readonly wrapUpHint?: WrapUpHintConfig;
   /** Optional caller-owned evaluator that supplies quality and evaluation data. */
   readonly evaluate?: RunEvaluator;
   /** Optional deterministic seed recorded in the replay trace. */