@muxoai/sdk 1.4.2 → 1.4.4

package/dist/durable-workflow.js

@@ -1,4 +1,7 @@
-/** Cloud provisioning pipeline modelled on Cloudflare Workflows primitives, shared by the Node engine and the edge worker. */
+/**
+ * Temporal-compatible Durable Workflows, Saga Compensations, Signals, and Cloudflare Workflows primitives,
+ * shared by the Node engine (src/engine.ts) and the Cloudflare Edge Worker (worker/index.ts).
+ */
 import { MuxoToolError } from "./mcp-schema.js";
 export const WORKFLOW_RESOURCE_COMPLETED_EVENT = "v2.provisioning.resource.completed";
 export function workflowNotFoundError(workflowId) {
@@ -14,12 +17,70 @@ export function normalizeWorkflowTarget(params) {
         serviceRef: (params.serviceRef || "postgres").toLowerCase().trim(),
     };
 }
+function appendTemporalEvent(history, eventType, attributes, now = new Date().toISOString()) {
+    history.push({
+        eventId: history.length + 1,
+        eventTime: now,
+        eventType,
+        taskQueue: "muxo-durable-execution-queue",
+        attributes,
+    });
+}
 export function createCloudProvisioningWorkflow(params) {
     const now = new Date().toISOString();
+    const region = params.region || "aws-us-east-1";
+    const apiVersion = params.apiVersion || "2026-09-30.preview";
+    const history = [];
+    appendTemporalEvent(history, "EVENT_TYPE_WORKFLOW_EXECUTION_STARTED", {
+        workflowType: "cloud_provisioning_pipeline",
+        workflowId: params.id,
+        workspaceId: params.workspaceId,
+        provider: params.provider,
+        serviceRef: params.serviceRef,
+        region,
+    }, now);
+    appendTemporalEvent(history, "EVENT_TYPE_ACTIVITY_TASK_COMPLETED", {
+        activityName: "check_stripe_v2_eligibility",
+        result: { status: "eligible", apiVersion },
+    }, now);
+    appendTemporalEvent(history, "EVENT_TYPE_ACTIVITY_TASK_COMPLETED", {
+        activityName: "ensure_payment_profile_and_provider_connection",
+        result: { provider: params.provider, paymentProfileStatus: "active" },
+    }, now);
+    appendTemporalEvent(history, "EVENT_TYPE_ACTIVITY_TASK_COMPLETED", {
+        activityName: "create_v2_provisioning_resource",
+        result: {
+            resourceId: params.resourceId,
+            provider: params.provider,
+            service_ref: params.serviceRef,
+            region,
+        },
+        compensationAction: `resource.${params.provider}.remove`,
+    }, now);
+    appendTemporalEvent(history, "EVENT_TYPE_TIMER_STARTED", {
+        waitingForSignal: WORKFLOW_RESOURCE_COMPLETED_EVENT,
+        resourceId: params.resourceId,
+    }, now);
+    const compensations = [
+        {
+            stepName: "ensure_payment_profile_and_provider_connection",
+            compensationAction: `provisioning.provider_connection.unlink`,
+            status: "registered",
+            description: `Unlink provider connection for ${params.provider} if downstream provisioning aborts`,
+        },
+        {
+            stepName: "create_v2_provisioning_resource",
+            compensationAction: `resource.${params.provider}.remove`,
+            status: "registered",
+            description: `Deprovision ${params.provider}/${params.serviceRef} (${params.resourceId}) and release reservation`,
+        },
+    ];
     return {
         id: params.id,
+        runId: `run_${params.id}`,
         workspaceId: params.workspaceId,
         workflowType: "cloud_provisioning_pipeline",
+        playbookSlug: null,
         status: "waiting_for_event",
         provider: params.provider,
         serviceRef: params.serviceRef,
@@ -29,7 +90,7 @@ export function createCloudProvisioningWorkflow(params) {
                 name: "check_stripe_v2_eligibility",
                 primitive: "step.do",
                 status: "completed",
-                output: { status: "eligible", apiVersion: params.apiVersion || "2026-09-30.preview" },
+                output: { status: "eligible", apiVersion },
                 completedAt: now,
             },
             {
@@ -38,6 +99,7 @@ export function createCloudProvisioningWorkflow(params) {
                 status: "completed",
                 output: { provider: params.provider, paymentProfileStatus: "active" },
                 completedAt: now,
+                compensationAction: "provisioning.provider_connection.unlink",
             },
             {
                 name: "create_v2_provisioning_resource",
@@ -47,22 +109,31 @@ export function createCloudProvisioningWorkflow(params) {
                     resourceId: params.resourceId,
                     provider: params.provider,
                     service_ref: params.serviceRef,
-                    region: params.region || "aws-us-east-1",
+                    region,
                 },
                 completedAt: now,
+                compensationAction: `resource.${params.provider}.remove`,
             },
             {
                 name: "wait_for_v2_provisioning_resource_completed",
                 primitive: "step.waitForEvent",
                 status: "waiting",
-                output: { expectedEvent: WORKFLOW_RESOURCE_COMPLETED_EVENT, resourceId: params.resourceId },
+                output: {
+                    expectedEvent: WORKFLOW_RESOURCE_COMPLETED_EVENT,
+                    resourceId: params.resourceId,
+                },
             },
             {
                 name: "reveal_access_configuration_and_seal_vault",
                 primitive: "step.do",
                 status: "pending",
+                compensationAction: "vault.revoke_secrets",
             },
         ],
+        compensations,
+        signals: [],
+        temporalEventHistory: history,
+        rollbackReason: null,
         createdAt: now,
         updatedAt: now,
     };
@@ -70,6 +141,12 @@ export function createCloudProvisioningWorkflow(params) {
 /** Completes every outstanding step once the resource-completed event (or a manual advance) arrives. */
 export function completeCloudProvisioningWorkflow(wf, params) {
     const now = new Date().toISOString();
+    const history = wf.temporalEventHistory || [];
+    const trigger = String(params.triggerEvent || WORKFLOW_RESOURCE_COMPLETED_EVENT);
+    appendTemporalEvent(history, "EVENT_TYPE_WORKFLOW_EXECUTION_SIGNALED", {
+        signalName: trigger,
+        resourceId: wf.resourceId,
+    }, now);
     for (const step of wf.steps) {
         if (step.status === "completed")
             continue;
@@ -80,11 +157,128 @@ export function completeCloudProvisioningWorkflow(wf, params) {
                 vaultEncrypted: true,
                 cipher: "AES-256-GCM",
                 secretKeys: params.secretKeys,
-                triggerEvent: params.triggerEvent || WORKFLOW_RESOURCE_COMPLETED_EVENT,
+                triggerEvent: trigger,
             };
         }
+        appendTemporalEvent(history, "EVENT_TYPE_ACTIVITY_TASK_COMPLETED", {
+            activityName: step.name,
+            result: step.output || { status: "completed" },
+        }, now);
     }
+    appendTemporalEvent(history, "EVENT_TYPE_WORKFLOW_EXECUTION_COMPLETED", {
+        workflowId: wf.id,
+        status: "completed",
+        secretKeysSealed: params.secretKeys,
+    }, now);
+    wf.temporalEventHistory = history;
     wf.status = "completed";
     wf.updatedAt = now;
     return wf;
 }
+/**
+ * Executes LIFO Saga Compensations on a DurableWorkflow, rolling back completed steps in reverse order
+ * and recording Temporal compensation activity events.
+ */
+export function rollbackDurableWorkflow(wf, params) {
+    const now = new Date().toISOString();
+    const failedStepName = params?.failedStepName || params?.failedStep;
+    const reason = params?.reason ||
+        "Saga rollback requested by operator or downstream step failure";
+    const history = wf.temporalEventHistory || [];
+    const compensations = wf.compensations || [];
+    if (failedStepName) {
+        appendTemporalEvent(history, "EVENT_TYPE_ACTIVITY_TASK_FAILED", {
+            activityName: failedStepName,
+            reason,
+        }, now);
+    }
+    // Execute registered compensations in reverse (LIFO) order
+    for (let i = compensations.length - 1; i >= 0; i--) {
+        const comp = compensations[i];
+        if (comp.status === "executed")
+            continue;
+        comp.status = "executed";
+        comp.executedAt = now;
+        comp.output = {
+            rolledBack: true,
+            action: comp.compensationAction,
+            resourceId: wf.resourceId,
+            reason,
+        };
+        appendTemporalEvent(history, "EVENT_TYPE_ACTIVITY_TASK_COMPLETED", {
+            activityName: `compensate:${comp.stepName}`,
+            compensationAction: comp.compensationAction,
+            result: comp.output,
+        }, now);
+    }
+    for (const step of wf.steps) {
+        if (step.status === "completed" && step.compensationAction) {
+            step.status = "compensated";
+            step.compensatedAt = now;
+        }
+        else if (step.status === "waiting" || step.status === "pending") {
+            step.status = "failed";
+        }
+    }
+    appendTemporalEvent(history, "EVENT_TYPE_WORKFLOW_EXECUTION_CANCELED", {
+        workflowId: wf.id,
+        status: "rolled_back",
+        reason,
+        compensatedStepsCount: compensations.filter((c) => c.status === "executed")
+            .length,
+    }, now);
+    wf.compensations = compensations;
+    wf.temporalEventHistory = history;
+    wf.rollbackReason = reason;
+    wf.status = "rolled_back";
+    wf.updatedAt = now;
+    return wf;
+}
+/**
+ * Sends a named Temporal signal to a DurableWorkflow (`human.approval.granted`, `oauth.connection.active`,
+ * `saga.abort`, or `v2.provisioning.resource.completed`).
+ */
+export function signalDurableWorkflow(wf, params) {
+    const now = new Date().toISOString();
+    const signalName = String(params.signalName || WORKFLOW_RESOURCE_COMPLETED_EVENT).trim();
+    const payload = params.payload || {};
+    wf.signals = wf.signals || [];
+    wf.signals.push({
+        signalName,
+        payload,
+        receivedAt: now,
+    });
+    if (signalName === "saga.abort" ||
+        signalName === "human.approval.rejected" ||
+        payload.action === "rollback") {
+        return rollbackDurableWorkflow(wf, {
+            reason: String(payload.reason || `Rolled back via signal ${signalName}`),
+        });
+    }
+    return completeCloudProvisioningWorkflow(wf, {
+        secretKeys: params.secretKeys || ["DATABASE_URL"],
+        triggerEvent: signalName,
+    });
+}
+/**
+ * Exports a DurableWorkflow in Temporal Web UI / `temporal workflow show` compatible EventHistory JSON format.
+ */
+export function exportTemporalEventHistory(wf) {
+    const events = wf.temporalEventHistory || [];
+    return {
+        namespace: `muxo.${wf.workspaceId}`,
+        workflowExecution: {
+            workflowId: wf.id,
+            runId: wf.runId || `run_${wf.id}`,
+        },
+        workflowType: {
+            name: wf.playbookSlug
+                ? `MuxoPlaybookSaga::${wf.playbookSlug}`
+                : `MuxoWorkflow::${wf.workflowType}`,
+        },
+        status: wf.status,
+        eventsCount: events.length,
+        compensationsCount: (wf.compensations || []).length,
+        events,
+    };
+}

package/dist/engine.d.ts

@@ -1,5 +1,6 @@
 import type { MuxoConfig } from "./config.js";
-import { type DurableWorkflow } from "./durable-workflow.js";
+import { exportTemporalEventHistory, type DurableWorkflow } from "./durable-workflow.js";
+import { type CommercialPlaybookDefinition, type CommercialRoiReport, type CompiledPolicyAsCodeBundle, type HarnessConfigurationBundle, type OtelTraceExportBundle, type PolicyAsCodeEvaluationResult, type RunReconciliationReport } from "./oss-suite.js";
 import { type NaturalLanguageResolution } from "./nl.js";
 import { describePolicyInPlainEnglish, type GuardrailCompileOptions, type LlmPolicyAndGovernanceBrief, type ParsedNaturalLanguageGuardrail, type PolicySimulationResult } from "./policy.js";
 import { ComposioInstantAdapter } from "./providers/composio-instant.js";
@@ -48,6 +49,7 @@ export declare class MuxoEngine {
     readonly governance: MicrosoftGovernanceAdapter;
     readonly supermemory: SupermemoryAdapter;
     private readonly durableWorkflows;
+    private readonly customPlaybooks;
     constructor(config: MuxoConfig, store: MuxoStore);
     getProfile(ctx: ExecutionContext): Record<string, unknown>;
     getOrganization(ctx: ExecutionContext): Record<string, unknown>;
@@ -191,9 +193,15 @@ export declare class MuxoEngine {
     }>;
     /**
      * Synthesizes a Bi-Temporal Knowledge Graph (entities, active relationships, superseded historical relationships,
-     * Mermaid diagram, and human + technical explanations) directly from SQLite temporal_facts, memories, resources, and connections.
+     * Mermaid diagram, point-in-time `asOf` time-travel, 2-hop BFS subgraph, and human + technical explanations)
+     * directly from SQLite temporal_facts, memories, resources, and connections.
      */
-    getMemoryGraph(ctx: ExecutionContext, query?: string): Promise<MemoryKnowledgeGraph>;
+    getMemoryGraph(ctx: ExecutionContext, queryOrOptions?: string | {
+        query?: string;
+        asOf?: string | null;
+        focalEntity?: string | null;
+        maxHops?: number;
+    }): Promise<MemoryKnowledgeGraph>;
     activateWorkspaceKillSwitch(ctx: ExecutionContext, params: {
         reason: string;
         action?: "terminate" | "quarantine" | "suspend";
@@ -226,7 +234,9 @@ export declare class MuxoEngine {
         governanceSignatureValid: boolean;
         agenticReceiptValid: boolean;
         explanation: HumanFriendlyExplanation;
+        businessSummary: NonNullable<ExecutionReceipt["businessSummary"]>;
     };
+    reconcileRun(ctx: ExecutionContext, runOrPlanId: string): RunReconciliationReport;
     listReceipts(ctx: ExecutionContext, limit?: number): {
         receipts: Array<ExecutionReceipt & {
             agenticReceipt: PortableAgenticReceipt;
@@ -338,7 +348,7 @@ export declare class MuxoEngine {
     }): Promise<{
         ok: boolean;
         executed: boolean;
-        status: "executed" | "planned_dry_run" | "awaiting_approval" | "awaiting_oauth_connection" | "missing_inputs" | "guardrail_applied" | "memory_saved" | "memory_forgotten" | "memory_recalled" | "memory_graph" | "governance_updated" | "governance_scanned" | "governance_status" | "context_inspected" | "receipt_explained" | "receipt_chain_verified" | "unresolved";
+        status: "executed" | "planned_dry_run" | "awaiting_approval" | "awaiting_oauth_connection" | "missing_inputs" | "guardrail_applied" | "memory_saved" | "memory_forgotten" | "memory_recalled" | "memory_graph" | "governance_updated" | "governance_scanned" | "governance_status" | "context_inspected" | "receipt_explained" | "receipt_chain_verified" | "playbook_listed" | "playbook_created" | "playbook_executed" | "workflow_rolled_back" | "workflow_signaled" | "workflow_history" | "cedar_compiled" | "cedar_evaluated" | "otel_exported" | "roi_analyzed" | "harness_configured" | "unresolved";
         intent: NaturalLanguageResolution;
         resolution: NaturalLanguageResolution;
         plan?: ActionPlan;
@@ -359,6 +369,15 @@ export declare class MuxoEngine {
         memoryRecord?: WorkspaceMemoryRecord;
         memoryOverview?: Awaited<ReturnType<MuxoEngine["getMemoryOverview"]>>;
         memoryGraph?: MemoryKnowledgeGraph;
+        playbooks?: CommercialPlaybookDefinition[];
+        playbook?: CommercialPlaybookDefinition;
+        workflow?: DurableWorkflow;
+        workflowHistory?: ReturnType<typeof exportTemporalEventHistory>;
+        cedarBundle?: CompiledPolicyAsCodeBundle;
+        cedarEvaluation?: PolicyAsCodeEvaluationResult;
+        otelTraces?: OtelTraceExportBundle;
+        roiReport?: CommercialRoiReport;
+        harnessConfig?: HarnessConfigurationBundle;
         deletedMemoryId?: string;
         governanceStatus?: ReturnType<MuxoEngine["getGovernanceOverview"]>;
         poisoningScan?: ReturnType<MuxoEngine["scanForContextPoisoning"]>;
@@ -417,6 +436,93 @@ export declare class MuxoEngine {
     }): Promise<DurableWorkflow>;
     advanceDurableWorkflow(ctx: ExecutionContext, workflowId: string, eventPayload?: Record<string, unknown>): Promise<DurableWorkflow>;
     listDurableWorkflows(workspaceId: string): DurableWorkflow[];
+    getDurableWorkflow(ctx: ExecutionContext, workflowId: string): DurableWorkflow;
+    getDurableWorkflowHistory(ctx: ExecutionContext, workflowId: string): {
+        namespace: string;
+        workflowExecution: {
+            workflowId: string;
+            runId: string;
+        };
+        workflowType: {
+            name: string;
+        };
+        status: DurableWorkflow["status"];
+        eventsCount: number;
+        compensationsCount: number;
+        events: import("./durable-workflow.js").TemporalHistoryEvent[];
+    };
+    signalDurableWorkflow(ctx: ExecutionContext, workflowId: string, params: {
+        signalName: string;
+        payload?: Record<string, unknown>;
+    }): DurableWorkflow;
+    rollbackDurableWorkflow(ctx: ExecutionContext, workflowId: string, params?: {
+        reason?: string;
+        failedStep?: string;
+    }): DurableWorkflow;
+    /**
+     * AWS Cedar & Open Policy Agent (OPA / Rego) Policy-as-Code Compiler & Evaluator.
+     */
+    getPolicyAsCodeBundle(ctx: ExecutionContext): CompiledPolicyAsCodeBundle;
+    evaluatePolicyAsCode(ctx: ExecutionContext, params: {
+        toolSlug: string;
+        input?: Record<string, unknown>;
+        riskLevel?: RiskLevel;
+        creditCost?: number;
+        lane?: string;
+    }): Promise<PolicyAsCodeEvaluationResult>;
+    /**
+     * OpenTelemetry (OTel GenAI / MCP Semantic Conventions) & Langfuse Trace Exporter.
+     */
+    exportOtelTraces(ctx: ExecutionContext, limit?: number): OtelTraceExportBundle;
+    /**
+     * Turnkey & Custom Commercial Business Saga Playbooks.
+     */
+    listCommercialPlaybooks(ctx?: ExecutionContext): CommercialPlaybookDefinition[];
+    createCustomPlaybook(ctx: ExecutionContext, params: {
+        prompt?: string;
+        input?: Record<string, unknown>;
+    }): {
+        ok: true;
+        playbook: CommercialPlaybookDefinition;
+        playbooks: CommercialPlaybookDefinition[];
+        humanMessage: string;
+    };
+    runCommercialPlaybook(ctx: ExecutionContext, params: {
+        slug: string;
+        input?: Record<string, unknown>;
+    }): {
+        ok: true;
+        playbook: CommercialPlaybookDefinition;
+        workflow: DurableWorkflow;
+        temporalFact: import("./types.js").TemporalGraphFact;
+        usableResult: {
+            playbookSlug: string;
+            playbookName: string;
+            status: "completed";
+            summary: string;
+            deliverableOutcome: string;
+            targetProvider: string;
+            targetEntity: string;
+            completedStepsCount: number;
+            registeredCompensationsCount: number;
+            estimatedCostUsd: number;
+            creditsMetered: number;
+            estimatedMinutesSaved: number;
+            recoveryGuarantee: string;
+        };
+    };
+    /**
+     * Turnkey Harness Preset & One-Shot Agent Configurator.
+     */
+    configureHarness(ctx: ExecutionContext, params?: {
+        preset?: string | null;
+        harness?: string | null;
+        prompt?: string | null;
+    }): Promise<HarnessConfigurationBundle>;
+    /**
+     * FinOps & Commercial ROI Unit-Economics Analytics.
+     */
+    getCommercialRoiReport(ctx: ExecutionContext): CommercialRoiReport;
     /**
      * Hybrid Semantic Vector + Bi-Temporal Recall (`@cf/baai/bge-base-en-v1.5` + Vectorize model).
      */