@dogpile/sdk 0.2.2 → 0.3.1

package/src/runtime/shared.ts

@@ -18,6 +18,7 @@ import type {
   Tier,
   TranscriptEntry
 } from "../types.js";
+import { createRunId, elapsedMs, nowMs, providerCallIdFor } from "./ids.js";
 import {
   addCost,
   createReplayTraceBudget,
@@ -36,8 +37,9 @@ import {
 import { throwIfAborted } from "./cancellation.js";
 import { parseAgentDecision } from "./decisions.js";
 import { generateModelTurn } from "./model.js";
-import { evaluateTerminationStop } from "./termination.js";
+import { evaluateTerminationStop, warnOnProtocolTerminationMisconfiguration } from "./termination.js";
 import { createRuntimeToolExecutor, executeModelResponseToolRequests, runtimeToolAvailability } from "./tools.js";
+import { createWrapUpHintController } from "./wrap-up.js";
 
 interface SharedRunOptions {
   readonly intent: string;
@@ -51,6 +53,7 @@ interface SharedRunOptions {
   readonly seed?: string | number;
   readonly signal?: AbortSignal;
   readonly terminate?: TerminationCondition;
+  readonly wrapUpHint?: DogpileOptions["wrapUpHint"];
   readonly emit?: (event: RunEvent) => void;
 }
 
@@ -67,6 +70,15 @@ export async function runShared(options: SharedRunOptions): Promise<RunResult> {
   const startedAtMs = nowMs();
   let stopped = false;
   let termination: TerminationStopRecord | undefined;
+  const wrapUpHint = createWrapUpHintController({
+    protocol: options.protocol,
+    tier: options.tier,
+    ...(options.budget ? { budget: options.budget } : {}),
+    ...(options.terminate ? { terminate: options.terminate } : {}),
+    ...(options.wrapUpHint ? { wrapUpHint: options.wrapUpHint } : {})
+  });
+
+  warnOnProtocolTerminationMisconfiguration(options.protocol, options.terminate);
 
   const emit = (event: RunEvent): void => {
     events.push(event);
@@ -126,16 +138,27 @@ export async function runShared(options: SharedRunOptions): Promise<RunResult> {
             turn,
             ...toolAvailability
           },
-          messages: [
+          messages: wrapUpHint.inject(
+            [
+              {
+                role: "system",
+                content: buildSystemPrompt(agent)
+              },
+              {
+                role: "user",
+                content: input
+              }
+            ],
             {
-              role: "system",
-              content: buildSystemPrompt(agent)
-            },
-            {
-              role: "user",
-              content: input
+              runId,
+              protocol: "shared",
+              cost: totalCost,
+              events,
+              transcript,
+              iteration: transcript.length,
+              elapsedMs: elapsedMs(startedAtMs)
             }
-          ]
+          )
         };
         const response = await generateModelTurn({
           model: options.model,
@@ -285,16 +308,20 @@ export async function runShared(options: SharedRunOptions): Promise<RunResult> {
       return stopped;
     }
 
-    const stopRecord = evaluateTerminationStop(options.terminate, {
-      runId,
-      protocol: "shared",
-      tier: options.tier,
-      cost: totalCost,
-      events,
-      transcript,
-      iteration: transcript.length,
-      elapsedMs: elapsedMs(startedAtMs)
-    });
+    const stopRecord = evaluateTerminationStop(
+      options.terminate,
+      wrapUpHint.context({
+        runId,
+        protocol: "shared",
+        protocolConfig: options.protocol,
+        protocolIteration: transcript.length,
+        cost: totalCost,
+        events,
+        transcript,
+        iteration: transcript.length,
+        elapsedMs: elapsedMs(startedAtMs)
+      })
+    );
 
     if (!stopRecord) {
       return false;
@@ -349,19 +376,3 @@ function responseCost(response: ModelResponse): CostSummary {
   };
 }
 
-function createRunId(): string {
-  const random = globalThis.crypto?.randomUUID?.();
-  return random ?? `run-${Date.now().toString(36)}`;
-}
-
-function nowMs(): number {
-  return globalThis.performance?.now() ?? Date.now();
-}
-
-function elapsedMs(startedAtMs: number): number {
-  return Math.max(0, nowMs() - startedAtMs);
-}
-
-function providerCallIdFor(runId: string, oneBasedIndex: number): string {
-  return `${runId}:provider-call:${oneBasedIndex}`;
-}

package/src/runtime/termination.ts

@@ -1,7 +1,9 @@
 import type {
+  BroadcastProtocolConfig,
   BudgetStopReason,
   BudgetTerminationCondition,
   ConvergenceTerminationCondition,
+  CoordinatorProtocolConfig,
   FirstOfTerminationCondition,
   FirstOfTerminationConditions,
   FirstOfTerminationOutput,
@@ -10,6 +12,9 @@ import type {
   JudgeTerminationCondition,
   JsonObject,
   NormalizedStopReason,
+  ProtocolConfig,
+  SequentialProtocolConfig,
+  SharedProtocolConfig,
   TerminationStopRecord,
   StopTerminationDecision,
   TerminationCondition,
@@ -85,6 +90,10 @@ export function evaluateTermination(
   condition: TerminationCondition,
   context: TerminationEvaluationContext
 ): TerminationDecision {
+  if (isTerminationFloorBlocked(condition, context)) {
+    return { type: "continue", condition };
+  }
+
   switch (condition.kind) {
     case "budget":
       return evaluateBudget(condition, context);
@@ -166,6 +175,30 @@ export function evaluateTerminationStop(
   return stopRecord(condition, decision);
 }
 
+/**
+ * Warn when a protocol-level termination floor cannot be satisfied because a
+ * lower iteration cap will stop the run first.
+ */
+export function warnOnProtocolTerminationMisconfiguration(
+  protocol: ProtocolConfig,
+  terminate: TerminationCondition | undefined,
+  warn: (message: string) => void = console.warn
+): void {
+  const minTurns = protocolMinTurns(protocol);
+  if (minTurns === undefined || !terminate) {
+    return;
+  }
+
+  const limitingIterationBudget = smallestIterationBudget(terminate);
+  if (limitingIterationBudget === undefined || limitingIterationBudget >= minTurns) {
+    return;
+  }
+
+  warn(
+    `[dogpile] protocol.minTurns (${minTurns}) exceeds terminate budget maxIterations (${limitingIterationBudget}); maxIterations will win.`
+  );
+}
+
 /**
  * Combine independently evaluated termination decisions with SDK precedence.
  *
@@ -384,6 +417,73 @@ function stopPrecedence(reason: NormalizedStopReason): number {
   return 2;
 }
 
+function isTerminationFloorBlocked(condition: TerminationCondition, context: TerminationEvaluationContext): boolean {
+  if (condition.kind !== "convergence" && condition.kind !== "judge") {
+    return false;
+  }
+
+  const floor = protocolTerminationFloor(context.protocolConfig);
+  if (floor === undefined || floor <= 0) {
+    return false;
+  }
+
+  const progress = protocolProgress(context);
+  return progress < floor;
+}
+
+function protocolTerminationFloor(protocol: ProtocolConfig | undefined): number | undefined {
+  if (!protocol) {
+    return undefined;
+  }
+
+  switch (protocol.kind) {
+    case "broadcast":
+      return protocol.minRounds;
+    case "coordinator":
+    case "sequential":
+    case "shared":
+      return protocol.minTurns;
+  }
+}
+
+function protocolProgress(context: TerminationEvaluationContext): number {
+  return context.protocolIteration ?? context.iteration ?? context.transcript.length;
+}
+
+function protocolMinTurns(
+  protocol: ProtocolConfig
+): SequentialProtocolConfig["minTurns"] | CoordinatorProtocolConfig["minTurns"] | SharedProtocolConfig["minTurns"] {
+  switch (protocol.kind) {
+    case "broadcast":
+      return undefined;
+    case "coordinator":
+    case "sequential":
+    case "shared":
+      return protocol.minTurns;
+  }
+}
+
+function smallestIterationBudget(condition: TerminationCondition): number | undefined {
+  switch (condition.kind) {
+    case "budget":
+      return condition.maxIterations;
+    case "convergence":
+    case "judge":
+      return undefined;
+    case "firstOf": {
+      let smallest: number | undefined;
+      for (const child of condition.conditions) {
+        const budget = smallestIterationBudget(child);
+        if (budget === undefined) {
+          continue;
+        }
+        smallest = smallest === undefined ? budget : Math.min(smallest, budget);
+      }
+      return smallest;
+    }
+  }
+}
+
 function judgeStopDetail(decision: JudgeEvaluationDecision, minScore?: number): JsonObject {
   return {
     decision: decision.type,