@deepstrike/sdk 0.2.39 → 0.2.40

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

@@ -1,9 +1,16 @@
 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;
+import type { SessionLog } from "./session-log.js";
+export declare const KERNEL_ABI_VERSION = 2;
 export interface KernelRuntimeHandle {
     step(inputJson: string): string;
+    prepareStep(inputJson: string): string;
+    commitPrepared(prepareToken: string): string;
+    abortPrepared(prepareToken: string): void;
+    snapshot(): string;
+    restore(snapshotJson: string): void;
+    diagnostics(): string;
     isTerminal(): boolean;
     turn(): number;
     recoveryContentBytes(): number;
@@ -11,6 +18,52 @@ export interface KernelRuntimeHandle {
     drainNewMessages(): Message[];
     preservedRefs(): string[];
 }
+export type KernelPreparationStatus = "prepared" | "replayed" | "rejected";
+export interface KernelPreparedStep {
+    status: KernelPreparationStatus;
+    base_generation: number;
+    prepare_token?: string;
+    input: Record<string, unknown>;
+    step: KernelStepJson;
+}
+export interface KernelDiagnostics {
+    lifecycle: string;
+    next_step_seq: number;
+    accepted_input_count: number;
+    accepted_input_bytes: number;
+    snapshot_input_limit: number;
+    snapshot_journal_bytes_limit: number;
+    max_input_bytes: number;
+    snapshot_overflowed: boolean;
+    recorded_event_count: number;
+    completed_effect_count: number;
+    pending_effect_count: number;
+}
+export declare function readKernelDiagnostics(runtime: KernelRuntimeHandle): KernelDiagnostics;
+export interface KernelSnapshot {
+    snapshot_version: 2;
+    abi_version: 2;
+    initial_policy: {
+        max_tokens: number;
+        max_turns: number;
+        max_total_tokens: string;
+        max_wall_ms?: string;
+    };
+    lifecycle: string;
+    operation_id?: string;
+    next_step_seq: number;
+    snapshot_input_limit: number;
+    max_input_bytes: number;
+    snapshot_journal_bytes_limit: number;
+    accepted_input_bytes: number;
+    accepted_inputs: Array<{
+        event_id: string;
+        [key: string]: unknown;
+    }>;
+    last_step?: Record<string, unknown>;
+}
+export declare function snapshotKernelRuntime(runtime: KernelRuntimeHandle): KernelSnapshot;
+export declare function restoreKernelRuntime(runtime: KernelRuntimeHandle, snapshot: KernelSnapshot): void;
 export interface PaceDecision {
     action: "continue" | "sleep" | "stop";
     delayMs?: number;
@@ -39,19 +92,67 @@ export type MilestoneVerifierKind = {
 };
 export type KernelRunnerAction = {
     kind: "call_provider";
+    effectId: string;
     context: RenderedContext;
     tools: ToolSchema[];
 } | {
     kind: "execute_tool";
+    effectId: string;
     calls: ToolCall[];
+} | {
+    kind: "request_approval";
+    effectId: string;
+    requests: Array<{
+        callId: string;
+        tool: string;
+        arguments: string;
+        reason: string;
+    }>;
+} | {
+    kind: "spawn_workflow";
+    effectId: string;
+    nodes: Array<Record<string, unknown>>;
+    budget?: Record<string, unknown>;
+} | {
+    kind: "preempt_sub_agents";
+    effectId: string;
+    agentIds: string[];
+    reason: string;
+} | {
+    kind: "persist_memory";
+    effectId: string;
+    memory: Record<string, unknown>;
+} | {
+    kind: "query_memory";
+    effectId: string;
+    query: Record<string, unknown>;
+    requestedK: number;
+} | {
+    kind: "spool_large_result";
+    effectId: string;
+    callId: string;
+    tool: string;
+    output: string;
+    originalSize: number;
+    previewSize: number;
+} | {
+    kind: "archive_page_out";
+    effectId: string;
+    turn: number;
+    action: string;
+    summary?: string;
+    archived: Message[];
+    tier: string;
 } | {
     kind: "evaluate_milestone";
+    effectId: string;
     phaseId: string;
     criteria: string[];
     verifier?: MilestoneVerifierKind;
     requiredEvidence: string[];
 } | {
     kind: "done";
+    effectId: string;
     result: KernelLoopResult;
 };
 export interface KernelObservation {
@@ -60,7 +161,7 @@ export interface KernelObservation {
     rho_after?: number;
     sprint?: number;
     summary?: string;
-    archived?: Message[];
+    archived_count?: number;
     turn?: number;
     checkpoint_history_len?: number;
     history_len?: number;
@@ -85,20 +186,44 @@ export interface KernelObservation {
     permitted_capability_ids?: string[];
     call_id?: string;
     tool?: string;
+    operation_id?: string;
+    delivery_id?: string;
+    attempt?: number;
     signal_id?: string;
     disposition?: string;
     queue_depth?: number;
     budget?: string;
+    reservation_id?: string;
+    tokens?: number;
+    subagents?: number;
+    rounds?: number;
     pending_calls?: string[];
+    pending_call_ids?: string[];
     approved?: string[];
     denied?: string[];
-    tier_hint?: string;
-    memory_id?: string;
+    tier?: string;
+    message_count?: number;
+    archive_ref?: string;
+    spool_ref?: string;
+    original_size?: number;
+    preview_size?: number;
+    record_id?: string;
+    scope?: {
+        tenant_id: string;
+        namespace: string;
+    };
+    name?: string;
     memory_kind?: string;
     size_bytes?: number;
-    query_context?: string;
+    query?: string;
     requested_k?: number;
     requires_async_response?: boolean;
+    recalls?: Array<{
+        record_id: string;
+        recall_count: number;
+        last_recalled_at: number;
+    }>;
+    recall_count?: number;
     /** memory_validation_failed (Phase 7). */
     error?: string;
     /** workflow_batch_spawned: per-node spawn descriptors (agent_id + goal + role/isolation). */
@@ -112,8 +237,9 @@ export interface KernelObservation {
         trust?: string;
     }>;
     /** workflow_completed. */
-    completed?: string[];
-    failed?: string[];
+    node_outcomes?: import("../types/agent.js").KernelWorkflowNodeOutcome[];
+    /** nodes_rejected. */
+    node_index?: number;
     score?: number;
     score_version?: number;
     rho?: number;
@@ -123,6 +249,19 @@ export interface KernelObservation {
     window_turns?: number;
     threshold?: number;
 }
+export interface KernelStepJson {
+    version: number;
+    operation_id: string;
+    input_event_id: string;
+    step_seq: number;
+    actions: Array<Record<string, unknown>>;
+    observations: KernelObservation[];
+    faults?: Array<{
+        code?: string;
+        message?: string;
+        effect_id?: string;
+    }>;
+}
 export declare function toolSchemaToKernel(schema: ToolSchema): Record<string, unknown>;
 export declare function skillMetadataToKernel(skill: SkillMetadata): Record<string, unknown>;
 export declare function messageToKernelMessage(message: Message): Record<string, unknown>;
@@ -135,6 +274,15 @@ export declare function capabilityCommandMount(capability: Record<string, unknow
 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;
+/**
+ * Execute one production transition behind the durable action-publish gate. Genesis is persisted
+ * before prepare; a newly prepared transaction is CAS-appended before commit; only the committed
+ * step is returned to callers, so actions and observations cannot escape early.
+ */
+export declare function durableKernelStep(runtime: KernelRuntimeHandle, sessionLog: SessionLog, sessionId: string, event: Record<string, unknown>): Promise<KernelStepJson>;
+export declare function durableKernelApply(runtime: KernelRuntimeHandle, sessionLog: SessionLog, sessionId: string, pending: KernelObservation[], event: Record<string, unknown>): Promise<KernelObservation[]>;
+export declare function durableKernelMaybeAction(runtime: KernelRuntimeHandle, sessionLog: SessionLog, sessionId: string, pending: KernelObservation[], event: Record<string, unknown>): Promise<KernelRunnerAction | null>;
+export declare function durableKernelAction(runtime: KernelRuntimeHandle, sessionLog: SessionLog, sessionId: string, pending: KernelObservation[], event: Record<string, unknown>): Promise<KernelRunnerAction>;
 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;
 /**
@@ -143,4 +291,5 @@ export declare function kernelAction(runtime: KernelRuntimeHandle, pending: Kern
  * 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;
+/** Internal ABI-v2 step primitive shared by SDK adapters and conformance tests. */
+export declare function kernelStep(runtime: KernelRuntimeHandle, event: Record<string, unknown>): KernelStepJson;

package/dist/runtime/kernel-step.js

@@ -1,4 +1,26 @@
-export const KERNEL_ABI_VERSION = 1;
+import { createKernelOperationGenesis, createKernelTransaction, kernelRecordDigest, } from "./kernel-transaction-log.js";
+export const KERNEL_ABI_VERSION = 2;
+export function readKernelDiagnostics(runtime) {
+    return JSON.parse(runtime.diagnostics());
+}
+export function snapshotKernelRuntime(runtime) {
+    return JSON.parse(runtime.snapshot());
+}
+export function restoreKernelRuntime(runtime, snapshot) {
+    runtime.restore(JSON.stringify(snapshot));
+    const operationId = snapshot.operation_id;
+    if (!operationId) {
+        kernelWireStates.delete(runtime);
+        return;
+    }
+    const nextEventSequence = snapshot.accepted_inputs.reduce((next, input) => {
+        const match = input.event_id.match(/-event-(\d+)$/);
+        return match ? Math.max(next, Number(match[1]) + 1) : next;
+    }, 1);
+    kernelWireStates.set(runtime, { operationId, nextEventSequence });
+}
+let nextOperationSequence = 1;
+const kernelWireStates = new WeakMap();
 function tryParseJson(s) {
     try {
         return JSON.parse(s);
@@ -223,10 +245,14 @@ function renderedContextToSdk(raw) {
     return ctx;
 }
 function mapKernelAction(raw) {
+    const effectId = String(raw.effect_id ?? "");
+    if (!effectId)
+        throw new Error(`kernel action ${String(raw.kind)} is missing effect_id`);
     switch (raw.kind) {
         case "call_provider":
             return {
                 kind: "call_provider",
+                effectId,
                 context: renderedContextToSdk(raw.context ?? {}),
                 tools: (raw.tools ?? []).map(t => ({
                     name: String(t.name ?? ""),
@@ -237,15 +263,77 @@ function mapKernelAction(raw) {
         case "execute_tool":
             return {
                 kind: "execute_tool",
+                effectId,
                 calls: (raw.calls ?? []).map(c => ({
                     id: String(c.id ?? ""),
                     name: String(c.name ?? ""),
                     arguments: JSON.stringify(c.arguments ?? {}),
                 })),
             };
+        case "request_approval":
+            return {
+                kind: "request_approval",
+                effectId,
+                requests: (raw.requests ?? []).map(request => ({
+                    callId: String(request.call_id ?? ""),
+                    tool: String(request.tool ?? ""),
+                    arguments: JSON.stringify(request.arguments ?? {}),
+                    reason: String(request.reason ?? ""),
+                })),
+            };
+        case "spawn_workflow":
+            return {
+                kind: "spawn_workflow",
+                effectId,
+                nodes: raw.nodes ?? [],
+                ...(raw.budget && typeof raw.budget === "object"
+                    ? { budget: raw.budget }
+                    : {}),
+            };
+        case "preempt_sub_agents":
+            return {
+                kind: "preempt_sub_agents",
+                effectId,
+                agentIds: raw.agent_ids ?? [],
+                reason: String(raw.reason ?? ""),
+            };
+        case "persist_memory":
+            return {
+                kind: "persist_memory",
+                effectId,
+                memory: raw.memory ?? {},
+            };
+        case "query_memory":
+            return {
+                kind: "query_memory",
+                effectId,
+                query: raw.query ?? {},
+                requestedK: Number(raw.requested_k ?? 0),
+            };
+        case "spool_large_result":
+            return {
+                kind: "spool_large_result",
+                effectId,
+                callId: String(raw.call_id ?? ""),
+                tool: String(raw.tool ?? ""),
+                output: String(raw.output ?? ""),
+                originalSize: Number(raw.original_size ?? 0),
+                previewSize: Number(raw.preview_size ?? 0),
+            };
+        case "archive_page_out":
+            return {
+                kind: "archive_page_out",
+                effectId,
+                turn: Number(raw.turn ?? 0),
+                action: String(raw.action ?? "auto_compact"),
+                ...(typeof raw.summary === "string" ? { summary: raw.summary } : {}),
+                archived: (raw.archived ?? []).map(kernelMessageToSdk),
+                tier: String(raw.tier ?? "durable"),
+            };
         case "evaluate_milestone":
             return {
                 kind: "evaluate_milestone",
+                effectId,
                 phaseId: String(raw.phase_id ?? ""),
                 criteria: raw.criteria ?? [],
                 verifier: raw.verifier,
@@ -256,6 +344,7 @@ function mapKernelAction(raw) {
             const pace = result.pace_decision;
             return {
                 kind: "done",
+                effectId,
                 result: {
                     termination: String(result.termination ?? "error"),
                     turnsUsed: Number(result.turns_used ?? 0),
@@ -278,11 +367,131 @@ function mapKernelAction(raw) {
             throw new Error(`unknown KernelAction kind: ${String(raw.kind)}`);
     }
 }
-function stepInput(event) {
-    return JSON.stringify({ version: KERNEL_ABI_VERSION, event });
+function stepInput(runtime, event) {
+    let state = kernelWireStates.get(runtime);
+    if (!state) {
+        state = {
+            operationId: `node-operation-${nextOperationSequence++}`,
+            nextEventSequence: 1,
+        };
+        kernelWireStates.set(runtime, state);
+    }
+    const correlatedEvent = event.kind === "cancel_operation"
+        ? { ...event, operation_id: state.operationId }
+        : event;
+    return JSON.stringify({
+        version: KERNEL_ABI_VERSION,
+        operation_id: state.operationId,
+        event_id: `${state.operationId}-event-${state.nextEventSequence++}`,
+        observed_at_ms: Date.now(),
+        event: correlatedEvent,
+    });
+}
+const durableKernelStates = new WeakMap();
+/**
+ * Execute one production transition behind the durable action-publish gate. Genesis is persisted
+ * before prepare; a newly prepared transaction is CAS-appended before commit; only the committed
+ * step is returned to callers, so actions and observations cannot escape early.
+ */
+export async function durableKernelStep(runtime, sessionLog, sessionId, event) {
+    const inputJson = stepInput(runtime, event);
+    const input = JSON.parse(inputJson);
+    const operationId = String(input.operation_id ?? "");
+    if (!operationId)
+        throw new Error("kernel input is missing operation_id");
+    let durableState = durableKernelStates.get(runtime);
+    if (!durableState) {
+        const snapshot = snapshotKernelRuntime(runtime);
+        const genesis = await createKernelOperationGenesis({
+            abi_version: KERNEL_ABI_VERSION,
+            operation_id: operationId,
+            initial_scheduler_policy: snapshot.initial_policy,
+            resolved_runtime_defaults: {
+                snapshot_version: snapshot.snapshot_version,
+                snapshot_input_limit: snapshot.snapshot_input_limit,
+                max_input_bytes: snapshot.max_input_bytes,
+                snapshot_journal_bytes_limit: snapshot.snapshot_journal_bytes_limit,
+            },
+            default_policy_version: 1,
+        });
+        const receipt = await sessionLog.appendKernelGenesis(sessionId, genesis);
+        durableState = {
+            sessionId,
+            operationId,
+            genesisDigest: receipt.genesis_digest,
+        };
+        durableKernelStates.set(runtime, durableState);
+    }
+    else if (durableState.sessionId !== sessionId || durableState.operationId !== operationId) {
+        throw new Error("kernel runtime cannot change its durable session or operation identity");
+    }
+    const prepared = JSON.parse(runtime.prepareStep(inputJson));
+    if (prepared.status !== "prepared")
+        return prepared.step;
+    const token = prepared.prepare_token;
+    if (!token)
+        throw new Error("prepared kernel transition is missing its commit token");
+    let committed = false;
+    try {
+        const head = await sessionLog.kernelTransactionHead(sessionId, operationId);
+        if (!head)
+            throw new Error("durable kernel genesis is missing before transaction append");
+        const transaction = await createKernelTransaction({
+            operation_id: operationId,
+            step_seq: prepared.step.step_seq,
+            base_generation: prepared.base_generation,
+            input: prepared.input,
+            step: prepared.step,
+            previous_transaction_digest: head,
+        });
+        await sessionLog.compareAndAppendKernelTransaction(sessionId, head, transaction);
+        const committedStep = parseStep(runtime.commitPrepared(token));
+        committed = true;
+        if (kernelRecordDigest(committedStep) !== transaction.step_digest) {
+            throw new Error("committed kernel step does not match the durable prepared step");
+        }
+        return committedStep;
+    }
+    catch (transitionError) {
+        if (!committed) {
+            try {
+                runtime.abortPrepared(token);
+            }
+            catch (abortError) {
+                throw new AggregateError([transitionError, abortError], "durable transition failed and the prepared kernel state could not be aborted");
+            }
+        }
+        throw transitionError;
+    }
+}
+export async function durableKernelApply(runtime, sessionLog, sessionId, pending, event) {
+    const step = await durableKernelStep(runtime, sessionLog, sessionId, event);
+    const fault = step.faults?.[0];
+    if (fault)
+        throw new Error(`${fault.code ?? "kernel_fault"}: ${fault.message ?? "kernel transition failed"}`);
+    pending.push(...step.observations);
+    return step.observations;
+}
+export async function durableKernelMaybeAction(runtime, sessionLog, sessionId, pending, event) {
+    const step = await durableKernelStep(runtime, sessionLog, sessionId, event);
+    const fault = step.faults?.[0];
+    if (fault)
+        throw new Error(`${fault.code ?? "kernel_fault"}: ${fault.message ?? "kernel transition failed"}`);
+    pending.push(...step.observations);
+    const raw = step.actions[0];
+    return raw ? mapKernelAction(raw) : null;
+}
+export async function durableKernelAction(runtime, sessionLog, sessionId, pending, event) {
+    const action = await durableKernelMaybeAction(runtime, sessionLog, sessionId, pending, event);
+    if (!action)
+        throw new Error("kernel transition must return one action");
+    return action;
 }
 export function kernelApply(runtime, pending, event) {
-    const step = parseStep(runtime.step(stepInput(event)));
+    const step = kernelStep(runtime, event);
+    const fault = step.faults?.[0];
+    if (fault)
+        throw new Error(`${fault.code ?? "kernel_fault"}: ${fault.message ?? "kernel transition failed"}`);
     pending.push(...step.observations);
     return step.observations;
 }
@@ -298,11 +507,15 @@ export function kernelAction(runtime, pending, event) {
  * or ignores returns no action. Returns `null` in that case.
  */
 export function kernelMaybeAction(runtime, pending, event) {
-    const step = parseStep(runtime.step(stepInput(event)));
+    const step = kernelStep(runtime, event);
+    const fault = step.faults?.[0];
+    if (fault)
+        throw new Error(`${fault.code ?? "kernel_fault"}: ${fault.message ?? "kernel transition failed"}`);
     pending.push(...step.observations);
     const raw = step.actions[0];
     return raw ? mapKernelAction(raw) : null;
 }
-export function forceCompact(runtime, pending) {
-    return kernelApply(runtime, pending, { kind: "force_compact" }).some(o => o.kind === "compressed");
+/** Internal ABI-v2 step primitive shared by SDK adapters and conformance tests. */
+export function kernelStep(runtime, event) {
+    return parseStep(runtime.step(stepInput(runtime, event)));
 }

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

@@ -0,0 +1,61 @@
+export declare const KERNEL_LOG_RECORD_VERSION: 1;
+export interface KernelOperationGenesisBody {
+    record_version: typeof KERNEL_LOG_RECORD_VERSION;
+    abi_version: number;
+    operation_id: string;
+    initial_scheduler_policy: Record<string, unknown>;
+    resolved_runtime_defaults: Record<string, unknown>;
+    default_policy_version: number;
+}
+export interface KernelOperationGenesis extends KernelOperationGenesisBody {
+    genesis_digest: string;
+}
+export interface KernelTransactionBody {
+    record_version: typeof KERNEL_LOG_RECORD_VERSION;
+    operation_id: string;
+    step_seq: number;
+    base_generation: number;
+    input: Record<string, unknown>;
+    input_digest: string;
+    previous_transaction_digest: string;
+    step_digest: string;
+}
+export interface KernelTransaction extends KernelTransactionBody {
+    transaction_digest: string;
+}
+export interface KernelGenesisReceipt {
+    log_seq: number;
+    genesis_digest: string;
+}
+export interface DurableAppendReceipt {
+    log_seq: number;
+    transaction_digest: string;
+}
+export interface KernelOperationCursor {
+    operation_id: string;
+    next_event_sequence: number;
+    next_step_seq: number;
+    transaction_head_digest: string;
+}
+export declare class KernelLogConflictError extends Error {
+    constructor(message: string);
+}
+export declare class KernelLogIntegrityError extends Error {
+    constructor(message: string);
+}
+export declare function canonicalKernelJson(value: unknown): string;
+export declare function kernelRecordDigest(value: unknown): string;
+export declare function createKernelOperationGenesis(input: Omit<KernelOperationGenesisBody, "record_version">): Promise<KernelOperationGenesis>;
+export declare function createKernelTransaction(input: {
+    operation_id: string;
+    step_seq: number;
+    base_generation: number;
+    input: Record<string, unknown>;
+    step: Record<string, unknown>;
+    previous_transaction_digest: string;
+}): Promise<KernelTransaction>;
+export declare function verifyKernelOperationGenesis(genesis: KernelOperationGenesis): void;
+export declare function verifyKernelTransaction(transaction: KernelTransaction): void;
+export declare function verifyKernelTransactionSuccessor(previous: KernelTransaction | undefined, transaction: KernelTransaction): void;
+/** Validate one complete authoritative operation stream and derive its next wire cursor. */
+export declare function verifyKernelTransactionStream(genesis: KernelOperationGenesis, transactions: readonly KernelTransaction[]): KernelOperationCursor;