@dogpile/sdk 0.2.2 → 0.3.0

package/src/runtime/coordinator.ts

@@ -38,8 +38,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 CoordinatorRunOptions {
   readonly intent: string;
@@ -53,6 +54,7 @@ interface CoordinatorRunOptions {
   readonly seed?: string | number;
   readonly signal?: AbortSignal;
   readonly terminate?: TerminationCondition;
+  readonly wrapUpHint?: DogpileOptions["wrapUpHint"];
   readonly emit?: (event: RunEvent) => void;
 }
 
@@ -69,6 +71,15 @@ export async function runCoordinator(options: CoordinatorRunOptions): Promise<Ru
   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,6 +137,9 @@ export async function runCoordinator(options: CoordinatorRunOptions): Promise<Ru
         providerCalls,
         toolExecutor,
         toolAvailability,
+        events,
+        startedAtMs,
+        wrapUpHint,
         emit,
         recordProtocolDecision
       });
@@ -150,6 +164,11 @@ export async function runCoordinator(options: CoordinatorRunOptions): Promise<Ru
             providerCallSlots,
             toolExecutor,
             toolAvailability,
+            totalCost,
+            events,
+            transcript: planTranscript,
+            startedAtMs,
+            wrapUpHint,
             emit
           })
         )
@@ -201,6 +220,9 @@ export async function runCoordinator(options: CoordinatorRunOptions): Promise<Ru
         providerCalls,
         toolExecutor,
         toolAvailability,
+        events,
+        startedAtMs,
+        wrapUpHint,
         emit,
         recordProtocolDecision
       });
@@ -290,16 +312,20 @@ export async function runCoordinator(options: CoordinatorRunOptions): Promise<Ru
       return stopped;
     }
 
-    const stopRecord = evaluateTerminationStop(options.terminate, {
-      runId,
-      protocol: "coordinator",
-      tier: options.tier,
-      cost: totalCost,
-      events,
-      transcript,
-      iteration: transcript.length,
-      elapsedMs: elapsedMs(startedAtMs)
-    });
+    const stopRecord = evaluateTerminationStop(
+      options.terminate,
+      wrapUpHint.context({
+        runId,
+        protocol: "coordinator",
+        protocolConfig: options.protocol,
+        protocolIteration: transcript.length,
+        cost: totalCost,
+        events,
+        transcript,
+        iteration: transcript.length,
+        elapsedMs: elapsedMs(startedAtMs)
+      })
+    );
 
     if (!stopRecord) {
       return false;
@@ -343,6 +369,9 @@ interface CoordinatorTurnOptions {
   readonly providerCalls: ReplayTraceProviderCall[];
   readonly toolExecutor: RuntimeToolExecutor;
   readonly toolAvailability: JsonObject;
+  readonly events: RunEvent[];
+  readonly startedAtMs: number;
+  readonly wrapUpHint: ReturnType<typeof createWrapUpHintController>;
   readonly emit: (event: RunEvent) => void;
   readonly recordProtocolDecision: (
     event: RunEvent,
@@ -366,16 +395,27 @@ async function runCoordinatorTurn(turn: CoordinatorTurnOptions): Promise<CostSum
       phase: turn.phase,
       ...turn.toolAvailability
     },
-    messages: [
-      {
-        role: "system",
-        content: buildSystemPrompt(turn.agent, turn.coordinator)
-      },
+    messages: turn.wrapUpHint.inject(
+      [
+        {
+          role: "system",
+          content: buildSystemPrompt(turn.agent, turn.coordinator)
+        },
+        {
+          role: "user",
+          content: turn.input
+        }
+      ],
       {
-        role: "user",
-        content: turn.input
+        runId: turn.runId,
+        protocol: "coordinator",
+        cost: turn.totalCost,
+        events: turn.events,
+        transcript: turn.transcript,
+        iteration: turn.transcript.length,
+        elapsedMs: elapsedMs(turn.startedAtMs)
       }
-    ]
+    )
   };
   const response = await generateModelTurn({
     model: turn.options.model,
@@ -445,6 +485,11 @@ interface CoordinatorWorkerTurnOptions {
   readonly providerCallSlots: ReplayTraceProviderCall[];
   readonly toolExecutor: RuntimeToolExecutor;
   readonly toolAvailability: JsonObject;
+  readonly totalCost: CostSummary;
+  readonly events: RunEvent[];
+  readonly transcript: readonly TranscriptEntry[];
+  readonly startedAtMs: number;
+  readonly wrapUpHint: ReturnType<typeof createWrapUpHintController>;
   readonly emit: (event: RunEvent) => void;
 }
 
@@ -473,16 +518,27 @@ async function runCoordinatorWorkerTurn(turn: CoordinatorWorkerTurnOptions): Pro
       phase: "worker",
       ...turn.toolAvailability
     },
-    messages: [
-      {
-        role: "system",
-        content: buildSystemPrompt(turn.agent, turn.coordinator)
-      },
+    messages: turn.wrapUpHint.inject(
+      [
+        {
+          role: "system",
+          content: buildSystemPrompt(turn.agent, turn.coordinator)
+        },
+        {
+          role: "user",
+          content: turn.input
+        }
+      ],
       {
-        role: "user",
-        content: turn.input
+        runId: turn.runId,
+        protocol: "coordinator",
+        cost: turn.totalCost,
+        events: turn.events,
+        transcript: turn.transcript,
+        iteration: turn.turn - 1,
+        elapsedMs: elapsedMs(turn.startedAtMs)
       }
-    ]
+    )
   };
   const response = await generateModelTurn({
     model: turn.options.model,

package/src/runtime/engine.ts

@@ -84,6 +84,7 @@ export function createEngine(options: EngineOptions): Engine {
         ...(options.seed !== undefined ? { seed: options.seed } : {}),
         ...(options.signal !== undefined ? { signal: options.signal } : {}),
         ...(terminate ? { terminate } : {}),
+        ...(options.wrapUpHint ? { wrapUpHint: options.wrapUpHint } : {}),
         ...(options.evaluate ? { evaluate: options.evaluate } : {})
       });
     },
@@ -516,6 +517,7 @@ interface RunProtocolOptions {
   readonly seed?: EngineOptions["seed"];
   readonly signal?: EngineOptions["signal"];
   readonly terminate?: EngineOptions["terminate"];
+  readonly wrapUpHint?: EngineOptions["wrapUpHint"];
   readonly emit?: (event: RunEvent) => void;
 }
 
@@ -618,6 +620,7 @@ function runProtocol(options: RunProtocolOptions): Promise<RunResult> {
         ...(options.seed !== undefined ? { seed: options.seed } : {}),
         ...(options.signal !== undefined ? { signal: options.signal } : {}),
         ...(options.terminate ? { terminate: options.terminate } : {}),
+        ...(options.wrapUpHint ? { wrapUpHint: options.wrapUpHint } : {}),
         ...(options.emit ? { emit: options.emit } : {})
       });
     case "broadcast":
@@ -633,6 +636,7 @@ function runProtocol(options: RunProtocolOptions): Promise<RunResult> {
         ...(options.seed !== undefined ? { seed: options.seed } : {}),
         ...(options.signal !== undefined ? { signal: options.signal } : {}),
         ...(options.terminate ? { terminate: options.terminate } : {}),
+        ...(options.wrapUpHint ? { wrapUpHint: options.wrapUpHint } : {}),
         ...(options.emit ? { emit: options.emit } : {})
       });
     case "coordinator":
@@ -648,6 +652,7 @@ function runProtocol(options: RunProtocolOptions): Promise<RunResult> {
         ...(options.seed !== undefined ? { seed: options.seed } : {}),
         ...(options.signal !== undefined ? { signal: options.signal } : {}),
         ...(options.terminate ? { terminate: options.terminate } : {}),
+        ...(options.wrapUpHint ? { wrapUpHint: options.wrapUpHint } : {}),
         ...(options.emit ? { emit: options.emit } : {})
       });
     case "shared":
@@ -663,6 +668,7 @@ function runProtocol(options: RunProtocolOptions): Promise<RunResult> {
         ...(options.seed !== undefined ? { seed: options.seed } : {}),
         ...(options.signal !== undefined ? { signal: options.signal } : {}),
         ...(options.terminate ? { terminate: options.terminate } : {}),
+        ...(options.wrapUpHint ? { wrapUpHint: options.wrapUpHint } : {}),
         ...(options.emit ? { emit: options.emit } : {})
       });
   }

package/src/runtime/sequential.ts

@@ -37,8 +37,9 @@ import {
 import { throwIfAborted } from "./cancellation.js";
 import { isParticipatingDecision, 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 SequentialRunOptions {
   readonly intent: string;
@@ -52,6 +53,7 @@ interface SequentialRunOptions {
   readonly seed?: string | number;
   readonly signal?: AbortSignal;
   readonly terminate?: TerminationCondition;
+  readonly wrapUpHint?: DogpileOptions["wrapUpHint"];
   readonly emit?: (event: RunEvent) => void;
 }
 
@@ -67,6 +69,15 @@ export async function runSequential(options: SequentialRunOptions): Promise<RunR
   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);
@@ -129,16 +140,27 @@ export async function runSequential(options: SequentialRunOptions): Promise<RunR
         turn,
         ...toolAvailability
       },
-      messages: [
-        {
-          role: "system",
-          content: buildSystemPrompt(agent)
-        },
+      messages: wrapUpHint.inject(
+        [
+          {
+            role: "system",
+            content: buildSystemPrompt(agent)
+          },
+          {
+            role: "user",
+            content: input
+          }
+        ],
         {
-          role: "user",
-          content: input
+          runId,
+          protocol: "sequential",
+          cost: totalCost,
+          events,
+          transcript,
+          iteration: transcript.length,
+          elapsedMs: elapsedMs(startedAtMs)
         }
-      ]
+      )
     };
     const response = await generateModelTurn({
       model: options.model,
@@ -277,16 +299,20 @@ export async function runSequential(options: SequentialRunOptions): Promise<RunR
       return stopped;
     }
 
-    const stopRecord = evaluateTerminationStop(options.terminate, {
-      runId,
-      protocol: "sequential",
-      tier: options.tier,
-      cost: totalCost,
-      events,
-      transcript,
-      iteration: transcript.length,
-      elapsedMs: elapsedMs(startedAtMs)
-    });
+    const stopRecord = evaluateTerminationStop(
+      options.terminate,
+      wrapUpHint.context({
+        runId,
+        protocol: "sequential",
+        protocolConfig: options.protocol,
+        protocolIteration: transcript.length,
+        cost: totalCost,
+        events,
+        transcript,
+        iteration: transcript.length,
+        elapsedMs: elapsedMs(startedAtMs)
+      })
+    );
 
     if (!stopRecord) {
       return false;

package/src/runtime/shared.ts

@@ -36,8 +36,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 +52,7 @@ interface SharedRunOptions {
   readonly seed?: string | number;
   readonly signal?: AbortSignal;
   readonly terminate?: TerminationCondition;
+  readonly wrapUpHint?: DogpileOptions["wrapUpHint"];
   readonly emit?: (event: RunEvent) => void;
 }
 
@@ -67,6 +69,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 +137,27 @@ export async function runShared(options: SharedRunOptions): Promise<RunResult> {
             turn,
             ...toolAvailability
           },
-          messages: [
-            {
-              role: "system",
-              content: buildSystemPrompt(agent)
-            },
+          messages: wrapUpHint.inject(
+            [
+              {
+                role: "system",
+                content: buildSystemPrompt(agent)
+              },
+              {
+                role: "user",
+                content: input
+              }
+            ],
             {
-              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 +307,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;

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,

package/src/runtime/validation.ts

@@ -65,6 +65,7 @@ export function validateDogpileOptions(options: DogpileOptions): void {
   validateOptionalTemperature(options.temperature, "temperature");
   validateOptionalBudgetCaps(options.budget, "budget");
   validateOptionalTerminationCondition(options.terminate, "terminate");
+  validateOptionalWrapUpHint(options.wrapUpHint, "wrapUpHint");
   validateOptionalFunction(options.evaluate, "evaluate");
   validateOptionalSeed(options.seed, "seed");
   validateOptionalAbortSignal(options.signal, "signal");
@@ -87,6 +88,7 @@ export function validateEngineOptions(options: EngineOptions): void {
   validateOptionalTemperature(options.temperature, "temperature");
   validateOptionalBudgetCaps(options.budget, "budget");
   validateOptionalTerminationCondition(options.terminate, "terminate");
+  validateOptionalWrapUpHint(options.wrapUpHint, "wrapUpHint");
   validateOptionalFunction(options.evaluate, "evaluate");
   validateOptionalSeed(options.seed, "seed");
   validateOptionalAbortSignal(options.signal, "signal");
@@ -169,12 +171,14 @@ function validateProtocolConfig(value: ProtocolConfig, path: string): void {
     case "sequential":
     case "shared":
       validateOptionalPositiveInteger(record.maxTurns, `${path}.maxTurns`);
+      validateOptionalNonNegativeInteger(record.minTurns, `${path}.minTurns`);
       if (kind === "shared") {
         validateOptionalString(record.organizationalMemory, `${path}.organizationalMemory`);
       }
       return;
     case "broadcast":
       validateOptionalPositiveInteger(record.maxRounds, `${path}.maxRounds`);
+      validateOptionalNonNegativeInteger(record.minRounds, `${path}.minRounds`);
       return;
   }
 }
@@ -409,6 +413,27 @@ function validateOptionalTemperature(value: number | undefined, path: string): v
   validateOptionalNumberInRange(value, path, 0, 2);
 }
 
+function validateOptionalWrapUpHint(value: unknown, path: string): void {
+  if (value === undefined) {
+    return;
+  }
+
+  const record = requireRecord(value, path);
+  validateOptionalNonNegativeInteger(record.atIteration, `${path}.atIteration`);
+  validateOptionalNumberInRange(record.atFraction, `${path}.atFraction`, 0, 1);
+  validateOptionalFunction(record.inject, `${path}.inject`);
+
+  if (record.atIteration === undefined && record.atFraction === undefined) {
+    invalidConfiguration({
+      path,
+      rule: "object",
+      message: "wrapUpHint must configure atIteration or atFraction.",
+      expected: "WrapUpHintConfig with atIteration or atFraction",
+      actual: value
+    });
+  }
+}
+
 function validateOptionalSeed(value: string | number | undefined, path: string): void {
   if (value === undefined) {
     return;