@deepstrike/sdk 0.2.36 → 0.2.38

package/dist/types/agent.d.ts

@@ -19,6 +19,16 @@ export interface AgentCapabilityFilter {
     allowedKinds?: string[];
     allowedIds?: string[];
 }
+export interface LoopRoundSpec {
+    /** Hard round cap across the loop's lifetime; continue/sleep at the cap is coerced to stop. */
+    maxRounds?: number;
+    /** Sleep clamp floor (ms). */
+    minSleepMs?: number;
+    /** Sleep clamp ceiling (ms). */
+    maxSleepMs?: number;
+    /** Fallback when a round ends without a pace call: "stop" (goal loops, default) | "sleep" (cron loops). */
+    defaultAction?: "stop" | "sleep";
+}
 export interface AgentRunSpec {
     identity: AgentIdentity;
     role: KernelAgentRole;
@@ -28,6 +38,9 @@ export interface AgentRunSpec {
     capabilityFilter?: AgentCapabilityFilter;
     milestones?: MilestoneContract;
     metadata?: Record<string, unknown>;
+    /** ③ loop-agent rounds: presence makes this run ONE round of a paced loop (gates the
+     *  kernel `pace` meta-tool and arms the pacing trap). */
+    loopRound?: LoopRoundSpec;
     /** M1/G3: per-agent model preference (e.g. "opus"/"sonnet"/"haiku"); the host resolves it to a
      *  provider via `RuntimeOptions.providerFor`. Host-side routing only — not sent to the kernel. */
     modelHint?: string;
@@ -72,6 +85,11 @@ export interface LoopResult {
     classifyBranch?: string;
     /** A#2 tournament verdict: a judge reports the winning entrant's agent id here. Sent only when set. */
     tournamentWinner?: string;
+    /** ③ loop-agent pacing: the kernel-adjudicated after-round decision, surfaced by the orchestrator
+     *  from the child's done event. For a loop-node iteration this is the PRIMARY continuation
+     *  vocabulary (stop → loopContinue=false); the legacy text-sniffed signal is the fallback.
+     *  SDK-internal — stripped by `subAgentResultToKernel`. */
+    paceDecision?: import("../runtime/kernel-step.js").PaceDecision;
 }
 export interface SubAgentResult {
     agentId: string;
@@ -147,6 +165,10 @@ export interface WorkflowNodeSpec {
     };
     /** M4/G5: cap this node's child run at `tokenBudget` cumulative tokens (the per-node "use N tokens"). */
     tokenBudget?: number;
+    /** O3: cap this node's child run at `maxTurns` provider turns (falls back to the parent's). */
+    maxTurns?: number;
+    /** O3: cap this node's child run at `maxWallMs` wall-clock milliseconds. */
+    maxWallMs?: number;
     /** Indices of nodes this node depends on. */
     dependsOn?: number[];
 }
@@ -168,7 +190,8 @@ export interface WorkflowSpawnInfo {
     output_schema?: Record<string, unknown>;
     /** G2: for a reduce node, the name of the registered host function to run (no LLM). */
     reducer?: string;
-    /** G2: the dependency agent ids whose outputs a reduce node consumes. */
+    /** The dependency agent ids for EVERY dependent node (W-N2: a DAG edge carries data). A reduce
+     *  node's registered function consumes them; every other node gets its deps' outputs in context. */
     input_agent_ids?: string[];
     /** A#2: present only for a tournament *judge* spawn — the two entrant agent ids whose produced
      *  outputs this judge compares. The runner looks them up and reports the winner as `tournamentWinner`. */
@@ -184,6 +207,10 @@ export interface WorkflowSpawnInfo {
     classify_labels?: string[];
     /** M4/G5: the node's per-node cumulative token cap, if set — the runner caps the child run here. */
     token_budget?: number;
+    /** O3: per-node turn cap → the child run's `maxTurns`. */
+    max_turns?: number;
+    /** O3: per-node wall-clock cap (ms) → the child run's timeout. */
+    max_wall_ms?: number;
 }
 /** G4 budget-as-signal: the workflow's remaining headroom under the active quota, carried on the
  *  `workflow_batch_spawned` observation so a coordinator node can scale its next submission. */

package/dist/types/agent.js

@@ -46,6 +46,14 @@ export function agentRunSpecToKernel(spec) {
         out.verification_contract_id = spec.verificationContractId;
     if (spec.milestones)
         out.milestones = milestoneContractToKernel(spec.milestones);
+    if (spec.loopRound) {
+        out.loop_round = {
+            ...(spec.loopRound.maxRounds !== undefined ? { max_rounds: spec.loopRound.maxRounds } : {}),
+            ...(spec.loopRound.minSleepMs !== undefined ? { min_sleep_ms: spec.loopRound.minSleepMs } : {}),
+            ...(spec.loopRound.maxSleepMs !== undefined ? { max_sleep_ms: spec.loopRound.maxSleepMs } : {}),
+            ...(spec.loopRound.defaultAction !== undefined ? { default_action: spec.loopRound.defaultAction } : {}),
+        };
+    }
     return out;
 }
 export function milestoneContractToKernel(contract) {
@@ -180,6 +188,9 @@ export function workflowNodeSpecToKernel(n) {
         ...(kind ? { kind } : {}),
         // M4/G5: per-node token cap (additive; omitted when unset).
         ...(n.tokenBudget != null ? { token_budget: n.tokenBudget } : {}),
+        // O3: per-node turn / wall-clock caps (additive; omitted when unset).
+        ...(n.maxTurns != null ? { max_turns: n.maxTurns } : {}),
+        ...(n.maxWallMs != null ? { max_wall_ms: n.maxWallMs } : {}),
         ...(n.dependsOn && n.dependsOn.length ? { depends_on: n.dependsOn } : {}),
     };
 }
@@ -356,10 +367,15 @@ export const startWorkflowTool = {
 };
 /** Build a sub-agent run spec for a kernel-generated workflow node. */
 export function workflowNodeToSpec(node, parentSessionId) {
+    // W-N6 transcript-as-carry: a loop node's iterations share ONE stable session id (the `-i{k}`
+    // suffix names the spawn, not the session), so iteration k replays the transcript of 0..k-1 —
+    // "do the next increment" actually sees the previous increments. The agent_id keeps the
+    // per-iteration suffix (kernel completion routing).
+    const sessionNodeId = node.loop_max_iters != null ? node.agent_id.replace(/-i\d+$/, "") : node.agent_id;
     return {
         identity: {
             agentId: node.agent_id,
-            sessionId: `${parentSessionId}-${node.agent_id}`,
+            sessionId: `${parentSessionId}-${sessionNodeId}`,
             isSubAgent: true,
             parentSessionId,
         },
@@ -370,6 +386,14 @@ export function workflowNodeToSpec(node, parentSessionId) {
         ...(node.model_hint ? { modelHint: node.model_hint } : {}),
         // M4/G5: carry the node's token cap so the orchestrator can bound the child run.
         ...(node.token_budget != null ? { tokenBudget: node.token_budget } : {}),
+        // O3: carry the node's turn / wall-clock caps (the orchestrator already honors these).
+        ...(node.max_turns != null ? { maxTurns: node.max_turns } : {}),
+        ...(node.max_wall_ms != null ? { maxWallMs: node.max_wall_ms } : {}),
+        // DW-3 one continuation vocabulary: a loop ITERATION runs with the pacing trap armed, so the
+        // agent signals continue/stop through the kernel-adjudicated `pace` meta-tool instead of a
+        // text-sniffed JSON blob. One iteration = one round; the DAG (not max_rounds) caps iterations,
+        // and default stop means "ended without pacing" = done — the CC silence-is-completion contract.
+        ...(node.loop_max_iters != null ? { loopRound: { defaultAction: "stop" } } : {}),
     };
 }
 /** Build the host manifest for a kernel-generated workflow node. */

package/dist/types.d.ts

@@ -155,6 +155,8 @@ export interface DoneEvent extends StreamEvent {
     totalTokens: number;
     status: string;
     dreamResult?: import("./memory/protocols.js").DreamResult;
+    /** ③ loop-agent: the kernel-adjudicated after-round decision (absent on non-loop runs). */
+    paceDecision?: import("./runtime/kernel-step.js").PaceDecision;
 }
 export interface ErrorEvent extends StreamEvent {
     type: "error";
@@ -203,6 +205,54 @@ export interface ToolAuditFailedEvent extends StreamEvent {
     label: string;
     error: string;
 }
+/** Kernel session-entropy measurement at a completed turn boundary. "Entropy" = session
+ *  disorder: repetition, tool failures, rollbacks, context pressure. The component vector is
+ *  the contract; `score` is a versioned default fold (`scoreVersion`). All normalized
+ *  components are in [0, 1]. */
+export interface EntropySample {
+    turn: number;
+    score: number;
+    scoreVersion: number;
+    /** Context pressure after this boundary's eviction pass. */
+    rho: number;
+    /** Consecutive-identical-turn streak, normalized against the RepeatFuse deny rung. */
+    repeatPressure: number;
+    /** Errored tool results / total tool results over the sliding window. */
+    failureRate: number;
+    /** Raw rollback count inside the window (normalize with `windowTurns`). */
+    rollbacksInWindow: number;
+    /** Effective window size in completed turns. */
+    windowTurns: number;
+}
+/** One kernel entropy sample, emitted once per completed turn (a heartbeat watch source:
+ *  subscribe to drive an external supervisor without tailing the audit log). */
+export interface EntropySampleEvent extends StreamEvent {
+    type: "entropy_sample";
+    sample: EntropySample;
+}
+/** The opt-in kernel entropy watch tripped: `score` crossed `threshold` while armed and
+ *  cooled down (see `RunnerOptions.entropyWatch`). Correlate components via the same-turn
+ *  `entropy_sample` event. */
+export interface EntropyAlertEvent extends StreamEvent {
+    type: "entropy_alert";
+    turn: number;
+    score: number;
+    threshold: number;
+}
+/** Opt-in kernel-side threshold watch over the per-turn entropy score. Sampling itself is
+ *  unconditional; this only controls alerting. `notifyModel` additionally routes the alert
+ *  into the model's own signal channel (durable `[SIGNAL]` directive at the next boundary) —
+ *  leave it off when a host supervisor injects task-aware guidance itself. */
+export interface EntropyWatchOptions {
+    enabled?: boolean;
+    /** Alert when `score >= threshold` (kernel default 0.65). */
+    threshold?: number;
+    /** Re-arm only after the score falls below `threshold - hysteresis` (default 0.1). */
+    hysteresis?: number;
+    /** Minimum completed turns between two alerts (default 4). */
+    cooldownTurns?: number;
+    notifyModel?: boolean;
+}
 export interface TokenUsage {
     /** Full prompt size: uncached input + cache reads + cache writes. */
     inputTokens: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepstrike/sdk",
-  "version": "0.2.36",
+  "version": "0.2.38",
   "description": "DeepStrike Node.js SDK",
   "type": "module",
   "main": "dist/index.js",
@@ -72,7 +72,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.99.0",
-    "@deepstrike/core": "0.2.36",
+    "@deepstrike/core": "0.2.38",
     "@google/generative-ai": "^0.24.1",
     "openai": "^5.23.2"
   },