@deepstrike/sdk 0.2.4 → 0.2.5

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

@@ -0,0 +1,220 @@
+export function categoryForKind(kind) {
+    switch (kind) {
+        case "tool_gated":
+        case "capability_changed":
+            return "syscall";
+        case "compressed":
+        case "page_out":
+        case "page_in":
+        case "page_in_requested":
+        case "renewed":
+        case "context_renewed":
+        case "large_result_spooled":
+        case "memory_written":
+        case "memory_queried":
+        case "memory_validation_failed":
+            return "mm";
+        case "agent_process_changed":
+            return "proc";
+        case "signal_disposed":
+            return "ipc";
+        default:
+            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({
+                kind: "compressed",
+                turn: t,
+                archived_seq_range: [start, latest],
+                action: compressionAction(obs.action),
+                summary: obs.summary,
+                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({
+                kind: "context_renewed",
+                turn: t,
+                sprint: obs.sprint ?? 0,
+                handoff_ref: "",
+            });
+        case "rollbacked":
+            return withCategory({
+                kind: "rollbacked",
+                turn: t,
+                checkpoint_history_len: obs.checkpoint_history_len ?? 0,
+                reason: obs.reason,
+            });
+        case "capability_changed":
+            return withCategory({
+                kind: "capability_changed",
+                turn: t,
+                added: obs.added ?? [],
+                removed: obs.removed ?? [],
+                ...(obs.change_kind != null && { change_kind: obs.change_kind }),
+                ...(obs.capability_id != null && { capability_id: obs.capability_id }),
+                ...(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({
+                kind: "milestone_advanced",
+                turn: t,
+                phase_id: obs.phase_id ?? "",
+                capabilities_unlocked: obs.capabilities_unlocked ?? [],
+            });
+        case "milestone_blocked":
+            return withCategory({
+                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({
+                kind: "checkpoint_taken",
+                turn: t,
+                history_len: obs.history_len ?? 0,
+            });
+        case "agent_process_changed":
+            return withCategory({
+                kind: "agent_process_changed",
+                turn: t,
+                agent_id: obs.agent_id ?? "",
+                parent_session_id: obs.parent_session_id ?? "",
+                role: obs.role ?? "",
+                isolation: obs.isolation ?? "",
+                context_inheritance: obs.context_inheritance ?? "",
+                state: obs.state ?? "running",
+                permitted_capability_ids: obs.permitted_capability_ids ?? [],
+                ...(obs.result_termination
+                    ? { result_termination: obs.result_termination }
+                    : {}),
+            });
+        case "tool_gated":
+            return withCategory({
+                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({
+                kind: "signal_disposed",
+                turn: t,
+                signal_id: obs.signal_id ?? "",
+                disposition: obs.disposition ?? "",
+                queue_depth: obs.queue_depth ?? 0,
+            });
+        case "budget_exceeded":
+            return withCategory({
+                kind: "budget_exceeded",
+                turn: t,
+                budget: obs.budget ?? "",
+            });
+        case "suspended":
+            return withCategory({
+                kind: "suspended",
+                turn: t,
+                reason: typeof obs.reason === "string" ? obs.reason : "",
+                pending_calls: obs.pending_calls ?? [],
+            });
+        case "resumed":
+            return withCategory({
+                kind: "resumed",
+                turn: t,
+                approved: obs.approved ?? [],
+                denied: obs.denied ?? [],
+            });
+        case "page_in_requested":
+            return null;
+        case "large_result_spooled":
+            return withCategory({
+                kind: "large_result_spooled",
+                turn: t,
+                call_id: obs.call_id ?? "",
+                tool: obs.tool ?? "",
+                original_size: obs.original_size ?? 0,
+                preview_size: obs.preview_size ?? 0,
+                spool_ref: opts.spoolRef,
+            });
+        case "memory_written":
+            return withCategory({
+                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({
+                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({
+                kind: "memory_validation_failed",
+                turn: t,
+                memory_id: obs.memory_id ?? "",
+                error: obs.error ?? "",
+            });
+        default:
+            return null;
+    }
+}
+export function primitiveForCategory(category) {
+    switch (category) {
+        case "syscall":
+            return "syscall";
+        case "mm":
+            return "mm";
+        case "proc":
+        case "ipc":
+        case "sched":
+        default:
+            return "sched";
+    }
+}
+export function primitiveForKind(kind) {
+    return primitiveForCategory(categoryForKind(kind));
+}

package/dist/runtime/kernel-primitives-dashboard.d.ts

@@ -0,0 +1,44 @@
+import type { SessionEvent } from "./session-log.js";
+export interface PrimitivesStats {
+    syscall: {
+        toolGatedCount: number;
+        toolDeniedCount: number;
+        toolCompletedCount: number;
+        capabilityChanges: number;
+    };
+    sched: {
+        turnCount: number;
+        suspendedCount: number;
+        resumedCount: number;
+        signalDisposedCount: number;
+        budgetExceededCount: number;
+        activeProcesses: Set<string>;
+        processState: Map<string, string>;
+        lastSuspendReason: string;
+    };
+    mm: {
+        compressedCount: number;
+        pageOutCount: number;
+        pageInCount: number;
+        largeResultSpooledCount: number;
+        totalSpooledBytes: number;
+        contextRenewedCount: number;
+    };
+}
+export declare class KernelPrimitivesDashboard {
+    private sessionId;
+    private stats;
+    constructor(sessionId: string);
+    /**
+     * Ingest a SessionEvent to update the metrics dashboard.
+     */
+    ingest(event: SessionEvent): void;
+    /**
+     * Return a formatted ANSI terminal dashboard representation.
+     */
+    render(): string;
+    /**
+     * Log the dashboard to the console.
+     */
+    print(): void;
+}

package/dist/runtime/kernel-primitives-dashboard.js

@@ -0,0 +1,135 @@
+import { primitiveForKind } from "./kernel-event-log.js";
+export class KernelPrimitivesDashboard {
+    sessionId;
+    stats = {
+        syscall: {
+            toolGatedCount: 0,
+            toolDeniedCount: 0,
+            toolCompletedCount: 0,
+            capabilityChanges: 0,
+        },
+        sched: {
+            turnCount: 0,
+            suspendedCount: 0,
+            resumedCount: 0,
+            signalDisposedCount: 0,
+            budgetExceededCount: 0,
+            activeProcesses: new Set(),
+            processState: new Map(),
+            lastSuspendReason: "",
+        },
+        mm: {
+            compressedCount: 0,
+            pageOutCount: 0,
+            pageInCount: 0,
+            largeResultSpooledCount: 0,
+            totalSpooledBytes: 0,
+            contextRenewedCount: 0,
+        },
+    };
+    constructor(sessionId) {
+        this.sessionId = sessionId;
+    }
+    /**
+     * Ingest a SessionEvent to update the metrics dashboard.
+     */
+    ingest(event) {
+        const prim = primitiveForKind(event.kind);
+        if ("turn" in event && event.turn !== undefined) {
+            this.stats.sched.turnCount = Math.max(this.stats.sched.turnCount, event.turn);
+        }
+        if (prim === "syscall") {
+            if (event.kind === "tool_gated")
+                this.stats.syscall.toolGatedCount++;
+            else if (event.kind === "tool_denied")
+                this.stats.syscall.toolDeniedCount++;
+            else if (event.kind === "capability_changed")
+                this.stats.syscall.capabilityChanges++;
+        }
+        else if (prim === "sched") {
+            if (event.kind === "suspended") {
+                this.stats.sched.suspendedCount++;
+                this.stats.sched.lastSuspendReason = event.reason;
+            }
+            else if (event.kind === "resumed") {
+                this.stats.sched.resumedCount++;
+            }
+            else if (event.kind === "signal_disposed") {
+                this.stats.sched.signalDisposedCount++;
+            }
+            else if (event.kind === "budget_exceeded") {
+                this.stats.sched.budgetExceededCount++;
+            }
+            else if (event.kind === "agent_process_changed") {
+                const state = event.state ?? "running";
+                this.stats.sched.processState.set(event.agent_id, state);
+                if (state === "running") {
+                    this.stats.sched.activeProcesses.add(event.agent_id);
+                }
+                else {
+                    this.stats.sched.activeProcesses.delete(event.agent_id);
+                }
+            }
+        }
+        else if (prim === "mm") {
+            if (event.kind === "compressed")
+                this.stats.mm.compressedCount++;
+            else if (event.kind === "page_out")
+                this.stats.mm.pageOutCount++;
+            else if (event.kind === "page_in")
+                this.stats.mm.pageInCount++;
+            else if (event.kind === "context_renewed")
+                this.stats.mm.contextRenewedCount++;
+            else if (event.kind === "large_result_spooled") {
+                this.stats.mm.largeResultSpooledCount++;
+                this.stats.mm.totalSpooledBytes += event.original_size;
+            }
+        }
+        // Special handling for tool completion which logs at outer runner
+        if (event.kind === "tool_completed") {
+            this.stats.syscall.toolCompletedCount += event.results.length;
+        }
+    }
+    /**
+     * Return a formatted ANSI terminal dashboard representation.
+     */
+    render() {
+        const esc = (code) => `\x1b[${code}m`;
+        const reset = esc("0");
+        const bold = esc("1");
+        const green = esc("32");
+        const cyan = esc("36");
+        const yellow = esc("33");
+        const magenta = esc("35");
+        const gray = esc("90");
+        const s = this.stats;
+        const header = `${bold}${cyan}╔══════════════════════════════════════════════════════════════════════╗${reset}`;
+        const footer = `${bold}${cyan}╚══════════════════════════════════════════════════════════════════════╝${reset}`;
+        const lines = [
+            header,
+            `${bold}${cyan}║  DeepStrike Kernel Primitives Diagnostics (Session: ${this.sessionId.slice(0, 8)})  ║${reset}`,
+            `${bold}${cyan}╠══════════════════════════════════════════════════════════════════════╣${reset}`,
+            `║ ${bold}${green}🔧 SYSCALL (Security & Host Tools)${reset}                                   ║`,
+            `║   - Tool Gated: ${s.syscall.toolGatedCount.toString().padEnd(10)} - Tool Completed: ${s.syscall.toolCompletedCount.toString().padEnd(10)}          ║`,
+            `║   - Tool Denied: ${s.syscall.toolDeniedCount.toString().padEnd(9)} - Cap. Changes: ${s.syscall.capabilityChanges.toString().padEnd(10)}            ║`,
+            `║                                                                      ║`,
+            `║ ${bold}${yellow}⏰ SCHED (Task Scheduler & Process Table)${reset}                          ║`,
+            `║   - Current Turn: ${s.sched.turnCount.toString().padEnd(9)} - Suspended/Resumed: ${s.sched.suspendedCount}/${s.sched.resumedCount}`.padEnd(70) + "║",
+            `║   - Active Sub-Agents: ${s.sched.activeProcesses.size.toString().padEnd(4)} - Signals Handled: ${s.sched.signalDisposedCount.toString().padEnd(10)}          ║`,
+            `║   - Last Suspend Reason: ${s.sched.lastSuspendReason.slice(0, 35).padEnd(35)}         ║`,
+            `║                                                                      ║`,
+            `║ ${bold}${magenta}💾 MM (Memory Management & Context Paging)${reset}                          ║`,
+            `║   - Compressions: ${s.mm.compressedCount.toString().padEnd(9)} - Page-Outs (Semantic): ${s.mm.pageOutCount.toString().padEnd(10)}       ║`,
+            `║   - Page-Ins (Cache): ${s.mm.pageInCount.toString().padEnd(7)} - Large Spooled: ${s.mm.largeResultSpooledCount.toString().padEnd(14)} ║`,
+            `║   - Total Spooled Bytes: ${(s.mm.totalSpooledBytes / 1024).toFixed(1).toString() + " KB"}`.padEnd(70) + "║",
+            footer
+        ];
+        return lines.join("\n");
+    }
+    /**
+     * Log the dashboard to the console.
+     */
+    print() {
+        console.log(this.render());
+    }
+}

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

@@ -65,13 +65,31 @@ export interface KernelObservation {
     phase_id?: string;
     capabilities_unlocked?: string[];
     evidence?: string[];
-    reason?: RollbackReason;
+    reason?: RollbackReason | string;
     agent_id?: string;
     parent_session_id?: string;
     role?: string;
     isolation?: string;
     context_inheritance?: string;
     permitted_capability_ids?: string[];
+    call_id?: string;
+    tool?: string;
+    signal_id?: string;
+    disposition?: string;
+    queue_depth?: number;
+    budget?: string;
+    pending_calls?: string[];
+    approved?: string[];
+    denied?: string[];
+    tier_hint?: string;
+    memory_id?: string;
+    memory_kind?: string;
+    size_bytes?: number;
+    query_context?: string;
+    requested_k?: number;
+    requires_async_response?: boolean;
+    /** memory_validation_failed (Phase 7). */
+    error?: string;
 }
 export declare function toolSchemaToKernel(schema: ToolSchema): Record<string, unknown>;
 export declare function skillMetadataToKernel(skill: SkillMetadata): Record<string, unknown>;
@@ -85,4 +103,10 @@ export declare function capabilityCommandMount(capability: Record<string, unknow
 export declare function capabilityCommandUnmount(capabilityKind: string, id: string): Record<string, unknown>;
 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;
+/**
+ * Like {@link kernelAction} but tolerates a zero-action step. Used for events
+ * whose outcome may not drive a provider call — e.g. a signal the kernel queues
+ * or ignores returns no action. Returns `null` in that case.
+ */
+export declare function kernelMaybeAction(runtime: KernelRuntimeHandle, pending: KernelObservation[], event: Record<string, unknown>): KernelRunnerAction | null;
 export declare function forceCompact(runtime: KernelRuntimeHandle, pending: KernelObservation[]): boolean;

package/dist/runtime/kernel-step.js

@@ -252,12 +252,21 @@ export function kernelApply(runtime, pending, event) {
     return step.observations;
 }
 export function kernelAction(runtime, pending, event) {
+    const action = kernelMaybeAction(runtime, pending, event);
+    if (!action)
+        throw new Error("kernel transition must return one action");
+    return action;
+}
+/**
+ * Like {@link kernelAction} but tolerates a zero-action step. Used for events
+ * whose outcome may not drive a provider call — e.g. a signal the kernel queues
+ * or ignores returns no action. Returns `null` in that case.
+ */
+export function kernelMaybeAction(runtime, pending, event) {
     const step = parseStep(runtime.step(stepInput(event)));
     pending.push(...step.observations);
     const raw = step.actions[0];
-    if (!raw)
-        throw new Error("kernel transition must return one action");
-    return mapKernelAction(raw);
+    return raw ? mapKernelAction(raw) : null;
 }
 export function forceCompact(runtime, pending) {
     return kernelApply(runtime, pending, { kind: "force_compact" }).some(o => o.kind === "compressed");

package/dist/runtime/large-result-spool.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Large result spool (Layer 1 of 5-layer compression pyramid).
+ *
+ * When a single tool result exceeds 50KB, write the full content to disk
+ * and keep only a 2KB preview in the message. Zero API overhead.
+ *
+ * Design principles:
+ * - Kernel defines policy (thresholds)
+ * - SDK performs I/O (disk write/read)
+ * - Model can retrieve full content via Read tool when needed
+ */
+export interface ToolResult {
+    callId: string;
+    tool: string;
+    output: string;
+    isError?: boolean;
+}
+export interface SpooledToolResult {
+    originalOutput: string;
+    preview: string;
+    spoolRef: string;
+    wasSpooled: boolean;
+}
+/**
+ * Large result spool configuration (mirrors kernel ContextConfig).
+ */
+export interface SpoolConfig {
+    /** Single result size threshold (bytes) */
+    spoolThresholdBytes: number;
+    /** Preview token count (~2KB) */
+    previewTokens: number;
+    /** Total message limit (bytes) */
+    totalMessageLimitBytes: number;
+    /** Custom spool directory path */
+    spoolDir?: string;
+    /** Maximum age of spooled files (default 7 days) */
+    maxAgeMs?: number;
+}
+export declare const DEFAULT_SPOOL_CONFIG: SpoolConfig;
+/**
+ * Large result spool manager.
+ */
+export declare class LargeResultSpool {
+    private config;
+    private spoolDir;
+    private activeWrites;
+    constructor(config?: Partial<SpoolConfig>);
+    /**
+     * Check if a tool result needs spooling.
+     */
+    private needsSpool;
+    /**
+     * Hash content for spool reference.
+     */
+    private hashContent;
+    /**
+     * Get spool file path for a hash.
+     */
+    private getSpoolPath;
+    /**
+     * Write large result to disk.
+     */
+    private writeToDisk;
+    /**
+     * Generate preview for a tool result.
+     */
+    private generatePreview;
+    /**
+     * Process a tool result: spool if large, return spooled result.
+     */
+    processToolResult(result: ToolResult): Promise<SpooledToolResult>;
+    /**
+     * Persist a kernel-spooled tool output to disk. Returns the on-disk path ref.
+     */
+    persistOutput(callId: string, content: string): Promise<string>;
+    /**
+     * Read a spooled result back from disk.
+     */
+    readSpooledResult(spoolRef: string): Promise<string>;
+    /**
+     * Clean up old spool files (optional maintenance).
+     */
+    cleanup(maxAgeMs?: number): Promise<number>;
+}