@lumenflow/kernel 3.0.0

package/dist/runtime/kernel-runtime.js

@@ -0,0 +1,751 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+import { randomBytes } from 'node:crypto';
+import { access, mkdir, open, readFile, rm } from 'node:fs/promises';
+import path from 'node:path';
+import YAML from 'yaml';
+import { z } from 'zod';
+import { canonical_json } from '../canonical-json.js';
+import { KERNEL_EVENT_KINDS, TOOL_TRACE_KINDS, isRunLifecycleEventKind, } from '../event-kinds.js';
+import { EXECUTION_METADATA_KEYS, KERNEL_POLICY_IDS, KERNEL_RUNTIME_EVENTS_DIR_NAME, KERNEL_RUNTIME_EVENTS_FILE_NAME, KERNEL_RUNTIME_EVENTS_LOCK_FILE_NAME, KERNEL_RUNTIME_EVIDENCE_DIR_NAME, KERNEL_RUNTIME_ROOT_DIR_NAME, KERNEL_RUNTIME_TASKS_DIR_NAME, LUMENFLOW_DIR_NAME, LUMENFLOW_SCOPE_NAME, PACKAGES_DIR_NAME, PACKS_DIR_NAME, UTF8_ENCODING, WORKSPACE_CONFIG_HASH_CONTEXT_KEYS, WORKSPACE_FILE_NAME, } from '../shared-constants.js';
+import { EventStore, projectTaskState, } from '../event-store/index.js';
+import { EvidenceStore } from '../evidence/evidence-store.js';
+import { ExecutionContextSchema, RUN_STATUSES, RunSchema, TOOL_HANDLER_KINDS, TaskSpecSchema, WorkspaceSpecSchema, } from '../kernel.schemas.js';
+import { PackLoader, resolvePackToolEntryPath } from '../pack/index.js';
+import { POLICY_TRIGGERS, PolicyEngine, } from '../policy/index.js';
+import { SandboxSubprocessDispatcher, } from '../sandbox/index.js';
+import { assertTransition } from '../state-machine/index.js';
+import { createBuiltinPolicyHook, registerBuiltinToolCapabilities, } from '../tool-host/builtins/index.js';
+import { ToolHost } from '../tool-host/tool-host.js';
+import { ToolRegistry } from '../tool-host/tool-registry.js';
+const DEFAULT_RUNTIME_ROOT = path.join(LUMENFLOW_DIR_NAME, KERNEL_RUNTIME_ROOT_DIR_NAME);
+const DEFAULT_PACKS_ROOT_CANDIDATES = [
+    PACKS_DIR_NAME,
+    path.join(PACKAGES_DIR_NAME, LUMENFLOW_SCOPE_NAME, PACKS_DIR_NAME),
+];
+const DEFAULT_PACK_TOOL_INPUT_SCHEMA = z.record(z.string(), z.unknown());
+const DEFAULT_PACK_TOOL_OUTPUT_SCHEMA = z.record(z.string(), z.unknown());
+const RUNTIME_LOAD_STAGE_ERROR_PREFIX = 'Runtime load stage failed for pack';
+const RUNTIME_REGISTRATION_STAGE_ERROR_PREFIX = 'Runtime registration stage failed for tool';
+const WORKSPACE_UPDATED_INIT_SUMMARY = 'Workspace config hash initialized during runtime startup.';
+const SPEC_TAMPERED_ERROR_CODE = 'SPEC_TAMPERED';
+const SPEC_TAMPERED_WORKSPACE_MESSAGE = 'Workspace configuration hash mismatch detected; execution blocked.';
+const SPEC_TAMPERED_WORKSPACE_MISSING_MESSAGE = 'Workspace configuration file is missing; execution blocked.';
+function normalizeTimestamp(now, inputTimestamp) {
+    return inputTimestamp ?? now().toISOString();
+}
+export function defaultRunIdFactory(taskId, nextRunNumber) {
+    const suffix = randomBytes(4).toString('hex');
+    return `run-${taskId}-${nextRunNumber}-${suffix}`;
+}
+function isRunLifecycleEvent(event) {
+    return isRunLifecycleEventKind(event.kind);
+}
+function buildRunHistory(events) {
+    const sortedEvents = [...events].sort((left, right) => {
+        return Date.parse(left.timestamp) - Date.parse(right.timestamp);
+    });
+    const byRun = new Map();
+    for (const event of sortedEvents) {
+        if (!isRunLifecycleEvent(event)) {
+            continue;
+        }
+        const existing = byRun.get(event.run_id);
+        if (event.kind === KERNEL_EVENT_KINDS.RUN_STARTED) {
+            byRun.set(event.run_id, RunSchema.parse({
+                run_id: event.run_id,
+                task_id: event.task_id,
+                status: RUN_STATUSES.EXECUTING,
+                started_at: event.timestamp,
+                by: event.by,
+                session_id: event.session_id,
+            }));
+            continue;
+        }
+        const fallback = existing ??
+            RunSchema.parse({
+                run_id: event.run_id,
+                task_id: event.task_id,
+                status: RUN_STATUSES.PLANNED,
+                started_at: event.timestamp,
+                by: 'unknown',
+                session_id: 'unknown',
+            });
+        if (event.kind === KERNEL_EVENT_KINDS.RUN_PAUSED) {
+            byRun.set(event.run_id, RunSchema.parse({
+                ...fallback,
+                status: RUN_STATUSES.PAUSED,
+            }));
+            continue;
+        }
+        if (event.kind === KERNEL_EVENT_KINDS.RUN_FAILED) {
+            byRun.set(event.run_id, RunSchema.parse({
+                ...fallback,
+                status: RUN_STATUSES.FAILED,
+                completed_at: event.timestamp,
+            }));
+            continue;
+        }
+        byRun.set(event.run_id, RunSchema.parse({
+            ...fallback,
+            status: RUN_STATUSES.SUCCEEDED,
+            completed_at: event.timestamp,
+        }));
+    }
+    return [...byRun.values()].sort((left, right) => {
+        return Date.parse(left.started_at) - Date.parse(right.started_at);
+    });
+}
+function dedupePolicyDecisions(decisions) {
+    const byKey = new Map();
+    for (const decision of decisions) {
+        const key = `${decision.policy_id}|${decision.decision}|${decision.reason ?? ''}`;
+        if (!byKey.has(key)) {
+            byKey.set(key, decision);
+        }
+    }
+    return [...byKey.values()];
+}
+function toPolicyHookDecisions(evaluation) {
+    if (evaluation.decisions.length === 0) {
+        return [
+            {
+                policy_id: KERNEL_POLICY_IDS.RUNTIME_FALLBACK,
+                decision: evaluation.decision,
+                reason: 'Effective policy decision without explicit matching rules.',
+            },
+        ];
+    }
+    if (evaluation.decision === 'deny') {
+        const hasHardDeny = evaluation.decisions.some((decision) => decision.decision === 'deny');
+        if (!hasHardDeny) {
+            return [
+                ...evaluation.decisions,
+                {
+                    policy_id: KERNEL_POLICY_IDS.RUNTIME_FALLBACK,
+                    decision: 'deny',
+                    reason: 'Effective policy decision is deny.',
+                },
+            ];
+        }
+    }
+    return evaluation.decisions;
+}
+function mergeStateAliases(loadedPacks) {
+    const aliases = {};
+    const validStates = new Set(['ready', 'active', 'blocked', 'waiting', 'done']);
+    for (const loadedPack of loadedPacks) {
+        for (const [state, alias] of Object.entries(loadedPack.manifest.state_aliases)) {
+            if (!validStates.has(state)) {
+                continue;
+            }
+            aliases[state] = alias;
+        }
+    }
+    return aliases;
+}
+function formatRuntimeLoadStageError(packId) {
+    return `${RUNTIME_LOAD_STAGE_ERROR_PREFIX} "${packId}"`;
+}
+function formatRuntimeRegistrationStageError(toolName, packId) {
+    return `${RUNTIME_REGISTRATION_STAGE_ERROR_PREFIX} "${toolName}" in pack "${packId}"`;
+}
+function buildPackToolDescription(toolName, packId) {
+    return `Pack tool ${toolName} declared by ${packId}`;
+}
+export async function defaultRuntimeToolCapabilityResolver(input) {
+    const resolvedEntry = resolvePackToolEntryPath(input.loadedPack.packRoot, input.tool.entry);
+    return {
+        name: input.tool.name,
+        domain: input.loadedPack.manifest.id,
+        version: input.loadedPack.manifest.version,
+        input_schema: DEFAULT_PACK_TOOL_INPUT_SCHEMA,
+        output_schema: DEFAULT_PACK_TOOL_OUTPUT_SCHEMA,
+        permission: input.tool.permission,
+        required_scopes: input.tool.required_scopes,
+        handler: {
+            kind: TOOL_HANDLER_KINDS.SUBPROCESS,
+            entry: resolvedEntry,
+        },
+        description: buildPackToolDescription(input.tool.name, input.loadedPack.manifest.id),
+        pack: input.loadedPack.pin.id,
+    };
+}
+async function fileExists(targetPath) {
+    try {
+        await access(targetPath);
+        return true;
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError.code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+}
+async function resolvePacksRoot(options) {
+    if (options.packsRoot) {
+        return path.resolve(options.packsRoot);
+    }
+    const workspaceRoot = path.resolve(options.workspaceRoot);
+    for (const candidate of DEFAULT_PACKS_ROOT_CANDIDATES) {
+        const absoluteCandidate = path.resolve(workspaceRoot, candidate);
+        if (await fileExists(absoluteCandidate)) {
+            return absoluteCandidate;
+        }
+    }
+    const fallbackCandidate = DEFAULT_PACKS_ROOT_CANDIDATES[0];
+    if (!fallbackCandidate) {
+        throw new Error('No default packs root candidates are configured.');
+    }
+    return path.resolve(workspaceRoot, fallbackCandidate);
+}
+function resolveTaskSpecPath(taskSpecRoot, taskId) {
+    return path.join(taskSpecRoot, `${taskId}.yaml`);
+}
+async function readTaskSpecFromDisk(taskSpecRoot, taskId) {
+    const taskSpecPath = resolveTaskSpecPath(taskSpecRoot, taskId);
+    try {
+        const yamlText = await readFile(taskSpecPath, UTF8_ENCODING);
+        return TaskSpecSchema.parse(YAML.parse(yamlText));
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+}
+async function writeTaskSpecImmutable(taskSpecRoot, task) {
+    await mkdir(taskSpecRoot, { recursive: true });
+    const taskSpecPath = resolveTaskSpecPath(taskSpecRoot, task.id);
+    const fileHandle = await open(taskSpecPath, 'wx');
+    try {
+        await fileHandle.writeFile(YAML.stringify(task), UTF8_ENCODING);
+    }
+    catch (writeError) {
+        await fileHandle.close();
+        await rm(taskSpecPath, { force: true });
+        throw writeError;
+    }
+    await fileHandle.close();
+    return taskSpecPath;
+}
+async function resolveWorkspaceSpec(options) {
+    const workspaceRoot = path.resolve(options.workspaceRoot);
+    const workspaceFilePath = path.resolve(options.workspaceFilePath ??
+        path.join(workspaceRoot, options.workspaceFileName ?? WORKSPACE_FILE_NAME));
+    const raw = await readFile(workspaceFilePath, UTF8_ENCODING);
+    const workspaceSpec = WorkspaceSpecSchema.parse(YAML.parse(raw));
+    return {
+        workspace_file_path: workspaceFilePath,
+        workspace_spec: workspaceSpec,
+        workspace_config_hash: canonical_json(raw),
+    };
+}
+function buildDefaultPolicyLayers(loadedPacks) {
+    const packRules = loadedPacks.flatMap((loadedPack) => {
+        return loadedPack.manifest.policies.map((policy) => ({
+            id: policy.id,
+            trigger: policy.trigger,
+            decision: policy.decision,
+            reason: policy.reason,
+        }));
+    });
+    return [
+        {
+            level: 'workspace',
+            default_decision: 'allow',
+            allow_loosening: true,
+            rules: [],
+        },
+        {
+            level: 'lane',
+            rules: [],
+        },
+        {
+            level: 'pack',
+            rules: packRules,
+        },
+        {
+            level: 'task',
+            rules: [],
+        },
+    ];
+}
+function createRuntimePolicyHook(policyEngine) {
+    const builtinPolicyHook = createBuiltinPolicyHook();
+    return async (input) => {
+        const builtinDecisions = await builtinPolicyHook(input);
+        if (builtinDecisions.some((decision) => decision.decision === 'deny')) {
+            return builtinDecisions;
+        }
+        const context = {
+            trigger: POLICY_TRIGGERS.ON_TOOL_REQUEST,
+            run_id: input.context.run_id,
+            task_id: input.context.task_id,
+            tool_name: input.capability.name,
+            pack_id: input.capability.pack,
+        };
+        const evaluation = await policyEngine.evaluate(context);
+        return [...builtinDecisions, ...toPolicyHookDecisions(evaluation)];
+    };
+}
+function resolveReplayTaskFilter(taskId) {
+    return {
+        taskId,
+    };
+}
+function resolveExecutionMetadata(context) {
+    if (!context.metadata || typeof context.metadata !== 'object') {
+        return {};
+    }
+    return context.metadata;
+}
+export class DefaultKernelRuntime {
+    workspaceSpec;
+    workspaceFilePath;
+    workspaceConfigHash;
+    loadedPacks;
+    taskSpecRoot;
+    eventStore;
+    evidenceStore;
+    toolHost;
+    policyEngine;
+    stateAliases;
+    now;
+    runIdFactory;
+    constructor(options) {
+        this.workspaceSpec = options.workspace_spec;
+        this.workspaceFilePath = options.workspace_file_path;
+        this.workspaceConfigHash = options.workspace_config_hash;
+        this.loadedPacks = options.loaded_packs;
+        this.taskSpecRoot = options.task_spec_root;
+        this.eventStore = options.event_store;
+        this.evidenceStore = options.evidence_store;
+        this.toolHost = options.tool_host;
+        this.policyEngine = options.policy_engine;
+        this.stateAliases = options.state_aliases ?? {};
+        this.now = options.now ?? (() => new Date());
+        this.runIdFactory = options.run_id_factory ?? defaultRunIdFactory;
+    }
+    getToolHost() {
+        return this.toolHost;
+    }
+    getPolicyEngine() {
+        return this.policyEngine;
+    }
+    async executeTool(name, input, ctx) {
+        const context = ExecutionContextSchema.parse(ctx);
+        const metadata = resolveExecutionMetadata(context);
+        const expectedHash = this.workspaceConfigHash;
+        let actualHash;
+        let missingWorkspaceFile = false;
+        try {
+            actualHash = await this.computeWorkspaceConfigHash();
+        }
+        catch (error) {
+            const nodeError = error;
+            if (nodeError.code !== 'ENOENT') {
+                throw error;
+            }
+            missingWorkspaceFile = true;
+            actualHash = canonical_json({
+                [WORKSPACE_CONFIG_HASH_CONTEXT_KEYS.WORKSPACE_FILE_MISSING]: this.workspaceFilePath,
+            });
+        }
+        if (actualHash !== expectedHash) {
+            const tamperedEvent = {
+                schema_version: 1,
+                kind: KERNEL_EVENT_KINDS.SPEC_TAMPERED,
+                spec: 'workspace',
+                id: this.workspaceSpec.id,
+                expected_hash: expectedHash,
+                actual_hash: actualHash,
+                timestamp: normalizeTimestamp(this.now),
+            };
+            await this.eventStore.append(tamperedEvent);
+            return {
+                success: false,
+                error: {
+                    code: SPEC_TAMPERED_ERROR_CODE,
+                    message: missingWorkspaceFile
+                        ? SPEC_TAMPERED_WORKSPACE_MISSING_MESSAGE
+                        : SPEC_TAMPERED_WORKSPACE_MESSAGE,
+                    details: {
+                        workspace_id: this.workspaceSpec.id,
+                        workspace_file_path: this.workspaceFilePath,
+                        [WORKSPACE_CONFIG_HASH_CONTEXT_KEYS.WORKSPACE_FILE_MISSING]: missingWorkspaceFile,
+                        expected_hash: expectedHash,
+                        actual_hash: actualHash,
+                    },
+                },
+            };
+        }
+        const runtimeContext = ExecutionContextSchema.parse({
+            ...context,
+            metadata: {
+                ...metadata,
+                [EXECUTION_METADATA_KEYS.WORKSPACE_CONFIG_HASH]: actualHash,
+            },
+        });
+        return this.toolHost.execute(name, input, runtimeContext);
+    }
+    async createTask(taskSpec) {
+        const parsedTask = TaskSpecSchema.parse(taskSpec);
+        if (parsedTask.workspace_id !== this.workspaceSpec.id) {
+            throw new Error(`Task workspace mismatch: expected ${this.workspaceSpec.id}, got ${parsedTask.workspace_id}`);
+        }
+        const laneExists = this.workspaceSpec.lanes.some((lane) => lane.id === parsedTask.lane_id);
+        if (!laneExists) {
+            throw new Error(`Task lane "${parsedTask.lane_id}" is not declared in workspace lanes.`);
+        }
+        let taskSpecPath;
+        try {
+            taskSpecPath = await writeTaskSpecImmutable(this.taskSpecRoot, parsedTask);
+        }
+        catch (error) {
+            const nodeError = error;
+            if (nodeError.code === 'EEXIST') {
+                throw new Error(`Task spec already exists for ${parsedTask.id} and is immutable.`, {
+                    cause: error,
+                });
+            }
+            throw error;
+        }
+        const createdEvent = {
+            schema_version: 1,
+            kind: KERNEL_EVENT_KINDS.TASK_CREATED,
+            task_id: parsedTask.id,
+            timestamp: normalizeTimestamp(this.now),
+            spec_hash: canonical_json(parsedTask),
+        };
+        try {
+            await this.eventStore.append(createdEvent);
+        }
+        catch (eventError) {
+            // Clean up the spec file if event emission fails (crash recovery).
+            // Without this, a spec file exists on disk with no corresponding event,
+            // and the task cannot be retried because 'wx' open will fail with EEXIST.
+            await rm(taskSpecPath, { force: true });
+            throw eventError;
+        }
+        return {
+            task: parsedTask,
+            task_spec_path: taskSpecPath,
+            event: createdEvent,
+        };
+    }
+    async claimTask(input) {
+        const task = await this.requireTaskSpec(input.task_id);
+        const projected = await this.projectTaskState(task.id);
+        assertTransition(projected.status, 'active', task.id, this.stateAliases);
+        const runId = this.runIdFactory(task.id, projected.run_count + 1);
+        const policy = await this.policyEngine.evaluate({
+            trigger: POLICY_TRIGGERS.ON_CLAIM,
+            run_id: runId,
+            task_id: task.id,
+            lane_id: task.lane_id,
+            pack_id: task.domain,
+        });
+        if (policy.decision === 'deny') {
+            throw new Error(`Policy denied claim for ${task.id}.`);
+        }
+        const claimedTimestamp = normalizeTimestamp(this.now, input.timestamp);
+        const claimedEvent = {
+            schema_version: 1,
+            kind: KERNEL_EVENT_KINDS.TASK_CLAIMED,
+            task_id: task.id,
+            timestamp: claimedTimestamp,
+            by: input.by,
+            session_id: input.session_id,
+            domain_data: input.domain_data,
+        };
+        const runStartedEvent = {
+            schema_version: 1,
+            kind: KERNEL_EVENT_KINDS.RUN_STARTED,
+            task_id: task.id,
+            run_id: runId,
+            timestamp: claimedTimestamp,
+            by: input.by,
+            session_id: input.session_id,
+        };
+        await this.eventStore.appendAll([claimedEvent, runStartedEvent]);
+        return {
+            task_id: task.id,
+            run: RunSchema.parse({
+                run_id: runId,
+                task_id: task.id,
+                status: RUN_STATUSES.EXECUTING,
+                started_at: runStartedEvent.timestamp,
+                by: input.by,
+                session_id: input.session_id,
+            }),
+            events: [claimedEvent, runStartedEvent],
+            policy,
+        };
+    }
+    async blockTask(input) {
+        const task = await this.requireTaskSpec(input.task_id);
+        const projected = await this.projectTaskState(task.id);
+        assertTransition(projected.status, 'blocked', task.id, this.stateAliases);
+        const reason = input.reason.trim();
+        if (reason.length === 0) {
+            throw new Error(`Cannot block ${task.id}: reason is required.`);
+        }
+        const blockedEvent = {
+            schema_version: 1,
+            kind: KERNEL_EVENT_KINDS.TASK_BLOCKED,
+            task_id: task.id,
+            timestamp: normalizeTimestamp(this.now, input.timestamp),
+            reason,
+        };
+        await this.eventStore.append(blockedEvent);
+        return {
+            task_id: task.id,
+            event: blockedEvent,
+        };
+    }
+    async unblockTask(input) {
+        const task = await this.requireTaskSpec(input.task_id);
+        const projected = await this.projectTaskState(task.id);
+        assertTransition(projected.status, 'active', task.id, this.stateAliases);
+        const unblockedEvent = {
+            schema_version: 1,
+            kind: KERNEL_EVENT_KINDS.TASK_UNBLOCKED,
+            task_id: task.id,
+            timestamp: normalizeTimestamp(this.now, input.timestamp),
+        };
+        await this.eventStore.append(unblockedEvent);
+        return {
+            task_id: task.id,
+            event: unblockedEvent,
+        };
+    }
+    async completeTask(input) {
+        const task = await this.requireTaskSpec(input.task_id);
+        const projected = await this.projectTaskState(task.id);
+        assertTransition(projected.status, 'done', task.id, this.stateAliases);
+        const runId = input.run_id ?? projected.current_run?.run_id;
+        if (!runId) {
+            throw new Error(`Cannot complete ${task.id}: no active run found.`);
+        }
+        const policy = await this.policyEngine.evaluate({
+            trigger: POLICY_TRIGGERS.ON_COMPLETION,
+            run_id: runId,
+            task_id: task.id,
+            lane_id: task.lane_id,
+            pack_id: task.domain,
+        });
+        if (policy.decision === 'deny') {
+            throw new Error(`Policy denied completion for ${task.id}.`);
+        }
+        const completedTimestamp = normalizeTimestamp(this.now, input.timestamp);
+        const runSucceededEvent = {
+            schema_version: 1,
+            kind: KERNEL_EVENT_KINDS.RUN_SUCCEEDED,
+            task_id: task.id,
+            run_id: runId,
+            timestamp: completedTimestamp,
+            evidence_refs: input.evidence_refs,
+        };
+        const taskCompletedEvent = {
+            schema_version: 1,
+            kind: KERNEL_EVENT_KINDS.TASK_COMPLETED,
+            task_id: task.id,
+            timestamp: completedTimestamp,
+            evidence_refs: input.evidence_refs,
+        };
+        await this.eventStore.appendAll([runSucceededEvent, taskCompletedEvent]);
+        await this.evidenceStore.pruneTask(task.id);
+        return {
+            task_id: task.id,
+            run_id: runId,
+            events: [runSucceededEvent, taskCompletedEvent],
+            policy,
+        };
+    }
+    async inspectTask(taskId) {
+        const task = await this.requireTaskSpec(taskId);
+        const replayResult = await this.eventStore.replay(resolveReplayTaskFilter(taskId));
+        const events = replayResult.events;
+        const state = projectTaskState(task, events);
+        const runHistory = buildRunHistory(events);
+        const receipts = await this.readReceiptsForTask(taskId);
+        const receiptDecisions = receipts.flatMap((receipt) => {
+            if (receipt.kind === TOOL_TRACE_KINDS.TOOL_CALL_FINISHED) {
+                return receipt.policy_decisions;
+            }
+            return [];
+        });
+        const completionDecisions = state.status === 'done' ? await this.evaluateCompletionPolicy(task, state) : [];
+        return {
+            task_id: taskId,
+            task,
+            state,
+            run_history: runHistory,
+            receipts,
+            policy_decisions: dedupePolicyDecisions([...receiptDecisions, ...completionDecisions]),
+            events,
+        };
+    }
+    async requireTaskSpec(taskId) {
+        const loaded = await readTaskSpecFromDisk(this.taskSpecRoot, taskId);
+        if (!loaded) {
+            throw new Error(`Task spec not found for ${taskId}`);
+        }
+        return loaded;
+    }
+    async projectTaskState(taskId) {
+        const task = await this.requireTaskSpec(taskId);
+        const { events } = await this.eventStore.replay(resolveReplayTaskFilter(taskId));
+        return projectTaskState(task, events);
+    }
+    async evaluateCompletionPolicy(task, state) {
+        const runId = state.current_run?.run_id;
+        if (!runId) {
+            return [];
+        }
+        const evaluation = await this.policyEngine.evaluate({
+            trigger: POLICY_TRIGGERS.ON_COMPLETION,
+            run_id: runId,
+            task_id: task.id,
+            lane_id: task.lane_id,
+            pack_id: task.domain,
+        });
+        return evaluation.decisions;
+    }
+    async computeWorkspaceConfigHash() {
+        const raw = await readFile(this.workspaceFilePath, UTF8_ENCODING);
+        return canonical_json(raw);
+    }
+    async readReceiptsForTask(taskId) {
+        const indexed = await this.evidenceStore.readTracesByTaskId(taskId);
+        if (indexed.length > 0) {
+            return indexed;
+        }
+        // After pruneTask (called during completeTask), the in-memory index is
+        // cleared but traces remain in orderedTraces.  Fall back to a full scan
+        // so inspectTask still returns receipts for completed tasks.
+        const traces = await this.evidenceStore.readTraces();
+        const receiptIds = new Set();
+        for (const trace of traces) {
+            if (trace.kind !== TOOL_TRACE_KINDS.TOOL_CALL_STARTED) {
+                continue;
+            }
+            if (trace.task_id === taskId) {
+                receiptIds.add(trace.receipt_id);
+            }
+        }
+        return traces.filter((trace) => {
+            if (trace.kind === TOOL_TRACE_KINDS.TOOL_CALL_STARTED) {
+                return trace.task_id === taskId;
+            }
+            return receiptIds.has(trace.receipt_id);
+        });
+    }
+}
+export async function initializeKernelRuntime(options) {
+    const workspaceRoot = path.resolve(options.workspaceRoot);
+    const resolvedWorkspace = await resolveWorkspaceSpec(options);
+    const workspaceSpec = resolvedWorkspace.workspace_spec;
+    const packsRoot = await resolvePacksRoot(options);
+    const now = options.now ?? (() => new Date());
+    const taskSpecRoot = path.resolve(options.taskSpecRoot ??
+        path.join(workspaceRoot, DEFAULT_RUNTIME_ROOT, KERNEL_RUNTIME_TASKS_DIR_NAME));
+    const eventsFilePath = path.resolve(options.eventsFilePath ??
+        path.join(workspaceRoot, DEFAULT_RUNTIME_ROOT, KERNEL_RUNTIME_EVENTS_DIR_NAME, KERNEL_RUNTIME_EVENTS_FILE_NAME));
+    const eventLockFilePath = path.resolve(options.eventLockFilePath ??
+        path.join(workspaceRoot, DEFAULT_RUNTIME_ROOT, KERNEL_RUNTIME_EVENTS_DIR_NAME, KERNEL_RUNTIME_EVENTS_LOCK_FILE_NAME));
+    const evidenceRoot = path.resolve(options.evidenceRoot ??
+        path.join(workspaceRoot, DEFAULT_RUNTIME_ROOT, KERNEL_RUNTIME_EVIDENCE_DIR_NAME));
+    const packLoader = new PackLoader({ packsRoot });
+    const loadedPacks = [];
+    for (const pin of workspaceSpec.packs) {
+        let loadedPack;
+        try {
+            loadedPack = await packLoader.load({
+                workspaceSpec,
+                packId: pin.id,
+            });
+        }
+        catch (error) {
+            throw new Error(formatRuntimeLoadStageError(pin.id), { cause: error });
+        }
+        loadedPacks.push(loadedPack);
+    }
+    const registry = new ToolRegistry();
+    if (options.includeBuiltinTools !== false) {
+        registerBuiltinToolCapabilities(registry, {
+            declaredScopes: workspaceSpec.security.allowed_scopes,
+        });
+    }
+    const toolCapabilityResolver = options.toolCapabilityResolver ?? defaultRuntimeToolCapabilityResolver;
+    for (const loadedPack of loadedPacks) {
+        for (const tool of loadedPack.manifest.tools) {
+            let capability;
+            try {
+                capability = await toolCapabilityResolver({
+                    workspaceSpec,
+                    loadedPack,
+                    tool,
+                });
+            }
+            catch (error) {
+                throw new Error(formatRuntimeRegistrationStageError(tool.name, loadedPack.pin.id), {
+                    cause: error,
+                });
+            }
+            if (capability) {
+                registry.register(capability);
+            }
+        }
+    }
+    const policyEngine = new PolicyEngine({
+        layers: options.policyLayers ?? buildDefaultPolicyLayers(loadedPacks),
+    });
+    const evidenceStore = new EvidenceStore({ evidenceRoot });
+    const eventStoreOptions = {
+        eventsFilePath,
+        lockFilePath: eventLockFilePath,
+        taskSpecLoader: async (taskId) => readTaskSpecFromDisk(taskSpecRoot, taskId),
+    };
+    const eventStore = new EventStore(eventStoreOptions);
+    const workspaceUpdatedEvent = {
+        schema_version: 1,
+        kind: KERNEL_EVENT_KINDS.WORKSPACE_UPDATED,
+        timestamp: normalizeTimestamp(now),
+        config_hash: resolvedWorkspace.workspace_config_hash,
+        changes_summary: WORKSPACE_UPDATED_INIT_SUMMARY,
+    };
+    await eventStore.append(workspaceUpdatedEvent);
+    const toolHost = new ToolHost({
+        registry,
+        evidenceStore,
+        subprocessDispatcher: options.subprocessDispatcher ||
+            new SandboxSubprocessDispatcher({
+                workspaceRoot,
+                ...options.sandboxSubprocessDispatcherOptions,
+            }),
+        policyHook: createRuntimePolicyHook(policyEngine),
+        runtimeVersion: options.runtimeVersion,
+    });
+    await toolHost.onStartup();
+    return new DefaultKernelRuntime({
+        workspace_spec: workspaceSpec,
+        workspace_file_path: resolvedWorkspace.workspace_file_path,
+        workspace_config_hash: resolvedWorkspace.workspace_config_hash,
+        loaded_packs: loadedPacks,
+        task_spec_root: taskSpecRoot,
+        event_store: eventStore,
+        evidence_store: evidenceStore,
+        tool_host: toolHost,
+        policy_engine: policyEngine,
+        state_aliases: mergeStateAliases(loadedPacks),
+        now,
+        run_id_factory: options.runIdFactory,
+    });
+}
+//# sourceMappingURL=kernel-runtime.js.map