@mongodb-js/agent-engine-runner-shared 0.11.3

package/dist/workflow/activity.d.ts

@@ -0,0 +1,71 @@
+/** Serial activity helpers for OE-owned durable workflow identity. */
+import { type Value } from "@bufbuild/protobuf/wkt";
+import { type ActivityCommand, type ActivityContext, type ActivityKind, type ActivityOutcome } from "../generated/workflow/v1/activity_pb.js";
+import { WorkflowErrorCode, type OperationPath } from "../generated/workflow/v1/common_pb.js";
+import type { AttemptContext } from "../generated/workflow/v1/runtime_pb.js";
+import { WorkflowClientError, type WorkflowClient } from "./client.js";
+type ActivityRuntimeClient = Pick<WorkflowClient, "startActivity" | "reportOutcome">;
+export type ActivityResolvedHook<T = unknown> = (client: ActivityRuntimeClient, context: ActivityContext, result: T) => void | Promise<void>;
+export declare class DurableActivityDeniedError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class DurableActivityInterrupted extends Error {
+    readonly controlFlow: unknown;
+    constructor(controlFlow: unknown);
+}
+export declare class ReplayedActivityFailedError extends WorkflowClientError {
+    constructor(code: WorkflowErrorCode, message: string);
+}
+export declare function semanticInputFromJson(value: unknown): Value;
+export declare function valueToJson(value: Value | undefined): unknown;
+export declare function buildActivityCommand(args: {
+    attempt: AttemptContext;
+    kind: ActivityKind;
+    name: string;
+    activityOrdinal: number;
+    semanticInput: unknown;
+    stepOrdinal?: number;
+    operationPath?: OperationPath;
+}): ActivityCommand;
+export declare function completedOutcome(context: ActivityContext, result: unknown): ActivityOutcome;
+export declare function failedOutcome(context: ActivityContext, message: string, code?: WorkflowErrorCode): ActivityOutcome;
+export declare function unwrapActivityOutcome(outcome: ActivityOutcome): unknown;
+export declare function runSerialActivity<T>(args: {
+    client: ActivityRuntimeClient;
+    kind: ActivityKind;
+    name: string;
+    activityOrdinal: number;
+    semanticInput: unknown;
+    execute: (context: ActivityContext) => T | Promise<T>;
+    onActivityResolved?: ActivityResolvedHook<T>;
+    attempt?: AttemptContext;
+    stepOrdinal?: number;
+    /** False only when the framework has assigned a stable activity identity. */
+    exclusive?: boolean;
+}): Promise<T>;
+type StreamingItems<T> = Iterable<T> | AsyncIterable<T>;
+/**
+ * Run one generator-shaped durable activity.
+ *
+ * Replay expands a recorded result back into stream items without executing
+ * the effect. A fresh dispatch yields live items immediately, then folds them
+ * into the single terminal result recorded by OE. Closing the stream early
+ * terminal-fails the dispatch instead of leaving it in flight.
+ */
+export declare function runStreamingActivity<T>(args: {
+    client: ActivityRuntimeClient;
+    kind: ActivityKind;
+    name: string;
+    activityOrdinal: number;
+    semanticInput: unknown;
+    execute: () => StreamingItems<T>;
+    replay: (result: unknown) => StreamingItems<T>;
+    fold: (items: T[]) => unknown | Promise<unknown>;
+    onActivityResolved?: ActivityResolvedHook;
+    attempt?: AttemptContext;
+    stepOrdinal?: number;
+    /** False when the caller has assigned a stable activity identity. */
+    exclusive?: boolean;
+}): AsyncGenerator<T>;
+export {};
+//# sourceMappingURL=activity.d.ts.map

package/dist/workflow/activity.d.ts.map

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

package/dist/workflow/activity.js

@@ -0,0 +1,357 @@
+/** Serial activity helpers for OE-owned durable workflow identity. */
+import { create, fromJson, toJson } from "@bufbuild/protobuf";
+import { ValueSchema } from "@bufbuild/protobuf/wkt";
+import { ActivityCommandSchema, ActivityContextSchema, ActivityOutcomeKind, ActivityOutcomeSchema, } from "../generated/workflow/v1/activity_pb.js";
+import { ActivityPositionSchema, OperationPathSchema, WorkflowErrorCode, WorkflowErrorSchema, } from "../generated/workflow/v1/common_pb.js";
+import { getLogger } from "../logger.js";
+import { ActivityReplay, WorkflowClientError, } from "./client.js";
+import { currentAttemptContext, currentOperationPath, currentStepOrdinal, activityRequiresReconstruction, recordInterruptedActivity, recordObservedActivity, recordReconstructedActivityInterrupt, } from "./context.js";
+const logger = getLogger("agent_engine_runner_shared.workflow.activity");
+export class DurableActivityDeniedError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "DurableActivityDeniedError";
+    }
+}
+export class DurableActivityInterrupted extends Error {
+    controlFlow;
+    constructor(controlFlow) {
+        super(controlFlow instanceof Error ? controlFlow.message : String(controlFlow));
+        this.controlFlow = controlFlow;
+        this.name = "DurableActivityInterrupted";
+    }
+}
+export class ReplayedActivityFailedError extends WorkflowClientError {
+    constructor(code, message) {
+        super(code, message);
+        this.name = "ReplayedActivityFailedError";
+    }
+}
+export function semanticInputFromJson(value) {
+    const encoded = JSON.stringify(value === undefined ? null : value);
+    if (encoded === undefined) {
+        throw new TypeError("semantic input is not JSON-serializable");
+    }
+    return fromJson(ValueSchema, JSON.parse(encoded));
+}
+export function valueToJson(value) {
+    if (value === undefined)
+        return null;
+    return toJson(ValueSchema, value);
+}
+export function buildActivityCommand(args) {
+    if (!args.attempt.workflowIdentity?.executionId) {
+        throw new WorkflowClientError(WorkflowErrorCode.INVALID_ARGUMENT, "ActivityCommand requires AttemptContext.workflow_identity");
+    }
+    if (args.activityOrdinal <= 0) {
+        throw new WorkflowClientError(WorkflowErrorCode.INVALID_ARGUMENT, "activity_ordinal must be positive");
+    }
+    const resolvedStep = args.stepOrdinal === undefined ? currentStepOrdinal() : args.stepOrdinal;
+    if (resolvedStep <= 0) {
+        throw new WorkflowClientError(WorkflowErrorCode.INVALID_ARGUMENT, "step_ordinal must be positive");
+    }
+    const operationPath = args.operationPath ?? currentOperationPath();
+    return create(ActivityCommandSchema, {
+        workflowIdentity: args.attempt.workflowIdentity,
+        attemptId: args.attempt.attemptId,
+        fencingToken: args.attempt.fencingToken,
+        position: create(ActivityPositionSchema, {
+            operationPath: create(OperationPathSchema, {
+                segments: operationPath.segments,
+            }),
+            activityOrdinal: BigInt(args.activityOrdinal),
+            stepOrdinal: BigInt(resolvedStep),
+        }),
+        activityKind: args.kind,
+        activityName: args.name,
+        semanticInput: semanticInputFromJson(args.semanticInput),
+    });
+}
+export function completedOutcome(context, result) {
+    return create(ActivityOutcomeSchema, {
+        workflowIdentity: context.workflowIdentity,
+        activityId: context.activityId,
+        attemptId: context.attemptId,
+        fencingToken: context.fencingToken,
+        outcomeKind: ActivityOutcomeKind.COMPLETED,
+        result: semanticInputFromJson(result),
+    });
+}
+export function failedOutcome(context, message, code = WorkflowErrorCode.OUTCOME_UNKNOWN) {
+    return create(ActivityOutcomeSchema, {
+        workflowIdentity: context.workflowIdentity,
+        activityId: context.activityId,
+        attemptId: context.attemptId,
+        fencingToken: context.fencingToken,
+        outcomeKind: ActivityOutcomeKind.FAILED,
+        error: create(WorkflowErrorSchema, { code, message }),
+    });
+}
+function contextFromOutcome(outcome) {
+    return create(ActivityContextSchema, {
+        workflowIdentity: outcome.workflowIdentity,
+        activityId: outcome.activityId,
+        attemptId: outcome.attemptId,
+        fencingToken: outcome.fencingToken,
+    });
+}
+function deniedOutcome(context, message) {
+    return create(ActivityOutcomeSchema, {
+        workflowIdentity: context.workflowIdentity,
+        activityId: context.activityId,
+        attemptId: context.attemptId,
+        fencingToken: context.fencingToken,
+        outcomeKind: ActivityOutcomeKind.DENIED,
+        // OE WorkflowError.Validate rejects UNSPECIFIED; denied fixtures use UNAUTHORIZED.
+        error: create(WorkflowErrorSchema, {
+            code: WorkflowErrorCode.UNAUTHORIZED,
+            message,
+        }),
+    });
+}
+export function unwrapActivityOutcome(outcome) {
+    switch (outcome.outcomeKind) {
+        case ActivityOutcomeKind.COMPLETED:
+            return valueToJson(outcome.result);
+        case ActivityOutcomeKind.DENIED:
+            throw new DurableActivityDeniedError(outcome.error?.message || "durable activity denied by policy");
+        case ActivityOutcomeKind.FAILED:
+            throw new ReplayedActivityFailedError(outcome.error?.code || WorkflowErrorCode.OUTCOME_UNKNOWN, outcome.error?.message || "durable activity failed");
+        case ActivityOutcomeKind.SUSPENDED:
+            throw new WorkflowClientError(WorkflowErrorCode.INVALID_ARGUMENT, "shared durable activities support terminal outcomes only; " +
+                "framework adapters must own suspension and resume");
+        case ActivityOutcomeKind.UNSPECIFIED:
+            throw new WorkflowClientError(WorkflowErrorCode.INVALID_ARGUMENT, "activity outcome kind is unspecified");
+        default: {
+            const _exhaustive = outcome.outcomeKind;
+            throw new WorkflowClientError(WorkflowErrorCode.INVALID_ARGUMENT, `activity outcome kind is unspecified: ${_exhaustive}`);
+        }
+    }
+}
+const attemptActivityGates = new Map();
+const CONFLICT_MESSAGE = "this attempt already has an in-flight activity";
+/**
+ * Admit one activity under the attempt-local concurrency gate. Activities with
+ * stable position identity may share the attempt; unkeyed effects are exclusive.
+ */
+function acquireActivitySlot(attemptId, exclusive) {
+    const gate = attemptActivityGates.get(attemptId) ?? {
+        exclusive: false,
+        shared: 0,
+    };
+    if (exclusive ? gate.exclusive || gate.shared > 0 : gate.exclusive) {
+        throw new WorkflowClientError(WorkflowErrorCode.CONFLICT, CONFLICT_MESSAGE);
+    }
+    if (exclusive)
+        gate.exclusive = true;
+    else
+        gate.shared += 1;
+    attemptActivityGates.set(attemptId, gate);
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        const current = attemptActivityGates.get(attemptId);
+        if (current === undefined)
+            return;
+        if (exclusive)
+            current.exclusive = false;
+        else
+            current.shared = Math.max(0, current.shared - 1);
+        if (!current.exclusive && current.shared === 0) {
+            attemptActivityGates.delete(attemptId);
+        }
+    };
+}
+async function withActivitySlot(attemptId, exclusive, fn) {
+    const release = acquireActivitySlot(attemptId, exclusive);
+    try {
+        return await fn();
+    }
+    finally {
+        release();
+    }
+}
+async function reportDenied(client, context, error) {
+    try {
+        await client.reportOutcome(deniedOutcome(context, error.message));
+    }
+    catch (reportError) {
+        if (reportError instanceof WorkflowClientError) {
+            logger.error("Failed to report denied activity outcome", error, reportError);
+            throw reportError;
+        }
+        logger.error("Failed to report denied activity outcome", reportError);
+    }
+}
+async function reportFailure(client, context, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    try {
+        await client.reportOutcome(failedOutcome(context, message));
+    }
+    catch (reportError) {
+        if (reportError instanceof WorkflowClientError) {
+            logger.error("Failed to report failed activity outcome", error, reportError);
+            throw reportError;
+        }
+        logger.error("Failed to report failed activity outcome", reportError);
+    }
+}
+function requireAttempt(attempt, caller) {
+    const resolved = attempt ?? currentAttemptContext() ?? undefined;
+    if (resolved === undefined) {
+        throw new WorkflowClientError(WorkflowErrorCode.INVALID_ARGUMENT, `${caller} requires an OE-issued AttemptContext`);
+    }
+    return resolved;
+}
+export async function runSerialActivity(args) {
+    const attempt = requireAttempt(args.attempt, "runSerialActivity");
+    return withActivitySlot(attempt.attemptId, args.exclusive ?? true, async () => {
+        const command = buildActivityCommand({
+            attempt,
+            kind: args.kind,
+            name: args.name,
+            activityOrdinal: args.activityOrdinal,
+            stepOrdinal: args.stepOrdinal,
+            semanticInput: args.semanticInput,
+        });
+        return runDispatchedActivity(args.client, command, args.execute, args.onActivityResolved);
+    });
+}
+/**
+ * Run one generator-shaped durable activity.
+ *
+ * Replay expands a recorded result back into stream items without executing
+ * the effect. A fresh dispatch yields live items immediately, then folds them
+ * into the single terminal result recorded by OE. Closing the stream early
+ * terminal-fails the dispatch instead of leaving it in flight.
+ */
+export async function* runStreamingActivity(args) {
+    const attempt = requireAttempt(args.attempt, "runStreamingActivity");
+    const release = acquireActivitySlot(attempt.attemptId, args.exclusive ?? true);
+    try {
+        const command = buildActivityCommand({
+            attempt,
+            kind: args.kind,
+            name: args.name,
+            activityOrdinal: args.activityOrdinal,
+            stepOrdinal: args.stepOrdinal,
+            semanticInput: args.semanticInput,
+        });
+        const started = await args.client.startActivity(command);
+        if (command.position !== undefined) {
+            recordObservedActivity(command.position);
+        }
+        if (started instanceof ActivityReplay) {
+            const result = unwrapActivityOutcome(started.outcome);
+            await args.onActivityResolved?.(args.client, contextFromOutcome(started.outcome), result);
+            for await (const item of args.replay(result)) {
+                yield item;
+            }
+            return;
+        }
+        yield* runDispatchedActivityStream(args.client, started.context, args.execute, args.fold, args.onActivityResolved);
+    }
+    finally {
+        release();
+    }
+}
+async function* runDispatchedActivityStream(client, context, execute, fold, onActivityResolved) {
+    let terminalReportStarted = false;
+    try {
+        const items = [];
+        try {
+            for await (const item of execute()) {
+                items.push(item);
+                yield item;
+            }
+        }
+        catch (error) {
+            terminalReportStarted = true;
+            if (error instanceof DurableActivityDeniedError) {
+                await reportDenied(client, context, error);
+            }
+            else {
+                await reportFailure(client, context, error);
+            }
+            throw error;
+        }
+        let outcome;
+        let result;
+        try {
+            result = await fold(items);
+            outcome = completedOutcome(context, result);
+        }
+        catch (error) {
+            terminalReportStarted = true;
+            await reportFailure(client, context, error);
+            throw error;
+        }
+        terminalReportStarted = true;
+        await client.reportOutcome(outcome);
+        await onActivityResolved?.(client, context, result);
+    }
+    finally {
+        // Closing an async generator stops its producer at the current yield. The
+        // dispatched effect must still receive a terminal outcome in that case.
+        if (!terminalReportStarted) {
+            await client.reportOutcome(failedOutcome(context, "stream abandoned before completion"));
+        }
+    }
+}
+async function runDispatchedActivity(client, command, execute, onActivityResolved) {
+    const started = await client.startActivity(command);
+    if (command.position !== undefined) {
+        recordObservedActivity(command.position);
+    }
+    if (started instanceof ActivityReplay) {
+        if (!activityRequiresReconstruction(started.outcome.activityId)) {
+            const result = unwrapActivityOutcome(started.outcome);
+            await onActivityResolved?.(client, contextFromOutcome(started.outcome), result);
+            return result;
+        }
+    }
+    const reconstructing = started instanceof ActivityReplay;
+    const context = reconstructing
+        ? contextFromOutcome(started.outcome)
+        : started.context;
+    let result;
+    try {
+        result = await execute(context);
+    }
+    catch (error) {
+        if (error instanceof DurableActivityDeniedError) {
+            if (!reconstructing)
+                await reportDenied(client, context, error);
+            throw error;
+        }
+        if (error instanceof DurableActivityInterrupted) {
+            if (reconstructing &&
+                recordReconstructedActivityInterrupt(context.activityId) > 1) {
+                throw new Error("a durable local tool cannot raise another native interrupt " +
+                    "after its recorded answer is resumed", { cause: error });
+            }
+            recordInterruptedActivity(command, error.controlFlow);
+            throw error.controlFlow;
+        }
+        if (!reconstructing)
+            await reportFailure(client, context, error);
+        throw error;
+    }
+    if (reconstructing) {
+        await onActivityResolved?.(client, context, result);
+        return result;
+    }
+    let outcome;
+    try {
+        outcome = completedOutcome(context, result);
+    }
+    catch (error) {
+        await reportFailure(client, context, error);
+        throw error;
+    }
+    await client.reportOutcome(outcome);
+    await onActivityResolved?.(client, context, result);
+    return result;
+}

package/dist/workflow/attempt.d.ts

@@ -0,0 +1,12 @@
+/** Build durable attempt inputs from an AER execute request. */
+import type { ExecuteRequest } from "../models.js";
+import type { StepSuspensionEntry } from "../generated/workflow/v1/activity_pb.js";
+import { type AttemptContext, type AttemptStartRequest } from "../generated/workflow/v1/runtime_pb.js";
+import { type CompleteExecutionCommand, type FinalizeStepCommand, type StateSnapshot } from "../generated/workflow/v1/state_pb.js";
+export declare function completeExecutionCommand(attempt: AttemptContext, state: StateSnapshot): CompleteExecutionCommand;
+export declare function newDurabilityOwnerId(): string;
+export declare function finalizeCurrentStepCommand(attempt: AttemptContext, state: StateSnapshot): FinalizeStepCommand;
+export declare function finalizeCurrentStepSuspensionsCommand(attempt: AttemptContext, suspensions: readonly StepSuspensionEntry[]): FinalizeStepCommand;
+export declare function attemptStartRequestFromExecute(request: ExecuteRequest, sessionId: string, ownerId: string, appName: string, workflowVersion?: string, memoryEnabled?: boolean): AttemptStartRequest | null;
+export declare function heartbeatIntervalMs(value: bigint): number;
+//# sourceMappingURL=attempt.d.ts.map

package/dist/workflow/attempt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attempt.d.ts","sourceRoot":"","sources":["../../src/workflow/attempt.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAMhE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAMnF,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACzB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAGL,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACxB,KAAK,aAAa,EACnB,MAAM,sCAAsC,CAAC;AAO9C,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,aAAa,GACnB,wBAAwB,CAO1B;AAED,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,aAAa,GACnB,mBAAmB,CAUrB;AAED,wBAAgB,qCAAqC,CACnD,OAAO,EAAE,cAAc,EACvB,WAAW,EAAE,SAAS,mBAAmB,EAAE,GAC1C,mBAAmB,CAoBrB;AA+BD,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,eAAe,CAAC,EAAE,MAAM,EACxB,aAAa,UAAQ,GACpB,mBAAmB,GAAG,IAAI,CAkB5B;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOzD"}

package/dist/workflow/attempt.js

@@ -0,0 +1,96 @@
+/** Build durable attempt inputs from an AER execute request. */
+import { hostname } from "node:os";
+import { randomUUID } from "node:crypto";
+import { create } from "@bufbuild/protobuf";
+import { TenantScopeSchema, WorkflowIdentitySchema, } from "../generated/workflow/v1/common_pb.js";
+import { AttemptStartRequestSchema, WorkflowDeclarationSchema, } from "../generated/workflow/v1/runtime_pb.js";
+import { CompleteExecutionCommandSchema, FinalizeStepCommandSchema, } from "../generated/workflow/v1/state_pb.js";
+import { getWorkflowAdapter } from "../hooks.js";
+import { currentStepOrdinal, observedActivityPositions } from "./context.js";
+/** Default workflow version when the runtime does not declare one. */
+const DEFAULT_WORKFLOW_VERSION = "1";
+export function completeExecutionCommand(attempt, state) {
+    return create(CompleteExecutionCommandSchema, {
+        workflowIdentity: attempt.workflowIdentity,
+        attemptId: attempt.attemptId,
+        fencingToken: attempt.fencingToken,
+        state,
+    });
+}
+export function newDurabilityOwnerId() {
+    return `${hostname()}:${process.pid}:${randomUUID()}`;
+}
+export function finalizeCurrentStepCommand(attempt, state) {
+    const stepOrdinal = currentStepOrdinal();
+    return create(FinalizeStepCommandSchema, {
+        workflowIdentity: attempt.workflowIdentity,
+        attemptId: attempt.attemptId,
+        fencingToken: attempt.fencingToken,
+        state,
+        stepOrdinal: BigInt(stepOrdinal),
+        observedActivityPositions: observedActivityPositions(stepOrdinal),
+    });
+}
+export function finalizeCurrentStepSuspensionsCommand(attempt, suspensions) {
+    if (suspensions.length === 0) {
+        throw new Error("step suspension finalization requires at least one entry");
+    }
+    const stepOrdinal = currentStepOrdinal();
+    if (suspensions.some((entry) => entry.position?.stepOrdinal !== BigInt(stepOrdinal))) {
+        throw new Error("step suspension entry belongs to another workflow step");
+    }
+    return create(FinalizeStepCommandSchema, {
+        workflowIdentity: attempt.workflowIdentity,
+        attemptId: attempt.attemptId,
+        fencingToken: attempt.fencingToken,
+        stepOrdinal: BigInt(stepOrdinal),
+        observedActivityPositions: observedActivityPositions(stepOrdinal),
+        suspensions: [...suspensions],
+    });
+}
+function workflowIdentityFromExecuteRequest(request, sessionId) {
+    const orgId = (request.org_id ?? "").trim();
+    const projectId = (request.project_id ?? "").trim();
+    const workspaceId = (request.workspace_id ?? "").trim();
+    const executionId = (request.execution_id ?? "").trim();
+    const resolvedSession = sessionId.trim();
+    if (!orgId ||
+        !projectId ||
+        !workspaceId ||
+        !executionId ||
+        !resolvedSession) {
+        return null;
+    }
+    return create(WorkflowIdentitySchema, {
+        tenantScope: create(TenantScopeSchema, {
+            orgId,
+            projectId,
+            workspaceId,
+        }),
+        sessionId: resolvedSession,
+        executionId,
+    });
+}
+export function attemptStartRequestFromExecute(request, sessionId, ownerId, appName, workflowVersion, memoryEnabled = false) {
+    const workflowIdentity = workflowIdentityFromExecuteRequest(request, sessionId);
+    const adapter = getWorkflowAdapter();
+    if (workflowIdentity === null || adapter === null)
+        return null;
+    return create(AttemptStartRequestSchema, {
+        workflowIdentity,
+        ownerId,
+        declaration: create(WorkflowDeclarationSchema, {
+            workflowName: appName,
+            workflowVersion: workflowVersion || DEFAULT_WORKFLOW_VERSION,
+            adapterName: adapter.name,
+            adapterVersion: adapter.version,
+            memoryEnabled,
+        }),
+    });
+}
+export function heartbeatIntervalMs(value) {
+    if (value <= 0n || value > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new Error("AttemptContext.heartbeat_interval_ms must be a positive safe duration");
+    }
+    return Number(value);
+}

package/dist/workflow/client.d.ts

@@ -0,0 +1,46 @@
+/** Thin ProtoJSON HTTP client for OE durable attempt, activity, and step APIs. */
+import { type Message } from "@bufbuild/protobuf";
+import type { GenMessage } from "@bufbuild/protobuf/codegenv2";
+import { type ActivityCommand, type ActivityContext, type ActivityMemoryCommand, type ActivityOutcome, type StepActivityEntry } from "../generated/workflow/v1/activity_pb.js";
+import { WorkflowErrorCode } from "../generated/workflow/v1/common_pb.js";
+import { type AttemptContext, type AttemptHeartbeatRequest, type AttemptStartRequest } from "../generated/workflow/v1/runtime_pb.js";
+import { type CompleteExecutionCommand, type FinalizeStepCommand } from "../generated/workflow/v1/state_pb.js";
+export declare class ActivityDispatch {
+    readonly context: ActivityContext;
+    constructor(context: ActivityContext);
+}
+export declare class ActivityReplay {
+    readonly outcome: ActivityOutcome;
+    constructor(outcome: ActivityOutcome);
+}
+export type StartActivityResult = ActivityDispatch | ActivityReplay;
+export declare class WorkflowClientError extends Error {
+    readonly code: WorkflowErrorCode;
+    constructor(code: WorkflowErrorCode, message: string, options?: ErrorOptions);
+}
+type FetchFn = typeof fetch;
+/**
+ * Encode one protobuf message as a ProtoJSON string using wire field names.
+ * Shared so framework adapters post platform-shaped JSON bodies without
+ * hand-rolling serialization.
+ */
+export declare function encodeProtoJson<T extends Message>(schema: GenMessage<T>, message: T): string;
+export declare class WorkflowClient {
+    private readonly baseUrl;
+    private readonly fetchFn;
+    private readonly timeoutMs;
+    constructor(oeUrl: string, options?: {
+        fetch?: FetchFn;
+        timeoutMs?: number;
+    });
+    startAttempt(request: AttemptStartRequest): Promise<AttemptContext | null>;
+    heartbeat(request: AttemptHeartbeatRequest): Promise<void>;
+    startActivity(command: ActivityCommand): Promise<StartActivityResult>;
+    reportOutcome(outcome: ActivityOutcome): Promise<void>;
+    ensureMemoryWritten(command: ActivityMemoryCommand): Promise<void>;
+    finalizeStep(command: FinalizeStepCommand): Promise<StepActivityEntry[]>;
+    completeExecution(command: CompleteExecutionCommand): Promise<void>;
+    private post;
+}
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/workflow/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/workflow/client.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAElF,OAAO,EAIL,KAAK,OAAO,EACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAE/D,OAAO,EAKL,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACvB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,iBAAiB,EAGlB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACzB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAIL,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACzB,MAAM,sCAAsC,CAAC;AAsB9C,qBAAa,gBAAgB;IACf,QAAQ,CAAC,OAAO,EAAE,eAAe;gBAAxB,OAAO,EAAE,eAAe;CAC9C;AAED,qBAAa,cAAc;IACb,QAAQ,CAAC,OAAO,EAAE,eAAe;gBAAxB,OAAO,EAAE,eAAe;CAC9C;AAED,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,GAAG,cAAc,CAAC;AAEpE,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;gBAG/B,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY;CAMzB;AAED,KAAK,OAAO,GAAG,OAAO,KAAK,CAAC;AAE5B;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,OAAO,EAC/C,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,EACrB,OAAO,EAAE,CAAC,GACT,MAAM,CAER;AAqND,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAGjC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO;IAOjD,YAAY,CAChB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAiE3B,SAAS,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAa1D,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAarE,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAatD,mBAAmB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAalE,YAAY,CAChB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAuBzB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC;YAa3D,IAAI;CA0BnB"}