@deepstrike/sdk 0.2.3 → 0.2.5

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { RuntimeRunner, collectText } from "./runtime/runner.js";
 export type { RuntimeOptions } from "./runtime/runner.js";
+export { KernelPrimitivesDashboard } from "./runtime/kernel-primitives-dashboard.js";
 export { FilteredExecutionPlane } from "./runtime/filtered-plane.js";
 export { SubAgentOrchestrator, defaultSubAgentOrchestrator, spawnStandalone } from "./runtime/sub-agent-orchestrator.js";
 export type { SubAgentRunContext } from "./runtime/sub-agent-orchestrator.js";
@@ -7,6 +8,11 @@ export { LocalExecutionPlane } from "./runtime/execution-plane.js";
 export type { ExecutionPlane, RunContext } from "./runtime/execution-plane.js";
 export { InMemorySessionLog, FileSessionLog } from "./runtime/session-log.js";
 export type { SessionLog, SessionEvent } from "./runtime/session-log.js";
+export { DEFAULT_NATIVE_ATTENTION_POLICY, DEFAULT_NATIVE_GOVERNANCE_POLICY, } from "./runtime/os-profile.js";
+export { rebuildOsSnapshotFromSessionEvents, sessionLogHasRequiredCategories, } from "./runtime/os-snapshot.js";
+export type { OsSnapshot } from "./runtime/os-snapshot.js";
+export { categoryForKind, kernelObservationToSessionEvent } from "./runtime/kernel-event-log.js";
+export type { KernelEventCategory } from "./runtime/kernel-event-log.js";
 export { NullArchiveStore, FileArchiveStore } from "./runtime/archive.js";
 export type { ArchiveStore } from "./runtime/archive.js";
 export { EnvCredentialVault, InMemoryCredentialVault, ChainedCredentialVault } from "./runtime/credential-vault.js";
@@ -38,19 +44,19 @@ export type { RegisteredTool } from "./tools/index.js";
 export { scanSkillDir, readSkillFile } from "./skills/loader.js";
 export type { SkillMetadata } from "./skills/loader.js";
 export { WorkingMemory } from "./memory/working.js";
-export type { DreamStore, DreamResult, SessionData, SessionMessage, MemoryEntry, CurationResult, CurationStats, } from "./memory/protocols.js";
+export type { DreamStore, DreamResult, SessionData, SessionMessage, MemoryEntry, CurationResult, CurationStats, MemoryWriteRequest, MemoryQuery, MemoryRetrieval, MemoryMetadata, MemoryKind, } from "./memory/protocols.js";
 export type { KnowledgeSource } from "./knowledge/source.js";
 export { ScheduledPrompt } from "./signals/scheduled.js";
 export { SignalGateway } from "./signals/gateway.js";
 export type { RuntimeSignal, SignalSource } from "./signals/types.js";
 export { PermissionManager, PermissionMode } from "./safety/permissions.js";
 export type { PermissionDecision, Permission } from "./safety/permissions.js";
-export { Governance } from "./governance.js";
-export type { GovernanceVerdict } from "./governance.js";
+export { Governance, governancePolicyToKernelEvent } from "./governance.js";
+export type { GovernanceVerdict, GovernancePolicy, GovernanceConstraint } from "./governance.js";
 export { SinglePassHarness, EvalLoopHarness, HarnessLoop } from "./harness/harness.js";
 export type { HarnessRequest, HarnessOutcome, HarnessLoopOptions, QualityGate } from "./harness/harness.js";
-export type { Message, ToolCall, ToolResult, ToolSchema, ContentPart, TextPart, ImagePart, AudioPart, StreamEvent, TextDelta, ThinkingDelta, ToolCallEvent, ToolChunk, ToolDeltaEvent, ToolSuspendEvent, ToolResultEvent, DoneEvent, ErrorEvent, PermissionRequestEvent, LLMProvider, RetryConfig, TokenUsage, ProviderToolSpec, ProviderRunState, ProviderReplay, RenderedContext, } from "./types.js";
-export type { AgentCapabilityFilter, AgentIdentity, AgentIsolation, AgentRunSpec, AgentSpawnedObservation, ContextInheritance, KernelAgentRole, LoopResult, MilestoneCheckResult, MilestoneContract, MilestonePhase, MilestonePolicy, SubAgentResult, TerminationReason, } from "./types/agent.js";
+export type { Message, ToolCall, ToolResult, ToolSchema, ContentPart, TextPart, ImagePart, AudioPart, StreamEvent, TextDelta, ThinkingDelta, ToolCallEvent, ToolChunk, ToolDeltaEvent, ToolSuspendEvent, ToolResultEvent, DoneEvent, ErrorEvent, PermissionRequestEvent, PermissionResolvedEvent, PermissionResponse, LLMProvider, RetryConfig, TokenUsage, ProviderToolSpec, ProviderRunState, ProviderReplay, RenderedContext, } from "./types.js";
+export type { AgentCapabilityFilter, AgentIdentity, AgentIsolation, AgentRunSpec, AgentProcessChangedObservation, ContextInheritance, KernelAgentRole, LoopResult, MilestoneCheckResult, MilestoneContract, MilestonePhase, MilestonePolicy, SubAgentResult, TerminationReason, } from "./types/agent.js";
 export { agentIdentitySub, agentRunSpecToKernel, milestoneCheckFail, milestoneCheckPass, milestoneCheckResultToKernel, subAgentResultToKernel, } from "./types/agent.js";
 export type { AcceptanceCriterion, VerificationContract, ContractCheckResult, } from "./collaboration/contract.js";
 export { ContractBuilder, formatContractForSystemPrompt, contractToCriteriaStrings, } from "./collaboration/contract.js";

package/dist/index.js

@@ -1,9 +1,13 @@
 // ── Runtime (Layer 1.5) ────────────────────────────────────────────────────
 export { RuntimeRunner, collectText } from "./runtime/runner.js";
+export { KernelPrimitivesDashboard } from "./runtime/kernel-primitives-dashboard.js";
 export { FilteredExecutionPlane } from "./runtime/filtered-plane.js";
 export { SubAgentOrchestrator, defaultSubAgentOrchestrator, spawnStandalone } from "./runtime/sub-agent-orchestrator.js";
 export { LocalExecutionPlane } from "./runtime/execution-plane.js";
 export { InMemorySessionLog, FileSessionLog } from "./runtime/session-log.js";
+export { DEFAULT_NATIVE_ATTENTION_POLICY, DEFAULT_NATIVE_GOVERNANCE_POLICY, } from "./runtime/os-profile.js";
+export { rebuildOsSnapshotFromSessionEvents, sessionLogHasRequiredCategories, } from "./runtime/os-snapshot.js";
+export { categoryForKind, kernelObservationToSessionEvent } from "./runtime/kernel-event-log.js";
 export { NullArchiveStore, FileArchiveStore } from "./runtime/archive.js";
 export { EnvCredentialVault, InMemoryCredentialVault, ChainedCredentialVault } from "./runtime/credential-vault.js";
 export { ProcessSandboxPlane } from "./runtime/process-sandbox-plane.js";
@@ -32,7 +36,7 @@ export { ScheduledPrompt } from "./signals/scheduled.js";
 export { SignalGateway } from "./signals/gateway.js";
 // ── Safety & Governance ────────────────────────────────────────────────────
 export { PermissionManager, PermissionMode } from "./safety/permissions.js";
-export { Governance } from "./governance.js";
+export { Governance, governancePolicyToKernelEvent } from "./governance.js";
 // ── Harness ────────────────────────────────────────────────────────────────
 export { SinglePassHarness, EvalLoopHarness, HarnessLoop } from "./harness/harness.js";
 export { agentIdentitySub, agentRunSpecToKernel, milestoneCheckFail, milestoneCheckPass, milestoneCheckResultToKernel, subAgentResultToKernel, } from "./types/agent.js";

package/dist/memory/agent.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Long-term memory agent implementation (Phase 7).
+ *
+ * Provides two main capabilities:
+ * 1. Extract memories from conversation transcripts (后台代理)
+ * 2. Select relevant memories for current context (LLM选择器)
+ *
+ * Design principles:
+ * - Kernel defines memory types and validation rules
+ * - SDK performs I/O and selection
+ * - LLM (Sonnet) acts as selector, not vector similarity
+ */
+import type { SessionData, MemoryEntry } from "./protocols.js";
+/**
+ * Memory metadata (matches kernel MemoryMetadata structure).
+ */
+export interface MemoryMetadata {
+    name: string;
+    description: string;
+    kind?: MemoryKind;
+    created_at: number;
+    updated_at: number;
+    session_id?: string;
+    user_role?: string;
+    expertise_level?: string;
+    preference_rule?: string;
+    approved_pattern?: string;
+    project_phase?: string;
+    relative_date?: string;
+    external_url?: string;
+    ticket_ref?: string;
+}
+/**
+ * Memory kind (4 types, mirroring Claude Code).
+ */
+export type MemoryKind = "user" | "feedback" | "project" | "reference";
+/**
+ * Memory write request (SDK → kernel).
+ */
+export interface MemoryWriteRequest {
+    metadata: MemoryMetadata;
+    content: string;
+}
+/**
+ * Memory query request (kernel → SDK).
+ */
+export interface MemoryQuery {
+    current_context: string;
+    active_tools: string[];
+    already_surfaced: string[];
+    top_k: number;
+}
+/**
+ * Memory retrieval response (SDK → kernel).
+ */
+export interface MemoryRetrieval {
+    selected_memory_ids: string[];
+    selection_rationale: string;
+}
+/**
+ * Memory index entry (from MEMORY.md).
+ */
+export interface MemoryIndexEntry {
+    name: string;
+    description: string;
+    kind?: MemoryKind;
+    file: string;
+    updated_at: number;
+}
+/**
+ * Extract memories from a completed session.
+ *
+ * This is typically called by a background agent after a session completes.
+ * It analyzes the conversation and generates new memory write requests.
+ *
+ * @param sessionData - The completed session data
+ * @param existingMemories - Existing memories to avoid duplicates
+ * @returns Array of memory write requests
+ */
+export declare function extractMemories(sessionData: SessionData, existingMemories: MemoryEntry[]): Promise<MemoryWriteRequest[]>;
+/**
+ * Select relevant memories for the current context.
+ *
+ * This uses an LLM (Sonnet) as a selector, not vector similarity.
+ * The process:
+ * 1. Read memory index (name + description for each memory)
+ * 2. Filter out already_surfaced and recentTools
+ * 3. Send the filtered list to LLM with current context
+ * 4. LLM returns top-5 most relevant memory IDs
+ *
+ * @param query - Memory query from kernel
+ * @param memoryIndex - Memory index entries
+ * @param model - Optional model name (default: claude-sonnet-4-20250514)
+ * @returns Memory retrieval result
+ */
+export declare function selectMemories(query: MemoryQuery, memoryIndex: MemoryIndexEntry[], model?: string): Promise<MemoryRetrieval>;
+/**
+ * Validate memory before writing (kernel-side validation mirror).
+ *
+ * This SDK-side validation provides early feedback before sending to kernel.
+ */
+export declare function validateMemory(request: MemoryWriteRequest): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Infer memory kind from metadata (mirrors kernel logic).
+ */
+export declare function inferMemoryKind(metadata: MemoryMetadata): MemoryKind;
+/** Build a memory index from DreamStore entries for {@link selectMemories}. */
+export declare function memoriesToIndex(entries: MemoryEntry[]): MemoryIndexEntry[];

package/dist/memory/agent.js

@@ -0,0 +1,151 @@
+/**
+ * Long-term memory agent implementation (Phase 7).
+ *
+ * Provides two main capabilities:
+ * 1. Extract memories from conversation transcripts (后台代理)
+ * 2. Select relevant memories for current context (LLM选择器)
+ *
+ * Design principles:
+ * - Kernel defines memory types and validation rules
+ * - SDK performs I/O and selection
+ * - LLM (Sonnet) acts as selector, not vector similarity
+ */
+/**
+ * Extract memories from a completed session.
+ *
+ * This is typically called by a background agent after a session completes.
+ * It analyzes the conversation and generates new memory write requests.
+ *
+ * @param sessionData - The completed session data
+ * @param existingMemories - Existing memories to avoid duplicates
+ * @returns Array of memory write requests
+ */
+export async function extractMemories(sessionData, existingMemories) {
+    // In a real implementation, this would:
+    // 1. Use an LLM to analyze the session transcript
+    // 2. Identify new insights, preferences, and context
+    // 3. Generate memory write requests with proper classification
+    // 4. Check for duplicates against existing memories
+    // For now, return a stub implementation
+    return [];
+}
+/**
+ * Select relevant memories for the current context.
+ *
+ * This uses an LLM (Sonnet) as a selector, not vector similarity.
+ * The process:
+ * 1. Read memory index (name + description for each memory)
+ * 2. Filter out already_surfaced and recentTools
+ * 3. Send the filtered list to LLM with current context
+ * 4. LLM returns top-5 most relevant memory IDs
+ *
+ * @param query - Memory query from kernel
+ * @param memoryIndex - Memory index entries
+ * @param model - Optional model name (default: claude-sonnet-4-20250514)
+ * @returns Memory retrieval result
+ */
+export async function selectMemories(query, memoryIndex, model = "claude-sonnet-4-20250514") {
+    // 1. Filter out already surfaced and tool-related memories
+    const filterOut = new Set([
+        ...query.already_surfaced,
+        ...query.active_tools,
+    ]);
+    const candidates = memoryIndex.filter((entry) => !filterOut.has(entry.name) && !isToolMemory(entry));
+    // 2. If no candidates, return empty
+    if (candidates.length === 0) {
+        return {
+            selected_memory_ids: [],
+            selection_rationale: "No candidates after filtering",
+        };
+    }
+    // 3. In a real implementation, this would:
+    // - Construct a prompt with current context and memory descriptions
+    // - Call the LLM API
+    // - Parse the response to extract selected memory IDs
+    // For now, return a stub implementation
+    return {
+        selected_memory_ids: candidates.slice(0, query.top_k).map((c) => c.name),
+        selection_rationale: "Stub implementation",
+    };
+}
+/**
+ * Check if a memory is tool-related (should be filtered from recentTools).
+ */
+function isToolMemory(entry) {
+    const toolKeywords = ["usage", "how to use", "example", "syntax", "api"];
+    const lowerDesc = entry.description.toLowerCase();
+    const lowerName = entry.name.toLowerCase();
+    // Filter out usage docs, but keep warnings/caveats
+    const isUsage = toolKeywords.some((kw) => lowerDesc.includes(kw) || lowerName.includes(kw));
+    const isWarning = lowerDesc.includes("warning") || lowerDesc.includes("caveat") || lowerDesc.includes("bug");
+    return isUsage && !isWarning;
+}
+/**
+ * Validate memory before writing (kernel-side validation mirror).
+ *
+ * This SDK-side validation provides early feedback before sending to kernel.
+ */
+export function validateMemory(request) {
+    // Check required fields
+    if (!request.metadata.name || request.metadata.name.trim().length === 0) {
+        return { valid: false, error: "Missing required field: name" };
+    }
+    if (!request.metadata.description || request.metadata.description.trim().length === 0) {
+        return { valid: false, error: "Missing required field: description" };
+    }
+    // Check name length
+    if (request.metadata.name.length > 100) {
+        return { valid: false, error: `Name too long: ${request.metadata.name.length} chars (limit: 100)` };
+    }
+    // Check content size
+    if (request.content.length > 10_000) {
+        return { valid: false, error: `Content too large: ${request.content.length} bytes (limit: 10000)` };
+    }
+    // Check forbidden patterns
+    const forbiddenPatterns = [
+        { pattern: "代码模式:", reason: "应从代码推，不应存储" },
+        { pattern: "文件路径:", reason: "应从git推，不应存储" },
+        { pattern: "架构:", reason: "应从实际代码推" },
+        { pattern: "git历史:", reason: "git log是权威" },
+        { pattern: "CLAUDE.md:", reason: "已在文档中" },
+        { pattern: "TODO:", reason: "临时任务不应进记忆" },
+    ];
+    for (const { pattern, reason } of forbiddenPatterns) {
+        if (request.content.includes(pattern)) {
+            return { valid: false, error: `Forbidden pattern '${pattern}': ${reason}` };
+        }
+    }
+    return { valid: true };
+}
+/**
+ * Infer memory kind from metadata (mirrors kernel logic).
+ */
+export function inferMemoryKind(metadata) {
+    if (metadata.user_role || metadata.expertise_level) {
+        return "user";
+    }
+    if (metadata.preference_rule || metadata.approved_pattern) {
+        return "feedback";
+    }
+    if (metadata.project_phase || metadata.relative_date) {
+        return "project";
+    }
+    if (metadata.external_url || metadata.ticket_ref) {
+        return "reference";
+    }
+    // Default: feedback (most common)
+    return "feedback";
+}
+/** Build a memory index from DreamStore entries for {@link selectMemories}. */
+export function memoriesToIndex(entries) {
+    return entries.map(entry => {
+        const meta = (entry.metadata ?? {});
+        return {
+            name: String(meta.name ?? entry.text.slice(0, 40)),
+            description: String(meta.description ?? entry.text.slice(0, 120)),
+            kind: meta.kind,
+            file: String(meta.file ?? ""),
+            updated_at: Number(meta.updated_at ?? 0),
+        };
+    });
+}

package/dist/memory/protocols.d.ts

@@ -45,6 +45,62 @@ export interface DreamStore {
     /** Persist a completed session for future consolidation via `Agent.dream()`. */
     saveSession(data: SessionData): Promise<void>;
 }
+/** Memory kind (4 types, mirroring Claude Code). */
+export type MemoryKind = "user" | "feedback" | "project" | "reference";
+/** Memory metadata (kernel stores, SDK provides full content). */
+export interface MemoryMetadata {
+    name: string;
+    description: string;
+    kind?: MemoryKind;
+    created_at: number;
+    updated_at: number;
+    session_id?: string;
+    user_role?: string;
+    expertise_level?: string;
+    preference_rule?: string;
+    approved_pattern?: string;
+    project_phase?: string;
+    relative_date?: string;
+    external_url?: string;
+    ticket_ref?: string;
+}
+/** Memory write request (SDK → kernel). */
+export interface MemoryWriteRequest {
+    metadata: MemoryMetadata;
+    content: string;
+}
+/** Memory query request (kernel → SDK). */
+export interface MemoryQuery {
+    current_context: string;
+    active_tools: string[];
+    already_surfaced: string[];
+    top_k: number;
+}
+/** Memory retrieval response (SDK → kernel). */
+export interface MemoryRetrieval {
+    selected_memory_ids: string[];
+    selection_rationale: string;
+}
+/** Memory validation error (mirroring kernel MemoryValidationError). */
+export type MemoryValidationError = {
+    error_kind: "missing_required_field";
+    field: string;
+} | {
+    error_kind: "content_too_large";
+    size: number;
+    limit: number;
+} | {
+    error_kind: "forbidden_pattern";
+    pattern: string;
+    reason: string;
+} | {
+    error_kind: "invalid_kind";
+    kind: string;
+} | {
+    error_kind: "name_too_long";
+    length: number;
+    limit: number;
+};
 /** Durable transcript storage for same-session conversational continuity. */
 export interface DreamResult {
     sessionsProcessed: number;

package/dist/providers/deepseek.js

@@ -35,17 +35,27 @@ export class DeepSeekProvider extends OpenAIChatProvider {
         let finalText = "";
         const stream = await this.client.chat.completions.create({
             ...omitExtensionKeys(extensions, [
-                "model", "messages", "tools", "stream", "extra_body", "reasoning_effort",
+                "model", "messages", "tools", "stream", "stream_options", "extra_body", "reasoning_effort",
                 "exposeReasoning", "thinking", "reasoningEffort",
             ]),
             model: this.model,
             messages: msgs,
             ...(tools.length ? { tools: this.chat.buildTools(tools) } : {}),
             stream: true,
+            stream_options: { include_usage: true },
             reasoning_effort: reasoningEffort,
             extra_body: { thinking: { type: thinking } },
         });
+        let totalTokens = 0;
+        let inputTokens = 0;
+        let outputTokens = 0;
         for await (const chunk of stream) {
+            if (chunk.usage) {
+                totalTokens = chunk.usage.total_tokens;
+                inputTokens = chunk.usage.prompt_tokens ?? 0;
+                outputTokens = chunk.usage.completion_tokens ?? 0;
+                continue;
+            }
             const choice = chunk.choices[0];
             if (!choice)
                 continue;
@@ -110,5 +120,7 @@ export class DeepSeekProvider extends OpenAIChatProvider {
             emittedToolCallIndexes.add(idx);
             yield { type: "tool_call", id: tb.id, name: tb.name, arguments: args };
         }
+        if (totalTokens > 0)
+            yield { type: "usage", totalTokens, inputTokens, outputTokens };
     }
 }

package/dist/runtime/execution-plane.d.ts

@@ -1,21 +1,16 @@
-import type { ToolCall, ToolSchema, StreamEvent, ToolSuspendEvent } from "../types.js";
+import type { ToolCall, ToolSchema, StreamEvent, ToolSuspendEvent, PermissionRequestEvent, PermissionResponse } from "../types.js";
 import type { RegisteredTool } from "../tools/index.js";
 import type { DreamStore } from "../memory/protocols.js";
 import type { KnowledgeSource } from "../knowledge/source.js";
+import { LargeResultSpool } from "./large-result-spool.js";
 export interface RunContext {
     agentId?: string;
     skillDir?: string;
     dreamStore?: DreamStore;
     knowledgeSource?: KnowledgeSource;
-    governance?: {
-        setTime?(nowMs: bigint): void;
-        evaluate(name: string, argsJson: string): {
-            kind: string;
-            reason?: string;
-            retryAfterMs?: number;
-        };
-    };
     onToolSuspend?: (event: ToolSuspendEvent) => Promise<unknown> | unknown;
+    onPermissionRequest?: (event: PermissionRequestEvent) => Promise<PermissionResponse | boolean> | PermissionResponse | boolean;
+    resultSpool?: LargeResultSpool;
 }
 export interface ExecutionPlane {
     register(...tools: RegisteredTool[]): this;
@@ -34,5 +29,7 @@ export declare class LocalExecutionPlane implements ExecutionPlane {
     unregister(name: string): this;
     schemas(): ToolSchema[];
     executeAll(calls: ToolCall[], ctx: RunContext): AsyncIterable<StreamEvent>;
+    private tryReadSpooledArgument;
     private executeSingle;
 }
+export declare function resolvePermissionRequest(request: PermissionRequestEvent, ctx: RunContext): Promise<PermissionResponse>;

package/dist/runtime/execution-plane.js

@@ -1,5 +1,6 @@
 import { isAsyncIterable, normalizeToolChunk, toolChunkText, validateToolArguments } from "../tools/index.js";
 import { readSkillFile } from "../skills/loader.js";
+import { LargeResultSpool } from "./large-result-spool.js";
 export class LocalExecutionPlane {
     tools = new Map();
     register(...tools) {
@@ -15,31 +16,7 @@ export class LocalExecutionPlane {
         return Array.from(this.tools.values()).map(t => t.schema);
     }
     async *executeAll(calls, ctx) {
-        // Governance pass — denied calls get an immediate tool_result so the kernel always
-        // receives a result for every call it dispatched.
-        const permitted = [];
-        for (const c of calls) {
-            if (ctx.governance) {
-                ctx.governance.setTime?.(BigInt(Date.now()));
-                const v = ctx.governance.evaluate(c.name, c.arguments);
-                if (v.kind === "deny") {
-                    yield { type: "tool_denied", callId: c.id, toolName: c.name, reason: v.reason ?? "" };
-                    yield { type: "tool_result", callId: c.id, name: c.name, content: `permission denied: ${v.reason ?? ""}`, isError: true };
-                    continue;
-                }
-                if (v.kind === "rate_limited") {
-                    yield { type: "error", message: `rate limited: ${c.name}` };
-                    yield { type: "tool_result", callId: c.id, name: c.name, content: "rate limited", isError: true };
-                    continue;
-                }
-                if (v.kind === "ask_user") {
-                    yield { type: "permission_request", callId: c.id, toolName: c.name, arguments: c.arguments, reason: v.reason ?? "" };
-                    yield { type: "tool_result", callId: c.id, name: c.name, content: "awaiting user approval", isError: true };
-                    continue;
-                }
-            }
-            permitted.push(c);
-        }
+        const permitted = calls;
         const skillCalls = permitted.filter(c => c.name === "skill");
         const memoryCalls = permitted.filter(c => c.name === "memory");
         const knowledgeCalls = permitted.filter(c => c.name === "knowledge");
@@ -98,7 +75,30 @@ export class LocalExecutionPlane {
             }
         }
     }
+    async tryReadSpooledArgument(call, ctx) {
+        const isReadTool = ["read", "read_file", "view_file", "read_spooled_result"].includes(call.name);
+        if (!isReadTool)
+            return null;
+        try {
+            const args = JSON.parse(call.arguments || "{}");
+            for (const val of Object.values(args)) {
+                if (typeof val === "string" && (val.startsWith(".spool/") || val.includes("/.spool/"))) {
+                    const spool = ctx.resultSpool ?? new LargeResultSpool();
+                    const content = await spool.readSpooledResult(val);
+                    return content;
+                }
+            }
+        }
+        catch {
+            // Ignore errors
+        }
+        return null;
+    }
     async *executeSingle(call, ctx) {
+        const spooledContent = await this.tryReadSpooledArgument(call, ctx);
+        if (spooledContent !== null) {
+            return { callId: call.id, output: spooledContent, isError: false };
+        }
         const registered = this.tools.get(call.name);
         if (!registered)
             return { callId: call.id, output: `unknown tool: ${call.name}`, isError: true };
@@ -168,3 +168,31 @@ function tryParseJson(s) {
         return null;
     }
 }
+export async function resolvePermissionRequest(request, ctx) {
+    if (!ctx.onPermissionRequest) {
+        return {
+            approved: false,
+            responder: "policy_gate",
+            reason: "no permission handler configured",
+        };
+    }
+    try {
+        return normalizePermissionDecision(await ctx.onPermissionRequest(request));
+    }
+    catch (err) {
+        return {
+            approved: false,
+            responder: "permission_handler",
+            reason: `permission handler failed: ${String(err)}`,
+        };
+    }
+}
+function normalizePermissionDecision(value) {
+    if (typeof value === "boolean")
+        return { approved: value, responder: "host" };
+    return {
+        approved: Boolean(value.approved),
+        responder: value.responder ?? "host",
+        ...(value.reason ? { reason: value.reason } : {}),
+    };
+}

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

@@ -0,0 +1,26 @@
+import type { KernelObservation } from "./kernel-step.js";
+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"];
+export declare function kernelObservationToSessionEvent(obs: KernelObservation, turn: number, opts?: {
+    nextArchiveStart?: number;
+    latestSeq?: number;
+    archiveRef?: string;
+    preservedRefs?: string[];
+    compressionAction?: (action?: string) => CompressionAction;
+    spoolRef?: string;
+}): SessionEvent | null;
+export type KernelPrimitive = "syscall" | "sched" | "mm";
+export declare function primitiveForCategory(category: KernelEventCategory): KernelPrimitive;
+export declare function primitiveForKind(kind: string): KernelPrimitive;
+export {};