@chainlink/cre-sdk 0.0.0 → 0.0.1-alpha

package/dist/sdk/cre/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Public API for the CRE SDK.
+ */
+import { ClientCapability as EVMClient } from '../../generated-sdk/capabilities/blockchain/evm/v1alpha/client_sdk_gen';
+import { ClientCapability as HTTPClient } from '../../generated-sdk/capabilities/networking/http/v1alpha/client_sdk_gen';
+import { HTTPCapability } from '../../generated-sdk/capabilities/networking/http/v1alpha/http_sdk_gen';
+import { CronCapability } from '../../generated-sdk/capabilities/scheduler/cron/v1/cron_sdk_gen';
+import { runInNodeMode } from '../runtime/run-in-node-mode';
+import { Runner } from '../workflow';
+export type { NodeRuntime, Runtime } from '../runtime/runtime';
+export declare const cre: {
+    capabilities: {
+        CronCapability: typeof CronCapability;
+        HTTPCapability: typeof HTTPCapability;
+        HTTPClient: typeof HTTPClient;
+        EVMClient: typeof EVMClient;
+    };
+    config: <TConfig>({ configParser, configSchema, }?: import("../utils/config").ConfigHandlerParams) => Promise<TConfig>;
+    handler: <TRawTriggerOutput extends import("@bufbuild/protobuf").Message<string>, TTriggerOutput = TRawTriggerOutput, TConfig = unknown>(trigger: import("../utils/triggers/trigger-interface").Trigger<TRawTriggerOutput, TTriggerOutput>, fn: import("../workflow").HandlerFn<TConfig, TTriggerOutput>) => import("../workflow").HandlerEntry<TConfig, TRawTriggerOutput, TTriggerOutput>;
+    newRunner: typeof Runner.newRunner;
+    runInNodeMode: typeof runInNodeMode;
+    utils: {
+        fetch: (input: import("../utils/capabilities/http/fetch").CreFetchRequest) => Promise<{
+            statusCode: number;
+            headers: {
+                [key: string]: string;
+            };
+            body: string;
+        }>;
+    };
+    sendResponseValue: (value: import("../utils").Value) => void;
+    sendError: (error: string | Error) => void;
+    withErrorBoundary: (fn: () => Promise<void>) => Promise<void>;
+};

package/dist/sdk/cre/index.js

@@ -0,0 +1,35 @@
+/**
+ * Public API for the CRE SDK.
+ */
+import { ClientCapability as EVMClient } from '../../generated-sdk/capabilities/blockchain/evm/v1alpha/client_sdk_gen';
+import { ClientCapability as HTTPClient } from '../../generated-sdk/capabilities/networking/http/v1alpha/client_sdk_gen';
+import { HTTPCapability } from '../../generated-sdk/capabilities/networking/http/v1alpha/http_sdk_gen';
+import { CronCapability } from '../../generated-sdk/capabilities/scheduler/cron/v1/cron_sdk_gen';
+import { runInNodeMode } from '../runtime/run-in-node-mode';
+import { creFetch } from '../utils/capabilities/http/fetch';
+import { configHandler } from '../utils/config';
+import { withErrorBoundary } from '../utils/error-boundary';
+import { prepareRuntime } from '../utils/prepare-runtime';
+import { sendError } from '../utils/send-error';
+import { sendResponseValue } from '../utils/send-response-value';
+import { handler, Runner } from '../workflow';
+prepareRuntime();
+versionV2();
+export const cre = {
+    capabilities: {
+        CronCapability,
+        HTTPCapability,
+        HTTPClient,
+        EVMClient,
+    },
+    config: configHandler,
+    handler,
+    newRunner: Runner.newRunner,
+    runInNodeMode,
+    utils: {
+        fetch: creFetch,
+    },
+    sendResponseValue,
+    sendError,
+    withErrorBoundary,
+};

package/dist/sdk/engine/execute.d.ts

@@ -0,0 +1,4 @@
+import { type CapabilityResponse, type ExecuteRequest } from '../../generated/sdk/v1alpha/sdk_pb';
+import type { Runtime } from '../runtime/runtime';
+import type { Workflow } from '../workflow';
+export declare const handleExecuteRequest: <TConfig>(req: ExecuteRequest, workflow: Workflow<TConfig>, config: TConfig, runtime: Runtime) => Promise<CapabilityResponse | undefined>;

package/dist/sdk/engine/execute.js

@@ -0,0 +1,12 @@
+import { Mode, } from '../../generated/sdk/v1alpha/sdk_pb';
+import { handleExecutionPhase } from './handleExecutionPhase';
+import { handleSubscribePhase } from './handleSubscribePhase';
+export const handleExecuteRequest = async (req, workflow, config, runtime) => {
+    if (req.request.case === 'subscribe') {
+        return handleSubscribePhase(req, workflow);
+    }
+    if (req.request.case === 'trigger') {
+        runtime.switchModes(Mode.DON);
+        return handleExecutionPhase(req, workflow, config, runtime);
+    }
+};

package/dist/sdk/engine/execute.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/engine/execute.test.js

@@ -0,0 +1,129 @@
+import { describe, expect, mock, test } from 'bun:test';
+import { create, fromBinary, toBinary } from '@bufbuild/protobuf';
+import { EmptySchema } from '@bufbuild/protobuf/wkt';
+import { TriggerEventSchema as ActionTriggerEventSchema } from '../../generated/capabilities/internal/actionandtrigger/v1/action_and_trigger_pb';
+import { OutputsSchema as BasicTriggerOutputsSchema } from '../../generated/capabilities/internal/basictrigger/v1/basic_trigger_pb';
+import { ExecuteRequestSchema, ExecutionResultSchema, } from '../../generated/sdk/v1alpha/sdk_pb';
+import { BasicCapability as ActionAndTriggerCapability } from '../../generated-sdk/capabilities/internal/actionandtrigger/v1/basic_sdk_gen';
+import { BasicCapability as BasicTriggerCapability } from '../../generated-sdk/capabilities/internal/basictrigger/v1/basic_sdk_gen';
+import { handleExecuteRequest } from './execute';
+import { mockHostBindings } from '../testhelpers/mock-host-bindings';
+import { mockedRuntime } from '../testhelpers/mock-runtime';
+import { getTypeUrl } from '../utils/typeurl';
+import { handler } from '../workflow';
+const emptyConfig = {};
+const decodeExecutionResult = (result) => fromBinary(ExecutionResultSchema, result);
+describe('engine/execute', () => {
+    test('subscribe returns TriggerSubscriptionRequest wrapped in ExecutionResult', async () => {
+        const subs = [];
+        // mock sendResponse to capture the payload
+        mockHostBindings.sendResponse.mockImplementation((resp) => {
+            const exec = decodeExecutionResult(resp);
+            const ts = exec.result.case === 'triggerSubscriptions' ? exec.result.value : undefined;
+            expect(ts).toBeDefined();
+            expect(ts.subscriptions.length).toBe(3);
+            ts.subscriptions.forEach((s) => subs.push(`${s.id}:${s.method}:${s.payload?.typeUrl}`));
+            return 0;
+        });
+        const basic = new BasicTriggerCapability();
+        const action = new ActionAndTriggerCapability();
+        const workflow = [
+            handler(basic.trigger({ name: 'first-trigger', number: 100 }), () => { }),
+            handler(action.trigger({ name: 'second-trigger', number: 150 }), () => { }),
+            handler(basic.trigger({ name: 'third-trigger', number: 200 }), () => { }),
+        ];
+        const req = create(ExecuteRequestSchema, {
+            config: new Uint8Array(),
+            request: { case: 'subscribe', value: create(EmptySchema) },
+            maxResponseSize: 0n,
+        });
+        await handleExecuteRequest(req, workflow, emptyConfig, mockedRuntime);
+        expect(subs[0]).toContain('basic-test-trigger@1.0.0:Trigger:type.googleapis.com/capabilities.internal.basictrigger.v1.Config');
+        expect(subs[1]).toContain('basic-test-action-trigger@1.0.0:Trigger:type.googleapis.com/capabilities.internal.actionandtrigger.v1.Config');
+        expect(subs[2]).toContain('basic-test-trigger@1.0.0:Trigger:type.googleapis.com/capabilities.internal.basictrigger.v1.Config');
+        mockHostBindings.sendResponse.mockRestore();
+    });
+    test('trigger routes by id and decodes payload for correct handler', async () => {
+        const calls = [];
+        const basic = new BasicTriggerCapability();
+        const action = new ActionAndTriggerCapability();
+        const workflow = [
+            handler(basic.trigger({ name: 'first-trigger', number: 100 }), (_e, _r, out) => {
+                // @ts-ignore
+                calls.push(`basic:${out.coolOutput}`);
+            }),
+            handler(action.trigger({ name: 'second-trigger', number: 150 }), (_e, _r, out) => {
+                // @ts-ignore
+                calls.push(`action:${out.coolOutput}`);
+            }),
+            handler(basic.trigger({ name: 'third-trigger', number: 200 }), (_e, _r, out) => {
+                // @ts-ignore
+                calls.push(`basic2:${out.coolOutput}`);
+            }),
+        ];
+        // Build ExecuteRequest with id=1 (second handler) and payload of Action TriggerEvent
+        const payloadAny = {
+            typeUrl: getTypeUrl(ActionTriggerEventSchema),
+            value: toBinary(ActionTriggerEventSchema, create(ActionTriggerEventSchema, { coolOutput: 'different' })),
+        };
+        const req = create(ExecuteRequestSchema, {
+            config: new Uint8Array(),
+            request: {
+                case: 'trigger',
+                value: { id: 1n, payload: payloadAny },
+            },
+            maxResponseSize: 0n,
+        });
+        await handleExecuteRequest(req, workflow, emptyConfig, mockedRuntime);
+        expect(calls).toEqual(['action:different']);
+    });
+    test('trigger ignores out-of-range id (no handler invoked)', async () => {
+        const calls = [];
+        const basic = new BasicTriggerCapability();
+        const action = new ActionAndTriggerCapability();
+        const workflow = [
+            handler(basic.trigger({ name: 'first-trigger', number: 100 }), () => {
+                calls.push('basic');
+            }),
+            handler(action.trigger({ name: 'second-trigger', number: 150 }), () => {
+                calls.push('action');
+            }),
+        ];
+        const payloadAny = {
+            typeUrl: getTypeUrl(ActionTriggerEventSchema),
+            value: toBinary(ActionTriggerEventSchema, create(ActionTriggerEventSchema, { coolOutput: 'x' })),
+        };
+        const req = create(ExecuteRequestSchema, {
+            config: new Uint8Array(),
+            request: { case: 'trigger', value: { id: 999n, payload: payloadAny } },
+            maxResponseSize: 0n,
+        });
+        await handleExecuteRequest(req, workflow, emptyConfig, mockedRuntime);
+        expect(calls).toEqual([]);
+    });
+    test('trigger ignores typeUrl mismatch for targeted handler', async () => {
+        const calls = [];
+        const basic = new BasicTriggerCapability();
+        const action = new ActionAndTriggerCapability();
+        const workflow = [
+            handler(basic.trigger({ name: 'first-trigger', number: 100 }), () => {
+                calls.push('basic');
+            }),
+            handler(action.trigger({ name: 'second-trigger', number: 150 }), () => {
+                calls.push('action');
+            }),
+        ];
+        // Intentionally send BasicTriggerOutputs payload to the action trigger handler (index 1)
+        const payloadAny = {
+            typeUrl: `type.googleapis.com/${BasicTriggerOutputsSchema.typeName}`,
+            value: toBinary(BasicTriggerOutputsSchema, create(BasicTriggerOutputsSchema, { coolOutput: 'mismatch' })),
+        };
+        const req = create(ExecuteRequestSchema, {
+            config: new Uint8Array(),
+            request: { case: 'trigger', value: { id: 1n, payload: payloadAny } },
+            maxResponseSize: 0n,
+        });
+        await handleExecuteRequest(req, workflow, emptyConfig, mockedRuntime);
+        expect(calls).toEqual([]);
+    });
+});

package/dist/sdk/engine/handleExecutionPhase.d.ts

@@ -0,0 +1,4 @@
+import type { CapabilityResponse, ExecuteRequest } from '../../generated/sdk/v1alpha/sdk_pb';
+import type { Runtime } from '../runtime/runtime';
+import type { Workflow } from '../workflow';
+export declare const handleExecutionPhase: <TConfig>(req: ExecuteRequest, workflow: Workflow<TConfig>, config: TConfig, runtime: Runtime) => Promise<CapabilityResponse | undefined>;

package/dist/sdk/engine/handleExecutionPhase.js

@@ -0,0 +1,34 @@
+import { fromBinary } from '@bufbuild/protobuf';
+import { getTypeUrl } from '../utils/typeurl';
+export const handleExecutionPhase = async (req, workflow, config, runtime) => {
+    if (req.request.case !== 'trigger') {
+        return;
+    }
+    const triggerMsg = req.request.value;
+    const index = Number(triggerMsg.id);
+    if (Number.isFinite(index) && index >= 0 && index < workflow.length) {
+        const entry = workflow[index];
+        const schema = entry.trigger.outputSchema();
+        const payloadAny = triggerMsg.payload;
+        if (!payloadAny) {
+            return;
+        }
+        // Extra safety: verify payload typeUrl matches expected schema type
+        const expectedTypeUrl = getTypeUrl(schema);
+        if (payloadAny.typeUrl && payloadAny.typeUrl !== expectedTypeUrl) {
+            return;
+        }
+        /**
+         * Note: do not hardcode method name; routing by id is authoritative.
+         *
+         * This matches the GO SDK behavior, which also just checks for the id.
+         *
+         * @see https://github.com/smartcontractkit/cre-sdk-go/blob/5a41d81e3e072008484e85dc96d746401aafcba2/cre/wasm/runner.go#L81
+         * */
+        const decoded = fromBinary(schema, payloadAny.value);
+        const adapted = await entry.trigger.adapt(decoded);
+        // By default config is a JSON string, send as bytes
+        const handlerEnv = config || JSON.parse(Buffer.from(req.config).toString());
+        await entry.fn(handlerEnv, runtime, adapted);
+    }
+};

package/dist/sdk/engine/handleSubscribePhase.d.ts

@@ -0,0 +1,3 @@
+import type { ExecuteRequest } from '../../generated/sdk/v1alpha/sdk_pb';
+import type { Workflow } from '../workflow';
+export declare const handleSubscribePhase: <TConfig>(req: ExecuteRequest, workflow: Workflow<TConfig>) => undefined;

package/dist/sdk/engine/handleSubscribePhase.js

@@ -0,0 +1,23 @@
+import { create, toBinary } from '@bufbuild/protobuf';
+import { ExecutionResultSchema, TriggerSubscriptionRequestSchema, } from '../../generated/sdk/v1alpha/sdk_pb';
+import { hostBindings } from '../runtime/host-bindings';
+export const handleSubscribePhase = (req, workflow) => {
+    if (req.request.case !== 'subscribe') {
+        return;
+    }
+    // Build TriggerSubscriptionRequest from the workflow entries
+    const subscriptions = workflow.map((entry) => ({
+        id: entry.trigger.capabilityId(),
+        method: entry.trigger.method(),
+        payload: entry.trigger.configAsAny(),
+    }));
+    const subscriptionRequest = create(TriggerSubscriptionRequestSchema, {
+        subscriptions,
+    });
+    // Wrap in ExecutionResult.triggerSubscriptions
+    const execResult = create(ExecutionResultSchema, {
+        result: { case: 'triggerSubscriptions', value: subscriptionRequest },
+    });
+    const encoded = toBinary(ExecutionResultSchema, execResult);
+    hostBindings.sendResponse(encoded);
+};

package/dist/sdk/index.d.ts

@@ -0,0 +1 @@
+export * from './cre';

package/dist/sdk/index.js

@@ -0,0 +1 @@
+export * from './cre';

package/dist/sdk/logger.d.ts

@@ -0,0 +1,7 @@
+export type Logger = {
+    log: (message: string) => void;
+    info: (message: string) => void;
+    error: (message: string) => void;
+    warn: (message: string) => void;
+};
+export declare const logger: Logger;

package/dist/sdk/logger.js

@@ -0,0 +1,18 @@
+export const logger = {
+    log: (message) => {
+        console.log(message);
+        log(message);
+    },
+    info: (message) => {
+        console.info(message);
+        log(message);
+    },
+    error: (message) => {
+        console.error(message);
+        log(message);
+    },
+    warn: (message) => {
+        console.warn(message);
+        log(message);
+    },
+};

package/dist/sdk/runtime/errors.d.ts

@@ -0,0 +1,23 @@
+import type { Mode } from '../../generated/sdk/v1alpha/sdk_pb';
+export declare class DonModeError extends Error {
+    name: string;
+    capabilityId?: string;
+    method?: string;
+    mode?: Mode;
+    constructor(message?: string, options?: {
+        capabilityId?: string;
+        method?: string;
+        mode?: Mode;
+    });
+}
+export declare class NodeModeError extends Error {
+    name: string;
+    capabilityId?: string;
+    method?: string;
+    mode?: Mode;
+    constructor(message?: string, options?: {
+        capabilityId?: string;
+        method?: string;
+        mode?: Mode;
+    });
+}

package/dist/sdk/runtime/errors.js

@@ -0,0 +1,30 @@
+export class DonModeError extends Error {
+    name;
+    capabilityId;
+    method;
+    mode;
+    constructor(message = 'cannot use Runtime inside RunInNodeMode', options) {
+        super(message);
+        this.name = 'DonModeError';
+        if (options) {
+            this.capabilityId = options.capabilityId;
+            this.method = options.method;
+            this.mode = options.mode;
+        }
+    }
+}
+export class NodeModeError extends Error {
+    name;
+    capabilityId;
+    method;
+    mode;
+    constructor(message = 'cannot use NodeRuntime outside RunInNodeMode', options) {
+        super(message);
+        this.name = 'NodeModeError';
+        if (options) {
+            this.capabilityId = options.capabilityId;
+            this.method = options.method;
+            this.mode = options.mode;
+        }
+    }
+}

package/dist/sdk/runtime/host-bindings.d.ts

@@ -0,0 +1,14 @@
+import { Mode } from '../../generated/sdk/v1alpha/sdk_pb';
+export declare const hostBindings: {
+    switchModes: (args_0: Mode, ...args: unknown[]) => void;
+    log: (args_0: string, ...args: unknown[]) => void;
+    sendResponse: (args_0: Uint8Array<ArrayBufferLike> | Uint8Array<ArrayBuffer>, ...args: unknown[]) => number;
+    randomSeed: (args_0: Mode.DON | Mode.NODE, ...args: unknown[]) => number;
+    versionV2: (...args: unknown[]) => void;
+    callCapability: (args_0: Uint8Array<ArrayBufferLike> | Uint8Array<ArrayBuffer>, ...args: unknown[]) => number;
+    awaitCapabilities: (args_0: Uint8Array<ArrayBufferLike> | Uint8Array<ArrayBuffer>, args_1: number, ...args: unknown[]) => Uint8Array<ArrayBufferLike> | Uint8Array<ArrayBuffer>;
+    getSecrets: (args_0: Uint8Array<ArrayBufferLike> | Uint8Array<ArrayBuffer>, args_1: number, ...args: unknown[]) => any;
+    awaitSecrets: (args_0: Uint8Array<ArrayBufferLike> | Uint8Array<ArrayBuffer>, args_1: number, ...args: unknown[]) => Uint8Array<ArrayBufferLike> | Uint8Array<ArrayBuffer>;
+    getWasiArgs: (...args: unknown[]) => string;
+    now: (...args: unknown[]) => number;
+};

package/dist/sdk/runtime/host-bindings.js

@@ -0,0 +1,56 @@
+import { Mode } from '../../generated/sdk/v1alpha/sdk_pb';
+import { z } from 'zod';
+// Zod schema for validating global host functions
+const globalHostBindingsSchema = z.object({
+    switchModes: z.function().args(z.nativeEnum(Mode)).returns(z.void()),
+    log: z.function().args(z.string()).returns(z.void()),
+    sendResponse: z
+        .function()
+        .args(z.union([z.instanceof(Uint8Array), z.custom()]))
+        .returns(z.number()),
+    randomSeed: z
+        .function()
+        .args(z.union([z.literal(Mode.DON), z.literal(Mode.NODE)]))
+        .returns(z.number()),
+    versionV2: z.function().args().returns(z.void()),
+    callCapability: z
+        .function()
+        .args(z.union([z.instanceof(Uint8Array), z.custom()]))
+        .returns(z.number()),
+    awaitCapabilities: z
+        .function()
+        .args(z.union([z.instanceof(Uint8Array), z.custom()]), z.number())
+        .returns(z.union([z.instanceof(Uint8Array), z.custom()])),
+    getSecrets: z
+        .function()
+        .args(z.union([z.instanceof(Uint8Array), z.custom()]), z.number())
+        .returns(z.any()),
+    awaitSecrets: z
+        .function()
+        .args(z.union([z.instanceof(Uint8Array), z.custom()]), z.number())
+        .returns(z.union([z.instanceof(Uint8Array), z.custom()])),
+    getWasiArgs: z.function().args().returns(z.string()),
+    now: z.function().args().returns(z.number()),
+});
+// Validate global host functions at runtime
+const validateGlobalHostBindings = () => {
+    const globalFunctions = globalThis;
+    try {
+        return globalHostBindingsSchema.parse(globalFunctions);
+    }
+    catch (error) {
+        const missingFunctions = Object.keys(globalHostBindingsSchema.shape).filter((key) => !(key in globalFunctions));
+        throw new Error(`Missing required global host functions: ${missingFunctions.join(', ')}. ` +
+            `This indicates the runtime environment is not properly configured.`);
+    }
+};
+// Initialize validated global functions (lazy evaluation for testing)
+let _hostBindings = null;
+export const hostBindings = new Proxy({}, {
+    get(target, prop) {
+        if (!_hostBindings) {
+            _hostBindings = validateGlobalHostBindings();
+        }
+        return _hostBindings[prop];
+    },
+});

package/dist/sdk/runtime/index.d.ts

@@ -0,0 +1,3 @@
+export { runInNodeMode } from './run-in-node-mode';
+export type * from './runtime';
+export * from './runtime';

package/dist/sdk/runtime/index.js

@@ -0,0 +1,2 @@
+export { runInNodeMode } from './run-in-node-mode';
+export * from './runtime';

package/dist/sdk/runtime/run-in-node-mode.d.ts

@@ -0,0 +1,12 @@
+import { type NodeRuntime } from './runtime';
+import type { ConsensusAggregation, PrimitiveTypes, UnwrapOptions } from '../utils';
+/**
+ * Runs the provided builder inside Node mode and returns the consensus result Value.
+ * Ensures mode is switched back to DON even if errors occur.
+ */
+/**
+ * Runs the provided builder inside Node mode and returns the consensus result Value.
+ * For primitive types (number, bigint, Date, boolean, string), it will use unwrap()
+ * For complex types, it will use unwrapToType() with the provided options
+ */
+export declare function runInNodeMode<TArgs extends any[], TOutput>(fn: (nodeRuntime: NodeRuntime, ...args: TArgs) => Promise<TOutput> | TOutput, consesusAggretation: ConsensusAggregation<TOutput, true>, unwrapOptions?: TOutput extends PrimitiveTypes ? never : UnwrapOptions<TOutput>): (...args: TArgs) => Promise<TOutput>;

package/dist/sdk/runtime/run-in-node-mode.js

@@ -0,0 +1,47 @@
+import { create } from '@bufbuild/protobuf';
+import { Mode, SimpleConsensusInputsSchema } from '../../generated/sdk/v1alpha/sdk_pb';
+import { ConsensusCapability } from '../../generated-sdk/capabilities/internal/consensus/v1alpha/consensus_sdk_gen';
+import { runtime } from './runtime';
+import { Value } from '../utils';
+/**
+ * Runs the provided builder inside Node mode and returns the consensus result Value.
+ * Ensures mode is switched back to DON even if errors occur.
+ */
+/**
+ * Runs the provided builder inside Node mode and returns the consensus result Value.
+ * For primitive types (number, bigint, Date, boolean, string), it will use unwrap()
+ * For complex types, it will use unwrapToType() with the provided options
+ */
+export function runInNodeMode(fn, consesusAggretation, unwrapOptions) {
+    return async (...args) => {
+        const nodeRuntime = runtime.switchModes(Mode.NODE);
+        const consensusInput = create(SimpleConsensusInputsSchema, {
+            descriptors: consesusAggretation.descriptor,
+        });
+        if (consesusAggretation.defaultValue) {
+            // This cast is safe, since ConsensusAggregation can only have true its second argument if T extends CreSerializable<TOutput>
+            consensusInput.default = Value.from(consesusAggretation.defaultValue).proto();
+        }
+        try {
+            const observation = await fn(nodeRuntime, ...args);
+            // This cast is safe, since ConsensusAggregation can only have true its second argument if T extends CreSerializable<TOutput>
+            consensusInput.observation = {
+                case: 'value',
+                value: Value.from(observation).proto(),
+            };
+        }
+        catch (e) {
+            consensusInput.observation = { case: 'error', value: e.message || String(e) };
+        }
+        finally {
+            // Always restore DON mode before invoking consensus
+            runtime.switchModes(Mode.DON);
+        }
+        const consensus = new ConsensusCapability();
+        const result = await consensus.simple(consensusInput).result();
+        const wrappedValue = Value.wrap(result);
+        return unwrapOptions
+            ? wrappedValue.unwrapToType(unwrapOptions)
+            : wrappedValue.unwrap();
+    };
+}

package/dist/sdk/runtime/run-in-node-mode.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/runtime/run-in-node-mode.test.js

@@ -0,0 +1,116 @@
+import { describe, expect, mock, test } from 'bun:test';
+import { create } from '@bufbuild/protobuf';
+import { AggregationType, ConsensusDescriptorSchema, } from '../../generated/sdk/v1alpha/sdk_pb';
+import { BasicActionCapability } from '../../generated-sdk/capabilities/internal/basicaction/v1/basicaction_sdk_gen';
+import { ConsensusCapability } from '../../generated-sdk/capabilities/internal/consensus/v1alpha/consensus_sdk_gen';
+import { runInNodeMode } from './run-in-node-mode';
+// Mock the host bindings before importing runtime
+import { calls } from '../testhelpers/mock-host-bindings';
+import { consensusIdenticalAggregation, consensusMedianAggregation, Value } from '../utils';
+function expectObservation(i) {
+    expect(i.observation.case).toEqual('value');
+    return Value.wrap(i.observation.value);
+}
+function expectError(i) {
+    expect(i.observation.case).toEqual('error');
+    return i.observation.value;
+}
+describe('runInNodeMode', () => {
+    test('successful run', async () => {
+        // Clear the calls array for this test
+        calls.length = 0;
+        const anyObservation = 120;
+        const anyResult = 123;
+        // spy on consensus.simple
+        const origSimple = ConsensusCapability.prototype.simple;
+        ConsensusCapability.prototype.simple = mock((inputs) => {
+            calls.push('CONSENSUS_SIMPLE');
+            // biome-ignore lint/suspicious/noExplicitAny: Needed for runtime type checking of protocol buffer messages
+            expect(inputs.$typeName).toBeDefined();
+            const castedInputs = inputs;
+            expect(castedInputs.default).toBeUndefined();
+            const actualObservation = expectObservation(castedInputs);
+            expect(Value.from(anyObservation)).toEqual(actualObservation);
+            const expectedDescriptor = create(ConsensusDescriptorSchema, {
+                descriptor: {
+                    case: 'aggregation',
+                    value: AggregationType.MEDIAN,
+                },
+            });
+            expect(castedInputs.descriptors).toEqual(expectedDescriptor);
+            return { result: async () => Value.from(anyResult).proto() };
+        });
+        const res = await runInNodeMode((_) => anyObservation, consensusMedianAggregation())();
+        expect(res).toEqual(anyResult);
+        expect(calls).toEqual(['NODE', 'DON', 'CONSENSUS_SIMPLE']);
+        // Restore the original method after the test
+        ConsensusCapability.prototype.simple = origSimple;
+    });
+    test('local failure with consensus', async () => {
+        // Clear the calls array for this test
+        calls.length = 0;
+        const anyError = Error('nope');
+        const anyResult = 123;
+        // spy on consensus.simple
+        const origSimple = ConsensusCapability.prototype.simple;
+        ConsensusCapability.prototype.simple = mock((inputs) => {
+            calls.push('CONSENSUS_SIMPLE');
+            // biome-ignore lint/suspicious/noExplicitAny: Needed for runtime type checking of protocol buffer messages
+            expect(inputs.$typeName).toBeDefined();
+            const castedInputs = inputs;
+            expect(castedInputs.default).toBeUndefined();
+            const actualError = expectError(castedInputs);
+            expect(anyError.message).toEqual(actualError);
+            const expectedDescriptor = create(ConsensusDescriptorSchema, {
+                descriptor: {
+                    case: 'aggregation',
+                    value: AggregationType.MEDIAN,
+                },
+            });
+            expect(castedInputs.descriptors).toEqual(expectedDescriptor);
+            return { result: async () => Value.from(anyResult).proto() };
+        });
+        const errFn = (_) => {
+            throw anyError;
+        };
+        const res = await runInNodeMode(errFn, consensusMedianAggregation())();
+        expect(res).toEqual(anyResult);
+        expect(calls).toEqual(['NODE', 'DON', 'CONSENSUS_SIMPLE']);
+        // Restore the original method after the test
+        ConsensusCapability.prototype.simple = origSimple;
+    });
+    test('guards DON calls while in node mode, also local and consensus failure', async () => {
+        // Simulate switchModes by touching global function used by host
+        const origSwitch = globalThis.switchModes;
+        globalThis.switchModes = (_m) => { };
+        // spy on consensus.simple
+        const origSimple = ConsensusCapability.prototype.simple;
+        ConsensusCapability.prototype.simple = mock((inputs) => {
+            calls.push('CONSENSUS_SIMPLE');
+            // biome-ignore lint/suspicious/noExplicitAny: Needed for runtime type checking of protocol buffer messages
+            expect(inputs.$typeName).toBeDefined();
+            const castedInputs = inputs;
+            expect(castedInputs.default).toBeUndefined();
+            const actualError = expectError(castedInputs);
+            expect(actualError).toContain('cannot use Runtime inside RunInNodeMode.');
+            const expectedDescriptor = create(ConsensusDescriptorSchema, {
+                descriptor: {
+                    case: 'aggregation',
+                    value: AggregationType.IDENTICAL,
+                },
+            });
+            expect(castedInputs.descriptors).toEqual(expectedDescriptor);
+            throw Error(actualError);
+        });
+        expect(async () => {
+            await runInNodeMode(async (_) => {
+                const ba = new BasicActionCapability();
+                const result = await ba.performAction({ inputThing: true }).result();
+                return result.adaptedThing;
+            }, consensusIdenticalAggregation())();
+        }).toThrow(/.*cannot use Runtime inside RunInNodeMode.*/);
+        // Restore the original method and global after the test
+        ConsensusCapability.prototype.simple = origSimple;
+        globalThis.switchModes = origSwitch;
+    });
+});