@lumenflow/kernel 3.0.0

package/dist/sandbox/tool-runner-worker.js

@@ -0,0 +1,159 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { z } from 'zod';
+import { ToolOutputSchema, ToolScopeSchema, } from '../kernel.schemas.js';
+import { UTF8_ENCODING } from '../shared-constants.js';
+import { resolveScopeEnforcementNote } from './profile.js';
+export const ToolRunnerWorkerInvocationSchema = z.object({
+    tool_name: z.string().min(1),
+    handler_entry: z.string().min(1),
+    input: z.unknown(),
+    scope_enforced: z.array(ToolScopeSchema),
+    receipt_id: z.string().min(1),
+});
+export const ToolRunnerWorkerResponseSchema = z.object({
+    output: ToolOutputSchema,
+});
+function buildFailureOutput(code, message, details) {
+    return {
+        success: false,
+        error: {
+            code,
+            message,
+            ...(details ? { details } : {}),
+        },
+    };
+}
+function withScopeNote(output, scopeEnforced) {
+    const note = resolveScopeEnforcementNote(scopeEnforced);
+    if (!note) {
+        return output;
+    }
+    return {
+        ...output,
+        metadata: {
+            ...(output.metadata || {}),
+            scope_enforcement_note: note,
+        },
+    };
+}
+async function defaultImportModule(specifier) {
+    return import(specifier);
+}
+function resolveEntrySpecifier(entry) {
+    if (entry.startsWith('file:')) {
+        return entry;
+    }
+    if (path.isAbsolute(entry)) {
+        return pathToFileURL(path.resolve(entry)).href;
+    }
+    if (entry.startsWith('.')) {
+        return pathToFileURL(path.resolve(process.cwd(), entry)).href;
+    }
+    return entry;
+}
+function isToolAdapter(value) {
+    return typeof value === 'function';
+}
+function selectAdapterExport(candidate) {
+    if (isToolAdapter(candidate)) {
+        return candidate;
+    }
+    if (!candidate || typeof candidate !== 'object') {
+        return null;
+    }
+    const moduleRecord = candidate;
+    const defaultExport = moduleRecord.default;
+    if (isToolAdapter(defaultExport)) {
+        return defaultExport;
+    }
+    const runExport = moduleRecord.run;
+    if (isToolAdapter(runExport)) {
+        return runExport;
+    }
+    const handlerExport = moduleRecord.handler;
+    if (isToolAdapter(handlerExport)) {
+        return handlerExport;
+    }
+    return null;
+}
+async function readStreamAsString(stream) {
+    let output = '';
+    for await (const chunk of stream) {
+        output += typeof chunk === 'string' ? chunk : chunk.toString(UTF8_ENCODING);
+    }
+    return output;
+}
+export function parseToolRunnerWorkerResponse(raw) {
+    const parsedPayload = JSON.parse(raw);
+    return ToolRunnerWorkerResponseSchema.parse(parsedPayload);
+}
+export async function executeToolRunnerInvocation(invocationInput, options = {}) {
+    const parsedInvocation = ToolRunnerWorkerInvocationSchema.safeParse(invocationInput);
+    if (!parsedInvocation.success) {
+        return buildFailureOutput('INVALID_INVOCATION_PAYLOAD', parsedInvocation.error.message);
+    }
+    const invocation = parsedInvocation.data;
+    const importModule = options.importModule || defaultImportModule;
+    let loadedModule;
+    try {
+        loadedModule = await importModule(resolveEntrySpecifier(invocation.handler_entry));
+    }
+    catch (error) {
+        return withScopeNote(buildFailureOutput('ADAPTER_LOAD_FAILED', `Failed to load adapter "${invocation.handler_entry}": ${error.message}`), invocation.scope_enforced);
+    }
+    const adapter = selectAdapterExport(loadedModule);
+    if (!adapter) {
+        return withScopeNote(buildFailureOutput('ADAPTER_LOAD_FAILED', `Adapter "${invocation.handler_entry}" does not export a function`), invocation.scope_enforced);
+    }
+    let rawOutput;
+    try {
+        rawOutput = await adapter(invocation.input, {
+            tool_name: invocation.tool_name,
+            receipt_id: invocation.receipt_id,
+            scope_enforced: invocation.scope_enforced,
+        });
+    }
+    catch (error) {
+        return withScopeNote(buildFailureOutput('TOOL_EXECUTION_FAILED', `Adapter "${invocation.handler_entry}" failed: ${error.message}`), invocation.scope_enforced);
+    }
+    const parsedOutput = ToolOutputSchema.safeParse(rawOutput);
+    if (!parsedOutput.success) {
+        return withScopeNote(buildFailureOutput('INVALID_OUTPUT', parsedOutput.error.message), invocation.scope_enforced);
+    }
+    return withScopeNote(parsedOutput.data, invocation.scope_enforced);
+}
+export async function runToolRunnerWorkerFromStreams(streams, options = {}) {
+    const rawPayload = await readStreamAsString(streams.stdin);
+    let payload;
+    try {
+        payload = JSON.parse(rawPayload);
+    }
+    catch {
+        const invalidPayload = buildFailureOutput('INVALID_INVOCATION_PAYLOAD', 'Worker stdin payload is not valid JSON');
+        streams.stdout.write(JSON.stringify({ output: invalidPayload }));
+        return;
+    }
+    const output = await executeToolRunnerInvocation(payload, options);
+    streams.stdout.write(JSON.stringify({ output }));
+}
+export async function runToolRunnerWorkerProcess() {
+    await runToolRunnerWorkerFromStreams({
+        stdin: process.stdin,
+        stdout: process.stdout,
+        stderr: process.stderr,
+    });
+}
+function shouldRunAsMain() {
+    const entryPath = process.argv[1];
+    if (!entryPath) {
+        return false;
+    }
+    return pathToFileURL(path.resolve(entryPath)).href === import.meta.url;
+}
+if (shouldRunAsMain()) {
+    void runToolRunnerWorkerProcess();
+}
+//# sourceMappingURL=tool-runner-worker.js.map

package/dist/sandbox/tool-runner-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-runner-worker.js","sourceRoot":"","sources":["../../src/sandbox/tool-runner-worker.ts"],"names":[],"mappings":"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"}

package/dist/shared-constants.d.ts

@@ -0,0 +1,48 @@
+export declare const UTF8_ENCODING: "utf8";
+export declare const BASE64_ENCODING: "base64";
+export declare const SHA256_ALGORITHM: "sha256";
+export declare const SHA256_HEX_LENGTH: 64;
+export declare const SHA256_HEX_REGEX: RegExp;
+export declare const SHA256_INTEGRITY_PREFIX: "sha256:";
+export declare const SHA256_INTEGRITY_REGEX: RegExp;
+export declare const WORKSPACE_FILE_NAME: "workspace.yaml";
+export declare const PACKS_DIR_NAME: "packs";
+export declare const PACK_MANIFEST_FILE_NAME: "manifest.yaml";
+export declare const PACKAGES_DIR_NAME: "packages";
+export declare const LUMENFLOW_SCOPE_NAME: "@lumenflow";
+export declare const LUMENFLOW_DIR_NAME: ".lumenflow";
+export declare const KERNEL_RUNTIME_ROOT_DIR_NAME: "kernel";
+export declare const KERNEL_RUNTIME_TASKS_DIR_NAME: "tasks";
+export declare const KERNEL_RUNTIME_EVENTS_DIR_NAME: "events";
+export declare const KERNEL_RUNTIME_EVIDENCE_DIR_NAME: "evidence";
+export declare const KERNEL_RUNTIME_EVENTS_FILE_NAME: "events.jsonl";
+export declare const KERNEL_RUNTIME_EVENTS_LOCK_FILE_NAME: "events.lock";
+export declare const RESERVED_FRAMEWORK_SCOPE_ROOT: ".lumenflow";
+export declare const RESERVED_FRAMEWORK_SCOPE_PREFIX: ".lumenflow/";
+export declare const RESERVED_FRAMEWORK_SCOPE_GLOB: ".lumenflow/**";
+export declare const DEFAULT_WORKSPACE_CONFIG_HASH: string;
+export declare const DEFAULT_KERNEL_RUNTIME_VERSION: "kernel-dev";
+export declare const WORKSPACE_CONFIG_HASH_CONTEXT_KEYS: {
+    readonly WORKSPACE_FILE_MISSING: "workspace_file_missing";
+};
+export declare const EXECUTION_METADATA_KEYS: {
+    readonly WORKSPACE_ALLOWED_SCOPES: "workspace_allowed_scopes";
+    readonly LANE_ALLOWED_SCOPES: "lane_allowed_scopes";
+    readonly TASK_DECLARED_SCOPES: "task_declared_scopes";
+    readonly WORKSPACE_CONFIG_HASH: "workspace_config_hash";
+    readonly RUNTIME_VERSION: "runtime_version";
+    readonly PACK_ID: "pack_id";
+    readonly PACK_VERSION: "pack_version";
+    readonly PACK_INTEGRITY: "pack_integrity";
+};
+export declare const KERNEL_POLICY_IDS: {
+    readonly ALLOW_ALL: "kernel.policy.allow-all";
+    readonly RUNTIME_FALLBACK: "kernel.policy.runtime-fallback";
+    readonly BUILTIN_DEFAULT: "kernel.policy.builtin-default";
+    readonly PROC_EXEC_DEFAULT_DENY: "kernel.policy.proc-exec-default-deny";
+    readonly SCOPE_RESERVED_PATH: "kernel.scope.reserved-path";
+    readonly SCOPE_BOUNDARY: "kernel.scope.boundary";
+    readonly RECONCILIATION: "kernel.reconciliation";
+};
+export type KernelPolicyId = (typeof KERNEL_POLICY_IDS)[keyof typeof KERNEL_POLICY_IDS];
+//# sourceMappingURL=shared-constants.d.ts.map

package/dist/shared-constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-constants.d.ts","sourceRoot":"","sources":["../src/shared-constants.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,aAAa,EAAG,MAAe,CAAC;AAC7C,eAAO,MAAM,eAAe,EAAG,QAAiB,CAAC;AACjD,eAAO,MAAM,gBAAgB,EAAG,QAAiB,CAAC;AAClD,eAAO,MAAM,iBAAiB,EAAG,EAAW,CAAC;AAC7C,eAAO,MAAM,gBAAgB,QAAmB,CAAC;AACjD,eAAO,MAAM,uBAAuB,EAAG,SAAkB,CAAC;AAC1D,eAAO,MAAM,sBAAsB,QAA0B,CAAC;AAC9D,eAAO,MAAM,mBAAmB,EAAG,gBAAyB,CAAC;AAC7D,eAAO,MAAM,cAAc,EAAG,OAAgB,CAAC;AAC/C,eAAO,MAAM,uBAAuB,EAAG,eAAwB,CAAC;AAChE,eAAO,MAAM,iBAAiB,EAAG,UAAmB,CAAC;AACrD,eAAO,MAAM,oBAAoB,EAAG,YAAqB,CAAC;AAE1D,eAAO,MAAM,kBAAkB,EAAG,YAAqB,CAAC;AACxD,eAAO,MAAM,4BAA4B,EAAG,QAAiB,CAAC;AAC9D,eAAO,MAAM,6BAA6B,EAAG,OAAgB,CAAC;AAC9D,eAAO,MAAM,8BAA8B,EAAG,QAAiB,CAAC;AAChE,eAAO,MAAM,gCAAgC,EAAG,UAAmB,CAAC;AACpE,eAAO,MAAM,+BAA+B,EAAG,cAAuB,CAAC;AACvE,eAAO,MAAM,oCAAoC,EAAG,aAAsB,CAAC;AAE3E,eAAO,MAAM,6BAA6B,cAAqB,CAAC;AAChE,eAAO,MAAM,+BAA+B,eAAoC,CAAC;AACjF,eAAO,MAAM,6BAA6B,iBAAsC,CAAC;AAEjF,eAAO,MAAM,6BAA6B,QAAgC,CAAC;AAC3E,eAAO,MAAM,8BAA8B,EAAG,YAAqB,CAAC;AAEpE,eAAO,MAAM,kCAAkC;;CAErC,CAAC;AAEX,eAAO,MAAM,uBAAuB;;;;;;;;;CAS1B,CAAC;AAEX,eAAO,MAAM,iBAAiB;;;;;;;;CAQpB,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/shared-constants.js

@@ -0,0 +1,49 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+export const UTF8_ENCODING = 'utf8';
+export const BASE64_ENCODING = 'base64';
+export const SHA256_ALGORITHM = 'sha256';
+export const SHA256_HEX_LENGTH = 64;
+export const SHA256_HEX_REGEX = /^[a-f0-9]{64}$/;
+export const SHA256_INTEGRITY_PREFIX = 'sha256:';
+export const SHA256_INTEGRITY_REGEX = /^sha256:[a-f0-9]{64}$/;
+export const WORKSPACE_FILE_NAME = 'workspace.yaml';
+export const PACKS_DIR_NAME = 'packs';
+export const PACK_MANIFEST_FILE_NAME = 'manifest.yaml';
+export const PACKAGES_DIR_NAME = 'packages';
+export const LUMENFLOW_SCOPE_NAME = '@lumenflow';
+export const LUMENFLOW_DIR_NAME = '.lumenflow';
+export const KERNEL_RUNTIME_ROOT_DIR_NAME = 'kernel';
+export const KERNEL_RUNTIME_TASKS_DIR_NAME = 'tasks';
+export const KERNEL_RUNTIME_EVENTS_DIR_NAME = 'events';
+export const KERNEL_RUNTIME_EVIDENCE_DIR_NAME = 'evidence';
+export const KERNEL_RUNTIME_EVENTS_FILE_NAME = 'events.jsonl';
+export const KERNEL_RUNTIME_EVENTS_LOCK_FILE_NAME = 'events.lock';
+export const RESERVED_FRAMEWORK_SCOPE_ROOT = LUMENFLOW_DIR_NAME;
+export const RESERVED_FRAMEWORK_SCOPE_PREFIX = `${LUMENFLOW_DIR_NAME}/`;
+export const RESERVED_FRAMEWORK_SCOPE_GLOB = `${LUMENFLOW_DIR_NAME}/**`;
+export const DEFAULT_WORKSPACE_CONFIG_HASH = '0'.repeat(SHA256_HEX_LENGTH);
+export const DEFAULT_KERNEL_RUNTIME_VERSION = 'kernel-dev';
+export const WORKSPACE_CONFIG_HASH_CONTEXT_KEYS = {
+    WORKSPACE_FILE_MISSING: 'workspace_file_missing',
+};
+export const EXECUTION_METADATA_KEYS = {
+    WORKSPACE_ALLOWED_SCOPES: 'workspace_allowed_scopes',
+    LANE_ALLOWED_SCOPES: 'lane_allowed_scopes',
+    TASK_DECLARED_SCOPES: 'task_declared_scopes',
+    WORKSPACE_CONFIG_HASH: 'workspace_config_hash',
+    RUNTIME_VERSION: 'runtime_version',
+    PACK_ID: 'pack_id',
+    PACK_VERSION: 'pack_version',
+    PACK_INTEGRITY: 'pack_integrity',
+};
+export const KERNEL_POLICY_IDS = {
+    ALLOW_ALL: 'kernel.policy.allow-all',
+    RUNTIME_FALLBACK: 'kernel.policy.runtime-fallback',
+    BUILTIN_DEFAULT: 'kernel.policy.builtin-default',
+    PROC_EXEC_DEFAULT_DENY: 'kernel.policy.proc-exec-default-deny',
+    SCOPE_RESERVED_PATH: 'kernel.scope.reserved-path',
+    SCOPE_BOUNDARY: 'kernel.scope.boundary',
+    RECONCILIATION: 'kernel.reconciliation',
+};
+//# sourceMappingURL=shared-constants.js.map

package/dist/shared-constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-constants.js","sourceRoot":"","sources":["../src/shared-constants.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,sCAAsC;AAEtC,MAAM,CAAC,MAAM,aAAa,GAAG,MAAe,CAAC;AAC7C,MAAM,CAAC,MAAM,eAAe,GAAG,QAAiB,CAAC;AACjD,MAAM,CAAC,MAAM,gBAAgB,GAAG,QAAiB,CAAC;AAClD,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAW,CAAC;AAC7C,MAAM,CAAC,MAAM,gBAAgB,GAAG,gBAAgB,CAAC;AACjD,MAAM,CAAC,MAAM,uBAAuB,GAAG,SAAkB,CAAC;AAC1D,MAAM,CAAC,MAAM,sBAAsB,GAAG,uBAAuB,CAAC;AAC9D,MAAM,CAAC,MAAM,mBAAmB,GAAG,gBAAyB,CAAC;AAC7D,MAAM,CAAC,MAAM,cAAc,GAAG,OAAgB,CAAC;AAC/C,MAAM,CAAC,MAAM,uBAAuB,GAAG,eAAwB,CAAC;AAChE,MAAM,CAAC,MAAM,iBAAiB,GAAG,UAAmB,CAAC;AACrD,MAAM,CAAC,MAAM,oBAAoB,GAAG,YAAqB,CAAC;AAE1D,MAAM,CAAC,MAAM,kBAAkB,GAAG,YAAqB,CAAC;AACxD,MAAM,CAAC,MAAM,4BAA4B,GAAG,QAAiB,CAAC;AAC9D,MAAM,CAAC,MAAM,6BAA6B,GAAG,OAAgB,CAAC;AAC9D,MAAM,CAAC,MAAM,8BAA8B,GAAG,QAAiB,CAAC;AAChE,MAAM,CAAC,MAAM,gCAAgC,GAAG,UAAmB,CAAC;AACpE,MAAM,CAAC,MAAM,+BAA+B,GAAG,cAAuB,CAAC;AACvE,MAAM,CAAC,MAAM,oCAAoC,GAAG,aAAsB,CAAC;AAE3E,MAAM,CAAC,MAAM,6BAA6B,GAAG,kBAAkB,CAAC;AAChE,MAAM,CAAC,MAAM,+BAA+B,GAAG,GAAG,kBAAkB,GAAY,CAAC;AACjF,MAAM,CAAC,MAAM,6BAA6B,GAAG,GAAG,kBAAkB,KAAc,CAAC;AAEjF,MAAM,CAAC,MAAM,6BAA6B,GAAG,GAAG,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAC3E,MAAM,CAAC,MAAM,8BAA8B,GAAG,YAAqB,CAAC;AAEpE,MAAM,CAAC,MAAM,kCAAkC,GAAG;IAChD,sBAAsB,EAAE,wBAAwB;CACxC,CAAC;AAEX,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,wBAAwB,EAAE,0BAA0B;IACpD,mBAAmB,EAAE,qBAAqB;IAC1C,oBAAoB,EAAE,sBAAsB;IAC5C,qBAAqB,EAAE,uBAAuB;IAC9C,eAAe,EAAE,iBAAiB;IAClC,OAAO,EAAE,SAAS;IAClB,YAAY,EAAE,cAAc;IAC5B,cAAc,EAAE,gBAAgB;CACxB,CAAC;AAEX,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,SAAS,EAAE,yBAAyB;IACpC,gBAAgB,EAAE,gCAAgC;IAClD,eAAe,EAAE,+BAA+B;IAChD,sBAAsB,EAAE,sCAAsC;IAC9D,mBAAmB,EAAE,4BAA4B;IACjD,cAAc,EAAE,uBAAuB;IACvC,cAAc,EAAE,uBAAuB;CAC/B,CAAC"}

package/dist/state-machine/index.d.ts

@@ -0,0 +1,30 @@
+import type { TaskState } from '../kernel.schemas.js';
+export declare const TASK_LIFECYCLE_STATES: {
+    readonly READY: "ready";
+    readonly ACTIVE: "active";
+    readonly BLOCKED: "blocked";
+    readonly WAITING: "waiting";
+    readonly DONE: "done";
+};
+export declare const TASK_LIFECYCLE_EVENTS: {
+    readonly CLAIM: "task.claim";
+    readonly BLOCK: "task.block";
+    readonly WAIT: "task.wait";
+    readonly COMPLETE: "task.complete";
+    readonly RELEASE: "task.release";
+    readonly UNBLOCK: "task.unblock";
+    readonly RESUME: "task.resume";
+};
+export type TaskLifecycleState = TaskState['status'];
+export type TaskStateAliases = Partial<Record<TaskLifecycleState, string>>;
+/**
+ * The canonical, single source of truth for task state transitions.
+ *
+ * WU-1865: The xstate machine definition was removed because it duplicated
+ * this map without being used at runtime. The runtime exclusively uses
+ * {@link assertTransition} which consults this map.
+ */
+export declare const ALLOWED_TRANSITIONS: Readonly<Record<TaskLifecycleState, TaskLifecycleState[]>>;
+export declare function resolveTaskState(state: string | null | undefined, aliases?: TaskStateAliases): TaskLifecycleState;
+export declare function assertTransition(from: string | null | undefined, to: string | null | undefined, taskId: string, aliases?: TaskStateAliases): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/state-machine/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/state-machine/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,eAAO,MAAM,qBAAqB;;;;;;CAMxB,CAAC;AAEX,eAAO,MAAM,qBAAqB;;;;;;;;CAQxB,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AACrD,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC,CAAC;AAiB3E;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,kBAAkB,EAAE,kBAAkB,EAAE,CAAC,CAM1F,CAAC;AA6BF,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAChC,OAAO,GAAE,gBAAqB,GAC7B,kBAAkB,CAmBpB;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC/B,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC7B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,gBAAqB,GAC7B,IAAI,CAaN"}

package/dist/state-machine/index.js

@@ -0,0 +1,92 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+export const TASK_LIFECYCLE_STATES = {
+    READY: 'ready',
+    ACTIVE: 'active',
+    BLOCKED: 'blocked',
+    WAITING: 'waiting',
+    DONE: 'done',
+};
+export const TASK_LIFECYCLE_EVENTS = {
+    CLAIM: 'task.claim',
+    BLOCK: 'task.block',
+    WAIT: 'task.wait',
+    COMPLETE: 'task.complete',
+    RELEASE: 'task.release',
+    UNBLOCK: 'task.unblock',
+    RESUME: 'task.resume',
+};
+/**
+ * Naming convention (WU-1865):
+ *   - Methods: camelCase (standard TypeScript convention)
+ *   - Data/event fields: snake_case (kernel event schema convention)
+ *   - Constants: UPPER_SNAKE_CASE (standard constant convention)
+ */
+const CANONICAL_STATES = [
+    TASK_LIFECYCLE_STATES.READY,
+    TASK_LIFECYCLE_STATES.ACTIVE,
+    TASK_LIFECYCLE_STATES.BLOCKED,
+    TASK_LIFECYCLE_STATES.WAITING,
+    TASK_LIFECYCLE_STATES.DONE,
+];
+/**
+ * The canonical, single source of truth for task state transitions.
+ *
+ * WU-1865: The xstate machine definition was removed because it duplicated
+ * this map without being used at runtime. The runtime exclusively uses
+ * {@link assertTransition} which consults this map.
+ */
+export const ALLOWED_TRANSITIONS = {
+    ready: ['active'],
+    active: ['blocked', 'waiting', 'done', 'ready'],
+    blocked: ['active', 'done'],
+    waiting: ['active', 'done'],
+    done: [],
+};
+function buildAliasLookup(aliases) {
+    const lookup = new Map();
+    for (const state of CANONICAL_STATES) {
+        lookup.set(state, state);
+    }
+    for (const [state, alias] of Object.entries(aliases)) {
+        if (!alias) {
+            continue;
+        }
+        const normalizedAlias = alias.trim();
+        if (!normalizedAlias) {
+            throw new Error(`Invalid alias for state "${state}": alias must be non-empty`);
+        }
+        const existing = lookup.get(normalizedAlias);
+        if (existing && existing !== state) {
+            throw new Error(`Ambiguous alias "${normalizedAlias}" resolves to both "${existing}" and "${state}"`);
+        }
+        lookup.set(normalizedAlias, state);
+    }
+    return lookup;
+}
+export function resolveTaskState(state, aliases = {}) {
+    if (state === null || state === undefined) {
+        throw new Error(`Invalid state: ${state}`);
+    }
+    const normalized = state.trim();
+    if (!normalized) {
+        throw new Error(`Invalid state: ${state}`);
+    }
+    const lookup = buildAliasLookup(aliases);
+    const resolved = lookup.get(normalized);
+    if (!resolved) {
+        throw new Error(`Invalid state: ${state}. Expected one of: ${Array.from(lookup.keys()).join(', ')}`);
+    }
+    return resolved;
+}
+export function assertTransition(from, to, taskId, aliases = {}) {
+    const fromState = resolveTaskState(from, aliases);
+    const toState = resolveTaskState(to, aliases);
+    const allowed = ALLOWED_TRANSITIONS[fromState];
+    if (!allowed.includes(toState)) {
+        const terminalHint = fromState === TASK_LIFECYCLE_STATES.DONE ? ' (done is a terminal state)' : '';
+        const allowedNext = allowed.length > 0 ? allowed.join(', ') : '(none)';
+        throw new Error(`Illegal state transition for ${taskId}: ${fromState} -> ${toState}${terminalHint}. Allowed next states: ${allowedNext}`);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/state-machine/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/state-machine/index.ts"],"names":[],"mappings":"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"}

package/dist/tool-host/builtins/capabilities.d.ts

@@ -0,0 +1,20 @@
+import type { ToolCapability, ToolScope } from '../../kernel.schemas.js';
+import type { PolicyHook } from '../tool-host.js';
+import { ToolRegistry } from '../tool-registry.js';
+export interface BuiltinSubprocessEntries {
+    fsWrite?: string;
+    procExec?: string;
+}
+export interface BuiltinToolOptions {
+    declaredScopes: ToolScope[];
+    includeInternalTools?: boolean;
+    subprocessEntries?: BuiltinSubprocessEntries;
+}
+export interface BuiltinPolicyOptions {
+    allowInternalProcExec?: boolean;
+}
+export declare function createBuiltinToolCapabilities(options: BuiltinToolOptions): ToolCapability[];
+export declare function listAgentVisibleBuiltinTools(capabilities: ToolCapability[]): ToolCapability[];
+export declare function registerBuiltinToolCapabilities(registry: ToolRegistry, options: BuiltinToolOptions): ToolCapability[];
+export declare function createBuiltinPolicyHook(options?: BuiltinPolicyOptions): PolicyHook;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/tool-host/builtins/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../../src/tool-host/builtins/capabilities.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAc,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAErF,OAAO,KAAK,EAAE,UAAU,EAAmB,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAuDnD,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,SAAS,EAAE,CAAC;IAC5B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,iBAAiB,CAAC,EAAE,wBAAwB,CAAC;CAC9C;AAED,MAAM,WAAW,oBAAoB;IACnC,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAsID,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,kBAAkB,GAAG,cAAc,EAAE,CAiB3F;AAED,wBAAgB,4BAA4B,CAAC,YAAY,EAAE,cAAc,EAAE,GAAG,cAAc,EAAE,CAE7F;AAED,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,kBAAkB,GAC1B,cAAc,EAAE,CAMlB;AAED,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,oBAAyB,GAAG,UAAU,CAqBtF"}

package/dist/tool-host/builtins/capabilities.js

@@ -0,0 +1,211 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import micromatch from 'micromatch';
+import { z } from 'zod';
+import { BASE64_ENCODING, KERNEL_POLICY_IDS, UTF8_ENCODING } from '../../shared-constants.js';
+import { ToolRegistry } from '../tool-registry.js';
+const BUILTIN_POLICY_IDS = {
+    DEFAULT_ALLOW: KERNEL_POLICY_IDS.BUILTIN_DEFAULT,
+    PROC_EXEC_DEFAULT_DENY: KERNEL_POLICY_IDS.PROC_EXEC_DEFAULT_DENY,
+};
+const BUILTIN_TOOL_NAMES = {
+    FS_READ: 'fs:read',
+    FS_WRITE: 'fs:write',
+    PROC_EXEC: 'proc:exec',
+};
+const BUILTIN_SUBPROCESS_ENTRIES = {
+    FS_WRITE: 'kernel/tool-impl/fs-write.js',
+    PROC_EXEC: 'kernel/tool-impl/proc-exec.js',
+};
+const BUILTIN_PACK_ID = 'kernel-builtins';
+const BUILTIN_TOOL_VERSION = '1.0.0';
+const TEXT_ENCODINGS = [UTF8_ENCODING, BASE64_ENCODING];
+const FsReadInputSchema = z.object({
+    path: z.string().min(1),
+    encoding: z.enum(TEXT_ENCODINGS).optional(),
+});
+const FsReadOutputSchema = z.object({
+    path: z.string().min(1),
+    content: z.string(),
+    bytes: z.number().int().nonnegative(),
+});
+const FsWriteInputSchema = z.object({
+    path: z.string().min(1),
+    content: z.string(),
+    encoding: z.enum(TEXT_ENCODINGS).optional(),
+});
+const FsWriteOutputSchema = z.object({
+    queued: z.boolean(),
+    target: z.string().min(1),
+});
+const ProcExecInputSchema = z.object({
+    command: z.string().min(1),
+    args: z.array(z.string()).default([]),
+});
+const ProcExecOutputSchema = z.object({
+    exit_code: z.number().int(),
+    stdout: z.string(),
+    stderr: z.string(),
+});
+function buildScopeKey(scope) {
+    if (scope.type === 'path') {
+        return `${scope.type}:${scope.access}:${scope.pattern}`;
+    }
+    return `${scope.type}:${scope.posture}`;
+}
+function dedupeScopes(scopes) {
+    const seen = new Set();
+    const deduped = [];
+    for (const scope of scopes) {
+        const key = buildScopeKey(scope);
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        deduped.push(scope);
+    }
+    return deduped;
+}
+function buildFailureOutput(code, message) {
+    return {
+        success: false,
+        error: {
+            code,
+            message,
+        },
+    };
+}
+async function runFsRead(input, scopes) {
+    const parsedInput = FsReadInputSchema.safeParse(input);
+    if (!parsedInput.success) {
+        return buildFailureOutput('INVALID_INPUT', parsedInput.error.message);
+    }
+    const resolvedPath = resolve(parsedInput.data.path);
+    const canReadPath = scopesAllowReadPath(scopes, resolvedPath);
+    if (!canReadPath) {
+        return buildFailureOutput('SCOPE_VIOLATION', `Path ${resolvedPath} is outside the enforced read scopes for fs:read.`);
+    }
+    const encoding = parsedInput.data.encoding || UTF8_ENCODING;
+    try {
+        const content = await readFile(resolvedPath, { encoding });
+        return {
+            success: true,
+            data: {
+                path: resolvedPath,
+                content,
+                bytes: Buffer.byteLength(content),
+            },
+        };
+    }
+    catch (error) {
+        return buildFailureOutput('FS_READ_FAILED', error.message);
+    }
+}
+function scopesAllowReadPath(scopes, filePath) {
+    const readScopes = scopes.filter((scope) => scope.type === 'path' && scope.access === 'read');
+    if (readScopes.length === 0) {
+        return false;
+    }
+    const normalizedPath = filePath.replace(/\\/g, '/');
+    return readScopes.some((scope) => micromatch.isMatch(normalizedPath, resolve(scope.pattern).replace(/\\/g, '/')));
+}
+function createFsReadCapability(scopes) {
+    return {
+        name: BUILTIN_TOOL_NAMES.FS_READ,
+        domain: 'filesystem',
+        version: BUILTIN_TOOL_VERSION,
+        input_schema: FsReadInputSchema,
+        output_schema: FsReadOutputSchema,
+        permission: 'read',
+        required_scopes: scopes,
+        handler: {
+            kind: 'in-process',
+            fn: (input) => runFsRead(input, scopes),
+        },
+        description: 'Read file content from an allowed scope',
+        pack: BUILTIN_PACK_ID,
+    };
+}
+function createFsWriteCapability(scopes, entry) {
+    return {
+        name: BUILTIN_TOOL_NAMES.FS_WRITE,
+        domain: 'filesystem',
+        version: BUILTIN_TOOL_VERSION,
+        input_schema: FsWriteInputSchema,
+        output_schema: FsWriteOutputSchema,
+        permission: 'write',
+        required_scopes: scopes,
+        handler: {
+            kind: 'subprocess',
+            entry,
+        },
+        description: 'Write file content through sandboxed subprocess execution',
+        pack: BUILTIN_PACK_ID,
+    };
+}
+function createProcExecCapability(scopes, entry) {
+    return {
+        name: BUILTIN_TOOL_NAMES.PROC_EXEC,
+        domain: 'process',
+        version: BUILTIN_TOOL_VERSION,
+        input_schema: ProcExecInputSchema,
+        output_schema: ProcExecOutputSchema,
+        permission: 'admin',
+        required_scopes: scopes,
+        handler: {
+            kind: 'subprocess',
+            entry,
+        },
+        description: 'Execute internal subprocess actions for pack tool implementations',
+        pack: BUILTIN_PACK_ID,
+    };
+}
+export function createBuiltinToolCapabilities(options) {
+    const dedupedScopes = dedupeScopes(options.declaredScopes);
+    const subprocessEntries = {
+        fsWrite: options.subprocessEntries?.fsWrite || BUILTIN_SUBPROCESS_ENTRIES.FS_WRITE,
+        procExec: options.subprocessEntries?.procExec || BUILTIN_SUBPROCESS_ENTRIES.PROC_EXEC,
+    };
+    const capabilities = [
+        createFsReadCapability(dedupedScopes),
+        createFsWriteCapability(dedupedScopes, subprocessEntries.fsWrite),
+    ];
+    if (options.includeInternalTools) {
+        capabilities.push(createProcExecCapability(dedupedScopes, subprocessEntries.procExec));
+    }
+    return capabilities;
+}
+export function listAgentVisibleBuiltinTools(capabilities) {
+    return capabilities.filter((capability) => capability.name !== BUILTIN_TOOL_NAMES.PROC_EXEC);
+}
+export function registerBuiltinToolCapabilities(registry, options) {
+    const capabilities = createBuiltinToolCapabilities(options);
+    for (const capability of capabilities) {
+        registry.register(capability);
+    }
+    return capabilities;
+}
+export function createBuiltinPolicyHook(options = {}) {
+    const allowInternalProcExec = options.allowInternalProcExec || false;
+    return async (input) => {
+        if (input.capability.name === BUILTIN_TOOL_NAMES.PROC_EXEC && !allowInternalProcExec) {
+            return [
+                {
+                    policy_id: BUILTIN_POLICY_IDS.PROC_EXEC_DEFAULT_DENY,
+                    decision: 'deny',
+                    reason: 'proc:exec is internal-only and default-denied by workspace policy.',
+                },
+            ];
+        }
+        return [
+            {
+                policy_id: BUILTIN_POLICY_IDS.DEFAULT_ALLOW,
+                decision: 'allow',
+                reason: 'Builtin tool allowed by default policy.',
+            },
+        ];
+    };
+}
+//# sourceMappingURL=capabilities.js.map