@muxoai/sdk 1.2.3 → 1.3.0

package/dist/providers/supermemory.d.ts

@@ -0,0 +1,64 @@
+import type { MuxoConfig } from "../config.js";
+import type { MemoryContextSummary, MemoryRecordKind } from "../types.js";
+/**
+ * Supermemory v5 Contextual Brain & Context-Aware Tool Call Adapter.
+ * Uses deterministic per-workspace namespaces (`/ns/muxo-v5-<hash>/...`)
+ * and strict secret redaction so credentials never enter external memory.
+ */
+export declare class SupermemoryAdapter {
+    private readonly config;
+    private readonly client;
+    constructor(config: MuxoConfig);
+    isEnabled(): boolean;
+    /**
+     * Derives a strict Supermemory v5 namespace (`^[a-zA-Z0-9_:-]+$`) scoped to a workspace.
+     */
+    namespaceForWorkspace(workspaceId: string): string;
+    getWorkspaceNamespace(workspaceId: string): string;
+    /**
+     * Strips any API keys, bearer tokens, connection strings, or .env secret assignments
+     * before content is stored in Supermemory (AGENTS.md Invariant #11 & #12).
+     */
+    sanitizeContent(raw: string): string;
+    /**
+     * Fetches the workspace's static + dynamic profile and optionally semantic search results
+     * in a single fail-open call.
+     */
+    getContextForWorkspace(workspaceIdOrParams: string | {
+        workspaceId: string;
+        query?: string;
+        limit?: number;
+    }, optionalQuery?: string): Promise<MemoryContextSummary>;
+    /**
+     * Stores a governed, secret-sanitized document/memory in the workspace's Supermemory v5 namespace.
+     */
+    addMemory(params: {
+        workspaceId: string;
+        documentId?: string;
+        title: string;
+        content: string;
+        kind: MemoryRecordKind;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        documentId: string;
+        namespace: string;
+        status: string;
+        sanitizedContent: string;
+    }>;
+    recordExecutionMemory(params: {
+        workspaceId: string;
+        toolSlug: string;
+        lane: string;
+        riskLevel: string;
+        reason: string;
+        status: string;
+        summary: string;
+    }): Promise<string | null>;
+    /**
+     * Deletes/forgets a memory document from the workspace's Supermemory v5 namespace.
+     */
+    deleteMemory(workspaceId: string, documentId: string): Promise<{
+        deleted: boolean;
+        namespace: string;
+    }>;
+}

package/dist/providers/supermemory.js

@@ -0,0 +1,224 @@
+import crypto from "node:crypto";
+import Supermemory from "supermemory";
+/**
+ * Supermemory v5 Contextual Brain & Context-Aware Tool Call Adapter.
+ * Uses deterministic per-workspace namespaces (`/ns/muxo-v5-<hash>/...`)
+ * and strict secret redaction so credentials never enter external memory.
+ */
+export class SupermemoryAdapter {
+    config;
+    client;
+    constructor(config) {
+        this.config = config;
+        if (config.supermemoryApiKey) {
+            this.client = new Supermemory({
+                apiKey: config.supermemoryApiKey,
+                baseUrl: config.supermemoryBaseUrl,
+                maxRetries: 1,
+            });
+        }
+        else {
+            this.client = null;
+        }
+    }
+    isEnabled() {
+        return Boolean(this.client);
+    }
+    /**
+     * Derives a strict Supermemory v5 namespace (`^[a-zA-Z0-9_:-]+$`) scoped to a workspace.
+     */
+    namespaceForWorkspace(workspaceId) {
+        const hash = crypto
+            .createHash("sha256")
+            .update(`muxo-v5-ns:${workspaceId}`)
+            .digest("hex")
+            .slice(0, 24);
+        return `muxo-v5-${hash}`;
+    }
+    getWorkspaceNamespace(workspaceId) {
+        return this.namespaceForWorkspace(workspaceId);
+    }
+    /**
+     * Strips any API keys, bearer tokens, connection strings, or .env secret assignments
+     * before content is stored in Supermemory (AGENTS.md Invariant #11 & #12).
+     */
+    sanitizeContent(raw) {
+        return raw
+            .replace(/\b(sk_live_|sk_test_|mk_live_|mk_test_|sm_|ak_|uak_|rk_live_|rk_test_|whsec_|ghp_|xoxb-|xoxp-)[A-Za-z0-9_\-]{6,}/g, "[REDACTED_KEY]")
+            .replace(/\b(postgres(?:ql)?|mysql|redis|rediss|mongodb(?:\+srv)?):\/\/[^\s"'`]+/gi, "$1://[REDACTED_CONNECTION_URI]")
+            .replace(/\b([A-Z0-9_]*(?:SECRET|TOKEN|PASSWORD|API_KEY|PRIVATE_KEY|CONNECTION_STRING)[A-Z0-9_]*)\s*=\s*[^\s\n]+/g, "$1=[REDACTED]");
+    }
+    /**
+     * Fetches the workspace's static + dynamic profile and optionally semantic search results
+     * in a single fail-open call.
+     */
+    async getContextForWorkspace(workspaceIdOrParams, optionalQuery) {
+        const params = typeof workspaceIdOrParams === "string"
+            ? { workspaceId: workspaceIdOrParams, query: optionalQuery, limit: 5 }
+            : workspaceIdOrParams;
+        const namespace = this.namespaceForWorkspace(params.workspaceId);
+        if (!this.client) {
+            return {
+                enabled: false,
+                namespace,
+                staticFacts: [],
+                dynamicContext: [],
+                recalledMemories: [],
+                formattedPromptContext: "Supermemory v5 disabled (no API key configured).",
+                profile: { static: [], dynamic: [], preferences: [] },
+                relevantMemories: [],
+            };
+        }
+        const limit = Math.min(10, Math.max(1, Number(params.limit || 5)));
+        let staticFacts = [];
+        let dynamicFacts = [];
+        let preferences = [];
+        const relevantMemories = [];
+        try {
+            const profileRes = await this.client.profile(namespace, {
+                ...(params.query ? { q: params.query } : {}),
+            });
+            staticFacts = Array.isArray(profileRes?.profile?.static)
+                ? profileRes.profile.static.map(String)
+                : [];
+            dynamicFacts = Array.isArray(profileRes?.profile?.dynamic)
+                ? profileRes.profile.dynamic.map(String)
+                : [];
+            preferences = Array.isArray(profileRes?.profile?.buckets?.preferences)
+                ? profileRes.profile.buckets.preferences.map(String)
+                : [];
+        }
+        catch {
+            // Fail-open: never block tool planning if profile endpoint times out
+        }
+        if (params.query && params.query.trim().length > 0) {
+            try {
+                const searchRes = await this.client.search(namespace, {
+                    query: params.query.trim(),
+                    limit,
+                    searchMode: "hybrid",
+                    include: { documents: true, forgotten: false, related: false },
+                    rewriteQuery: false,
+                });
+                for (const item of (searchRes?.results || []).slice(0, limit)) {
+                    const doc = item.included?.document;
+                    const title = String(doc?.metadata?.title ||
+                        doc?.title ||
+                        item.memory ||
+                        item.chunk ||
+                        "Workspace Memory").slice(0, 120);
+                    const snippet = String(item.memory || item.chunk || doc?.metadata?.summary || "").slice(0, 300);
+                    relevantMemories.push({
+                        documentId: String(doc?.id || item.id || ""),
+                        title,
+                        snippet,
+                        similarity: Number(item.similarity || 0),
+                    });
+                }
+            }
+            catch {
+                // Fail-open
+            }
+        }
+        const promptLines = [
+            `[Supermemory Brain — Namespace: ${namespace}]`,
+        ];
+        if (staticFacts.length > 0) {
+            promptLines.push(`Static Facts: ${staticFacts.join(" | ")}`);
+        }
+        if (dynamicFacts.length > 0) {
+            promptLines.push(`Dynamic Context: ${dynamicFacts.join(" | ")}`);
+        }
+        if (relevantMemories.length > 0) {
+            promptLines.push(`Recalled Memories: ${relevantMemories.map((m) => `${m.title}: ${m.snippet}`).join(" | ")}`);
+        }
+        return {
+            enabled: true,
+            namespace,
+            staticFacts,
+            dynamicContext: dynamicFacts,
+            recalledMemories: relevantMemories,
+            formattedPromptContext: promptLines.join("\n"),
+            profile: {
+                static: staticFacts,
+                dynamic: dynamicFacts,
+                preferences,
+            },
+            relevantMemories,
+        };
+    }
+    /**
+     * Stores a governed, secret-sanitized document/memory in the workspace's Supermemory v5 namespace.
+     */
+    async addMemory(params) {
+        const namespace = this.namespaceForWorkspace(params.workspaceId);
+        const sanitizedContent = this.sanitizeContent(params.content);
+        const docId = params.documentId || `mem_${crypto.randomBytes(8).toString("hex")}`;
+        if (!this.client) {
+            return {
+                documentId: docId,
+                namespace,
+                status: "local_only",
+                sanitizedContent,
+            };
+        }
+        const res = await this.client.add(namespace, {
+            id: docId,
+            content: `${params.title}\n\n${sanitizedContent}`,
+            taskType: "memory",
+            metadata: {
+                title: params.title,
+                muxoWorkspaceId: params.workspaceId,
+                muxoKind: params.kind,
+                ...(params.metadata || {}),
+            },
+        });
+        return {
+            documentId: String(res.id || docId),
+            namespace,
+            status: String(res.status || "queued"),
+            sanitizedContent,
+        };
+    }
+    async recordExecutionMemory(params) {
+        try {
+            const added = await this.addMemory({
+                workspaceId: params.workspaceId,
+                title: `Execution: ${params.toolSlug} (${params.status})`,
+                content: params.summary,
+                kind: "execution_outcome",
+                metadata: {
+                    toolSlug: params.toolSlug,
+                    lane: params.lane,
+                    riskLevel: params.riskLevel,
+                    status: params.status,
+                },
+            });
+            return added.documentId;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Deletes/forgets a memory document from the workspace's Supermemory v5 namespace.
+     */
+    async deleteMemory(workspaceId, documentId) {
+        const namespace = this.namespaceForWorkspace(workspaceId);
+        if (!this.client) {
+            return { deleted: true, namespace };
+        }
+        try {
+            const res = await this.client.documents.delete(namespace, {
+                ids: [documentId],
+            });
+            return {
+                deleted: (res?.count || 0) >= 1,
+                namespace,
+            };
+        }
+        catch {
+            return { deleted: false, namespace };
+        }
+    }
+}

package/{index.d.ts → dist/sdk.d.ts}

@@ -1,4 +1,4 @@
-import type { ActionPlan, ConnectionRecord, ExecutionReceipt, ExecutionRun, MuxoTool, ProviderLane, ProvisionedResource, RiskLevel, SupplierSettlementSummary, Workspace, WorkspaceMemoryRecord } from "./types.js";
+import type { ActionPlan, ByokKeyRecord, ConnectionRecord, ExecutionReceipt, ExecutionRun, MuxoTool, ProviderLane, ProvisionedResource, RiskLevel, SupplierSettlementSummary, Workspace, WorkspaceMemoryRecord } from "./types.js";
 export interface MuxoClientOptions {
     baseUrl?: string;
     apiKey?: string | (() => string | Promise<string>);
@@ -174,4 +174,80 @@ export declare class MuxoClient {
         namespace: string;
         records: WorkspaceMemoryRecord[];
     }>;
+    do(prompt: string, options?: {
+        input?: Record<string, unknown>;
+        autoApprove?: boolean;
+        dryRun?: boolean;
+    }): Promise<{
+        ok: boolean;
+        executed: boolean;
+        status: string;
+        intent: {
+            toolSlug: string | null;
+            input: Record<string, unknown>;
+            extractedInput: Record<string, unknown>;
+            reason: string;
+            confidence: number;
+        };
+        resolution: Record<string, unknown>;
+        plan?: ActionPlan;
+        run?: ExecutionRun;
+        receipt?: ExecutionReceipt;
+        humanMessage: string;
+    }>;
+    ask(prompt: string, options?: {
+        input?: Record<string, unknown>;
+        autoApprove?: boolean;
+        dryRun?: boolean;
+    }): Promise<{
+        ok: boolean;
+        executed: boolean;
+        status: string;
+        intent: {
+            toolSlug: string | null;
+            input: Record<string, unknown>;
+            extractedInput: Record<string, unknown>;
+            reason: string;
+            confidence: number;
+        };
+        resolution: Record<string, unknown>;
+        plan?: ActionPlan;
+        run?: ExecutionRun;
+        receipt?: ExecutionReceipt;
+        humanMessage: string;
+    }>;
+    listByokKeys(): Promise<{
+        ok: true;
+        workspaceId: string;
+        keys: ByokKeyRecord[];
+    }>;
+    setByokKey(provider: string, secretKey: string): Promise<{
+        ok: true;
+        key: ByokKeyRecord;
+        keys: ByokKeyRecord[];
+    }>;
+    deleteByokKey(provider: string): Promise<{
+        ok: true;
+        deleted: boolean;
+        provider: string;
+        keys: ByokKeyRecord[];
+    }>;
+    upgradePlan(): Promise<{
+        ok: true;
+        tier: string;
+        workspace: Workspace;
+        settlementSummary: SupplierSettlementSummary;
+    }>;
+    createCheckoutSession(kind?: "starter_subscription" | "credit_topup"): Promise<{
+        ok: true;
+        sessionId: string;
+        url: string;
+        mode?: string;
+    }>;
+    verifyCheckoutSession(sessionId: string): Promise<{
+        ok: true;
+        fulfilled: boolean;
+        workspace: Workspace | null;
+        kind: string;
+    }>;
 }

package/dist/sdk.js

@@ -0,0 +1,270 @@
+export class MuxoClient {
+    baseUrl;
+    apiKeyResolver;
+    fetchImpl;
+    timeoutMs;
+    constructor(options = {}) {
+        this.baseUrl = (options.baseUrl ||
+            process.env.MUXO_BASE_URL ||
+            "https://app.muxo.ai").replace(/\/+$/, "");
+        if (typeof options.apiKey === "function") {
+            this.apiKeyResolver = options.apiKey;
+        }
+        else if (typeof options.apiKey === "string") {
+            const key = options.apiKey;
+            this.apiKeyResolver = () => key;
+        }
+        else if (process.env.MUXO_API_KEY) {
+            const key = process.env.MUXO_API_KEY;
+            this.apiKeyResolver = () => key;
+        }
+        this.fetchImpl = options.fetch || fetch;
+        this.timeoutMs = options.timeoutMs ?? 30000;
+    }
+    async request(path, init = {}) {
+        const headers = {
+            Accept: "application/json",
+        };
+        if (this.apiKeyResolver) {
+            const token = await this.apiKeyResolver();
+            if (token)
+                headers.Authorization = `Bearer ${token}`;
+        }
+        if (init.body !== undefined) {
+            headers["Content-Type"] = "application/json";
+        }
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method: init.method || "GET",
+            headers,
+            body: init.body !== undefined ? JSON.stringify(init.body) : undefined,
+            signal: AbortSignal.timeout(this.timeoutMs),
+        });
+        const payload = (await res.json());
+        if (!res.ok || payload.ok === false) {
+            throw new Error(String(payload.error || `Muxo request failed with HTTP ${res.status}`));
+        }
+        return payload;
+    }
+    static async signup(params = {}, baseUrl = "https://app.muxo.ai") {
+        const client = new MuxoClient({ baseUrl });
+        return client.signupAgent({
+            agentName: params.agentName || params.workspaceName || "muxo-sdk-agent",
+            harness: params.harness || "muxo-sdk",
+        });
+    }
+    async signupAgent(params) {
+        return this.request("/api/v1/agents/signup", {
+            method: "POST",
+            body: params,
+        });
+    }
+    async whoami() {
+        const res = await this.mcpCall("get_organization", {});
+        const workspace = (res.workspace || res.organization);
+        return {
+            ok: true,
+            ...res,
+            workspace,
+        };
+    }
+    async mcpCall(name, args = {}) {
+        const rpcRes = await this.request("/mcp", {
+            method: "POST",
+            body: {
+                jsonrpc: "2.0",
+                id: Date.now(),
+                method: "tools/call",
+                params: { name, arguments: args },
+            },
+        });
+        if (rpcRes.error) {
+            throw new Error(rpcRes.error.message || "MCP call failed");
+        }
+        if (rpcRes.result?.structuredContent) {
+            return rpcRes.result.structuredContent;
+        }
+        const text = rpcRes.result?.content?.[0]?.text;
+        if (text) {
+            return JSON.parse(text);
+        }
+        return (rpcRes.result || {});
+    }
+    async searchTools(params) {
+        const qs = new URLSearchParams();
+        if (params?.query)
+            qs.set("query", params.query);
+        if (params?.lane)
+            qs.set("lane", params.lane);
+        if (params?.riskLevel)
+            qs.set("risk_level", params.riskLevel);
+        if (params?.limit)
+            qs.set("limit", String(params.limit));
+        const suffix = qs.toString() ? `?${qs.toString()}` : "";
+        return this.request(`/api/v1/tools${suffix}`);
+    }
+    async inspectTool(slug) {
+        return this.request(`/api/v1/tools/${encodeURIComponent(slug)}`);
+    }
+    async planAction(params) {
+        return this.request("/api/v1/plans", {
+            method: "POST",
+            body: params,
+        });
+    }
+    async approvePlan(planId) {
+        return this.request(`/api/v1/plans/${encodeURIComponent(planId)}/approve`, {
+            method: "POST",
+        });
+    }
+    async executePlan(planId) {
+        return this.request(`/api/v1/plans/${encodeURIComponent(planId)}/execute`, {
+            method: "POST",
+        });
+    }
+    async exec(toolSlug, input = {}, options = {}) {
+        const planned = await this.planAction({
+            toolSlug,
+            input,
+            reason: options.reason,
+        });
+        let plan = planned.plan;
+        if (plan.approvalStatus === "pending_approval" && options.approve) {
+            const approved = await this.approvePlan(plan.id);
+            plan = approved.plan;
+        }
+        const executed = await this.executePlan(plan.id);
+        return {
+            ok: true,
+            plan,
+            run: executed.run,
+            receipt: executed.receipt,
+            settlement: executed.settlement ||
+                executed.receipt?.supplierSettlement ||
+                null,
+        };
+    }
+    async verifyReceipt(receiptId) {
+        const res = await this.request(`/api/v1/receipts/${encodeURIComponent(receiptId)}`);
+        const isOk = Boolean(res.valid ?? res.verified ?? true);
+        return {
+            ok: true,
+            valid: isOk,
+            verified: isOk,
+            receipt: res.receipt,
+        };
+    }
+    async startConnection(paramsOrProvider) {
+        const body = typeof paramsOrProvider === "string"
+            ? { provider: paramsOrProvider }
+            : paramsOrProvider;
+        return this.request("/api/v1/connections", {
+            method: "POST",
+            body,
+        });
+    }
+    async waitForConnection(paramsOrProvider, options) {
+        const body = typeof paramsOrProvider === "string"
+            ? { provider: paramsOrProvider, ...options }
+            : paramsOrProvider;
+        const res = await this.request("/api/v1/connections/wait", {
+            method: "POST",
+            body,
+        });
+        return {
+            ...res,
+            status: res.status || res.connection?.status || "pending",
+        };
+    }
+    async listResources() {
+        return this.request("/api/v1/resources");
+    }
+    async pullEnv() {
+        const res = await this.request("/api/v1/resources/env");
+        return Object.assign(res, {
+            includes: (substr) => String(res.dotenv || "").includes(substr),
+            toString: () => String(res.dotenv || ""),
+        });
+    }
+    async topupCredits(paramsOrCredits, description) {
+        const body = typeof paramsOrCredits === "number"
+            ? { credits: paramsOrCredits, description }
+            : paramsOrCredits;
+        const res = await this.request("/api/v1/billing/topup", {
+            method: "POST",
+            body,
+        });
+        return {
+            ...res,
+            creditBalance: res.creditBalance ?? res.workspace?.creditsBalance ?? 0,
+        };
+    }
+    async getBillingStatus() {
+        return this.getSettlements();
+    }
+    async settlements() {
+        const res = await this.getSettlements();
+        return {
+            ...res,
+            summary: res.settlementSummary,
+        };
+    }
+    async getSettlements() {
+        const res = await this.request("/api/v1/billing/settlements");
+        if (res.settlementSummary &&
+            res.settlementSummary.totalCustomerChargedCredits === undefined) {
+            res.settlementSummary.totalCustomerChargedCredits =
+                res.settlementSummary.totalCreditsConsumed;
+        }
+        return res;
+    }
+    async recallMemory(query) {
+        const suffix = query ? `?query=${encodeURIComponent(query)}` : "";
+        return this.request(`/api/v1/memory${suffix}`);
+    }
+    async do(prompt, options = {}) {
+        return this.request("/api/v1/do", {
+            method: "POST",
+            body: {
+                prompt,
+                input: options.input,
+                autoApprove: options.autoApprove !== false,
+                dryRun: options.dryRun === true,
+            },
+        });
+    }
+    async ask(prompt, options) {
+        return this.do(prompt, options);
+    }
+    async listByokKeys() {
+        return this.request("/api/v1/byok");
+    }
+    async setByokKey(provider, secretKey) {
+        return this.request("/api/v1/byok", {
+            method: "POST",
+            body: { provider, secretKey },
+        });
+    }
+    async deleteByokKey(provider) {
+        return this.request(`/api/v1/byok/${encodeURIComponent(provider)}`, {
+            method: "DELETE",
+        });
+    }
+    async upgradePlan() {
+        return this.request("/api/v1/billing/upgrade", {
+            method: "POST",
+            body: {},
+        });
+    }
+    async createCheckoutSession(kind = "credit_topup") {
+        return this.request("/api/v1/billing/checkout", {
+            method: "POST",
+            body: { kind },
+        });
+    }
+    async verifyCheckoutSession(sessionId) {
+        return this.request("/api/v1/billing/verify-session", {
+            method: "POST",
+            body: { sessionId },
+        });
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,10 @@
+import http from "node:http";
+import { type MuxoConfig } from "./config.js";
+import { MuxoEngine } from "./engine.js";
+import { MuxoStore } from "./store.js";
+export declare function createMuxoServer(customConfig?: Partial<MuxoConfig>): {
+    server: http.Server;
+    engine: MuxoEngine;
+    store: MuxoStore;
+    defaultApiKey?: string;
+};