@kalphq/core 0.1.0

package/eslint.config.js

@@ -0,0 +1,33 @@
+import { config as baseConfig } from "@repo/eslint-config/base";
+
+/** @type {import("eslint").Linter.Config[]} */
+export default [
+  ...baseConfig,
+  {
+    rules: {
+      "no-restricted-imports": [
+        "error",
+        {
+          patterns: [
+            {
+              group: ["@kalphq/cloudflare*"],
+              message: "Core cannot depend on Cloudflare package.",
+            },
+            {
+              group: ["@kalphq/test-utils*"],
+              message: "Core cannot depend on test-utils.",
+            },
+            {
+              group: ["cloudflare:*"],
+              message: "Core cannot import CF platform APIs.",
+            },
+            {
+              group: ["@cloudflare/*"],
+              message: "Core cannot import CF worker types.",
+            },
+          ],
+        },
+      ],
+    },
+  },
+];

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@kalphq/core",
+  "version": "0.1.0",
+  "license": "MIT",
+  "author": "Kalp HQ",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./factory": {
+      "types": "./dist/factory.d.ts",
+      "import": "./dist/factory.js"
+    }
+  },
+  "dependencies": {
+    "@kalphq/sdk": "0.3.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.5.2"
+  },
+  "scripts": {
+    "build": "tsup"
+  }
+}

package/src/adapters/interfaces.ts

@@ -0,0 +1,248 @@
+/**
+ * Adapter interfaces for the Kalp v2 Orchestration Reactor.
+ *
+ * These contracts decouple the runtime core from any specific infrastructure.
+ * The reactor never touches storage, scheduling, or transport directly —
+ * it always goes through these interfaces.
+ *
+ * Implementations:
+ * - Cloudflare DO adapter (DurableObjectStorage, Alarms, fetch)
+ * - InMemory adapter (Maps, timeouts) — local dev / tests
+ *
+ * @module
+ */
+
+import type { ExecutionEvent } from "../engine/types";
+
+// ────────────────────────────────────────────────────────────────────────────
+// Sub-stores (decomposed persistence)
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * KV-like state store for agent runtime data.
+ *
+ * Supports get/set/delete and atomic transactions. Co-located with the
+ * actor — adapters decide backing store (DO storage, Redis, in-memory).
+ */
+export interface StateStore {
+  /**
+   * Reads a value from state.
+   *
+   * @param key - The state key.
+   * @returns The stored value, or `null` if not found.
+   */
+  get(key: string): Promise<unknown>;
+
+  /**
+   * Writes a value to state.
+   *
+   * @param key - The state key.
+   * @param value - The value to store (must be JSON-serializable).
+   */
+  set(key: string, value: unknown): Promise<void>;
+
+  /**
+   * Deletes a key from state.
+   *
+   * @param key - The state key to delete.
+   */
+  delete(key: string): Promise<void>;
+
+  /**
+   * Atomically increments a numeric value.
+   *
+   * @param key - The key to increment.
+   * @param amount - The amount to add.
+   * @returns The new value.
+   */
+  increment(key: string, amount: number): Promise<number>;
+
+  /**
+   * Executes a function within an atomic transaction.
+   *
+   * @param fn - The transactional function receiving a scoped store.
+   * @returns The transaction's return value.
+   */
+  transaction<T>(fn: (tx: StateStore) => Promise<T>): Promise<T>;
+}
+
+/**
+ * Append-only execution event log.
+ *
+ * All structured events flow through this store. It is the system's source
+ * of truth for replay, debugging, and observability.
+ */
+export interface EventStore {
+  /**
+   * Appends a structured event to the execution log.
+   * Events are append-only and ordered by insertion time.
+   *
+   * @param event - The execution event to persist.
+   */
+  append(event: ExecutionEvent): Promise<void>;
+
+  /**
+   * Loads all events from the execution log, ordered by insertion.
+   * Used for replay, debugging, and rehydration.
+   *
+   * @returns An ordered array of all persisted execution events.
+   */
+  loadAll(): Promise<ExecutionEvent[]>;
+
+  /**
+   * Loads events filtered by thread ID.
+   *
+   * @param threadId - The thread to filter by.
+   * @returns Events belonging to the specified thread.
+   */
+  loadByThread(threadId: string): Promise<ExecutionEvent[]>;
+
+  /**
+   * Loads events filtered by trace ID.
+   *
+   * @param traceId - The trace to filter by.
+   * @returns Events belonging to the specified trace.
+   */
+  loadByTrace(traceId: string): Promise<ExecutionEvent[]>;
+}
+
+/**
+ * KV store with TTL for idempotency deduplication.
+ *
+ * Actor-scoped (not global). Stored via the adapter's backing store.
+ * Zero race conditions since the actor is single-threaded.
+ */
+export interface IdempotencyStore {
+  /**
+   * Retrieves a cached result by idempotency key.
+   *
+   * @param key - The composite idempotency key.
+   * @returns The cached result, or `null` if not found or expired.
+   */
+  get(key: string): Promise<unknown | null>;
+
+  /**
+   * Stores a result with an optional TTL.
+   *
+   * @param key - The composite idempotency key.
+   * @param result - The result to cache.
+   * @param opts - Optional settings (TTL in milliseconds).
+   */
+  set(key: string, result: unknown, opts?: { ttlMs?: number }): Promise<void>;
+}
+
+/**
+ * Thread metadata store.
+ *
+ * Stores and retrieves metadata associated with a thread (actor instance).
+ */
+export interface ThreadStore {
+  /**
+   * Retrieves metadata for a thread.
+   *
+   * @param threadId - The thread identifier.
+   * @returns The thread metadata, or `null` if not set.
+   */
+  getMeta(threadId: string): Promise<Record<string, unknown> | null>;
+
+  /**
+   * Stores metadata for a thread.
+   *
+   * @param threadId - The thread identifier.
+   * @param meta - The metadata to store.
+   */
+  setMeta(threadId: string, meta: Record<string, unknown>): Promise<void>;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Persistence (composite adapter)
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Composite persistence adapter decomposed into specialized sub-stores.
+ *
+ * This prevents a single monolithic adapter from hiding 4 different
+ * storage patterns behind one interface. Each sub-store has clear semantics.
+ */
+export interface PersistenceAdapter {
+  /** KV-like state store (get/set/delete/transaction). */
+  state: StateStore;
+  /** Append-only execution event log. */
+  events: EventStore;
+  /** KV with TTL for idempotency deduplication. */
+  idempotency: IdempotencyStore;
+  /** Thread metadata store. */
+  threads: ThreadStore;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Scheduling
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Scheduler adapter for deferred execution (alarms, timers).
+ *
+ * Used by `actions.wait`, `actions.loop`, and `actions.schedule` for future
+ * wake-ups. The adapter is responsible for persisting the alarm and re-entering
+ * the reactor when it fires.
+ *
+ * Adapters may have limitations (e.g. CF: 1 alarm per DO). Core handles
+ * multi-schedule queuing in {@link StateStore}; adapter fires one at a time.
+ *
+ * **Best-effort timing** — scheduled events are approximate, not guaranteed
+ * to fire at the exact requested time.
+ */
+export interface SchedulerAdapter {
+  /**
+   * Schedules a wake-up at the given timestamp (ms since epoch).
+   * If an alarm already exists, it should be replaced.
+   *
+   * @param at - Unix timestamp in milliseconds for the wake-up.
+   */
+  schedule(at: number): Promise<void>;
+
+  /**
+   * Cancels any pending scheduled wake-up.
+   */
+  cancel(): Promise<void>;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Transport
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Transport adapter for sending responses back to the caller.
+ *
+ * Used when the reactor needs to push data to a connected client
+ * (e.g. WebSocket message, streaming response).
+ */
+export interface TransportAdapter {
+  /**
+   * Sends a response payload to the connected client.
+   *
+   * @param response - The data to send (will be JSON-serialized).
+   */
+  send(response: unknown): Promise<void>;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Cross-thread messaging
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Adapter for cross-thread (cross-actor) messaging.
+ *
+ * Core never uses HTTP semantics directly. The adapter maps to the
+ * appropriate transport (CF: fetch to DO, Node: IPC, tests: direct call).
+ */
+export interface CrossThreadAdapter {
+  /**
+   * Sends an event to another thread (actor).
+   *
+   * @param targetThreadId - The target thread's opaque identifier.
+   * @param event - The event name.
+   * @param payload - The event payload.
+   */
+  send(targetThreadId: string, event: string, payload: unknown): Promise<void>;
+}

package/src/engine/context-builder.ts

@@ -0,0 +1,151 @@
+/**
+ * Handler context builder for the Kalp v2 Orchestration Reactor.
+ *
+ * Assembles the {@link HandlerContext} that is passed to every handler function.
+ * Each primitive in the context is intercepted — all operations emit structured
+ * events to the execution log.
+ *
+ * The context shape matches the SDK's `HandlerContext` interface exactly,
+ * preserving DX:
+ *
+ * ```ts
+ * const { fetch, loop, run, wait } = actions;
+ * const { delete: deleteKey, get, put } = storage;
+ * const { classify, generate, stream } = ai;
+ * ```
+ *
+ * @module
+ */
+
+import type {
+  HandlerContext,
+  KalpAuth,
+  KalpMemory,
+  KalpVault,
+} from "@kalphq/sdk";
+import type { StateStore, SchedulerAdapter } from "@/adapters/interfaces";
+import type { ExecutionLog } from "@/engine/execution-log";
+import type { AIProvider } from "@/engine/primitives/ai";
+import type { DispatchAction } from "@/engine/primitives/actions";
+import { createAIPrimitive } from "@/engine/primitives/ai";
+import { createStoragePrimitive } from "@/engine/primitives/storage";
+import { createActionsPrimitive } from "@/engine/primitives/actions";
+import { createMcpPrimitive } from "@/engine/primitives/mcp";
+import { createDatePrimitive } from "@/engine/primitives/date";
+import { createMathPrimitive } from "@/engine/primitives/math";
+import { createAgentMetaPrimitive } from "@/engine/primitives/agent-meta";
+import type { ExecutionContext } from "@/engine/types";
+
+// ────────────────────────────────────────────────────────────────────────────
+// External providers injected by the host adapter
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * External provider implementations injected by the host adapter.
+ * These are NOT part of the reactor core — they come from infrastructure.
+ */
+export interface RuntimeProviders {
+  /** AI provider implementation (e.g. OpenAI, Anthropic, Cloudflare AI). */
+  ai: AIProvider;
+  /** Authentication context for the current request. */
+  auth: KalpAuth;
+  /** Memory (conversation history) provider. */
+  memory: KalpMemory;
+  /** Secrets vault provider. */
+  vault: KalpVault;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Context builder
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Builds a {@link HandlerContext} with fully intercepted primitives.
+ *
+ * Every operation on the returned context (ai.generate, storage.put,
+ * actions.run, etc.) is intercepted to emit structured events to the
+ * execution log. The handler never touches infrastructure directly.
+ *
+ * @param log - The execution log for event emission.
+ * @param stateStore - The state sub-store for KV operations.
+ * @param scheduler - The scheduler adapter for deferred execution.
+ * @param dispatch - Callback to enqueue handler tasks in the reactor.
+ * @param providers - External providers (ai, auth, memory, vault).
+ * @param execCtx - Optional execution context for event identity.
+ * @param agentConfig - Optional agent configuration for metadata.
+ * @returns A complete {@link HandlerContext} matching the SDK interface.
+ */
+export function buildHandlerContext(
+  log: ExecutionLog,
+  stateStore: StateStore,
+  scheduler: SchedulerAdapter,
+  dispatch: DispatchAction,
+  providers: RuntimeProviders,
+  execCtx?: ExecutionContext,
+  agentConfig?: {
+    name: string;
+    systemPrompt: string;
+    metadata?: Record<string, unknown>;
+  },
+): HandlerContext {
+  const ids = {
+    executionId: execCtx?.executionId ?? "",
+    traceId: execCtx?.traceId ?? "",
+    threadId: execCtx?.threadId ?? "",
+  };
+
+  return {
+    ai: createAIPrimitive(providers.ai, log),
+    storage: createStoragePrimitive(stateStore, log, execCtx),
+    actions: createActionsPrimitive(log, scheduler, dispatch, execCtx),
+    auth: providers.auth,
+    memory: providers.memory,
+    vault: providers.vault,
+    mcp: createMcpPrimitive(log, execCtx),
+    agent: createAgentMetaPrimitive(log, execCtx, agentConfig),
+    date: createDatePrimitive(log, execCtx),
+    math: createMathPrimitive(log, execCtx),
+    log: {
+      debug: (msg, data) =>
+        void log.emit({
+          type: "log",
+          level: "debug",
+          msg,
+          data,
+          ...ids,
+          timestamp: Date.now(),
+        }),
+      info: (msg, data) =>
+        void log.emit({
+          type: "log",
+          level: "info",
+          msg,
+          data,
+          ...ids,
+          timestamp: Date.now(),
+        }),
+      warn: (msg, data) =>
+        void log.emit({
+          type: "log",
+          level: "warn",
+          msg,
+          data,
+          ...ids,
+          timestamp: Date.now(),
+        }),
+      error: (err, data) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        const errorData =
+          err instanceof Error ? { ...data, stack: err.stack } : data;
+        void log.emit({
+          type: "log",
+          level: "error",
+          msg,
+          data: errorData,
+          ...ids,
+          timestamp: Date.now(),
+        });
+      },
+    },
+  };
+}

package/src/engine/execution-log.ts

@@ -0,0 +1,73 @@
+/**
+ * Structured execution log for the Kalp v2 Orchestration Reactor.
+ *
+ * The execution log is the system's source of truth. Every runtime operation
+ * emits a structured event that is persisted via the {@link PersistenceAdapter}.
+ * This enables replay, time-travel debugging, billing, and observability.
+ *
+ * Rule: **If it doesn't emit an event, it doesn't exist.**
+ *
+ * @module
+ */
+
+import type { EventStore } from "@/adapters/interfaces";
+import type { ExecutionEvent } from "@/engine/types";
+
+/**
+ * Append-only structured event log backed by an {@link EventStore}.
+ *
+ * All reactor operations flow through this class. It provides a unified
+ * interface for emitting and loading events regardless of the underlying
+ * storage mechanism.
+ */
+export class ExecutionLog {
+  /** In-memory buffer of events emitted during the current processing cycle. */
+  private buffer: ExecutionEvent[] = [];
+
+  /**
+   * Creates a new execution log backed by the given event store.
+   *
+   * @param eventStore - The store used to persist and load events.
+   */
+  constructor(private eventStore: EventStore) {}
+
+  /**
+   * Emits a structured execution event.
+   *
+   * The event is immediately persisted via the adapter and buffered in memory
+   * for the current processing cycle.
+   *
+   * @param event - The execution event to emit.
+   */
+  async emit(event: ExecutionEvent): Promise<void> {
+    this.buffer.push(event);
+    await this.eventStore.append(event);
+  }
+
+  /**
+   * Loads all previously persisted events from the adapter.
+   *
+   * Used for replay, rehydration, and debugging.
+   *
+   * @returns An ordered array of all persisted execution events.
+   */
+  async load(): Promise<ExecutionEvent[]> {
+    return this.eventStore.loadAll();
+  }
+
+  /**
+   * Returns events emitted during the current processing cycle (in-memory only).
+   *
+   * @returns The in-memory event buffer.
+   */
+  getBuffer(): ReadonlyArray<ExecutionEvent> {
+    return this.buffer;
+  }
+
+  /**
+   * Clears the in-memory buffer. Called between processing cycles.
+   */
+  clearBuffer(): void {
+    this.buffer = [];
+  }
+}