@alveus-ai/core 0.1.0

package/.turbo/turbo-test.log

@@ -0,0 +1,28 @@
+
+Serialized handler source: async(event2,ctx)=>{const result2=await ctx.db.save(event2.data);return{saved:result2}}
+Mock DB: Saving hello from POC
+✅ POC Success! Result: { saved: 'saved:hello from POC' }
+✅ Arrow function test passed: { count: 6 }
+Mock fetch: https://api.example.com/v2?retries=3
+✅ Configuration passing test passed: response from https://api.example.com/v2?retries=3
+✅ Complex context test passed: { saveId: 'save-id-456', response: 'AI generated response' }
+  Logs: [
+  'INFO: Processing request for user user-789',
+  "db.query: SELECT * FROM users WHERE id = 'user-789'",
+  'openai.complete: Summarize this document',
+  'db.save: {"userId":"user-789","response":"AI generated response"}'
+]
+▶ Capability Injection POC
+  ✔ should inject capabilities into a deserialized function (1.540707ms)
+  ✔ should work with arrow functions (0.255949ms)
+  ✔ should pass configuration via event/state, not outer scope (0.253008ms)
+  ✔ should handle complex context with multiple capabilities (0.437631ms)
+✔ Capability Injection POC (3.096825ms)
+ℹ tests 4
+ℹ suites 1
+ℹ pass 4
+ℹ fail 0
+ℹ cancelled 0
+ℹ skipped 0
+ℹ todo 0
+ℹ duration_ms 1464.19065

package/dist/agent.d.ts

@@ -0,0 +1,4 @@
+import type { Agent, AgentHandler, AgentOptions } from './types.js';
+export declare function agent$<TState = any, TEvent = any, TContext = any, TResult = any>(handler: AgentHandler<TState, TEvent, TContext, TResult>, options?: AgentOptions): Agent<TState, TEvent, TContext, TResult>;
+export declare function serializeHandler(handler: (...args: unknown[]) => unknown): string;
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,YAAY,EAAmB,MAAM,YAAY,CAAC;AAgBrF,wBAAgB,MAAM,CAAC,MAAM,GAAG,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,QAAQ,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG,EAC9E,OAAO,EAAE,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,EACxD,OAAO,CAAC,EAAE,YAAY,GACrB,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,CAwB1C;AAYD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,GAAG,MAAM,CAEjF"}

package/dist/agent.js

@@ -0,0 +1,30 @@
+import crypto from 'node:crypto';
+export function agent$(handler, options) {
+    const handlerSource = handler.toString();
+    const hash = computeHash(handlerSource);
+    const definition = {
+        hash,
+        inputs: {
+            state: 'any',
+            event: 'any',
+            context: 'any',
+        },
+        metadata: {
+            name: options?.name,
+            version: options?.version,
+            description: options?.description,
+        },
+    };
+    return {
+        definition,
+        handler,
+        options,
+    };
+}
+function computeHash(source) {
+    return crypto.createHash('sha256').update(source).digest('hex');
+}
+export function serializeHandler(handler) {
+    return handler.toString();
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,aAAa,CAAC;AAiBjC,MAAM,UAAU,MAAM,CACpB,OAAwD,EACxD,OAAsB;IAGtB,MAAM,aAAa,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IACzC,MAAM,IAAI,GAAG,WAAW,CAAC,aAAa,CAAC,CAAC;IAExC,MAAM,UAAU,GAA8C;QAC5D,IAAI;QACJ,MAAM,EAAE;YACN,KAAK,EAAE,KAAK;YACZ,KAAK,EAAE,KAAK;YACZ,OAAO,EAAE,KAAK;SACf;QACD,QAAQ,EAAE;YACR,IAAI,EAAE,OAAO,EAAE,IAAI;YACnB,OAAO,EAAE,OAAO,EAAE,OAAO;YACzB,WAAW,EAAE,OAAO,EAAE,WAAW;SAClC;KACF,CAAC;IAEF,OAAO;QACL,UAAU;QACV,OAAO;QACP,OAAO;KACR,CAAC;AACJ,CAAC;AAKD,SAAS,WAAW,CAAC,MAAc;IACjC,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAClE,CAAC;AAKD,MAAM,UAAU,gBAAgB,CAAC,OAAwC;IACvE,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC;AAC5B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { agent$, serializeHandler } from './agent.js';
+export type { Agent, AgentDefinition, AgentHandler, AgentOptions, ExecutionContext, VirtualAgent, } from './types.js';
+export { isVirtualAgent } from './types.js';
+export { isDurableContext, withDurableContext } from './runtime.js';
+export type { DurableExecutionContext, ExecutionRequest, ExecutionResult, ExecutionStatus, Registry, Runtime, RuntimeConfig, SimpleRuntimeConfig, DurableRuntimeConfig, ChatMessage, ChatOptions, LLMCapability, StorageCapability, BlobStore, AlveusEvent, EventCapability, LoggerCapability, } from './runtime.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGtD,YAAY,EACV,KAAK,EACL,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,YAAY,GACb,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG5C,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEpE,YAAY,EAEV,uBAAuB,EACvB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,QAAQ,EACR,OAAO,EACP,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EAEpB,WAAW,EACX,WAAW,EACX,aAAa,EAEb,iBAAiB,EACjB,SAAS,EAET,WAAW,EACX,eAAe,EAEf,gBAAgB,GACjB,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { agent$, serializeHandler } from './agent.js';
+export { isVirtualAgent } from './types.js';
+export { isDurableContext, withDurableContext } from './runtime.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAatD,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG5C,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}

package/dist/runtime.d.ts

@@ -0,0 +1,121 @@
+import type { ExecutionContext } from './types.js';
+export interface AlveusEvent {
+    id: string;
+    topic: string;
+    data: any;
+    source?: string;
+    timestamp: number;
+    targetWorkflowId?: string;
+}
+export interface EventCapability {
+    emit(topic: string, data: any): Promise<void>;
+    waitFor(topic: string, timeoutMs?: number): Promise<AlveusEvent>;
+}
+export interface SecretsCapability {
+    get(key: string): string | undefined;
+    has(key: string): boolean;
+    keys(): string[];
+}
+export interface LoggerCapability {
+    info(message: string, attrs?: Record<string, any>): void;
+    warn(message: string, attrs?: Record<string, any>): void;
+    error(message: string, attrs?: Record<string, any>): void;
+    debug(message: string, attrs?: Record<string, any>): void;
+}
+export interface ChatMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+export interface ChatOptions {
+    provider?: 'openai' | 'anthropic' | 'ollama' | 'mock';
+    model?: string;
+    temperature?: number;
+    jsonMode?: boolean;
+    maxTokens?: number;
+    streamId?: string;
+}
+export interface LLMCapability {
+    chat(messages: ChatMessage[], options?: ChatOptions): Promise<string>;
+}
+export interface StorageCapability {
+    put(data: string | Buffer): Promise<string>;
+    get(key: string): Promise<string | null>;
+}
+export interface BlobStore {
+    put(data: string | Buffer): Promise<string>;
+    get(key: string): Promise<string | null>;
+    exists(key: string): Promise<boolean>;
+    delete?(key: string): Promise<void>;
+    list?(): Promise<string[]>;
+}
+export interface DurableExecutionContext extends ExecutionContext {
+    sleep(duration: number | string): Promise<void>;
+    sleepUntil(timestamp: string | Date): Promise<void>;
+    getExecutionId(): string;
+    getAttempt(): number;
+    log: {
+        info(message: string, ...args: any[]): void;
+        warn(message: string, ...args: any[]): void;
+        error(message: string, ...args: any[]): void;
+        debug(message: string, ...args: any[]): void;
+    };
+}
+export interface ExecutionRequest<TState = any, TEvent = any> {
+    hash: string;
+    state: TState;
+    event: TEvent;
+    executionId?: string;
+    parentExecutionId?: string;
+}
+export interface ExecutionResult<TResult = any> {
+    success: boolean;
+    result?: TResult;
+    error?: string;
+    metadata: {
+        hash: string;
+        executionId: string;
+        duration: number;
+        timestamp: string;
+        attempts?: number;
+    };
+}
+export interface Registry {
+    store(hash: string, content: string): Promise<void>;
+    retrieve(hash: string): Promise<string | null>;
+    list(): Promise<string[]>;
+    exists(hash: string): Promise<boolean>;
+}
+export interface Runtime {
+    readonly name: string;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    execute<TState = any, TEvent = any, TResult = any>(request: ExecutionRequest<TState, TEvent>): Promise<ExecutionResult<TResult>>;
+    getExecutionStatus(executionId: string): Promise<ExecutionStatus>;
+    cancelExecution(executionId: string): Promise<void>;
+}
+export interface ExecutionStatus {
+    executionId: string;
+    hash: string;
+    status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+    startedAt?: string;
+    completedAt?: string;
+    error?: string;
+    result?: any;
+}
+export interface RuntimeConfig {
+    registry: Registry;
+    capabilities?: Record<string, any>;
+}
+export interface DurableRuntimeConfig extends RuntimeConfig {
+    address: string;
+    namespace: string;
+    taskQueue: string;
+    identity?: string;
+}
+export interface SimpleRuntimeConfig extends RuntimeConfig {
+    port?: number;
+    host?: string;
+}
+export declare function isDurableContext(ctx: ExecutionContext): ctx is DurableExecutionContext;
+export declare function withDurableContext<TState, TEvent, TResult>(handler: (state: TState, event: TEvent, ctx: DurableExecutionContext) => Promise<TResult>): (state: TState, event: TEvent, ctx: ExecutionContext) => Promise<TResult>;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

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

package/dist/runtime.js

@@ -0,0 +1,51 @@
+export function isDurableContext(ctx) {
+    return 'sleep' in ctx && typeof ctx.sleep === 'function';
+}
+export function withDurableContext(handler) {
+    return async (state, event, ctx) => {
+        const durableCtx = isDurableContext(ctx)
+            ? ctx
+            : {
+                ...ctx,
+                sleep: async (duration) => {
+                    const ms = typeof duration === 'number' ? duration : parseDuration(duration);
+                    return new Promise((resolve) => setTimeout(resolve, ms));
+                },
+                sleepUntil: async (timestamp) => {
+                    const target = typeof timestamp === 'string' ? new Date(timestamp) : timestamp;
+                    const now = Date.now();
+                    const delay = target.getTime() - now;
+                    if (delay > 0) {
+                        await new Promise((resolve) => setTimeout(resolve, delay));
+                    }
+                },
+                getExecutionId: () => `simple-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+                getAttempt: () => 1,
+                log: {
+                    info: (msg, ...args) => console.log(`[INFO] ${msg}`, ...args),
+                    warn: (msg, ...args) => console.warn(`[WARN] ${msg}`, ...args),
+                    error: (msg, ...args) => console.error(`[ERROR] ${msg}`, ...args),
+                    debug: (msg, ...args) => console.debug(`[DEBUG] ${msg}`, ...args),
+                },
+            };
+        return handler(state, event, durableCtx);
+    };
+}
+function parseDuration(duration) {
+    const match = duration.match(/^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$/);
+    if (!match) {
+        throw new Error(`Invalid duration format: ${duration}`);
+    }
+    const [, days, hours, minutes, seconds] = match;
+    let ms = 0;
+    if (days)
+        ms += parseInt(days, 10) * 24 * 60 * 60 * 1000;
+    if (hours)
+        ms += parseInt(hours, 10) * 60 * 60 * 1000;
+    if (minutes)
+        ms += parseInt(minutes, 10) * 60 * 1000;
+    if (seconds)
+        ms += parseFloat(seconds) * 1000;
+    return ms;
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,47 @@
+export interface AgentDefinition<TState = any, TEvent = any, TContext = any> {
+    hash: string;
+    inputs: {
+        state: string;
+        event: string;
+        context: string;
+    };
+    metadata?: {
+        name?: string;
+        version?: string;
+        description?: string;
+    };
+    __types?: {
+        state: TState;
+        event: TEvent;
+        context: TContext;
+    };
+}
+export type AgentHandler<TState = any, TEvent = any, TContext = any, TResult = any> = (state: TState, event: TEvent, context: TContext) => Promise<TResult> | TResult;
+export interface AgentOptions {
+    name?: string;
+    description?: string;
+    version?: string;
+}
+export interface Agent<TState = any, TEvent = any, TContext = any, TResult = any> {
+    definition: AgentDefinition<TState, TEvent, TContext>;
+    handler: AgentHandler<TState, TEvent, TContext, TResult>;
+    options?: AgentOptions;
+}
+export interface VirtualAgent<TInput = any> {
+    definition: Agent;
+    defaultInput: Partial<TInput>;
+}
+export declare function isVirtualAgent(agent: any): agent is VirtualAgent;
+export interface ExecutionContext {
+    workflowId: string;
+    call<TInput = any, TOutput = any>(agent: Agent<any, TInput, any, TOutput> | string, input: TInput): Promise<TOutput>;
+    sleep(duration: number): Promise<void>;
+    getState<T = any>(key: string): Promise<T | null>;
+    setState(key: string, value: any): Promise<void>;
+    llm: import('./runtime.js').LLMCapability;
+    storage: import('./runtime.js').StorageCapability;
+    events: import('./runtime.js').EventCapability;
+    logger: import('./runtime.js').LoggerCapability;
+    secrets: import('./runtime.js').SecretsCapability;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,eAAe,CAAC,MAAM,GAAG,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,QAAQ,GAAG,GAAG;IAEzE,IAAI,EAAE,MAAM,CAAC;IAGb,MAAM,EAAE;QACN,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IAGF,QAAQ,CAAC,EAAE;QACT,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IAGF,OAAO,CAAC,EAAE;QACR,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,QAAQ,CAAC;KACnB,CAAC;CACH;AAKD,MAAM,MAAM,YAAY,CAAC,MAAM,GAAG,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,QAAQ,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,CACpF,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,QAAQ,KACd,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;AAKhC,MAAM,WAAW,YAAY;IAE3B,IAAI,CAAC,EAAE,MAAM,CAAC;IAGd,WAAW,CAAC,EAAE,MAAM,CAAC;IAGrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAKD,MAAM,WAAW,KAAK,CAAC,MAAM,GAAG,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,QAAQ,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG;IAE9E,UAAU,EAAE,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;IAGtD,OAAO,EAAE,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAGzD,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAaD,MAAM,WAAW,YAAY,CAAC,MAAM,GAAG,GAAG;IAExC,UAAU,EAAE,KAAK,CAAC;IAGlB,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;CAC/B;AAKD,wBAAgB,cAAc,CAAC,KAAK,EAAE,GAAG,GAAG,KAAK,IAAI,YAAY,CAShE;AAQD,MAAM,WAAW,gBAAgB;IAE/B,UAAU,EAAE,MAAM,CAAC;IAGnB,IAAI,CAAC,MAAM,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG,EAC9B,KAAK,EAAE,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,MAAM,EAChD,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAAC;IAMpB,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAGvC,QAAQ,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAGlD,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAGjD,GAAG,EAAE,OAAO,cAAc,EAAE,aAAa,CAAC;IAG1C,OAAO,EAAE,OAAO,cAAc,EAAE,iBAAiB,CAAC;IAGlD,MAAM,EAAE,OAAO,cAAc,EAAE,eAAe,CAAC;IAG/C,MAAM,EAAE,OAAO,cAAc,EAAE,gBAAgB,CAAC;IAGhD,OAAO,EAAE,OAAO,cAAc,EAAE,iBAAiB,CAAC;CACnD"}

package/dist/types.js

@@ -0,0 +1,9 @@
+export function isVirtualAgent(agent) {
+    return (agent !== null &&
+        typeof agent === 'object' &&
+        'definition' in agent &&
+        'defaultInput' in agent &&
+        typeof agent.definition === 'object' &&
+        'definition' in agent.definition);
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA4FA,MAAM,UAAU,cAAc,CAAC,KAAU;IACvC,OAAO,CACL,KAAK,KAAK,IAAI;QACd,OAAO,KAAK,KAAK,QAAQ;QACzB,YAAY,IAAI,KAAK;QACrB,cAAc,IAAI,KAAK;QACvB,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ;QACpC,YAAY,IAAI,KAAK,CAAC,UAAU,CACjC,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@alveus-ai/core",
+  "version": "0.1.0",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "node --import tsx --test test/**/*.test.ts",
+    "type-check": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}

package/src/agent.ts

@@ -0,0 +1,59 @@
+import crypto from 'node:crypto';
+import type { Agent, AgentHandler, AgentOptions, AgentDefinition } from './types.js';
+
+/**
+ * Define an Alveus agent.
+ *
+ * @example
+ * ```ts
+ * const myAgent = agent$(
+ *   async (state, event, ctx) => {
+ *     const reply = await ctx.llm.chat([{ role: 'user', content: event.message }]);
+ *     return { reply };
+ *   },
+ *   { name: 'my-agent' }
+ * );
+ * ```
+ */
+export function agent$<TState = any, TEvent = any, TContext = any, TResult = any>(
+  handler: AgentHandler<TState, TEvent, TContext, TResult>,
+  options?: AgentOptions,
+): Agent<TState, TEvent, TContext, TResult> {
+  // In development mode, we compute the hash of the handler source
+  const handlerSource = handler.toString();
+  const hash = computeHash(handlerSource);
+
+  const definition: AgentDefinition<TState, TEvent, TContext> = {
+    hash,
+    inputs: {
+      state: 'any',
+      event: 'any',
+      context: 'any',
+    },
+    metadata: {
+      name: options?.name,
+      version: options?.version,
+      description: options?.description,
+    },
+  };
+
+  return {
+    definition,
+    handler,
+    options,
+  };
+}
+
+/**
+ * Compute SHA-256 hash of a string
+ */
+function computeHash(source: string): string {
+  return crypto.createHash('sha256').update(source).digest('hex');
+}
+
+/**
+ * Serialize an agent handler to its source string representation.
+ */
+export function serializeHandler(handler: (...args: unknown[]) => unknown): string {
+  return handler.toString();
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+/**
+ * @alveus-ai/core - The runtime SDK for Alveus agents
+ *
+ * This package provides the core primitives for defining and executing agents.
+ */
+
+// Agent definition and serialization
+export { agent$, serializeHandler } from './agent.js';
+
+// Core types
+export type {
+  Agent,
+  AgentDefinition,
+  AgentHandler,
+  AgentOptions,
+  ExecutionContext,
+  VirtualAgent,
+} from './types.js';
+
+// Virtual Agent support
+export { isVirtualAgent } from './types.js';
+
+// Runtime abstraction layer
+export { isDurableContext, withDurableContext } from './runtime.js';
+
+export type {
+  // Runtime interfaces
+  DurableExecutionContext,
+  ExecutionRequest,
+  ExecutionResult,
+  ExecutionStatus,
+  Registry,
+  Runtime,
+  RuntimeConfig,
+  SimpleRuntimeConfig,
+  DurableRuntimeConfig,
+  // LLM capability
+  ChatMessage,
+  ChatOptions,
+  LLMCapability,
+  // Storage capability
+  StorageCapability,
+  BlobStore,
+  // Event capability
+  AlveusEvent,
+  EventCapability,
+  // Logger capability
+  LoggerCapability,
+} from './runtime.js';

package/src/runtime.ts

@@ -0,0 +1,576 @@
+/**
+ * Runtime Abstraction Layer
+ *
+ * This module defines the interfaces that allow Alveus to run on different
+ * execution backends.
+ *
+ * Key concepts:
+ * - ExecutionContext: What agents see (call, sleep, emit, etc.)
+ * - Runtime: The execution environment that provides the context
+ * - LLMCapability: Model-agnostic AI generation
+ * - StorageCapability: Large payload handling via content-addressed references
+ * - EventCapability: Reactive event system for external triggers
+ */
+
+import type { ExecutionContext } from './types.js';
+
+// ============================================================================
+// Event Capability
+// ============================================================================
+
+/**
+ * AlveusEvent - A durable event in the system
+ */
+export interface AlveusEvent {
+  /** Unique event ID */
+  id: string;
+
+  /** Topic/channel for routing (e.g., "market.btc.price", "user.approval") */
+  topic: string;
+
+  /** Event payload - any JSON-serializable data */
+  data: any;
+
+  /** Source identifier (e.g., workflow ID, external system) */
+  source?: string;
+
+  /** Unix timestamp in milliseconds */
+  timestamp: number;
+
+  /** Optional target workflow ID for direct routing */
+  targetWorkflowId?: string;
+}
+
+/**
+ * EventCapability - Reactive event system for agents
+ *
+ * Enables agents to:
+ * 1. Publish events to the global event bus
+ * 2. Pause execution and wait for specific events (durable wait)
+ *
+ * @example
+ * ```ts
+ * // Publish an event
+ * await ctx.events.emit('order.completed', { orderId: '123', total: 99.99 });
+ *
+ * // Wait for an external event (durable - survives restarts)
+ * const approval = await ctx.events.waitFor('human.approval', 60000);
+ * if (approval.data.approved) {
+ *   // Continue with approved action
+ * }
+ * ```
+ */
+export interface EventCapability {
+  /**
+   * Publish an event to the global event bus
+   *
+   * @param topic - Event topic for routing (e.g., "user.signup", "order.paid")
+   * @param data - Event payload (must be JSON-serializable)
+   */
+  emit(topic: string, data: any): Promise<void>;
+
+  /**
+   * Pause execution and wait for a specific event topic
+   *
+   * This is a DURABLE wait - the workflow will resume even after:
+   * - Worker restarts
+   * - System failures
+   * - Long delays (hours, days)
+   *
+   * @param topic - Event topic to wait for
+   * @param timeoutMs - Optional timeout in milliseconds
+   * @returns The event that matched the topic
+   * @throws TimeoutError if timeout is reached without receiving event
+   */
+  waitFor(topic: string, timeoutMs?: number): Promise<AlveusEvent>;
+}
+
+// ============================================================================
+// Secrets Capability
+// ============================================================================
+
+/**
+ * SecretsCapability - Secure runtime secrets for agents
+ *
+ * Provides access to secrets that are securely injected into the
+ * agent's execution context at runtime.
+ *
+ * @example
+ * ```ts
+ * // Get a secret
+ * const apiKey = ctx.secrets.get('OPENAI_API_KEY');
+ * if (!apiKey) throw new Error('OPENAI_API_KEY secret not configured');
+ *
+ * // Check if a secret exists
+ * if (ctx.secrets.has('DATABASE_URL')) {
+ *   // Connect to database
+ * }
+ *
+ * // List available secrets (for debugging - shows keys only)
+ * console.log('Available secrets:', ctx.secrets.keys());
+ * ```
+ */
+export interface SecretsCapability {
+  /**
+   * Get a secret value by key
+   *
+   * @param key - Secret key (e.g., "OPENAI_API_KEY")
+   * @returns The secret value or undefined if not set
+   */
+  get(key: string): string | undefined;
+
+  /**
+   * Check if a secret exists
+   *
+   * @param key - Secret key to check
+   */
+  has(key: string): boolean;
+
+  /**
+   * Get all available secret keys (not values - for debugging)
+   *
+   * @returns Array of secret key names
+   */
+  keys(): string[];
+}
+
+// ============================================================================
+// Logger Capability
+// ============================================================================
+
+/**
+ * LoggerCapability - Deterministic logging for agents
+ *
+ * Provides a consistent logging interface that is safe for use in all
+ * execution environments, including replay-safe durable runtimes.
+ *
+ * @example
+ * ```ts
+ * ctx.logger.info('Processing order', { orderId: '123' });
+ * ctx.logger.warn('Retrying operation', { attempt: 2 });
+ * ctx.logger.error('Failed to process', { error: err.message });
+ * ```
+ */
+export interface LoggerCapability {
+  /** Log informational message */
+  info(message: string, attrs?: Record<string, any>): void;
+
+  /** Log warning message */
+  warn(message: string, attrs?: Record<string, any>): void;
+
+  /** Log error message */
+  error(message: string, attrs?: Record<string, any>): void;
+
+  /** Log debug message */
+  debug(message: string, attrs?: Record<string, any>): void;
+}
+
+// ============================================================================
+// LLM Capability
+// ============================================================================
+
+/**
+ * Chat message format - provider-agnostic
+ */
+export interface ChatMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+
+/**
+ * Options for LLM generation
+ */
+export interface ChatOptions {
+  /** Provider to use. Default: process.env.DEFAULT_LLM_PROVIDER or 'openai' */
+  provider?: 'openai' | 'anthropic' | 'ollama' | 'mock';
+
+  /** Model identifier (e.g., 'gpt-4o', 'claude-3-opus', 'llama2') */
+  model?: string;
+
+  /** Temperature for generation. Default: 0.7 */
+  temperature?: number;
+
+  /** Enforce JSON output format */
+  jsonMode?: boolean;
+
+  /** Maximum tokens to generate */
+  maxTokens?: number;
+
+  /** Stream ID for real-time token delivery. */
+  streamId?: string;
+}
+
+/**
+ * LLM Capability - Model-agnostic AI generation
+ *
+ * Allows agents to use any LLM provider without coupling to specific SDKs.
+ * The implementation handles provider routing, retries, and rate limits.
+ *
+ * @example
+ * ```ts
+ * const response = await ctx.llm.chat([
+ *   { role: 'system', content: 'You are a helpful assistant.' },
+ *   { role: 'user', content: 'What is 2+2?' }
+ * ], { provider: 'openai', model: 'gpt-4o' });
+ * ```
+ */
+export interface LLMCapability {
+  /**
+   * Generate a chat completion
+   *
+   * @param messages - Array of chat messages
+   * @param options - Provider and model options
+   * @returns The assistant's response content
+   */
+  chat(messages: ChatMessage[], options?: ChatOptions): Promise<string>;
+}
+
+// ============================================================================
+// Storage Capability
+// ============================================================================
+
+/**
+ * Storage Capability - Large payload handling via content-addressed references
+ *
+ * Solves payload size limits by offloading large data to external storage.
+ * Agents can pass massive context using small reference keys.
+ *
+ * @example
+ * ```ts
+ * // Store large context
+ * const key = await ctx.storage.put(JSON.stringify(largeHistory));
+ *
+ * // Pass key to child agent (small payload)
+ * await ctx.call(childAgent, { historyRef: key });
+ *
+ * // Child retrieves the data
+ * const history = JSON.parse(await ctx.storage.get(key));
+ * ```
+ */
+export interface StorageCapability {
+  /**
+   * Store data and get a reference key
+   *
+   * @param data - String or Buffer to store
+   * @returns Content-addressed key (e.g., "blob:sha256hash")
+   */
+  put(data: string | Buffer): Promise<string>;
+
+  /**
+   * Retrieve data by key
+   *
+   * @param key - The reference key from put()
+   * @returns The stored data, or null if not found
+   */
+  get(key: string): Promise<string | null>;
+}
+
+/**
+ * BlobStore Interface - Provider-agnostic blob storage abstraction
+ */
+export interface BlobStore {
+  /**
+   * Store data and return content-addressed key
+   */
+  put(data: string | Buffer): Promise<string>;
+
+  /**
+   * Retrieve data by key
+   */
+  get(key: string): Promise<string | null>;
+
+  /**
+   * Check if a blob exists
+   */
+  exists(key: string): Promise<boolean>;
+
+  /**
+   * Delete a blob (optional - for cleanup)
+   */
+  delete?(key: string): Promise<void>;
+
+  /**
+   * List all blob keys (optional - for admin/debug)
+   */
+  list?(): Promise<string[]>;
+}
+
+/**
+ * Extended ExecutionContext with durable execution primitives
+ *
+ * This extends the base ExecutionContext with methods needed for
+ * durable execution (sleep, scheduleAt, etc.)
+ */
+export interface DurableExecutionContext extends ExecutionContext {
+  /**
+   * Sleep for a duration (durable — survives process restarts)
+   *
+   * @param duration - Duration in milliseconds, or ISO 8601 duration string
+   * @example
+   * await ctx.sleep(5000);           // Sleep for 5 seconds
+   * await ctx.sleep('PT1H');         // Sleep for 1 hour (ISO 8601)
+   * await ctx.sleep('P1D');          // Sleep for 1 day
+   */
+  sleep(duration: number | string): Promise<void>;
+
+  /**
+   * Schedule execution to resume at a specific time
+   *
+   * @param timestamp - ISO 8601 timestamp or Date object
+   * @example
+   * await ctx.sleepUntil('2024-12-25T00:00:00Z');
+   * await ctx.sleepUntil(new Date('2024-12-25'));
+   */
+  sleepUntil(timestamp: string | Date): Promise<void>;
+
+  /**
+   * Get the current workflow/execution ID
+   * Useful for correlation and debugging
+   */
+  getExecutionId(): string;
+
+  /**
+   * Get the current attempt number (for retries)
+   */
+  getAttempt(): number;
+
+  /** Deterministic logger (safe for durable execution replay) */
+  log: {
+    info(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+    debug(message: string, ...args: any[]): void;
+  };
+}
+
+/**
+ * Execution Request - Input to execute an agent
+ */
+export interface ExecutionRequest<TState = any, TEvent = any> {
+  /** The content hash of the agent to execute */
+  hash: string;
+
+  /** The state to pass to the agent */
+  state: TState;
+
+  /** The event/input to pass to the agent */
+  event: TEvent;
+
+  /** Optional execution ID (generated if not provided) */
+  executionId?: string;
+
+  /** Optional parent execution ID (for tracing) */
+  parentExecutionId?: string;
+}
+
+/**
+ * Execution Result - Output from agent execution
+ */
+export interface ExecutionResult<TResult = any> {
+  /** Whether execution succeeded */
+  success: boolean;
+
+  /** The result if successful */
+  result?: TResult;
+
+  /** Error message if failed */
+  error?: string;
+
+  /** Execution metadata */
+  metadata: {
+    hash: string;
+    executionId: string;
+    duration: number;
+    timestamp: string;
+    attempts?: number;
+  };
+}
+
+/**
+ * Registry Interface - Abstraction for blob storage
+ */
+export interface Registry {
+  /** Store a blob and return its hash */
+  store(hash: string, content: string): Promise<void>;
+
+  /** Retrieve a blob by hash */
+  retrieve(hash: string): Promise<string | null>;
+
+  /** List all stored hashes */
+  list(): Promise<string[]>;
+
+  /** Check if a hash exists */
+  exists(hash: string): Promise<boolean>;
+}
+
+/**
+ * Runtime Interface - The execution environment abstraction
+ */
+export interface Runtime {
+  /** Runtime name for debugging */
+  readonly name: string;
+
+  /** Start the runtime (connect to services, etc.) */
+  start(): Promise<void>;
+
+  /** Stop the runtime gracefully */
+  stop(): Promise<void>;
+
+  /**
+   * Execute an agent by hash
+   *
+   * @param request - The execution request
+   * @returns The execution result
+   */
+  execute<TState = any, TEvent = any, TResult = any>(
+    request: ExecutionRequest<TState, TEvent>,
+  ): Promise<ExecutionResult<TResult>>;
+
+  /**
+   * Get the status of an execution
+   *
+   * @param executionId - The execution ID to check
+   */
+  getExecutionStatus(executionId: string): Promise<ExecutionStatus>;
+
+  /**
+   * Cancel a running execution
+   *
+   * @param executionId - The execution ID to cancel
+   */
+  cancelExecution(executionId: string): Promise<void>;
+}
+
+/**
+ * Execution Status - Current state of an execution
+ */
+export interface ExecutionStatus {
+  executionId: string;
+  hash: string;
+  status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+  startedAt?: string;
+  completedAt?: string;
+  error?: string;
+  result?: any;
+}
+
+/**
+ * Runtime Configuration
+ */
+export interface RuntimeConfig {
+  /** Registry for blob storage */
+  registry: Registry;
+
+  /** Custom capability providers */
+  capabilities?: Record<string, any>;
+}
+
+/**
+ * Durable runtime configuration
+ */
+export interface DurableRuntimeConfig extends RuntimeConfig {
+  /** Server address */
+  address: string;
+
+  /** Namespace */
+  namespace: string;
+
+  /** Task queue name */
+  taskQueue: string;
+
+  /** Worker identity */
+  identity?: string;
+}
+
+/**
+ * Simple runtime configuration
+ */
+export interface SimpleRuntimeConfig extends RuntimeConfig {
+  /** Port to listen on */
+  port?: number;
+
+  /** Host to bind to */
+  host?: string;
+}
+
+/**
+ * Type guard for checking if context supports durable execution
+ */
+export function isDurableContext(ctx: ExecutionContext): ctx is DurableExecutionContext {
+  return 'sleep' in ctx && typeof (ctx as any).sleep === 'function';
+}
+
+/**
+ * Helper to create a runtime-agnostic agent handler
+ *
+ * This wrapper ensures agents can run on any runtime by:
+ * 1. Providing safe defaults for non-durable contexts
+ * 2. Adding type safety for durable operations
+ *
+ * @example
+ * ```ts
+ * const myAgent = agent$(
+ *   withDurableContext(async (state, event, ctx) => {
+ *     // ctx is now typed as DurableExecutionContext
+ *     await ctx.sleep(5000);
+ *     const result = await ctx.call(otherAgent, { data: 'hello' });
+ *     return { processed: true };
+ *   })
+ * );
+ * ```
+ */
+export function withDurableContext<TState, TEvent, TResult>(
+  handler: (state: TState, event: TEvent, ctx: DurableExecutionContext) => Promise<TResult>,
+): (state: TState, event: TEvent, ctx: ExecutionContext) => Promise<TResult> {
+  return async (state: TState, event: TEvent, ctx: ExecutionContext) => {
+    // If not a durable context, provide fallback implementations
+    const durableCtx: DurableExecutionContext = isDurableContext(ctx)
+      ? ctx
+      : {
+          ...ctx,
+          sleep: async (duration: number | string) => {
+            const ms = typeof duration === 'number' ? duration : parseDuration(duration);
+            return new Promise((resolve) => setTimeout(resolve, ms));
+          },
+          sleepUntil: async (timestamp: string | Date) => {
+            const target = typeof timestamp === 'string' ? new Date(timestamp) : timestamp;
+            const now = Date.now();
+            const delay = target.getTime() - now;
+            if (delay > 0) {
+              await new Promise((resolve) => setTimeout(resolve, delay));
+            }
+          },
+          getExecutionId: () => `simple-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+          getAttempt: () => 1,
+          log: {
+            info: (msg, ...args) => console.log(`[INFO] ${msg}`, ...args),
+            warn: (msg, ...args) => console.warn(`[WARN] ${msg}`, ...args),
+            error: (msg, ...args) => console.error(`[ERROR] ${msg}`, ...args),
+            debug: (msg, ...args) => console.debug(`[DEBUG] ${msg}`, ...args),
+          },
+        };
+
+    return handler(state, event, durableCtx);
+  };
+}
+
+/**
+ * Parse ISO 8601 duration string to milliseconds
+ * Supports: PT#H, PT#M, PT#S, P#D formats
+ */
+function parseDuration(duration: string): number {
+  const match = duration.match(/^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$/);
+  if (!match) {
+    throw new Error(`Invalid duration format: ${duration}`);
+  }
+
+  const [, days, hours, minutes, seconds] = match;
+  let ms = 0;
+
+  if (days) ms += parseInt(days, 10) * 24 * 60 * 60 * 1000;
+  if (hours) ms += parseInt(hours, 10) * 60 * 60 * 1000;
+  if (minutes) ms += parseInt(minutes, 10) * 60 * 1000;
+  if (seconds) ms += parseFloat(seconds) * 1000;
+
+  return ms;
+}

package/src/types.ts

@@ -0,0 +1,146 @@
+/**
+ * Core type definitions for Alveus agents
+ */
+
+/**
+ * Agent Definition - The immutable representation of an agent
+ */
+export interface AgentDefinition<TState = any, TEvent = any, TContext = any> {
+  /** Content-addressed hash of the agent code */
+  hash: string;
+
+  /** Input schema definition */
+  inputs: {
+    state: string;
+    event: string;
+    context: string;
+  };
+
+  /** Metadata about the agent */
+  metadata?: {
+    name?: string;
+    version?: string;
+    description?: string;
+  };
+
+  /** Phantom properties for type safety (not present at runtime) */
+  __types?: {
+    state: TState;
+    event: TEvent;
+    context: TContext;
+  };
+}
+
+/**
+ * Agent Handler Function - The actual executable code
+ */
+export type AgentHandler<TState = any, TEvent = any, TContext = any, TResult = any> = (
+  state: TState,
+  event: TEvent,
+  context: TContext,
+) => Promise<TResult> | TResult;
+
+/**
+ * Agent Configuration Options
+ */
+export interface AgentOptions {
+  /** Optional name for debugging/logging */
+  name?: string;
+
+  /** Optional description */
+  description?: string;
+
+  /** Optional version identifier */
+  version?: string;
+}
+
+/**
+ * Agent - The result of calling agent$()
+ */
+export interface Agent<TState = any, TEvent = any, TContext = any, TResult = any> {
+  /** The agent definition (with hash) */
+  definition: AgentDefinition<TState, TEvent, TContext>;
+
+  /** The handler function (only available at compile time) */
+  handler: AgentHandler<TState, TEvent, TContext, TResult>;
+
+  /** Optional configuration */
+  options?: AgentOptions;
+}
+
+/**
+ * Virtual Agent - A configuration wrapper around a compiled agent.
+ *
+ * Allows creating pre-configured variants of an agent without
+ * generating new code.
+ *
+ * @example
+ * ```ts
+ * const myAgent = createReActAgent({ systemPrompt: '...', tools: {...} });
+ * ```
+ */
+export interface VirtualAgent<TInput = any> {
+  /** The underlying agent definition */
+  definition: Agent;
+
+  /** Pre-filled input that gets merged with runtime input */
+  defaultInput: Partial<TInput>;
+}
+
+/**
+ * Type guard to check if something is a VirtualAgent
+ */
+export function isVirtualAgent(agent: any): agent is VirtualAgent {
+  return (
+    agent !== null &&
+    typeof agent === 'object' &&
+    'definition' in agent &&
+    'defaultInput' in agent &&
+    typeof agent.definition === 'object' &&
+    'definition' in agent.definition // Has nested Agent structure
+  );
+}
+
+/**
+ * Execution Context - Injected capabilities and utilities
+ *
+ * This is the base context available to all agents. For durable execution
+ * features (sleep, sleepUntil, etc.), see DurableExecutionContext in runtime.ts.
+ */
+export interface ExecutionContext {
+  /** Unique identifier for this execution */
+  workflowId: string;
+
+  /** Call another agent (RPC-style) */
+  call<TInput = any, TOutput = any>(
+    agent: Agent<any, TInput, any, TOutput> | string,
+    input: TInput,
+  ): Promise<TOutput>;
+
+  /**
+   * Sleep for a duration
+   * @param duration - Duration in milliseconds
+   */
+  sleep(duration: number): Promise<void>;
+
+  /** Get a value from state storage */
+  getState<T = any>(key: string): Promise<T | null>;
+
+  /** Set a value in state storage */
+  setState(key: string, value: any): Promise<void>;
+
+  /** LLM capability - model-agnostic AI generation */
+  llm: import('./runtime.js').LLMCapability;
+
+  /** Storage capability - large payload handling */
+  storage: import('./runtime.js').StorageCapability;
+
+  /** Event capability - publish events and wait for external triggers */
+  events: import('./runtime.js').EventCapability;
+
+  /** Logger capability - deterministic, replay-safe logging */
+  logger: import('./runtime.js').LoggerCapability;
+
+  /** Secrets capability - secure runtime secrets */
+  secrets: import('./runtime.js').SecretsCapability;
+}

package/test/capability-injection.test.ts

@@ -0,0 +1,99 @@
+/**
+ * Capability Injection Test
+ *
+ * Validates the "Data-Only Closures" + "Capabilities" pattern:
+ * agent handlers receive all external dependencies via the context
+ * parameter, never via captured outer scope.
+ */
+
+import { describe, test } from 'node:test';
+import assert from 'node:assert';
+
+describe('Capability Injection', () => {
+  test('should inject capabilities into a handler via context', async () => {
+    const handler = async (
+      event: { data: string },
+      ctx: { db: { save: (data: string) => Promise<string> } },
+    ) => {
+      const result = await ctx.db.save(event.data);
+      return { saved: result };
+    };
+
+    const mockContext = {
+      db: {
+        save: async (data: string) => `saved:${data}`,
+      },
+    };
+
+    const result = await handler({ data: 'hello' }, mockContext);
+    assert.deepStrictEqual(result, { saved: 'saved:hello' });
+  });
+
+  test('should pass configuration via event/state, not outer scope', async () => {
+    const handler = async (
+      event: { url: string; config: { apiVersion: string; maxRetries: number } },
+      ctx: { fetch: (url: string) => Promise<string> },
+    ) => {
+      const fullUrl = `${event.url}/${event.config.apiVersion}?retries=${event.config.maxRetries}`;
+      return ctx.fetch(fullUrl);
+    };
+
+    const mockContext = {
+      fetch: async (url: string) => `response from ${url}`,
+    };
+
+    const result = await handler(
+      { url: 'https://api.example.com', config: { apiVersion: 'v2', maxRetries: 3 } },
+      mockContext,
+    );
+
+    assert.ok(result.includes('v2'));
+    assert.ok(result.includes('retries=3'));
+  });
+
+  test('should handle complex context with multiple capabilities', async () => {
+    interface Context {
+      db: {
+        query: (sql: string) => Promise<any[]>;
+        save: (data: any) => Promise<string>;
+      };
+      llm: {
+        complete: (prompt: string) => Promise<string>;
+      };
+      logger: {
+        info: (msg: string) => void;
+      };
+    }
+
+    const handler = async (event: { userId: string; prompt: string }, ctx: Context) => {
+      ctx.logger.info(`Processing request for user ${event.userId}`);
+      await ctx.db.query(`SELECT * FROM users WHERE id = '${event.userId}'`);
+      const aiResponse = await ctx.llm.complete(event.prompt);
+      const saveId = await ctx.db.save({ userId: event.userId, response: aiResponse });
+      return { saveId, response: aiResponse };
+    };
+
+    const logs: string[] = [];
+    const mockContext: Context = {
+      db: {
+        query: async () => [{ id: '123', name: 'Test User' }],
+        save: async () => 'save-id-456',
+      },
+      llm: {
+        complete: async () => 'AI generated response',
+      },
+      logger: {
+        info: (msg) => logs.push(msg),
+      },
+    };
+
+    const result = await handler(
+      { userId: 'user-789', prompt: 'Summarize this document' },
+      mockContext,
+    );
+
+    assert.strictEqual(result.saveId, 'save-id-456');
+    assert.strictEqual(result.response, 'AI generated response');
+    assert.ok(logs.length > 0);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}