@deepstrike/sdk 0.2.4 → 0.2.6

package/dist/runtime/large-result-spool.js

@@ -0,0 +1,167 @@
+/**
+ * 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
+ */
+import * as crypto from 'crypto';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+export const DEFAULT_SPOOL_CONFIG = {
+    spoolThresholdBytes: 50 * 1024, // 50KB
+    previewTokens: 500, // ~2KB
+    totalMessageLimitBytes: 200 * 1024, // 200KB
+};
+/**
+ * Large result spool manager.
+ */
+export class LargeResultSpool {
+    config;
+    spoolDir;
+    activeWrites = new Map();
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_SPOOL_CONFIG, ...config };
+        this.spoolDir = config.spoolDir ?? '.spool';
+    }
+    /**
+     * Check if a tool result needs spooling.
+     */
+    needsSpool(result) {
+        return result.output.length > this.config.spoolThresholdBytes;
+    }
+    /**
+     * Hash content for spool reference.
+     */
+    hashContent(content) {
+        return crypto.createHash('sha256').update(content).digest('hex');
+    }
+    /**
+     * Get spool file path for a hash.
+     */
+    getSpoolPath(hash) {
+        return path.join(this.spoolDir, `${hash}.txt`);
+    }
+    /**
+     * Write large result to disk.
+     */
+    async writeToDisk(content, hash) {
+        const spoolPath = this.getSpoolPath(hash);
+        let promise = this.activeWrites.get(spoolPath);
+        if (!promise) {
+            promise = (async () => {
+                try {
+                    await fs.mkdir(this.spoolDir, { recursive: true });
+                    await fs.writeFile(spoolPath, content, 'utf-8');
+                    return spoolPath;
+                }
+                finally {
+                    this.activeWrites.delete(spoolPath);
+                }
+            })();
+            this.activeWrites.set(spoolPath, promise);
+        }
+        return promise;
+    }
+    /**
+     * Generate preview for a tool result.
+     */
+    generatePreview(content) {
+        const previewTokens = Math.min(this.config.previewTokens, content.length / 4);
+        const preview = content.substring(0, previewTokens);
+        const omitted = content.length - previewTokens;
+        return `[tool_result_spooled]
+size: ${content.length} bytes
+preview: first ${previewTokens} chars
+omitted: ${omitted} chars
+[full content available via Read tool]
+`;
+    }
+    /**
+     * Process a tool result: spool if large, return spooled result.
+     */
+    async processToolResult(result) {
+        if (!this.needsSpool(result)) {
+            return {
+                originalOutput: result.output,
+                preview: result.output,
+                spoolRef: '',
+                wasSpooled: false
+            };
+        }
+        // Hash the content
+        const hash = this.hashContent(result.output);
+        // Write to disk
+        const spoolRef = await this.writeToDisk(result.output, hash);
+        // Generate preview
+        const preview = this.generatePreview(result.output);
+        return {
+            originalOutput: result.output,
+            preview,
+            spoolRef,
+            wasSpooled: true
+        };
+    }
+    /**
+     * Persist a kernel-spooled tool output to disk. Returns the on-disk path ref.
+     */
+    async persistOutput(callId, content) {
+        const hash = this.hashContent(content);
+        const spoolPath = this.getSpoolPath(`${callId}-${hash.slice(0, 16)}`);
+        let promise = this.activeWrites.get(spoolPath);
+        if (!promise) {
+            promise = (async () => {
+                try {
+                    await fs.mkdir(this.spoolDir, { recursive: true });
+                    await fs.writeFile(spoolPath, content, 'utf-8');
+                    return spoolPath;
+                }
+                finally {
+                    this.activeWrites.delete(spoolPath);
+                }
+            })();
+            this.activeWrites.set(spoolPath, promise);
+        }
+        return promise;
+    }
+    /**
+     * Read a spooled result back from disk.
+     */
+    async readSpooledResult(spoolRef) {
+        try {
+            const content = await fs.readFile(spoolRef, 'utf-8');
+            return content;
+        }
+        catch (error) {
+            throw new Error(`Failed to read spooled result: ${error}`);
+        }
+    }
+    /**
+     * Clean up old spool files (optional maintenance).
+     */
+    async cleanup(maxAgeMs) {
+        const limit = maxAgeMs ?? this.config.maxAgeMs ?? 7 * 24 * 60 * 60 * 1000;
+        try {
+            const files = await fs.readdir(this.spoolDir);
+            let count = 0;
+            const now = Date.now();
+            for (const file of files) {
+                const filePath = path.join(this.spoolDir, file);
+                const stats = await fs.stat(filePath);
+                if (now - stats.mtimeMs > limit) {
+                    await fs.unlink(filePath);
+                    count++;
+                }
+            }
+            return count;
+        }
+        catch (error) {
+            // Ignore if directory doesn't exist or other file error
+            return 0;
+        }
+    }
+}

package/dist/runtime/os-profile.d.ts

@@ -0,0 +1,30 @@
+import type { GovernancePolicy } from "../governance.js";
+export type OsProfileId = "native";
+export interface NativeOsProfile {
+    id: OsProfileId;
+    attentionPolicy: {
+        maxQueueSize?: number;
+    };
+    governancePolicy: GovernancePolicy;
+}
+/** Default attention policy for native profile smoke tests. */
+export declare const DEFAULT_NATIVE_ATTENTION_POLICY: {
+    maxQueueSize: number;
+};
+/** Permissive governance policy for native runs that do not need AskUser. */
+export declare const DEFAULT_NATIVE_GOVERNANCE_POLICY: GovernancePolicy;
+/** Default restrictive sandbox policy template requiring confirmation for modification/execution. */
+export declare const DEFAULT_SANDBOX_POLICY: GovernancePolicy;
+/** Resolve a named OS profile into concrete kernel-owned policy defaults. */
+export declare function osProfile(profile?: OsProfileId | NativeOsProfile): NativeOsProfile;
+/** Assert that a runtime is using a valid native microkernel policy profile. */
+export declare function assertNativeProfile(profile?: OsProfileId | NativeOsProfile): NativeOsProfile;
+/**
+ * Validates the declarative policies statically to prevent runtime crashes when loaded into the microkernel.
+ */
+export declare function validateDeclarativePolicy(govPolicy?: GovernancePolicy, attentionPolicy?: {
+    maxQueueSize?: number;
+}): {
+    valid: boolean;
+    errors: string[];
+};

package/dist/runtime/os-profile.js

@@ -0,0 +1,71 @@
+/** Default attention policy for native profile smoke tests. */
+export const DEFAULT_NATIVE_ATTENTION_POLICY = { maxQueueSize: 64 };
+/** Permissive governance policy for native runs that do not need AskUser. */
+export const DEFAULT_NATIVE_GOVERNANCE_POLICY = {
+    rules: [{ pattern: "*", action: "allow" }],
+};
+/** Default restrictive sandbox policy template requiring confirmation for modification/execution. */
+export const DEFAULT_SANDBOX_POLICY = {
+    rules: [
+        { pattern: "read_file", action: "allow" },
+        { pattern: "write_file", action: "ask_user" },
+        { pattern: "run_command", action: "ask_user" },
+        { pattern: "*", action: "deny" },
+    ],
+};
+/** Resolve a named OS profile into concrete kernel-owned policy defaults. */
+export function osProfile(profile = "native") {
+    if (typeof profile !== "string")
+        return profile;
+    if (profile !== "native")
+        throw new Error(`Unsupported OS profile: ${profile}`);
+    return {
+        id: "native",
+        attentionPolicy: DEFAULT_NATIVE_ATTENTION_POLICY,
+        governancePolicy: DEFAULT_NATIVE_GOVERNANCE_POLICY,
+    };
+}
+/** Assert that a runtime is using a valid native microkernel policy profile. */
+export function assertNativeProfile(profile = "native") {
+    const resolved = osProfile(profile);
+    if (resolved.id !== "native") {
+        throw new Error(`Unsupported OS profile: ${resolved.id}`);
+    }
+    const validation = validateDeclarativePolicy(resolved.governancePolicy, resolved.attentionPolicy);
+    if (!validation.valid) {
+        throw new Error(`Invalid native OS profile: ${validation.errors.join("; ")}`);
+    }
+    return resolved;
+}
+/**
+ * Validates the declarative policies statically to prevent runtime crashes when loaded into the microkernel.
+ */
+export function validateDeclarativePolicy(govPolicy, attentionPolicy) {
+    const errors = [];
+    if (govPolicy) {
+        if (!Array.isArray(govPolicy.rules)) {
+            errors.push("GovernancePolicy rules must be an array");
+        }
+        else {
+            govPolicy.rules.forEach((rule, idx) => {
+                if (!rule.pattern || typeof rule.pattern !== "string") {
+                    errors.push(`Rule[${idx}] pattern is missing or not a string`);
+                }
+                if (!["allow", "deny", "ask_user"].includes(rule.action)) {
+                    errors.push(`Rule[${idx}] action '${rule.action}' is invalid. Allowed: allow, deny, ask_user`);
+                }
+            });
+        }
+    }
+    if (attentionPolicy) {
+        if (attentionPolicy.maxQueueSize !== undefined) {
+            if (typeof attentionPolicy.maxQueueSize !== "number" || attentionPolicy.maxQueueSize <= 0) {
+                errors.push("AttentionPolicy maxQueueSize must be a positive integer");
+            }
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}

package/dist/runtime/os-snapshot.d.ts

@@ -0,0 +1,35 @@
+import type { SessionEvent } from "./session-log.js";
+export interface OsSnapshot {
+    lastSuspend?: {
+        turn: number;
+        reason: string;
+        pending_calls: string[];
+    };
+    lastResumedTurn?: number;
+    processByAgent: Array<{
+        turn: number;
+        agent_id: string;
+        parent_session_id: string;
+        state: string;
+    }>;
+    budgetExceeded: Array<{
+        turn: number;
+        budget: string;
+    }>;
+    signals: Array<{
+        turn: number;
+        signal_id: string;
+        disposition: string;
+        queue_depth: number;
+    }>;
+    pageOutCount: number;
+    pageInCount: number;
+    spoolCount: number;
+    toolGatedCount: number;
+    memoryWrittenCount: number;
+    memoryQueriedCount: number;
+    memoryValidationFailedCount: number;
+    memoryRetrievalResultCount: number;
+}
+export declare function rebuildOsSnapshotFromSessionEvents(events: SessionEvent[]): OsSnapshot;
+export declare function sessionLogHasRequiredCategories(events: SessionEvent[]): boolean;

package/dist/runtime/os-snapshot.js

@@ -0,0 +1,128 @@
+import { categoryForKind, primitiveForKind } from "./kernel-event-log.js";
+const KERNEL_KINDS = new Set([
+    "compressed",
+    "page_out",
+    "page_in",
+    "large_result_spooled",
+    "capability_changed",
+    "context_renewed",
+    "suspended",
+    "resumed",
+    "tool_gated",
+    "signal_disposed",
+    "budget_exceeded",
+    "checkpoint_taken",
+    "rollbacked",
+    "agent_process_changed",
+    "milestone_advanced",
+    "milestone_blocked",
+    "milestone_evidence",
+    "memory_written",
+    "memory_queried",
+    "memory_validation_failed",
+]);
+export function rebuildOsSnapshotFromSessionEvents(events) {
+    const snap = {
+        processByAgent: [],
+        budgetExceeded: [],
+        signals: [],
+        pageOutCount: 0,
+        pageInCount: 0,
+        spoolCount: 0,
+        toolGatedCount: 0,
+        memoryWrittenCount: 0,
+        memoryQueriedCount: 0,
+        memoryValidationFailedCount: 0,
+        memoryRetrievalResultCount: 0,
+    };
+    const index = new Map();
+    for (const event of events) {
+        if (event.kind === "memory_retrieval_result") {
+            snap.memoryRetrievalResultCount += 1;
+            continue;
+        }
+        if (!KERNEL_KINDS.has(event.kind) && event.kind !== "suspended" && event.kind !== "resumed") {
+            continue;
+        }
+        switch (event.kind) {
+            case "suspended":
+                snap.lastSuspend = {
+                    turn: event.turn,
+                    reason: event.reason,
+                    pending_calls: event.pending_calls ?? [],
+                };
+                break;
+            case "resumed":
+                snap.lastResumedTurn = event.turn;
+                break;
+            case "tool_gated":
+                snap.toolGatedCount += 1;
+                break;
+            case "agent_process_changed": {
+                const record = {
+                    turn: event.turn,
+                    agent_id: event.agent_id,
+                    parent_session_id: event.parent_session_id,
+                    state: event.state ?? "running",
+                };
+                const idx = index.get(event.agent_id);
+                if (idx !== undefined)
+                    snap.processByAgent[idx] = record;
+                else {
+                    index.set(event.agent_id, snap.processByAgent.length);
+                    snap.processByAgent.push(record);
+                }
+                break;
+            }
+            case "budget_exceeded":
+                snap.budgetExceeded.push({ turn: event.turn, budget: event.budget });
+                break;
+            case "signal_disposed":
+                snap.signals.push({
+                    turn: event.turn,
+                    signal_id: event.signal_id,
+                    disposition: event.disposition,
+                    queue_depth: event.queue_depth,
+                });
+                break;
+            case "page_out":
+                snap.pageOutCount += 1;
+                break;
+            case "page_in":
+                snap.pageInCount += 1;
+                break;
+            case "large_result_spooled":
+                snap.spoolCount += 1;
+                break;
+            case "memory_written":
+                snap.memoryWrittenCount += 1;
+                break;
+            case "memory_queried":
+                snap.memoryQueriedCount += 1;
+                break;
+            case "memory_validation_failed":
+                snap.memoryValidationFailedCount += 1;
+                break;
+            default:
+                break;
+        }
+    }
+    return snap;
+}
+export function sessionLogHasRequiredCategories(events) {
+    for (const event of events) {
+        if (!KERNEL_KINDS.has(event.kind))
+            continue;
+        const cat = event.category;
+        if (!cat)
+            return false;
+        if (cat !== categoryForKind(event.kind))
+            return false;
+        const prim = event.primitive;
+        if (prim !== undefined) {
+            if (prim !== primitiveForKind(event.kind))
+                return false;
+        }
+    }
+    return true;
+}

package/dist/runtime/runner.d.ts

@@ -1,12 +1,19 @@
-import type { LLMProvider, Message, ToolSchema, StreamEvent, ToolSuspendEvent, AsyncSummarizer } from "../types.js";
-import type { DreamStore } from "../memory/protocols.js";
+import type { LLMProvider, Message, ToolSchema, StreamEvent, ToolSuspendEvent, PermissionRequestEvent, PermissionResponse, AsyncSummarizer, DreamSummarizer } from "../types.js";
+import type { DreamStore, MemoryEntry, MemoryQuery, MemoryWriteRequest } from "../memory/protocols.js";
 import type { KnowledgeSource } from "../knowledge/source.js";
 import type { SignalSource } from "../signals/types.js";
 import type { SessionLog, SessionEvent } from "./session-log.js";
 import type { ArchiveStore } from "./archive.js";
 import type { ExecutionPlane } from "./execution-plane.js";
+import { type MemoryPolicy, type ResourceQuota } from "../kernel.js";
 import type { AgentRunSpec, MilestoneCheckResult, MilestoneContract, MilestonePolicy } from "../types/agent.js";
 import { type SubAgentOrchestrator } from "./sub-agent-orchestrator.js";
+import { type GovernancePolicy } from "../governance.js";
+import { type NativeOsProfile, type OsProfileId } from "./os-profile.js";
+import { LargeResultSpool } from "./large-result-spool.js";
+export interface SchedulerBudget {
+    maxWallMs?: number;
+}
 export interface RuntimeOptions {
     provider: LLMProvider;
     sessionLog: SessionLog;
@@ -22,18 +29,51 @@ export interface RuntimeOptions {
     knowledgeSource?: KnowledgeSource;
     signalSource?: SignalSource;
     extensions?: Record<string, unknown>;
-    governance?: {
-        setTime?(nowMs: bigint): void;
-        evaluate(name: string, argsJson: string): {
-            kind: string;
-            reason?: string;
-            retryAfterMs?: number;
-        };
+    /** Named or concrete OS profile. Defaults to the native microkernel profile. */
+    osProfile?: OsProfileId | NativeOsProfile;
+    /**
+     * Declarative governance policy loaded into the kernel (`load_governance_policy`).
+     * The kernel enforces deny/veto/rate-limit/param-constraint before tools execute;
+     * AskUser calls surface as `tool_gated` and run through `onPermissionRequest`.
+     */
+    governancePolicy?: GovernancePolicy;
+    /**
+     * Enable in-kernel signal routing (`set_attention_policy`). When set, inbound
+     * signals are dispatched through the kernel attention policy (dedup + disposition
+     * + queue) and surface as `signal_disposed` observations, instead of the legacy
+     * SDK-side router. `maxQueueSize` defaults to 64.
+     */
+    attentionPolicy?: {
+        maxQueueSize?: number;
     };
+    /**
+     * Optional scheduler budget overrides. `maxWallMs` is the wall-clock run budget
+     * in milliseconds; when set, the kernel terminates the run when exceeded.
+     * Other axes (maxTurns, maxTokens) are set via RuntimeOptions directly.
+     */
+    schedulerBudget?: SchedulerBudget;
+    /**
+     * Optional declarative resource quotas (`set_resource_quota`). Bounds spawn concurrency /
+     * nesting depth and memory-write rate at the kernel's single syscall trap. When unset, spawn
+     * and memory-write syscalls are admitted unconditionally (pre-M2 behavior).
+     */
+    resourceQuota?: ResourceQuota;
+    /**
+     * Optional long-term memory policy (`set_memory_policy`). Tunes the kernel's memory subsystem
+     * (retrieval top-k, stale-warning age, write validation, memory path). Unset leaves the kernel
+     * defaults. Enabling memory still requires `dreamStore` + `agentId`.
+     */
+    memoryPolicy?: MemoryPolicy;
     tokenizer?: string;
     enablePlanTool?: boolean;
+    /**
+     * Persist full tool outputs when the kernel emits `large_result_spooled`.
+     * Defaults to `.spool/` under the process cwd.
+     */
+    resultSpool?: LargeResultSpool;
     compressionStore?: ArchiveStore;
     onToolSuspend?: (event: ToolSuspendEvent) => Promise<unknown> | unknown;
+    onPermissionRequest?: (event: PermissionRequestEvent) => Promise<PermissionResponse | boolean> | PermissionResponse | boolean;
     /** Default: terminate — stop with milestone_pending when a phase needs evaluation. */
     milestonePolicy?: MilestonePolicy;
     /** Optional external verifier when milestonePolicy is not auto_pass. */
@@ -59,6 +99,13 @@ export interface RuntimeOptions {
     };
     /** Optional system prompt injected into the dream synthesis call. */
     dreamSystemPrompt?: string;
+    /** Custom LLM provider used for background memory consolidation (dream loop). */
+    dreamProvider?: LLMProvider;
+    /**
+     * Optional LLM summarizer for semantic page_out events. When unset, `dreamProvider`
+     * (or the runtime provider) is used to produce long-term summaries for DreamStore.
+     */
+    dreamSummarizer?: DreamSummarizer;
     /**
      * Optional async LLM summarizer. When provided, a background call is fired
      * after each compression event to produce a richer semantic summary.
@@ -66,6 +113,8 @@ export interface RuntimeOptions {
      * on the next wake() in place of the rule-based summary.
      */
     asyncSummarizer?: AsyncSummarizer;
+    /** Enable real-time CLI diagnostics dashboard grouped by the three kernel primitives (Syscall, Sched, Mm) */
+    enableDiagnosticsDashboard?: boolean;
 }
 export declare class RuntimeRunner {
     private readonly opts;
@@ -74,9 +123,25 @@ export declare class RuntimeRunner {
     private pendingObservations;
     private currentSessionId;
     private nextArchiveStart;
+    /** Full tool outputs keyed by call_id until Layer-1 spool observations are logged. */
+    private pendingSpoolOutputs;
+    /** Local cache of paged-out/archived messages for priority memory retrieval. */
+    private localPageOutCache;
+    private dashboard;
     constructor(opts: RuntimeOptions);
     /** Host configuration (for coordinator / sub-agent spawn). */
     get hostOptions(): RuntimeOptions;
+    writeMemory(memory: MemoryWriteRequest, opts?: {
+        sessionId?: string;
+        agentId?: string;
+    }): Promise<void>;
+    queryMemory(query: MemoryQuery, opts?: {
+        sessionId?: string;
+        agentId?: string;
+    }): Promise<MemoryEntry[]>;
+    private logMemoryRetrievalResult;
+    private createSyscallRuntime;
+    private appendMemorySyscallObservations;
     /** Mount a tool capability on the currently-running kernel runtime. No-op if not running. */
     mountTool(schema: ToolSchema): void;
     /** Mount a skill capability on the currently-running kernel runtime. No-op if not running. */
@@ -85,6 +150,8 @@ export declare class RuntimeRunner {
     mountMarker(kind: string, id: string, description: string): void;
     /** Unmount a capability by kind + id from the active run. No-op if not running. */
     unmountCapability(kind: string, id: string): void;
+    /** Phase 4: satisfy kernel page-in requests before meta-tool execution. */
+    private applyKernelPageIn;
     /** Push content into the Knowledge slot (memory retrievals, skill definitions, artifacts). */
     pushKnowledge(message: Message, tokens?: number): void;
     /**
@@ -106,8 +173,11 @@ export declare class RuntimeRunner {
     }): AsyncIterable<StreamEvent>;
     wake(sessionId: string, extensions?: Record<string, unknown>): AsyncIterable<StreamEvent>;
     dream(agentId: string, nowMs?: number): AsyncIterable<StreamEvent>;
+    /** Resolve in-kernel AskUser suspend; returns resume lists and stream events to yield. */
+    private resolveKernelSuspend;
     private execute;
     private appendObservations;
+    private archiveSemanticPageOut;
     private upgradeCompressedSummary;
 }
 export declare function replayMessages(events: Array<{