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

package/dist/workflow/client.js

@@ -0,0 +1,299 @@
+/** Thin ProtoJSON HTTP client for OE durable attempt, activity, and step APIs. */
+import { fromJson, toJsonString, } from "@bufbuild/protobuf";
+import { ActivityCommandSchema, ActivityContextSchema, ActivityMemoryCommandSchema, ActivityOutcomeSchema, } from "../generated/workflow/v1/activity_pb.js";
+import { WorkflowErrorCode, WorkflowErrorSchema, } from "../generated/workflow/v1/common_pb.js";
+import { AttemptHeartbeatRequestSchema, AttemptStartRequestSchema, AttemptStartResponseSchema, } from "../generated/workflow/v1/runtime_pb.js";
+import { CompleteExecutionCommandSchema, FinalizeStepCommandSchema, FinalizeStepResponseSchema, } from "../generated/workflow/v1/state_pb.js";
+import { fetchPlatform, getFetchOptionsWithTLS } from "../tls_client.js";
+const ATTEMPT_START_PATH = "/executor/attempt/start";
+const ATTEMPT_HEARTBEAT_PATH = "/executor/attempt/heartbeat";
+const ACTIVITY_START_PATH = "/executor/activity/start";
+const ACTIVITY_OUTCOME_PATH = "/executor/activity/outcome";
+const ACTIVITY_MEMORY_PATH = "/executor/activity/memory";
+const STEP_FINALIZE_PATH = "/executor/step/finalize";
+const EXECUTION_COMPLETE_PATH = "/executor/complete";
+const DEFAULT_TIMEOUT_MS = 10_000;
+const STATUS_TO_CODE = {
+    400: WorkflowErrorCode.INVALID_ARGUMENT,
+    401: WorkflowErrorCode.UNAUTHORIZED,
+    403: WorkflowErrorCode.UNAUTHORIZED,
+    404: WorkflowErrorCode.NOT_FOUND,
+    409: WorkflowErrorCode.CONFLICT,
+    412: WorkflowErrorCode.STALE_FENCE,
+};
+export class ActivityDispatch {
+    context;
+    constructor(context) {
+        this.context = context;
+    }
+}
+export class ActivityReplay {
+    outcome;
+    constructor(outcome) {
+        this.outcome = outcome;
+    }
+}
+export class WorkflowClientError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = "WorkflowClientError";
+        this.code = code;
+    }
+}
+/**
+ * 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 function encodeProtoJson(schema, message) {
+    return toJsonString(schema, message, { useProtoFieldName: true });
+}
+function codeForStatus(status) {
+    return STATUS_TO_CODE[status] ?? WorkflowErrorCode.OUTCOME_UNKNOWN;
+}
+function parseJsonObject(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body || "{}");
+    }
+    catch (error) {
+        throw new Error("response is not valid JSON", { cause: error });
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("response must be a ProtoJSON object");
+    }
+    return parsed;
+}
+function errorFromObject(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    try {
+        return fromJson(WorkflowErrorSchema, value, {
+            ignoreUnknownFields: true,
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+function raiseOnError(status, body, operation) {
+    let object;
+    try {
+        object = parseJsonObject(body);
+    }
+    catch (error) {
+        if (status >= 200 && status < 300)
+            return;
+        throw new WorkflowClientError(codeForStatus(status), `${operation} failed with HTTP ${status}`, { cause: error });
+    }
+    // A present `error` member is always a failure, even on 2xx and even when
+    // it is not a coded WorkflowError. Matches Python `_raise_error_member`.
+    const errorMember = object["error"];
+    if (errorMember !== undefined && errorMember !== null) {
+        const wrapped = errorFromObject(errorMember);
+        if (wrapped?.code) {
+            throw new WorkflowClientError(wrapped.code, wrapped.message || `${operation} failed`);
+        }
+        throw new WorkflowClientError(codeForStatus(status), wrapped?.message || `${operation} failed with HTTP ${status}`);
+    }
+    const bare = errorFromObject(object);
+    if (bare?.code) {
+        throw new WorkflowClientError(bare.code, bare.message || `${operation} failed`);
+    }
+    if (status < 200 || status >= 300) {
+        throw new WorkflowClientError(codeForStatus(status), `${operation} failed with HTTP ${status}`);
+    }
+}
+function isCompleteWorkflowIdentity(identity) {
+    const scope = identity?.tenantScope;
+    if (identity === undefined || scope === undefined)
+        return false;
+    return Boolean(scope.orgId.trim() &&
+        scope.projectId.trim() &&
+        scope.workspaceId.trim() &&
+        identity.sessionId.trim() &&
+        identity.executionId.trim());
+}
+function workflowIdentitiesEqual(left, right) {
+    if (left === undefined || right === undefined)
+        return false;
+    return ((left.tenantScope?.orgId ?? "") === (right.tenantScope?.orgId ?? "") &&
+        (left.tenantScope?.projectId ?? "") ===
+            (right.tenantScope?.projectId ?? "") &&
+        (left.tenantScope?.workspaceId ?? "") ===
+            (right.tenantScope?.workspaceId ?? "") &&
+        left.sessionId === right.sessionId &&
+        left.executionId === right.executionId);
+}
+function requireDispatchContext(command, context) {
+    // Reject tickets that cannot later record an outcome under this command.
+    if (!context.activityId ||
+        !context.attemptId ||
+        context.fencingToken <= 0n ||
+        !isCompleteWorkflowIdentity(context.workflowIdentity)) {
+        throw new WorkflowClientError(WorkflowErrorCode.INVALID_ARGUMENT, "activity start response activity_context is missing identity fields");
+    }
+    if (context.attemptId !== command.attemptId ||
+        context.fencingToken !== command.fencingToken ||
+        !workflowIdentitiesEqual(context.workflowIdentity, command.workflowIdentity)) {
+        throw new WorkflowClientError(WorkflowErrorCode.INVALID_ARGUMENT, "activity start response activity_context does not match the submitted command");
+    }
+    return context;
+}
+async function readResponseText(response, operation) {
+    try {
+        return await response.text();
+    }
+    catch (error) {
+        throw new WorkflowClientError(WorkflowErrorCode.OUTCOME_UNKNOWN, `${operation} transport failure: ${error instanceof Error ? error.name : typeof error}`, { cause: error });
+    }
+}
+function interpretActivityStartResponse(command, status, body) {
+    let object;
+    try {
+        object = parseJsonObject(body);
+    }
+    catch (error) {
+        throw new WorkflowClientError(status >= 200 && status < 300
+            ? WorkflowErrorCode.INVALID_ARGUMENT
+            : codeForStatus(status), "activity start response is not valid JSON", { cause: error });
+    }
+    raiseOnError(status, body, "activity start");
+    if (status < 200 || status >= 300) {
+        throw new WorkflowClientError(codeForStatus(status), `activity start failed with HTTP ${status}`);
+    }
+    const outcomeMember = object["outcome"];
+    if (outcomeMember !== undefined && outcomeMember !== null) {
+        try {
+            return new ActivityReplay(fromJson(ActivityOutcomeSchema, outcomeMember, {
+                ignoreUnknownFields: true,
+            }));
+        }
+        catch (error) {
+            throw new WorkflowClientError(WorkflowErrorCode.INVALID_ARGUMENT, "activity start response is not valid ProtoJSON", { cause: error });
+        }
+    }
+    const contextMember = object["activity_context"];
+    if (contextMember !== undefined && contextMember !== null) {
+        try {
+            return new ActivityDispatch(requireDispatchContext(command, fromJson(ActivityContextSchema, contextMember, {
+                ignoreUnknownFields: true,
+            })));
+        }
+        catch (error) {
+            if (error instanceof WorkflowClientError)
+                throw error;
+            throw new WorkflowClientError(WorkflowErrorCode.INVALID_ARGUMENT, "activity start response is not valid ProtoJSON", { cause: error });
+        }
+    }
+    throw new WorkflowClientError(WorkflowErrorCode.INVALID_ARGUMENT, "activity start response carries neither activity_context nor outcome");
+}
+export class WorkflowClient {
+    baseUrl;
+    fetchFn;
+    timeoutMs;
+    constructor(oeUrl, options = {}) {
+        this.baseUrl = oeUrl.replace(/\/$/, "");
+        this.fetchFn = options.fetch ?? fetch;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    async startAttempt(request) {
+        const response = await this.post(ATTEMPT_START_PATH, encodeProtoJson(AttemptStartRequestSchema, request), "attempt start");
+        const body = await readResponseText(response, "attempt start");
+        let object;
+        try {
+            object = parseJsonObject(body);
+        }
+        catch (error) {
+            if (response.status === 404)
+                return null;
+            throw new WorkflowClientError(response.ok
+                ? WorkflowErrorCode.INVALID_ARGUMENT
+                : codeForStatus(response.status), response.ok
+                ? "attempt start response is not valid ProtoJSON"
+                : `attempt start failed with HTTP ${response.status}`, { cause: error });
+        }
+        let parsed;
+        try {
+            parsed = fromJson(AttemptStartResponseSchema, object, {
+                ignoreUnknownFields: true,
+            });
+        }
+        catch (error) {
+            if (response.status === 404)
+                return null;
+            throw new WorkflowClientError(response.ok
+                ? WorkflowErrorCode.INVALID_ARGUMENT
+                : codeForStatus(response.status), response.ok
+                ? "attempt start response is not valid ProtoJSON"
+                : `attempt start failed with HTTP ${response.status}`, { cause: error });
+        }
+        if (parsed.error !== undefined) {
+            throw new WorkflowClientError(parsed.error.code, parsed.error.message);
+        }
+        const bareError = errorFromObject(object);
+        if (bareError?.code) {
+            throw new WorkflowClientError(bareError.code, bareError.message || "attempt start failed");
+        }
+        if (!response.ok) {
+            if (response.status === 404)
+                return null;
+            throw new WorkflowClientError(codeForStatus(response.status), `attempt start failed with HTTP ${response.status}`);
+        }
+        if (parsed.attemptContext === undefined) {
+            throw new WorkflowClientError(WorkflowErrorCode.INVALID_ARGUMENT, "attempt start response carries neither attempt_context nor error");
+        }
+        return parsed.attemptContext;
+    }
+    async heartbeat(request) {
+        const response = await this.post(ATTEMPT_HEARTBEAT_PATH, encodeProtoJson(AttemptHeartbeatRequestSchema, request), "attempt heartbeat");
+        raiseOnError(response.status, await readResponseText(response, "attempt heartbeat"), "attempt heartbeat");
+    }
+    async startActivity(command) {
+        const response = await this.post(ACTIVITY_START_PATH, encodeProtoJson(ActivityCommandSchema, command), "activity start");
+        return interpretActivityStartResponse(command, response.status, await readResponseText(response, "activity start"));
+    }
+    async reportOutcome(outcome) {
+        const response = await this.post(ACTIVITY_OUTCOME_PATH, encodeProtoJson(ActivityOutcomeSchema, outcome), "activity outcome");
+        raiseOnError(response.status, await readResponseText(response, "activity outcome"), "activity outcome");
+    }
+    async ensureMemoryWritten(command) {
+        const response = await this.post(ACTIVITY_MEMORY_PATH, encodeProtoJson(ActivityMemoryCommandSchema, command), "activity memory");
+        raiseOnError(response.status, await readResponseText(response, "activity memory"), "activity memory");
+    }
+    async finalizeStep(command) {
+        const response = await this.post(STEP_FINALIZE_PATH, encodeProtoJson(FinalizeStepCommandSchema, command), "step finalization");
+        const body = await readResponseText(response, "step finalization");
+        raiseOnError(response.status, body, "step finalization");
+        let parsed;
+        try {
+            parsed = fromJson(FinalizeStepResponseSchema, parseJsonObject(body), {
+                ignoreUnknownFields: true,
+            });
+        }
+        catch (error) {
+            throw new WorkflowClientError(WorkflowErrorCode.INVALID_ARGUMENT, "step finalization response is not valid ProtoJSON", { cause: error });
+        }
+        return parsed.entries;
+    }
+    async completeExecution(command) {
+        const response = await this.post(EXECUTION_COMPLETE_PATH, encodeProtoJson(CompleteExecutionCommandSchema, command), "execution completion");
+        raiseOnError(response.status, await readResponseText(response, "execution completion"), "execution completion");
+    }
+    async post(path, payload, operation) {
+        const url = `${this.baseUrl}${path}`;
+        try {
+            return await fetchPlatform(url, {
+                ...getFetchOptionsWithTLS(url),
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: payload,
+                signal: AbortSignal.timeout(this.timeoutMs),
+            }, this.fetchFn);
+        }
+        catch (error) {
+            throw new WorkflowClientError(WorkflowErrorCode.OUTCOME_UNKNOWN, `${operation} transport failure: ${error instanceof Error ? error.name : typeof error}`, { cause: error });
+        }
+    }
+}

package/dist/workflow/context.d.ts

@@ -0,0 +1,37 @@
+/** Request-local durable attempt identity, positions, and observed activities. */
+import { type ActivityCommand } from "../generated/workflow/v1/activity_pb.js";
+import { type ActivityPosition, type OperationPath } from "../generated/workflow/v1/common_pb.js";
+import type { AttemptContext } from "../generated/workflow/v1/runtime_pb.js";
+export interface ChildOperationBoundary {
+    name: string;
+    occurrenceKey: string;
+}
+export type OperationPathResolver = () => readonly ChildOperationBoundary[];
+export declare class UnsupportedChildOperationFanOutError extends Error {
+    constructor(message: string);
+}
+export interface InterruptedActivity {
+    readonly command: ActivityCommand;
+    readonly controlFlow: unknown;
+}
+export declare function runWithAttemptContext<T>(attempt: AttemptContext, fn: () => T): T;
+export declare function currentAttemptContext(): AttemptContext | null;
+export declare function currentStepOrdinal(): number;
+export declare function currentOperationPath(): OperationPath;
+export declare function runWithOperationPathResolver<T>(resolver: OperationPathResolver, fn: () => T): T;
+export declare function childOperationBoundaryScope<T>(boundary: ChildOperationBoundary, fn: () => T): T;
+export declare function recordObservedActivity(position: ActivityPosition): void;
+export declare function observedActivityPositions(stepOrdinal: number): ActivityPosition[];
+export declare function recordInterruptedActivity(command: ActivityCommand, controlFlow: unknown): void;
+export declare function interruptedActivities(stepOrdinal: number): InterruptedActivity[];
+export declare function setActivityReconstructionIds(activityIds: readonly string[]): void;
+export declare function activityRequiresReconstruction(activityId: string): boolean;
+export declare function recordReconstructedActivityInterrupt(activityId: string): number;
+export declare function advanceStepOrdinal(committedStepOrdinal: number): number;
+export declare function toolActivityKey(toolCallId: string): string;
+export declare function allocateActivityOrdinal(key?: string): number;
+export declare function preallocateActivityOrdinals(keys: readonly string[]): number[];
+export declare function preallocateChildOperationOrdinals(boundaries: readonly ChildOperationBoundary[]): number[];
+export declare function currentPendingChildOperationBatch(): readonly ChildOperationBoundary[];
+export declare function setPendingChildOperationBatch(boundaries: readonly ChildOperationBoundary[]): void;
+//# sourceMappingURL=context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/workflow/context.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAKlF,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAIL,KAAK,gBAAgB,EACrB,KAAK,aAAa,EACnB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAsB7E,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,qBAAqB,GAAG,MAAM,SAAS,sBAAsB,EAAE,CAAC;AAS5E,qBAAa,oCAAqC,SAAQ,KAAK;gBACjD,OAAO,EAAE,MAAM;CAI5B;AAqED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B;AAmOD,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,OAAO,EAAE,cAAc,EACvB,EAAE,EAAE,MAAM,CAAC,GACV,CAAC,CAgBH;AAED,wBAAgB,qBAAqB,IAAI,cAAc,GAAG,IAAI,CAE7D;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAS3C;AAED,wBAAgB,oBAAoB,IAAI,aAAa,CAOpD;AAED,wBAAgB,4BAA4B,CAAC,CAAC,EAC5C,QAAQ,EAAE,qBAAqB,EAC/B,EAAE,EAAE,MAAM,CAAC,GACV,CAAC,CAEH;AAED,wBAAgB,2BAA2B,CAAC,CAAC,EAC3C,QAAQ,EAAE,sBAAsB,EAChC,EAAE,EAAE,MAAM,CAAC,GACV,CAAC,CAeH;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAEvE;AAED,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,GAClB,gBAAgB,EAAE,CAEpB;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,eAAe,EACxB,WAAW,EAAE,OAAO,GACnB,IAAI,CAEN;AAED,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,GAClB,mBAAmB,EAAE,CAEvB;AAED,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,IAAI,CAEN;AAED,wBAAgB,8BAA8B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAE1E;AAED,wBAAgB,oCAAoC,CAClD,UAAU,EAAE,MAAM,GACjB,MAAM,CAIR;AAED,wBAAgB,kBAAkB,CAAC,oBAAoB,EAAE,MAAM,GAAG,MAAM,CAOvE;AAED,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAK1D;AAED,wBAAgB,uBAAuB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAM5D;AAED,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAM7E;AAED,wBAAgB,iCAAiC,CAC/C,UAAU,EAAE,SAAS,sBAAsB,EAAE,GAC5C,MAAM,EAAE,CAOV;AAED,wBAAgB,iCAAiC,IAAI,SAAS,sBAAsB,EAAE,CAErF;AAED,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,SAAS,sBAAsB,EAAE,GAC5C,IAAI,CAQN"}