@deepstrike/sdk 0.2.36 → 0.2.38

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { runAgent, runFanout } from "./runtime/facade.js";
+export { runLoop, LoopDriver, foldLoopState } from "./runtime/loop-driver.js";
+export type { LoopSpec, LoopOutcome } from "./runtime/loop-driver.js";
 export type { RunAgentOptions, RunFanoutOptions } from "./runtime/facade.js";
 export { RuntimeRunner, collectText } from "./runtime/runner.js";
 export type { RuntimeOptions } from "./runtime/runner.js";
@@ -29,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/index.js

@@ -12,6 +12,8 @@
 // ╚══════════════════════════════════════════════════════════════════════════╝
 // ── Start here: the canonical entry points ─────────────────────────────────
 export { runAgent, runFanout } from "./runtime/facade.js";
+// ③ dynamic loop agents: self-pacing rounds over the kernel pacing trap.
+export { runLoop, LoopDriver, foldLoopState } from "./runtime/loop-driver.js";
 export { RuntimeRunner, collectText } from "./runtime/runner.js";
 // ── Execution plane + session log (the defaults) ────────────────────────────
 export { LocalExecutionPlane } from "./runtime/execution-plane.js";

package/dist/os/public.d.ts

@@ -1,6 +1,6 @@
 export { DEFAULT_NATIVE_ATTENTION_POLICY, DEFAULT_NATIVE_GOVERNANCE_POLICY, assertNativeProfile, osProfile, } from "../runtime/os-profile.js";
 export type { NativeOsProfile, OsProfileId } from "../runtime/os-profile.js";
-export { rebuildOsSnapshotFromSessionEvents, sessionLogHasRequiredCategories } from "../runtime/os-snapshot.js";
+export { rebuildOsSnapshotFromSessionEvents } from "../runtime/os-snapshot.js";
 export type { OsSnapshot } from "../runtime/os-snapshot.js";
 export type { KernelEventCategory } from "../runtime/kernel-event-log.js";
 export { KernelPrimitivesDashboard } from "../runtime/kernel-primitives-dashboard.js";

package/dist/os/public.js

@@ -1,7 +1,7 @@
 // `@deepstrike/sdk/os` — Agent-OS diagnostics, profiles, signal/permission machinery, replay-testing,
 // and the scheduler/quota/policy types referenced by advanced `RuntimeOptions` fields.
 export { DEFAULT_NATIVE_ATTENTION_POLICY, DEFAULT_NATIVE_GOVERNANCE_POLICY, assertNativeProfile, osProfile, } from "../runtime/os-profile.js";
-export { rebuildOsSnapshotFromSessionEvents, sessionLogHasRequiredCategories } from "../runtime/os-snapshot.js";
+export { rebuildOsSnapshotFromSessionEvents } from "../runtime/os-snapshot.js";
 export { KernelPrimitivesDashboard } from "../runtime/kernel-primitives-dashboard.js";
 // Signals + SDK-side permissions.
 export { ScheduledPrompt } from "../signals/scheduled.js";

package/dist/runtime/facade.js

@@ -15,6 +15,7 @@
 import { RuntimeRunner, collectText } from "./runner.js";
 import { LocalExecutionPlane } from "./execution-plane.js";
 import { InMemorySessionLog } from "./session-log.js";
+import { fanoutSynthesize } from "../types/agent.js";
 /**
  * Run a single agent to completion and return its final text — `RuntimeRunner` + `run` + `collectText`
  * in one call. Register tools by passing `tools`; everything else has a working default.
@@ -46,17 +47,16 @@ export async function runFanout(opts) {
         maxTokens: opts.maxTokens ?? 32_000,
         ...(opts.maxTurns !== undefined ? { maxTurns: opts.maxTurns } : {}),
     });
-    const workerRole = opts.workerRole ?? "explore";
-    const spec = {
-        nodes: [
-            ...opts.tasks.map(task => ({ task, role: workerRole })),
-            {
-                task: opts.synthesize,
-                role: opts.synthesisRole ?? "plan",
-                dependsOn: opts.tasks.map((_, i) => i),
-            },
-        ],
-    };
+    // W-N8: build the spec via the ONE fanout template (it pins the pattern's isolation /
+    // context-inheritance choices — read-only system-only workers, full-context synthesizer — which
+    // this facade used to silently drop), then apply the caller's role overrides on top.
+    const spec = fanoutSynthesize(opts.tasks, opts.synthesize);
+    if (opts.workerRole) {
+        for (const node of spec.nodes.slice(0, opts.tasks.length))
+            node.role = opts.workerRole;
+    }
+    if (opts.synthesisRole)
+        spec.nodes[spec.nodes.length - 1].role = opts.synthesisRole;
     const outcome = await runner.runWorkflow(spec, opts.sessionId ? { sessionId: opts.sessionId } : undefined);
     // The synthesis node is the last spec node; the kernel ids nodes `wf-node{index}`. Prefer that id,
     // but fall back to the last completed node's output so a kernel id-scheme change can't silently

package/dist/runtime/kernel-event-log.d.ts

@@ -3,12 +3,6 @@ import type { SessionEvent } from "./session-log.js";
 /** Agent OS kernel event category (Phase 5). */
 export type KernelEventCategory = "syscall" | "sched" | "mm" | "proc" | "ipc";
 export declare function categoryForKind(kind: string): KernelEventCategory;
-export declare function withCategory<T extends {
-    kind: string;
-}>(event: T): T & {
-    category: KernelEventCategory;
-    primitive: KernelPrimitive;
-};
 type CompressionAction = Extract<SessionEvent, {
     kind: "compressed";
 }>["action"];

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

@@ -22,33 +22,16 @@ export function categoryForKind(kind) {
             return "sched";
     }
 }
-export function withCategory(event) {
-    const category = categoryForKind(event.kind);
-    return {
-        ...event,
-        category,
-        primitive: primitiveForCategory(category),
-    };
-}
 export function kernelObservationToSessionEvent(obs, turn, opts = {}) {
     const t = obs.turn ?? turn;
     const compressionAction = opts.compressionAction ?? (() => undefined);
     switch (obs.kind) {
-        case "page_out":
-            return withCategory({
-                kind: "page_out",
-                turn: t,
-                action: compressionAction(obs.action),
-                summary: obs.summary,
-                tier_hint: obs.tier_hint ?? "durable",
-                message_count: Array.isArray(obs.archived) ? obs.archived.length : 0,
-            });
         case "compressed": {
             const latest = opts.latestSeq ?? -1;
             const start = opts.nextArchiveStart ?? 0;
             if (latest < start)
                 return null;
-            return withCategory({
+            return {
                 kind: "compressed",
                 turn: t,
                 archived_seq_range: [start, latest],
@@ -57,24 +40,24 @@ export function kernelObservationToSessionEvent(obs, turn, opts = {}) {
                 summary_tokens: obs.summary ? Math.max(1, Math.ceil(obs.summary.length / 4)) : undefined,
                 archive_ref: opts.archiveRef,
                 preserved_refs: opts.preservedRefs ?? [],
-            });
+            };
         }
         case "renewed":
-            return withCategory({
+            return {
                 kind: "context_renewed",
                 turn: t,
                 sprint: obs.sprint ?? 0,
                 handoff_ref: "",
-            });
+            };
         case "rollbacked":
-            return withCategory({
+            return {
                 kind: "rollbacked",
                 turn: t,
                 checkpoint_history_len: obs.checkpoint_history_len ?? 0,
                 reason: obs.reason,
-            });
+            };
         case "capability_changed":
-            return withCategory({
+            return {
                 kind: "capability_changed",
                 turn: t,
                 added: obs.added ?? [],
@@ -84,36 +67,48 @@ export function kernelObservationToSessionEvent(obs, turn, opts = {}) {
                 ...(obs.version != null && { version: obs.version }),
                 ...(obs.mounted_by != null && { mounted_by: obs.mounted_by }),
                 ...(obs.mount_reason != null && { mount_reason: obs.mount_reason }),
-            });
+            };
         case "milestone_advanced":
-            return withCategory({
+            return {
                 kind: "milestone_advanced",
                 turn: t,
                 phase_id: obs.phase_id ?? "",
                 capabilities_unlocked: obs.capabilities_unlocked ?? [],
-            });
+            };
         case "milestone_blocked":
-            return withCategory({
+            return {
                 kind: "milestone_blocked",
                 turn: t,
                 phase_id: obs.phase_id ?? "",
                 reason: typeof obs.reason === "string" ? obs.reason : "",
-            });
-        case "milestone_evidence":
-            return withCategory({
-                kind: "milestone_evidence",
-                turn: t,
-                phase_id: obs.phase_id ?? "",
-                evidence: obs.evidence ?? [],
-            });
+            };
         case "checkpoint_taken":
-            return withCategory({
+            return {
                 kind: "checkpoint_taken",
                 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 withCategory({
+            return {
                 kind: "agent_process_changed",
                 turn: t,
                 agent_id: obs.agent_id ?? "",
@@ -126,47 +121,47 @@ export function kernelObservationToSessionEvent(obs, turn, opts = {}) {
                 ...(obs.result_termination
                     ? { result_termination: obs.result_termination }
                     : {}),
-            });
+            };
         case "tool_gated":
-            return withCategory({
+            return {
                 kind: "tool_gated",
                 turn: t,
                 call_id: obs.call_id ?? "",
                 tool: obs.tool ?? "",
                 reason: typeof obs.reason === "string" ? obs.reason : "",
-            });
+            };
         case "signal_disposed":
-            return withCategory({
+            return {
                 kind: "signal_disposed",
                 turn: t,
                 signal_id: obs.signal_id ?? "",
                 disposition: obs.disposition ?? "",
                 queue_depth: obs.queue_depth ?? 0,
-            });
+            };
         case "budget_exceeded":
-            return withCategory({
+            return {
                 kind: "budget_exceeded",
                 turn: t,
                 budget: obs.budget ?? "",
-            });
+            };
         case "suspended":
-            return withCategory({
+            return {
                 kind: "suspended",
                 turn: t,
                 reason: typeof obs.reason === "string" ? obs.reason : "",
                 pending_calls: obs.pending_calls ?? [],
-            });
+            };
         case "resumed":
-            return withCategory({
+            return {
                 kind: "resumed",
                 turn: t,
                 approved: obs.approved ?? [],
                 denied: obs.denied ?? [],
-            });
+            };
         case "page_in_requested":
             return null;
         case "large_result_spooled":
-            return withCategory({
+            return {
                 kind: "large_result_spooled",
                 turn: t,
                 call_id: obs.call_id ?? "",
@@ -174,51 +169,51 @@ export function kernelObservationToSessionEvent(obs, turn, opts = {}) {
                 original_size: obs.original_size ?? 0,
                 preview_size: obs.preview_size ?? 0,
                 spool_ref: opts.spoolRef,
-            });
+            };
         case "memory_written":
-            return withCategory({
+            return {
                 kind: "memory_written",
                 turn: t,
                 memory_id: obs.memory_id ?? "",
                 memory_kind: obs.memory_kind ?? "",
                 size_bytes: obs.size_bytes ?? 0,
-            });
+            };
         case "memory_queried":
-            return withCategory({
+            return {
                 kind: "memory_queried",
                 turn: t,
                 query_context: obs.query_context ?? "",
                 requested_k: obs.requested_k ?? 0,
                 requires_async_response: obs.requires_async_response ?? false,
-            });
+            };
         case "memory_validation_failed":
-            return withCategory({
+            return {
                 kind: "memory_validation_failed",
                 turn: t,
                 memory_id: obs.memory_id ?? "",
                 error: obs.error ?? "",
-            });
+            };
         case "workflow_batch_spawned": {
             // Batch metadata persisted for resume recovery; individual nodes are
             // recorded when they complete (via workflow_node_completed).
             const nodes = obs.nodes ?? [];
-            return withCategory({
+            return {
                 kind: "workflow_batch_spawned",
                 turn: t,
                 node_count: nodes.length,
                 node_ids: nodes.map((n) => n.agent_id ?? ""),
-            });
+            };
         }
         case "workflow_completed": {
             const completed = obs.completed ?? [];
             const failed = obs.failed ?? [];
-            return withCategory({
+            return {
                 kind: "workflow_completed",
                 turn: t,
                 completed,
                 failed,
                 total_nodes: completed.length + failed.length,
-            });
+            };
         }
         default:
             return null;

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;
@@ -11,10 +11,19 @@ export interface KernelRuntimeHandle {
     drainNewMessages(): Message[];
     preservedRefs(): string[];
 }
+export interface PaceDecision {
+    action: "continue" | "sleep" | "stop";
+    delayMs?: number;
+    reason: string;
+    /** Set when the kernel trap coerced the model's proposal (clamped delay / forced stop). */
+    coercedFrom?: string;
+}
 export interface KernelLoopResult {
     termination: string;
     turnsUsed: number;
     totalTokensUsed: number;
+    /** ③ loop-agent: the kernel-adjudicated after-round decision (absent on non-loop runs). */
+    paceDecision?: PaceDecision;
 }
 export type MilestoneVerifierKind = {
     kind: "machine_check";
@@ -105,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>;
@@ -116,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 = {
@@ -240,12 +253,24 @@ function mapKernelAction(raw) {
             };
         case "done": {
             const result = raw.result ?? {};
+            const pace = result.pace_decision;
             return {
                 kind: "done",
                 result: {
                     termination: String(result.termination ?? "error"),
                     turnsUsed: Number(result.turns_used ?? 0),
                     totalTokensUsed: Number(result.total_tokens_used ?? 0),
+                    // ③ loop-agent: the kernel-adjudicated after-round decision (absent on non-loop runs).
+                    ...(pace
+                        ? {
+                            paceDecision: {
+                                action: (pace.action ?? "stop"),
+                                delayMs: pace.delay_ms,
+                                reason: pace.reason ?? "",
+                                coercedFrom: pace.coerced_from,
+                            },
+                        }
+                        : {}),
                 },
             };
         }

package/dist/runtime/loop-driver.d.ts

@@ -0,0 +1,108 @@
+/**
+ * ③ Dynamic loop-agent engineering system — the SDK driver.
+ *
+ * A loop agent is NOT a new execution engine:
+ * - a ROUND is exactly one bounded `RuntimeRunner.run()` (compaction, RepeatFuse,
+ *   criteria gate, and budget verdicts all apply per round for free);
+ * - CONTINUITY is the session log replayed under ONE stable sessionId;
+ * - LIFETIME GOVERNANCE is the RunGroup the rounds are members of;
+ * - the only new decision — what happens AFTER a round — is the model-proposed,
+ *   kernel-adjudicated `pace` verb (see the kernel pacing trap). The kernel never
+ *   sleeps; all timers and judge calls live here, in SDK I/O land.
+ *
+ * Durable pacing: every round appends `round_started` / `round_paced` to the loop's
+ * session log, so `LoopDriver.resume()`-style recovery is a fold over the log
+ * (the SessionLogGroupBudgetStore pattern) — zero new storage. A stateless host
+ * reads `wake_at_ms` from the fold and re-arms via its own cron/queue; an
+ * in-process host lets `run()` sleep inline.
+ */
+import type { RuntimeRunner } from "./runner.js";
+import type { SessionEvent } from "./session-log.js";
+import type { PaceDecision } from "./kernel-step.js";
+import type { StreamEvent } from "../types.js";
+export interface LoopSpec {
+    /** Stable loop id = the ONE session id every round replays (transcript continuity). */
+    loopId: string;
+    goal: string;
+    criteria?: string[];
+    /** Hard round cap; the kernel coerces continue/sleep to stop at the cap. */
+    maxRounds?: number;
+    /** Sleep clamp bounds (ms), enforced in-kernel. */
+    minSleepMs?: number;
+    maxSleepMs?: number;
+    /** "stop" (goal loop, default) | "sleep" (cron loop) when a round never calls pace. */
+    defaultAction?: "stop" | "sleep";
+    /** Cross-round done-gate: judges a stop proposal; a failing verdict overrides
+     *  stop→continue at most `maxVerdictOverrides` times, its feedback becoming the
+     *  next round's steering note. The in-kernel O4 criteria gate is the per-round rung
+     *  of the same ladder — this is the cross-round rung. */
+    verdictFn?: (ctx: {
+        loopId: string;
+        round: number;
+        reason: string;
+    }) => Promise<{
+        pass: boolean;
+        feedback?: string;
+    }> | {
+        pass: boolean;
+        feedback?: string;
+    };
+    maxVerdictOverrides?: number;
+    /** Sleep implementation (injectable for tests / stateless hosts). Default: setTimeout.
+     *  Return `false` to hand the wake to an external scheduler and end `run()` dormant. */
+    sleeper?: (delayMs: number, wakeAtMs: number) => Promise<boolean>;
+    /** Per-round event tap (streaming passthrough). */
+    onEvent?: (round: number, event: StreamEvent) => void;
+}
+export interface LoopOutcome {
+    loopId: string;
+    roundsCompleted: number;
+    stopped: boolean;
+    /** "stopped" | "dormant" (sleeper handed off to an external scheduler) */
+    state: "stopped" | "dormant";
+    lastPace?: PaceDecision;
+    lastStatus?: string;
+    /** Absolute wake time when dormant. */
+    wakeAtMs?: number;
+}
+/** Fold the loop's session log into resumable pacing state — zero new storage. DW-5: the judge's
+ *  override budget folds too, so a crash/restart can't grant the verdictFn fresh overrides. */
+export declare function foldLoopState(events: Array<{
+    seq: number;
+    event: SessionEvent;
+}>): {
+    roundsCompleted: number;
+    pendingWakeAtMs?: number;
+    lastPace?: {
+        action: string;
+        reason: string;
+    };
+    overridesUsed: number;
+};
+/**
+ * DW-6 completion→wake bridge, composed from two existing seams (zero new mechanism): a `sleeper`
+ * that races the timer against an L0 recipient-addressed signal on the shared gateway. Ingest a
+ * signal with `recipient: loopId` (a subagent/workflow completion, a webhook) and the sleeping loop
+ * wakes into its next round immediately — where the SAME queued signal then reaches the model
+ * through the kernel's normal signal path, so the wake reason is visible in-round.
+ */
+export declare function signalAwareSleeper(gateway: {
+    onSignal(listener: (sig: {
+        recipient?: string;
+    }) => void): () => void;
+}, loopId: string): NonNullable<LoopSpec["sleeper"]>;
+export declare class LoopDriver {
+    private readonly runner;
+    private readonly spec;
+    private overridesUsed;
+    constructor(runner: RuntimeRunner, spec: LoopSpec);
+    /**
+     * Drive rounds until the loop stops or goes dormant. Resumable by construction:
+     * the round count and any pending wake are folded from the session log, so
+     * calling `run()` again after a crash / on a stateless host continues in place.
+     */
+    run(): Promise<LoopOutcome>;
+    private sleep;
+}
+/** Facade: run a self-pacing loop agent (joins runAgent/runFanout as an entry point). */
+export declare function runLoop(runner: RuntimeRunner, spec: LoopSpec): Promise<LoopOutcome>;