@muxoai/sdk 1.3.0 → 1.4.3

package/dist/engine.d.ts

@@ -1,13 +1,38 @@
 import type { MuxoConfig } from "./config.js";
+import { type DurableWorkflow } from "./durable-workflow.js";
+import { type CommercialPlaybookDefinition, type CommercialRoiReport, type CompiledPolicyAsCodeBundle, type OtelTraceExportBundle, type PolicyAsCodeEvaluationResult } 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";
 import { ComposioSdkAdapter } from "./providers/composio-sdk.js";
 import { MicrosoftGovernanceAdapter } from "./providers/microsoft-governance.js";
 import { StripeBillingAdapter } from "./providers/stripe-billing.js";
 import { StripeProjectsAdapter } from "./providers/stripe-projects.js";
-import { SupermemoryAdapter } from "./providers/supermemory.js";
+import { SupermemoryAdapter, type ActiveMemoryDefaults } from "./providers/supermemory.js";
 import type { MuxoStore } from "./store.js";
-import type { ActionPlan, ConnectionRecord, ExecutionReceipt, ExecutionRun, GovernanceDecisionRecord, MemoryContextSummary, MuxoTool, ProviderLane, RiskLevel, User, Workspace, WorkspaceMemoryRecord } from "./types.js";
+import type { ActionPlan, ConnectionRecord, ExecutionReceipt, ExecutionRun, GovernanceDecisionRecord, HumanFriendlyExplanation, HumanHandoff, LanguageMode, LlmGuidance, MemoryContextSummary, MemoryKnowledgeGraph, MuxoTool, PortableAgenticReceipt, ProviderLane, RiskLevel, User, Workspace, WorkspaceMemoryRecord } from "./types.js";
+export type RunContextPayload = {
+    workspaceId: string;
+    workspaceSlug: string;
+    projectsEnvironment: string;
+    policy: Workspace["policy"];
+    plainEnglishPolicy: ReturnType<typeof describePolicyInPlainEnglish>;
+    languageMode: LanguageMode;
+    customInstructions: string[];
+    activeDefaults: ActiveMemoryDefaults;
+    activeGuardrails: string[];
+    creditsBalance: number;
+    monthlyActionsRemaining: number;
+    provisionedResources: ReturnType<MuxoStore["listResources"]>;
+    environmentVariablesRedacted: Record<string, string>;
+    supermemoryBrain: MemoryContextSummary;
+    temporalFacts: NonNullable<MemoryContextSummary["temporalFacts"]>;
+    governance: ReturnType<MicrosoftGovernanceAdapter["getStatus"]>;
+    trustScore: ReturnType<MicrosoftGovernanceAdapter["getWorkspaceTrustScore"]>;
+    llmSystemPrompt: string;
+    explanation: HumanFriendlyExplanation;
+    envPullHint: string;
+};
 export interface ExecutionContext {
     user: User;
     workspace: Workspace;
@@ -23,6 +48,7 @@ export declare class MuxoEngine {
     readonly stripeBilling: StripeBillingAdapter;
     readonly governance: MicrosoftGovernanceAdapter;
     readonly supermemory: SupermemoryAdapter;
+    private readonly durableWorkflows;
     constructor(config: MuxoConfig, store: MuxoStore);
     getProfile(ctx: ExecutionContext): Record<string, unknown>;
     getOrganization(ctx: ExecutionContext): Record<string, unknown>;
@@ -41,6 +67,7 @@ export declare class MuxoEngine {
         provider?: string;
         syncLive?: boolean;
     }): Promise<Record<string, unknown>>;
+    getHostedSiteHtml(slug: string, filePath?: string): string | null;
     startConnection(ctx: ExecutionContext, params: {
         provider: string;
         lane?: ProviderLane;
@@ -54,11 +81,16 @@ export declare class MuxoEngine {
         timeoutSeconds?: number;
         pollIntervalMs?: number;
     }): Promise<{
+        ok: true;
         connected: boolean;
+        ready: boolean;
+        timedOut: boolean;
         provider: string;
         status: ConnectionRecord["status"];
         connection: ConnectionRecord;
         redirectUrl: string | null;
+        polledAttempts: number;
+        elapsedMs: number;
         message: string;
     }>;
     handleOAuthCallback(params: {
@@ -78,6 +110,7 @@ export declare class MuxoEngine {
         toolSlug: string;
         input?: Record<string, unknown>;
         reason?: string;
+        fundingMode?: "muxo_funded" | "byok";
     }): Promise<{
         plan: ActionPlan;
         tool: MuxoTool;
@@ -91,42 +124,217 @@ export declare class MuxoEngine {
             externalAccountId: string | null;
             instructions: string;
         };
+        humanHandoff?: HumanHandoff;
+        llmGuidance: LlmGuidance;
         nextStep: string;
     }>;
     getPlan(ctx: ExecutionContext, planId: string): ActionPlan;
+    waitForPlanApproval(ctx: ExecutionContext, params: {
+        planId: string;
+        timeoutSeconds?: number;
+        pollIntervalMs?: number;
+    }): Promise<{
+        ok: true;
+        approved: boolean;
+        rejected: boolean;
+        timedOut: boolean;
+        waitedForApproval: true;
+        approvalStatus: ActionPlan["approvalStatus"];
+        approvalUrl: string;
+        waitedMs: number;
+        plan: ActionPlan;
+    }>;
     approvePlan(ctx: ExecutionContext, planId: string, decision?: "approved" | "rejected"): ActionPlan;
-    getRunContext(ctx: ExecutionContext, query?: string): Promise<Record<string, unknown>>;
+    private buildApprovalHandoff;
+    private buildOAuthHandoff;
+    private buildPlanLlmGuidance;
+    private enrichMemoryContext;
+    getRunContext(ctx: ExecutionContext, query?: string): Promise<{
+        explanation: HumanFriendlyExplanation;
+        plainEnglishPolicy: ReturnType<typeof describePolicyInPlainEnglish>;
+        activeDefaults: ActiveMemoryDefaults;
+        activeGuardrails: string[];
+        [key: string]: unknown;
+    }>;
     getMemoryOverview(ctx: ExecutionContext, query?: string): Promise<{
         enabled: boolean;
         namespace: string;
+        fundingSource: string;
         context: MemoryContextSummary;
+        activeDefaults: ActiveMemoryDefaults;
+        activeGuardrails: string[];
+        explanation: HumanFriendlyExplanation;
         recentMemories: WorkspaceMemoryRecord[];
         memories: WorkspaceMemoryRecord[];
+        temporalFacts: ReturnType<MuxoStore["listTemporalFacts"]>;
+        historicalFacts: ReturnType<MuxoStore["listTemporalFacts"]>;
     }>;
     addWorkspaceMemory(ctx: ExecutionContext, params: {
         title: string;
         content: string;
         kind?: WorkspaceMemoryRecord["kind"];
         metadata?: Record<string, unknown>;
+        subject?: string;
+        predicate?: string;
+        object?: string;
     }): Promise<WorkspaceMemoryRecord>;
     deleteWorkspaceMemory(ctx: ExecutionContext, idOrDocId: string): Promise<{
         deleted: boolean;
         record: WorkspaceMemoryRecord | null;
     }>;
+    forgetWorkspaceMemoryMatching(ctx: ExecutionContext, query: string): Promise<{
+        query: string;
+        deletedLocalCount: number;
+        invalidatedFactsCount: number;
+        deletedRemoteIds: string[];
+        deletedMemories: WorkspaceMemoryRecord[];
+        invalidatedFacts: ReturnType<MuxoStore["listTemporalFacts"]>;
+    }>;
+    /**
+     * Synthesizes a Bi-Temporal Knowledge Graph (entities, active relationships, superseded historical relationships,
+     * 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, queryOrOptions?: string | {
+        query?: string;
+        asOf?: string | null;
+        focalEntity?: string | null;
+        maxHops?: number;
+    }): Promise<MemoryKnowledgeGraph>;
+    activateWorkspaceKillSwitch(ctx: ExecutionContext, params: {
+        reason: string;
+        action?: "terminate" | "quarantine" | "suspend";
+    }): Promise<Record<string, unknown>>;
+    resumeWorkspaceKillSwitch(ctx: ExecutionContext): Record<string, unknown>;
     executePlanForRisk(ctx: ExecutionContext, planId: string, expectedRisk: RiskLevel): Promise<{
         run: ExecutionRun;
         receipt: ExecutionReceipt;
     }>;
     getRun(ctx: ExecutionContext, runId: string): ExecutionRun;
-    cancelRun(ctx: ExecutionContext, runId: string): {
+    cancelRun(ctx: ExecutionContext, runId: string, reason?: string): {
+        ok: true;
+        cancelled: true;
+        alreadyCancelled: boolean;
+        previousStatus: ExecutionRun["status"];
         run: ExecutionRun;
-        receipt: ExecutionReceipt | null;
+        receipt: ExecutionReceipt;
+        signatureValid: boolean;
+        message: string;
     };
+    explainReceipt(receipt: ExecutionReceipt, verification: {
+        signatureValid: boolean;
+        governanceSignatureValid: boolean;
+        agenticReceiptValid?: boolean;
+    }, policy?: Partial<Workspace["policy"]> | null, languageMode?: LanguageMode): HumanFriendlyExplanation;
     getReceipt(ctx: ExecutionContext, receiptOrRunId: string): {
         receipt: ExecutionReceipt;
+        agenticReceipt: PortableAgenticReceipt;
         signatureValid: boolean;
         governanceSignatureValid: boolean;
+        agenticReceiptValid: boolean;
+        explanation: HumanFriendlyExplanation;
+    };
+    listReceipts(ctx: ExecutionContext, limit?: number): {
+        receipts: Array<ExecutionReceipt & {
+            agenticReceipt: PortableAgenticReceipt;
+            signatureValid: boolean;
+            governanceSignatureValid: boolean;
+            agenticReceiptValid: boolean;
+            explanation: HumanFriendlyExplanation;
+        }>;
+        total: number;
+        explanation: HumanFriendlyExplanation;
+    };
+    /**
+     * Verifies the entire cryptographic receipt chain (`prevReceiptHash` -> `receiptHash`,
+     * HMAC vault signatures, Ed25519 Governance DecisionRecords, and portable Ed25519 AgenticReceipts).
+     */
+    verifyReceiptChain(ctx: ExecutionContext, limit?: number): {
+        ok: true;
+        valid: boolean;
+        workspaceId: string;
+        agentDid: string;
+        publicKeyHex: string;
+        chainValid: boolean;
+        hashLinksValid: boolean;
+        allHmacValid: boolean;
+        allEd25519AgenticValid: boolean;
+        allGovernanceValid: boolean;
+        totalReceipts: number;
+        totalChecked: number;
+        validCount: number;
+        brokenLinks: Array<{
+            receiptId: string;
+            runId: string;
+            reason: string;
+        }>;
+        genesisHash: string;
+        headReceiptHash: string;
+        links: Array<{
+            index: number;
+            receiptId: string;
+            runId: string;
+            toolSlug: string;
+            prevReceiptHash: string;
+            receiptHash: string;
+            hashLinkValid: boolean;
+            hmacValid: boolean;
+            ed25519AgenticValid: boolean;
+            governanceValid: boolean;
+            issuedAt: string;
+        }>;
+        explanation: HumanFriendlyExplanation;
+    };
+    getGovernanceOverview(ctx: ExecutionContext): {
+        workspaceId: string;
+        killSwitch: {
+            active: boolean;
+            reason: string | null;
+        };
+        governance: ReturnType<MicrosoftGovernanceAdapter["getStatus"]>;
+        trustScore: ReturnType<MicrosoftGovernanceAdapter["getWorkspaceTrustScore"]>;
+        policy: Workspace["policy"];
+        plainEnglish: ReturnType<typeof describePolicyInPlainEnglish>;
+        llmPolicyBrief: LlmPolicyAndGovernanceBrief;
+        explanation: HumanFriendlyExplanation;
+    };
+    resetWorkspaceGuardrails(ctx: ExecutionContext): {
+        ok: true;
+        action: "reset_guardrails";
+        workspace: Workspace;
+        policy: Workspace["policy"];
+        plainEnglish: ReturnType<typeof describePolicyInPlainEnglish>;
+        llmPolicyBrief: LlmPolicyAndGovernanceBrief;
+        explanation: HumanFriendlyExplanation;
+    };
+    checkToolPolicy(ctx: ExecutionContext, params: {
+        toolSlug: string;
+        input?: Record<string, unknown>;
+    }): Promise<PolicySimulationResult>;
+    setKillSwitch(ctx: ExecutionContext, active: boolean, reason?: string): Workspace;
+    scanForContextPoisoning(workspaceId: string, text: string): {
+        poisoned: boolean;
+        severity: string;
+        matchedPatterns: string[];
+        findingsCount: number;
+        integrityValid: boolean;
+    };
+    getGuardrailsSummary(ctx: ExecutionContext): {
+        workspaceId: string;
+        policy: Workspace["policy"];
+        plainEnglish: ReturnType<typeof describePolicyInPlainEnglish>;
+        llmPolicyBrief: LlmPolicyAndGovernanceBrief;
+        activeDefaults: ActiveMemoryDefaults;
+        activeGuardrails: string[];
     };
+    applyNaturalLanguageGuardrail(ctx: ExecutionContext, prompt: string, options?: GuardrailCompileOptions): Promise<{
+        ok: boolean;
+        workspace: Workspace;
+        guardrail: ParsedNaturalLanguageGuardrail;
+        plainEnglish: ReturnType<typeof describePolicyInPlainEnglish>;
+        llmPolicyBrief: LlmPolicyAndGovernanceBrief;
+        memoryRecord?: WorkspaceMemoryRecord;
+    }>;
     doNaturalLanguage(ctx: ExecutionContext, params: {
         prompt: string;
         input?: Record<string, unknown>;
@@ -137,13 +345,38 @@ export declare class MuxoEngine {
     }): Promise<{
         ok: boolean;
         executed: boolean;
-        status: "executed" | "planned_dry_run" | "awaiting_approval" | "awaiting_oauth_connection" | "missing_inputs" | "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" | "unresolved";
         intent: NaturalLanguageResolution;
         resolution: NaturalLanguageResolution;
         plan?: ActionPlan;
         run?: ExecutionRun;
         receipt?: ExecutionReceipt;
+        receiptVerification?: {
+            receipt: ExecutionReceipt;
+            agenticReceipt?: PortableAgenticReceipt;
+            signatureValid: boolean;
+            governanceSignatureValid: boolean;
+            agenticReceiptValid?: boolean;
+            explanation: HumanFriendlyExplanation;
+        };
+        receiptsList?: ReturnType<MuxoEngine["listReceipts"]>;
+        receiptChain?: ReturnType<MuxoEngine["verifyReceiptChain"]>;
+        guardrail?: ParsedNaturalLanguageGuardrail;
+        plainEnglishGuardrails?: ReturnType<typeof describePolicyInPlainEnglish>;
+        memoryRecord?: WorkspaceMemoryRecord;
+        memoryOverview?: Awaited<ReturnType<MuxoEngine["getMemoryOverview"]>>;
+        memoryGraph?: MemoryKnowledgeGraph;
+        deletedMemoryId?: string;
+        governanceStatus?: ReturnType<MuxoEngine["getGovernanceOverview"]>;
+        poisoningScan?: ReturnType<MuxoEngine["scanForContextPoisoning"]>;
+        runContext?: Awaited<ReturnType<MuxoEngine["getRunContext"]>>;
+        explanation?: HumanFriendlyExplanation;
+        activeDefaults?: ActiveMemoryDefaults;
+        activeMemoryDefaults?: ActiveMemoryDefaults;
+        memoryAutoFilled?: Record<string, unknown>;
         authHandoff?: Record<string, unknown>;
+        humanHandoff?: HumanHandoff;
+        llmGuidance?: LlmGuidance;
         byokPrompt?: {
             needed: boolean;
             provider: string;
@@ -153,4 +386,142 @@ export declare class MuxoEngine {
         };
         humanMessage: string;
     }>;
+    /**
+     * Parallel Governed Multi-Tool Batch Execution (`COMPOSIO_MULTI_EXECUTE_TOOL` pattern).
+     * Evaluates governance & policy across every item, then executes all approved plans concurrently.
+     */
+    executeBatchPlans(ctx: ExecutionContext, params: {
+        items: Array<{
+            toolSlug: string;
+            input: Record<string, unknown>;
+            reason: string;
+        }>;
+        autoApprove?: boolean;
+    }): Promise<{
+        batchId: string;
+        totalRequested: number;
+        succeededCount: number;
+        blockedOrPendingCount: number;
+        results: Array<{
+            toolSlug: string;
+            status: "succeeded" | "failed" | "awaiting_approval" | "awaiting_oauth";
+            planId?: string;
+            runId?: string;
+            receiptId?: string;
+            output?: Record<string, unknown>;
+            error?: string;
+        }>;
+    }>;
+    /**
+     * Cloudflare Workflows (`step.do`, `step.waitForEvent`, `step.sleep`) Durable Orchestrator
+     * for multi-stage async Stripe v2 Cloud Provisioning & Vault Secret Injection.
+     */
+    startDurableWorkflow(ctx: ExecutionContext, params: {
+        provider?: string;
+        serviceRef?: string;
+        name?: string;
+        region?: string;
+    }): 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 Commercial Business Saga Playbooks.
+     */
+    listCommercialPlaybooks(): CommercialPlaybookDefinition[];
+    runCommercialPlaybook(ctx: ExecutionContext, params: {
+        slug: string;
+        input?: Record<string, unknown>;
+    }): {
+        ok: true;
+        playbook: CommercialPlaybookDefinition;
+        workflow: DurableWorkflow;
+        temporalFact: import("./types.js").TemporalGraphFact;
+    };
+    /**
+     * 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).
+     */
+    searchMemoryHybrid(workspaceId: string, query: string, limit?: number): {
+        rankedMemories: Array<WorkspaceMemoryRecord & {
+            hybridScore: number;
+            vectorSimilarity: number;
+            lexicalOverlap: number;
+        }>;
+        vectorDimensions: number;
+        embeddingModel: string;
+        topScore: number;
+    };
+    /**
+     * Tamper-Evident R2 / WORM Audit Archive Bundle signed by the workspace's Ed25519 AgentIdentity.
+     */
+    exportTamperEvidentArchive(workspaceId: string): {
+        archiveId: string;
+        workspaceId: string;
+        storageTarget: string;
+        retentionMode: string;
+        exportedAt: string;
+        chainIntegrity: {
+            verified: boolean;
+            algorithm: string;
+            agentDid: string;
+            publicKeyFingerprint: string;
+            headMerkleHash: string;
+            bundleDigest: string;
+        };
+        counts: {
+            receipts: number;
+            governanceDecisions: number;
+            auditLogs: number;
+            temporalFacts: number;
+        };
+        merkleChain: {
+            sequence: number;
+            receiptId: string;
+            toolSlug: string;
+            prevHash: string;
+            entryHash: string;
+            createdAt: string;
+        }[];
+    };
 }