@deepstrike/sdk 0.2.37 → 0.2.38

package/dist/index.d.ts

@@ -31,5 +31,5 @@ export { Governance } from "./governance.js";
 export type { GovernanceVerdict, GovernancePolicy, GovernanceConstraint } from "./governance.js";
 export { AgentPool } from "./collaboration/pool.js";
 export type { RuntimeSignal, SignalSource } from "./signals/types.js";
-export type { Message, ToolCall, ToolResult, ToolSchema, ContentPart, TextPart, ImagePart, AudioPart, StreamEvent, TextDelta, ThinkingDelta, ToolCallEvent, ToolChunk, ToolDeltaEvent, ToolSuspendEvent, ToolResultEvent, ToolAuditFailedEvent, DoneEvent, ErrorEvent, PermissionRequestEvent, PermissionResolvedEvent, PermissionResponse, LLMProvider, RetryConfig, TokenUsage, } from "./types.js";
+export type { Message, ToolCall, ToolResult, ToolSchema, ContentPart, TextPart, ImagePart, AudioPart, StreamEvent, TextDelta, ThinkingDelta, ToolCallEvent, ToolChunk, ToolDeltaEvent, ToolSuspendEvent, ToolResultEvent, ToolAuditFailedEvent, DoneEvent, ErrorEvent, PermissionRequestEvent, PermissionResolvedEvent, PermissionResponse, EntropySample, EntropySampleEvent, EntropyAlertEvent, EntropyWatchOptions, LLMProvider, RetryConfig, TokenUsage, } from "./types.js";
 export type { WorkflowSpec, WorkflowNodeSpec, } from "./types/agent.js";

package/dist/runtime/kernel-event-log.js

@@ -88,6 +88,25 @@ export function kernelObservationToSessionEvent(obs, turn, opts = {}) {
                 turn: t,
                 history_len: obs.history_len ?? 0,
             };
+        case "entropy_sample":
+            return {
+                kind: "entropy_sample",
+                turn: t,
+                score: obs.score ?? 0,
+                score_version: obs.score_version ?? 0,
+                rho: obs.rho ?? 0,
+                repeat_pressure: obs.repeat_pressure ?? 0,
+                failure_rate: obs.failure_rate ?? 0,
+                rollbacks_in_window: obs.rollbacks_in_window ?? 0,
+                window_turns: obs.window_turns ?? 0,
+            };
+        case "entropy_alert":
+            return {
+                kind: "entropy_alert",
+                turn: t,
+                score: obs.score ?? 0,
+                threshold: obs.threshold ?? 0,
+            };
         case "agent_process_changed":
             return {
                 kind: "agent_process_changed",

package/dist/runtime/kernel-step.d.ts

@@ -1,4 +1,4 @@
-import type { Message, RenderedContext, TaskUpdate, ToolCall, ToolResult, ToolSchema } from "../types.js";
+import type { EntropySample, Message, RenderedContext, TaskUpdate, ToolCall, ToolResult, ToolSchema } from "../types.js";
 import type { SkillMetadata } from "../skills/loader.js";
 import type { RollbackReason } from "./session-log.js";
 export declare const KERNEL_ABI_VERSION = 1;
@@ -114,6 +114,14 @@ export interface KernelObservation {
     /** workflow_completed. */
     completed?: string[];
     failed?: string[];
+    score?: number;
+    score_version?: number;
+    rho?: number;
+    repeat_pressure?: number;
+    failure_rate?: number;
+    rollbacks_in_window?: number;
+    window_turns?: number;
+    threshold?: number;
 }
 export declare function toolSchemaToKernel(schema: ToolSchema): Record<string, unknown>;
 export declare function skillMetadataToKernel(skill: SkillMetadata): Record<string, unknown>;
@@ -125,6 +133,8 @@ export declare function capabilitySkill(skill: SkillMetadata): Record<string, un
 export declare function capabilityMarker(kind: string, id: string, description: string): Record<string, unknown>;
 export declare function capabilityCommandMount(capability: Record<string, unknown>, mountedBy?: string, mountReason?: string): Record<string, unknown>;
 export declare function capabilityCommandUnmount(capabilityKind: string, id: string): Record<string, unknown>;
+/** Camel-case an `entropy_sample` kernel observation into the SDK's `EntropySample`. */
+export declare function entropySampleFromObservation(obs: KernelObservation): EntropySample;
 export declare function kernelApply(runtime: KernelRuntimeHandle, pending: KernelObservation[], event: Record<string, unknown>): KernelObservation[];
 export declare function kernelAction(runtime: KernelRuntimeHandle, pending: KernelObservation[], event: Record<string, unknown>): KernelRunnerAction;
 /**

package/dist/runtime/kernel-step.js

@@ -135,6 +135,19 @@ export function capabilityCommandUnmount(capabilityKind, id) {
 function parseStep(raw) {
     return JSON.parse(raw);
 }
+/** Camel-case an `entropy_sample` kernel observation into the SDK's `EntropySample`. */
+export function entropySampleFromObservation(obs) {
+    return {
+        turn: obs.turn ?? 0,
+        score: obs.score ?? 0,
+        scoreVersion: obs.score_version ?? 0,
+        rho: obs.rho ?? 0,
+        repeatPressure: obs.repeat_pressure ?? 0,
+        failureRate: obs.failure_rate ?? 0,
+        rollbacksInWindow: obs.rollbacks_in_window ?? 0,
+        windowTurns: obs.window_turns ?? 0,
+    };
+}
 function kernelMessageToSdk(raw) {
     const content = raw.content;
     const message = {

package/dist/runtime/runner.d.ts

@@ -1,4 +1,4 @@
-import type { LLMProvider, Message, ContentPart, ToolSchema, StreamEvent, ToolSuspendEvent, PermissionRequestEvent, PermissionResponse, AsyncSummarizer, DreamSummarizer } from "../types.js";
+import type { LLMProvider, Message, ContentPart, ToolSchema, StreamEvent, ToolSuspendEvent, PermissionRequestEvent, PermissionResponse, AsyncSummarizer, DreamSummarizer, EntropySample, EntropyWatchOptions } from "../types.js";
 import type { DreamStore, MemoryEntry, MemoryQuery, MemoryWriteRequest } from "../memory/protocols.js";
 import type { KnowledgeSource } from "../knowledge/source.js";
 import type { SignalSource, RuntimeSignalUrgency } from "../signals/types.js";
@@ -161,6 +161,14 @@ export interface RuntimeOptions {
      * entries and skill pins are never budget-evicted. `0` disables. Default: kernel's 0.25.
      */
     knowledgeBudgetRatio?: number;
+    /**
+     * Opt-in kernel entropy watch: threshold alerting over the per-turn session-entropy score
+     * (`entropy_sample` events stream unconditionally regardless). When the score crosses
+     * `threshold` — armed via hysteresis and past the cooldown — the run emits an `entropy_alert`
+     * stream event (and session-log record); with `notifyModel` the kernel also feeds the model a
+     * durable `[SIGNAL]` directive. Absent ⇒ disabled (kernel default).
+     */
+    entropyWatch?: EntropyWatchOptions;
     /**
      * K3: default lease (in turns) for every skill activation. After that many turns the kernel
      * auto-deactivates the skill — toolset re-widens, knowledge pin boundary-swept — exactly like
@@ -307,6 +315,8 @@ export declare class RuntimeRunner {
      *  at the next safe point (after the tool turn resolves, kernel back in Reason — not suspended). */
     private pendingAuthoredWorkflows;
     private dashboard;
+    /** Most recent kernel entropy sample of the active/last run (see `latestEntropy`). */
+    private lastEntropySample;
     constructor(opts: RuntimeOptions);
     /** Host configuration (for coordinator / sub-agent spawn). */
     get hostOptions(): RuntimeOptions;
@@ -468,6 +478,10 @@ export declare class RuntimeRunner {
      *  without wiring a full `SignalSource`. `urgency` maps to the kernel disposition ladder: `"normal"`
      *  queues for the next boundary (default), `"high"` soft-interrupts, `"critical"` preempts. */
     injectNote(text: string, urgency?: RuntimeSignalUrgency): void;
+    /** The most recent kernel session-entropy sample (one per completed turn), or `null` before the
+     *  first boundary. A pull companion to the streamed `entropy_sample` events — hosts polling from
+     *  outside the stream (e.g. a heartbeat supervisor) read the latest measurement here. */
+    latestEntropy(): EntropySample | null;
     /** Injected-note drain shared by the main loop's per-turn poll: injected notes first (FIFO), then
      *  the configured `signalSource`. Keeps the two inbound channels on one code path so they never drift. */
     private nextInboundSignal;

package/dist/runtime/runner.js

@@ -5,7 +5,7 @@ import { peekProviderReplay, seedProviderReplayFromEvents } from "./provider-rep
 import { sanitizeReplayText } from "./replay-sanitize.js";
 import { buildLlmCompletedEvent, buildRunTerminalEvent, buildWorkflowNodeCompletedEvent, buildWorkflowNodesSubmittedEvent, recoverCompletedWorkflowNodes, recoverSubmittedWorkflowNodes, repairEventsForRecovery, } from "./session-repair.js";
 import { KernelPrimitivesDashboard } from "./kernel-primitives-dashboard.js";
-import { capabilityMarker, capabilitySkill, capabilityTool, capabilityCommandMount, capabilityCommandUnmount, kernelAction, kernelApply, kernelMaybeAction, messageToKernelMessage, skillMetadataToKernel, taskUpdateToKernel, toolResultToKernel, toolSchemaToKernel, } from "./kernel-step.js";
+import { capabilityMarker, capabilitySkill, capabilityTool, capabilityCommandMount, capabilityCommandUnmount, entropySampleFromObservation, kernelAction, kernelApply, kernelMaybeAction, messageToKernelMessage, skillMetadataToKernel, taskUpdateToKernel, toolResultToKernel, toolSchemaToKernel, } from "./kernel-step.js";
 import { agentRunSpecToKernel, findSpawnProcessObservation, milestoneCheckPass, milestoneCheckResultToKernel, spawnObservationToManifest, subAgentResultToKernel, submitWorkflowNodesToKernel, submitWorkflowToKernel, workflowBudgetNote, workflowNodeToManifest, workflowNodeToSpec, workflowSpecToKernel, } from "../types/agent.js";
 import { defaultSubAgentOrchestrator } from "./sub-agent-orchestrator.js";
 import { extractJsonValue, schemaInstruction, schemaRetryInstruction, validateAgainstSchema, } from "./output-schema.js";
@@ -40,6 +40,8 @@ export class RuntimeRunner {
      *  at the next safe point (after the tool turn resolves, kernel back in Reason — not suspended). */
     pendingAuthoredWorkflows = [];
     dashboard = null;
+    /** Most recent kernel entropy sample of the active/last run (see `latestEntropy`). */
+    lastEntropySample = null;
     constructor(opts) {
         this.opts = opts;
         if (opts.enableDiagnosticsDashboard) {
@@ -209,6 +211,18 @@ export class RuntimeRunner {
         if (this.opts.knowledgeBudgetRatio !== undefined) {
             config.knowledge_budget_ratio = this.opts.knowledgeBudgetRatio;
         }
+        // Entropy watch (opt-in): threshold alerting over the per-turn session-entropy score.
+        // Absent fields keep kernel defaults (threshold 0.65 / hysteresis 0.1 / cooldown 4).
+        if (this.opts.entropyWatch !== undefined) {
+            const ew = this.opts.entropyWatch;
+            config.entropy_watch = {
+                enabled: ew.enabled ?? true,
+                ...(ew.threshold !== undefined ? { threshold: ew.threshold } : {}),
+                ...(ew.hysteresis !== undefined ? { hysteresis: ew.hysteresis } : {}),
+                ...(ew.cooldownTurns !== undefined ? { cooldown_turns: ew.cooldownTurns } : {}),
+                ...(ew.notifyModel !== undefined ? { notify_model: ew.notifyModel } : {}),
+            };
+        }
         kernelApply(runtime, this.pendingObservations, { kind: "configure_run", config });
     }
     async appendMemorySyscallObservations(sessionId, observations) {
@@ -805,6 +819,12 @@ export class RuntimeRunner {
             payload: { goal: text },
         });
     }
+    /** The most recent kernel session-entropy sample (one per completed turn), or `null` before the
+     *  first boundary. A pull companion to the streamed `entropy_sample` events — hosts polling from
+     *  outside the stream (e.g. a heartbeat supervisor) read the latest measurement here. */
+    latestEntropy() {
+        return this.lastEntropySample;
+    }
     /** Injected-note drain shared by the main loop's per-turn poll: injected notes first (FIFO), then
      *  the configured `signalSource`. Keeps the two inbound channels on one code path so they never drift. */
     async nextInboundSignal() {
@@ -1711,10 +1731,27 @@ export class RuntimeRunner {
                         }
                         catch { /* malformed skill args — skip activation */ }
                     }
+                    const entropyObsStart = this.pendingObservations.length;
                     action = kernelAction(runtime, this.pendingObservations, {
                         kind: "tool_results",
                         results: toolResults.map(toolResultToKernel),
                     });
+                    // Surface the boundary's entropy measurement live (the heartbeat watch source) —
+                    // the session-log record lands via the normal appendObservations path.
+                    for (const obs of this.pendingObservations.slice(entropyObsStart)) {
+                        if (obs.kind === "entropy_sample") {
+                            this.lastEntropySample = entropySampleFromObservation(obs);
+                            yield { type: "entropy_sample", sample: this.lastEntropySample };
+                        }
+                        else if (obs.kind === "entropy_alert") {
+                            yield {
+                                type: "entropy_alert",
+                                turn: obs.turn ?? 0,
+                                score: obs.score ?? 0,
+                                threshold: obs.threshold ?? 0,
+                            };
+                        }
+                    }
                 }
                 else if (action.kind === "evaluate_milestone") {
                     const milestonePolicy = this.opts.milestonePolicy ?? "require_verifier";

package/dist/runtime/session-log.d.ts

@@ -160,6 +160,21 @@ export type SessionEvent = {
     kind: "checkpoint_taken";
     turn: number;
     history_len: number;
+} | {
+    kind: "entropy_sample";
+    turn: number;
+    score: number;
+    score_version: number;
+    rho: number;
+    repeat_pressure: number;
+    failure_rate: number;
+    rollbacks_in_window: number;
+    window_turns: number;
+} | {
+    kind: "entropy_alert";
+    turn: number;
+    score: number;
+    threshold: number;
 } | {
     kind: "agent_process_changed";
     turn: number;

package/dist/types.d.ts

@@ -205,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.37",
+  "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.37",
+    "@deepstrike/core": "0.2.38",
     "@google/generative-ai": "^0.24.1",
     "openai": "^5.23.2"
   },