@muxoai/platform 1.3.3 → 1.4.1

package/dist/mcp-schema.js

@@ -0,0 +1,1076 @@
+export const MCP_TOOLS_OAUTH_SCOPE = "mcp:tools";
+/** Workspace-bound tools require an OAuth bearer token (or workspace API key). */
+export const DEFAULT_TOOL_SECURITY_SCHEMES = [
+    { type: "oauth2", scopes: [MCP_TOOLS_OAUTH_SCOPE] },
+];
+/** Catalog discovery tools work anonymously and also accept OAuth. */
+export const PUBLIC_TOOL_SECURITY_SCHEMES = [
+    { type: "noauth" },
+    { type: "oauth2", scopes: [MCP_TOOLS_OAUTH_SCOPE] },
+];
+export const PUBLIC_MCP_TOOL_NAMES = new Set([
+    "search_tools",
+    "inspect_tool",
+    "search",
+    "fetch",
+]);
+/** Stable per-workspace agent identity returned at agent signup on both runtimes. */
+export function workspaceAgentDid(workspaceId) {
+    return `did:agent:muxo:${workspaceId}`;
+}
+/** JSON-RPC methods that anonymous MCP clients may call for discovery. */
+export const PUBLIC_MCP_METHODS = new Set([
+    "initialize",
+    "ping",
+    "tools/list",
+    "resources/list",
+    "resources/read",
+    "resources/templates/list",
+    "prompts/list",
+]);
+/** True when a single JSON-RPC MCP request only needs public discovery access. */
+export function isPublicMcpRequest(rpc) {
+    if (!rpc || typeof rpc !== "object" || Array.isArray(rpc))
+        return false;
+    const message = rpc;
+    const method = String(message.method || "");
+    if (method.startsWith("notifications/") || PUBLIC_MCP_METHODS.has(method))
+        return true;
+    if (method === "tools/call") {
+        const params = (message.params || {});
+        return PUBLIC_MCP_TOOL_NAMES.has(String(params.name || ""));
+    }
+    return false;
+}
+export function securitySchemesForTool(name) {
+    return PUBLIC_MCP_TOOL_NAMES.has(name)
+        ? PUBLIC_TOOL_SECURITY_SCHEMES
+        : DEFAULT_TOOL_SECURITY_SCHEMES;
+}
+/** Maximum in-turn polling window for wait_for_connection and get_plan(wait_for_approval). */
+export const MAX_MCP_WAIT_SECONDS = 120;
+export const DEFAULT_MCP_WAIT_SECONDS = 15;
+export function clampWaitSeconds(raw, fallback = DEFAULT_MCP_WAIT_SECONDS, max = MAX_MCP_WAIT_SECONDS) {
+    const n = raw === undefined || raw === null || raw === "" ? fallback : Number(raw);
+    if (!Number.isFinite(n))
+        return Math.min(fallback, max);
+    return Math.max(0, Math.min(max, n));
+}
+/** Matches explicit catalog slugs (e.g. 'app.github.create_issue') as opposed to natural-language requests. */
+export function looksLikeToolSlug(raw) {
+    return /^[a-z0-9_-]+(\.[a-z0-9_-]+)+$/i.test(String(raw || "").trim());
+}
+/**
+ * Picks the live Composio search hit for a requested `app.<toolkit>.<action>` slug: an exact
+ * slug/upstream match, else a same-toolkit tool whose slug contains every action word. Returns
+ * null rather than an unrelated top search result.
+ */
+export function matchAppToolSlug(requestedSlug, candidates) {
+    const clean = String(requestedSlug || "").trim();
+    const parts = clean.split(".");
+    if (parts[0] !== "app" || parts.length < 3)
+        return null;
+    const toolkit = parts[1].toLowerCase();
+    const action = parts.slice(2).join("_").toLowerCase();
+    const upstream = `${toolkit}_${action}`.toUpperCase();
+    const exact = candidates.find((c) => c.slug === clean || c.upstreamSlug.toUpperCase() === upstream);
+    if (exact)
+        return exact;
+    const words = action.split(/[_\s]+/).filter(Boolean);
+    if (words.length === 0)
+        return null;
+    return (candidates.find((c) => c.providerSlug.toLowerCase() === toolkit &&
+        words.every((w) => c.slug.toLowerCase().includes(w))) || null);
+}
+export const DEFAULT_MCP_SKILL_NAME = "muxo";
+/**
+ * SEP-2640 `skills/get` lookup. A `uri` takes precedence over `name`, and a miss returns
+ * `skill: undefined` so callers answer with JSON-RPC -32602 rather than a default skill.
+ */
+export function findMcpSkill(skills, params) {
+    const requestedUri = String(params.uri || "").trim();
+    if (requestedUri) {
+        return { skill: skills.find((s) => s.uri === requestedUri), requested: requestedUri };
+    }
+    const requestedName = String(params.name || "").trim() || DEFAULT_MCP_SKILL_NAME;
+    return { skill: skills.find((s) => s.name === requestedName), requested: requestedName };
+}
+export const APPROVED_PLAN_STATUSES = new Set([
+    "approved",
+    "auto_approved",
+    "executed",
+]);
+export const GET_RUN_CONTEXT_ACTIONS = [
+    "inspect",
+    "remember",
+    "recall",
+    "forget",
+    "memory_graph",
+    "set_guardrail",
+    "governance_status",
+    "scan_context",
+    "list_workspaces",
+    "switch_workspace",
+    "onboard_team",
+];
+/** Error carrying a structured MCP/REST payload (merged into structuredContent / JSON body). */
+export class MuxoToolError extends Error {
+    code;
+    statusCode;
+    payload;
+    constructor(message, options) {
+        super(message);
+        this.name = "MuxoToolError";
+        this.code = options.code;
+        this.statusCode = options.statusCode ?? 400;
+        this.payload = { code: options.code, ...(options.payload || {}) };
+    }
+}
+export function unknownToolError(slug) {
+    const clean = String(slug || "").trim();
+    const keyword = clean.split(".").filter(Boolean).slice(-1)[0] || clean;
+    const message = clean
+        ? `Tool not found: '${clean}' is not in the Muxo catalog. Call search_tools with a keyword (e.g. query "${keyword}") to find a valid tool slug, then call inspect_tool or plan_action with that slug.`
+        : "tool_slug is required. Call search_tools to find a valid tool slug, then call inspect_tool or plan_action with that slug.";
+    return new MuxoToolError(message, {
+        code: "tool_not_found",
+        statusCode: 404,
+        payload: {
+            toolSlug: clean || null,
+            recovery: {
+                summary: "Search the catalog for a valid slug, then retry with it.",
+                nextToolCalls: [
+                    {
+                        tool: "search_tools",
+                        input: { query: keyword || "" },
+                        when: "To find the correct tool slug",
+                    },
+                ],
+            },
+        },
+    });
+}
+export function buildApprovalUrl(baseUrl, planId) {
+    return `${baseUrl.replace(/\/$/, "")}/approve/${encodeURIComponent(planId)}`;
+}
+/** Structured response returned when execute_<risk> is called on a plan still awaiting approval. */
+export function buildApprovalRequiredPayload(baseUrl, plan) {
+    const approvalUrl = buildApprovalUrl(baseUrl, plan.id);
+    return {
+        approvalRequired: true,
+        planId: plan.id,
+        toolSlug: plan.toolSlug,
+        riskLevel: plan.riskLevel,
+        approvalStatus: plan.approvalStatus,
+        approvalUrl,
+        humanHandoff: {
+            kind: "approval",
+            url: approvalUrl,
+            ctaLabel: "Review & approve",
+            headline: `Muxo needs your approval to run ${plan.toolSlug}`,
+            instructions: `Open ${approvalUrl} to review and approve this ${plan.riskLevel}-risk action with one click (or run \`muxo approve ${plan.id}\`). Nothing runs until you approve.`,
+            planId: plan.id,
+        },
+        polling: {
+            tool: "get_plan",
+            input: { plan_id: plan.id, wait_for_approval: true, timeout_seconds: 30 },
+            restUrl: `${baseUrl.replace(/\/$/, "")}/api/v1/plans/${encodeURIComponent(plan.id)}/wait?timeout_seconds=30`,
+        },
+        llmGuidance: {
+            summary: `Plan ${plan.id} is awaiting human approval. Share ${approvalUrl} with the user, poll get_plan(wait_for_approval: true), then call execute_${plan.riskLevel} once approved.`,
+            nextToolCalls: [
+                {
+                    tool: "get_plan",
+                    input: { plan_id: plan.id, wait_for_approval: true, timeout_seconds: 30 },
+                    when: `After sharing ${approvalUrl} with the user, to wait in-turn until they click Approve`,
+                },
+                {
+                    tool: `execute_${plan.riskLevel}`,
+                    input: { plan_id: plan.id },
+                    when: "Only after get_plan reports approved: true",
+                },
+            ],
+        },
+    };
+}
+export function approvalRequiredError(baseUrl, plan) {
+    const approvalUrl = buildApprovalUrl(baseUrl, plan.id);
+    return new MuxoToolError(`Plan '${plan.id}' (${plan.riskLevel}) is awaiting human approval. Open ${approvalUrl} to approve it (or run 'muxo approve ${plan.id}'), then poll get_plan with wait_for_approval: true before calling execute_${plan.riskLevel}.`, {
+        code: "approval_required",
+        statusCode: 409,
+        payload: buildApprovalRequiredPayload(baseUrl, plan),
+    });
+}
+export function errorPayloadFrom(err, fallback = "Tool execution failed") {
+    const message = String(err?.message || err || fallback);
+    return err instanceof MuxoToolError
+        ? { ok: false, error: message, ...err.payload }
+        : { ok: false, error: message };
+}
+/**
+ * MCP onboard_team never mints credentials in-band; it returns the human handoff
+ * (Console / CLI / REST) that issues a Team API key so secrets stay out of agent transcripts.
+ */
+export function buildOnboardTeamGuide(input) {
+    const base = input.baseUrl.replace(/\/$/, "");
+    const teamName = (input.teamName || "").trim() || "Engineering Team";
+    return {
+        ok: true,
+        action: "onboard_team",
+        workspaceId: input.workspaceId,
+        workspaceName: input.workspaceName,
+        teamName,
+        consoleUrl: `${base}/keys`,
+        onboardingEndpoint: {
+            method: "POST",
+            url: `${base}/api/v1/workspaces/onboard-team`,
+            body: { teamName, mode: "shared_workspace", role: "operator" },
+        },
+        cli: {
+            onboard: `muxo workspace onboard-team --team "${teamName}"`,
+            join: "muxo workspace join --api-key <team_key>",
+        },
+        instructions: "Generate a shared Team API Key in the Muxo Console (API Keys & Access), via `muxo workspace onboard-team`, or POST /api/v1/workspaces/onboard-team; teammates then join with `muxo workspace join --api-key <key>`.",
+        workspaces: input.workspaces || [],
+    };
+}
+/**
+ * Concise server instructions (<512 chars) per OpenAI Plugin MCP Server specification:
+ * https://developers.openai.com/plugins/build/mcp-server
+ */
+export const MUXO_MCP_SERVER_INSTRUCTIONS = "Muxo governs SaaS actions (app.*), Instant tools (instant.*), Cloud Infrastructure (resource.*), Memory, and Guardrails. Workflow: 1) search_tools & inspect_tool. 2) plan_action to get a plan_*. 3) If authHandoff.required, show humanHandoff.url and call wait_for_connection. 4) If approvalStatus is pending_approval, send humanHandoff.url or call get_plan(wait_for_approval:true). 5) Execute via execute_<risk>. 6) Manage memory/guardrails via get_run_context.";
+export const MUXO_MCP_TOOLS = [
+    {
+        name: "get_profile",
+        title: "Get Authenticated Profile",
+        description: "Get the authenticated actor profile, user ID, email, workspace ID, and subscription tier.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        },
+        outputSchema: {
+            $schema: "https://json-schema.org/draft/2020-12/schema",
+            type: "object",
+            properties: {
+                id: {
+                    type: "string",
+                    minLength: 1,
+                    pattern: "\\S",
+                    description: "Unique identifier for the user.",
+                },
+                name: {
+                    type: "string",
+                    description: "Full name of the user.",
+                },
+                email: {
+                    type: "string",
+                    description: "Email address of the user.",
+                },
+                nickname: {
+                    type: "string",
+                    description: "Handle or username of the user.",
+                },
+                workspaceId: {
+                    type: "string",
+                    description: "Active workspace ID.",
+                },
+                workspaceName: {
+                    type: "string",
+                    description: "Active workspace name.",
+                },
+                tier: {
+                    type: "string",
+                    description: "Workspace subscription tier.",
+                },
+                authType: {
+                    type: "string",
+                    description: "Authentication type (session or api_key).",
+                },
+                actorId: {
+                    type: "string",
+                    description: "Actor identifier.",
+                },
+                user: {
+                    type: "object",
+                    description: "User profile record.",
+                },
+            },
+            required: ["id"],
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+        _meta: {
+            "openai/profile": true,
+        },
+    },
+    {
+        name: "get_organization",
+        title: "Get Organization & Billing Summary",
+        description: "Get workspace governance policy, plain-English guardrails, monthly action usage, credit balance, workspace memberships, and active connection/resource counts.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+    },
+    {
+        name: "search_tools",
+        title: "Search Unified Tool Catalog",
+        description: "Search the unified Muxo catalog across Connected Apps (app.*), Instant Tools (instant.*), Billing (billing.*), and Cloud Infrastructure (resource.*).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Search keywords (e.g. 'postgres', 'github issue', 'web search', 'seo audit', 'stripe refund', 'redis')",
+                },
+                lane: {
+                    type: "string",
+                    enum: ["all", "composio_sdk", "composio_instant", "stripe_projects"],
+                    default: "all",
+                },
+                risk_level: {
+                    type: "string",
+                    enum: [
+                        "read",
+                        "write",
+                        "admin",
+                        "financial",
+                        "provisioning",
+                        "destructive",
+                    ],
+                },
+                limit: { type: "number", default: 20 },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: "inspect_tool",
+        title: "Inspect Tool Schema & Risk",
+        description: "Inspect a tool's full input JSON schema, risk classification, provider lane, LLM context URL, and credit cost before planning.",
+        inputSchema: {
+            type: "object",
+            required: ["tool_slug"],
+            properties: {
+                tool_slug: {
+                    type: "string",
+                    description: "Canonical Muxo tool slug (e.g. 'instant.seo.audit', 'app.gmail.send_email', 'billing.stripe.create_refund', or 'resource.turso.database')",
+                },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+    },
+    {
+        name: "connection_status",
+        title: "Check Connection Status",
+        description: "Check connection status across Connected Apps, Instant Tools, and linked Cloud Infrastructure providers.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                provider: {
+                    type: "string",
+                    description: "Optional provider filter (e.g. 'github', 'gmail', 'slack', 'neon', 'turso')",
+                },
+                sync_live: {
+                    type: "boolean",
+                    default: true,
+                    description: "Whether to sync live connection status from upstream providers",
+                },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: "start_connection",
+        title: "Start OAuth Connection Handoff",
+        description: "Initiate a managed OAuth connection handoff for a Connected App or link a Cloud Infrastructure provider.",
+        inputSchema: {
+            type: "object",
+            required: ["provider"],
+            properties: {
+                provider: {
+                    type: "string",
+                    description: "Provider or toolkit slug (e.g. 'github', 'gmail', 'slack', 'neon')",
+                },
+                lane: {
+                    type: "string",
+                    enum: ["composio_sdk", "stripe_projects"],
+                    description: "Provider lane (defaults to composio_sdk unless prefixed with resource.)",
+                },
+                callback_url: {
+                    type: "string",
+                    description: "Optional OAuth callback URL",
+                },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: "wait_for_connection",
+        title: "Wait for OAuth Connection Handoff",
+        description: "Poll and wait for an external user's pending OAuth connection handoff to become active before resuming a planned operation.",
+        inputSchema: {
+            type: "object",
+            required: ["provider"],
+            properties: {
+                provider: {
+                    type: "string",
+                    description: "Provider or toolkit slug (e.g. 'github', 'gmail', 'slack', 'notion', 'linear')",
+                },
+                timeout_seconds: {
+                    type: "number",
+                    default: 15,
+                    description: "Maximum seconds to poll for OAuth completion (0-120, default 15)",
+                },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: "plan_action",
+        title: "Create Governed Action Plan",
+        description: "Create a governed execution plan (plan_*) for any tool, billing operation, or infrastructure provisioning operation. Accepts either an exact tool_slug (e.g. 'instant.seo.audit', 'app.gmail.send_email', 'billing.stripe.create_refund', 'resource.turso.database') or a natural-language instruction. Evaluates workspace policy, conditional parameter guardrails, risk level, Workspace Memory recall, BYOK vs Muxo-funded mode, and credit balance.",
+        inputSchema: {
+            type: "object",
+            required: ["tool_slug"],
+            properties: {
+                tool_slug: {
+                    type: "string",
+                    description: "Muxo tool slug (e.g. 'instant.seo.audit', 'billing.stripe.create_refund') or natural-language request",
+                },
+                input: {
+                    type: "object",
+                    description: "Arguments matching the tool's inputSchema (auto-extracted when tool_slug is natural language)",
+                },
+                reason: {
+                    type: "string",
+                    description: "Audit reason explaining why this action is being planned",
+                },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+    },
+    {
+        name: "get_plan",
+        title: "Get Action Plan",
+        description: "Inspect the status, risk level, governance decision record, and approval state of a planned action. Set wait_for_approval: true to poll in-turn while a human approves the plan at /approve/<plan_id>.",
+        inputSchema: {
+            type: "object",
+            required: ["plan_id"],
+            properties: {
+                plan_id: { type: "string", description: "Plan ID (plan_*)" },
+                wait_for_approval: {
+                    type: "boolean",
+                    description: "If true, wait in-turn (up to timeout_seconds) until the plan transitions out of pending_approval.",
+                },
+                timeout_seconds: {
+                    type: "number",
+                    description: "Maximum seconds to wait when wait_for_approval is true (default 15, max 60).",
+                },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+    },
+    {
+        name: "get_run_context",
+        title: "Get & Manage Workspace Context, Memory & Guardrails",
+        description: "Get or manage the workspace runtime context, Supermemory v5 contextual brain (profile, hybrid search recall, remember/forget, bi-temporal knowledge graph), conditional Guardrails (natural language or structured parameter_rules compiled by your LLM harness), workspace switching, and active provisioned resources.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Optional semantic search query to recall relevant workspace memories or filter the bi-temporal knowledge graph",
+                },
+                action: {
+                    type: "string",
+                    enum: [
+                        "inspect",
+                        "remember",
+                        "recall",
+                        "forget",
+                        "memory_graph",
+                        "set_guardrail",
+                        "governance_status",
+                        "scan_context",
+                        "list_workspaces",
+                        "switch_workspace",
+                        "onboard_team",
+                    ],
+                    description: "Control-plane operation: 'inspect' (default), 'remember' (save fact/preference), 'recall' (list memories), 'forget' (delete matching memories), 'memory_graph' (bi-temporal entity/relationship lineage), 'set_guardrail' (apply plain-English or structured parameter_rules guardrail), 'governance_status', 'scan_context' (OWASP ASI-06 check), 'list_workspaces', 'switch_workspace', or 'onboard_team'",
+                },
+                prompt: {
+                    type: "string",
+                    description: "Natural-language instruction when action is 'remember', 'set_guardrail', or 'scan_context' (e.g. 'Only allow sending emails to @muxo.ai' or 'Require approval for Stripe refunds over $50, auto-approve under $50')",
+                },
+                parameter_rules: {
+                    type: "array",
+                    description: "Optional structured conditional parameter guardrail rules compiled by the caller LLM harness when action='set_guardrail'. Each item: { toolPattern, parameter, operator, value, unit?, action, elseAction?, description }",
+                    items: {
+                        type: "object",
+                        properties: {
+                            id: { type: "string" },
+                            toolPattern: {
+                                type: "string",
+                                description: "Tool slug or wildcard pattern (e.g. 'app.gmail.send_email', '*refund*', '*email*')",
+                            },
+                            parameter: {
+                                type: "string",
+                                description: "Parameter name or comma-separated aliases (e.g. 'to', 'amount', 'channel')",
+                            },
+                            operator: {
+                                type: "string",
+                                enum: [
+                                    "equals",
+                                    "must_equal",
+                                    "not_equals",
+                                    "contains",
+                                    "not_contains",
+                                    "starts_with",
+                                    "must_start_with",
+                                    "ends_with",
+                                    "must_end_with",
+                                    "domain_in",
+                                    "domain_not_in",
+                                    "max_number",
+                                    "min_number",
+                                    "gt",
+                                    "gte",
+                                    "lt",
+                                    "lte",
+                                    "in",
+                                    "not_in",
+                                    "regex",
+                                ],
+                            },
+                            value: {
+                                description: "Target value (string, number, or array of strings)",
+                            },
+                            unit: {
+                                type: "string",
+                                enum: ["usd", "cents", "credits", "raw"],
+                            },
+                            action: {
+                                type: "string",
+                                enum: ["block", "require_approval", "allow", "auto_approve"],
+                            },
+                            elseAction: {
+                                type: "string",
+                                enum: ["block", "require_approval", "allow", "auto_approve"],
+                            },
+                            description: { type: "string" },
+                        },
+                    },
+                },
+                workspace_id: {
+                    type: "string",
+                    description: "Target workspace ID when action='switch_workspace'",
+                },
+                team_name: {
+                    type: "string",
+                    description: "Team name when action='onboard_team'",
+                },
+                title: {
+                    type: "string",
+                    description: "Optional memory title when saving a fact via action='remember'",
+                },
+                content: {
+                    type: "string",
+                    description: "Optional memory content or text to scan",
+                },
+                include_graph: {
+                    type: "boolean",
+                    description: "If true, attach the Bi-Temporal Knowledge Graph (nodes, activeEdges, historicalEdges, mermaid) to the context response",
+                },
+                plan_id: {
+                    type: "string",
+                    description: "Optional plan ID to inspect context for",
+                },
+                run_id: {
+                    type: "string",
+                    description: "Optional run ID to inspect context for",
+                },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+    },
+    {
+        name: "execute_read",
+        title: "Execute Read Plan",
+        description: "Execute an approved plan with riskLevel = 'read'.",
+        inputSchema: {
+            type: "object",
+            required: ["plan_id"],
+            properties: {
+                plan_id: { type: "string", description: "Plan ID (plan_*)" },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: "execute_write",
+        title: "Execute Write Plan",
+        description: "Execute an approved plan with riskLevel = 'write'.",
+        inputSchema: {
+            type: "object",
+            required: ["plan_id"],
+            properties: {
+                plan_id: { type: "string", description: "Plan ID (plan_*)" },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: "execute_admin",
+        title: "Execute Admin Plan",
+        description: "Execute an approved plan with riskLevel = 'admin'.",
+        inputSchema: {
+            type: "object",
+            required: ["plan_id"],
+            properties: {
+                plan_id: { type: "string", description: "Plan ID (plan_*)" },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: "execute_financial",
+        title: "Execute Financial Plan",
+        description: "Execute an approved plan with riskLevel = 'financial'.",
+        inputSchema: {
+            type: "object",
+            required: ["plan_id"],
+            properties: {
+                plan_id: { type: "string", description: "Plan ID (plan_*)" },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: "execute_provisioning",
+        title: "Execute Infrastructure Provisioning Plan",
+        description: "Execute an approved infrastructure provisioning plan with riskLevel = 'provisioning' via Stripe Projects.",
+        inputSchema: {
+            type: "object",
+            required: ["plan_id"],
+            properties: {
+                plan_id: { type: "string", description: "Plan ID (plan_*)" },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: "execute_destructive",
+        title: "Execute Destructive Plan",
+        description: "Execute an approved plan with riskLevel = 'destructive'.",
+        inputSchema: {
+            type: "object",
+            required: ["plan_id"],
+            properties: {
+                plan_id: { type: "string", description: "Plan ID (plan_*)" },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: "get_run",
+        title: "Get Execution Run",
+        description: "Get the execution status, output, duration, and metered cost of a run (run_*).",
+        inputSchema: {
+            type: "object",
+            required: ["run_id"],
+            properties: {
+                run_id: { type: "string", description: "Run ID (run_*)" },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+    },
+    {
+        name: "cancel_run",
+        title: "Cancel Execution Run",
+        description: "Cancel a run (status becomes 'cancelled') and issue a signed cancellation receipt. Completed runs cannot be cancelled.",
+        inputSchema: {
+            type: "object",
+            required: ["run_id"],
+            properties: {
+                run_id: { type: "string", description: "Run ID (run_*)" },
+                reason: {
+                    type: "string",
+                    description: "Optional audit reason recorded on the cancellation receipt",
+                },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            openWorldHint: false,
+        },
+    },
+    {
+        name: "get_receipt",
+        title: "Verify Execution Receipt",
+        description: "Fetch and cryptographically verify the HMAC-SHA256 + portable Ed25519 AgenticReceipt + Microsoft Governance DecisionRecord for a run (or pass receipt_id='latest' or 'chain' / verify_chain=true to audit the full workspace hash chain).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                receipt_id: {
+                    type: "string",
+                    description: "Receipt ID (rcpt_*), Run ID (run_*), 'latest', or 'chain'. Provide receipt_id or run_id.",
+                },
+                run_id: {
+                    type: "string",
+                    description: "Run ID (run_*) whose receipt should be returned",
+                },
+                verify_chain: {
+                    type: "boolean",
+                    description: "If true, also verify the entire workspace receipt SHA-256 + Ed25519 hash chain from genesis to head",
+                },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+    },
+];
+/**
+ * OpenAI Company Knowledge standard `search` and `fetch` tool definitions
+ * per https://developers.openai.com/plugins/build/mcp-server#company-knowledge-compatibility
+ */
+export const OPENAI_COMPANY_KNOWLEDGE_TOOLS = [
+    {
+        name: "search",
+        title: "Search Muxo Tools & Workspace Memory",
+        description: "Search across Muxo tools, provisioned cloud resources, and Supermemory v5 workspace knowledge.",
+        inputSchema: {
+            type: "object",
+            required: ["query"],
+            properties: {
+                query: { type: "string", description: "Search query string." },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+    },
+    {
+        name: "fetch",
+        title: "Fetch Muxo Tool or Memory Record",
+        description: "Retrieve complete details for a Muxo tool, resource, or workspace memory record by ID.",
+        inputSchema: {
+            type: "object",
+            required: ["id"],
+            properties: {
+                id: {
+                    type: "string",
+                    description: "Identifier returned by search (e.g. 'tool:instant.seo.audit' or 'memory:mem_123').",
+                },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+    },
+];
+/**
+ * Enriches any MCP tool output object with structured `llmGuidance` so agent harnesses
+ * (Claude Code, Cursor, Codex, OpenAI MCP, Windsurf) always know the exact next tool call.
+ */
+export function attachMcpHarnessGuidance(toolName, toolArgs, output) {
+    if (!output || typeof output !== "object" || Array.isArray(output)) {
+        return output;
+    }
+    const obj = output;
+    if (obj.llmGuidance) {
+        return output;
+    }
+    let guidance = null;
+    switch (toolName) {
+        case "get_profile":
+        case "get_organization":
+            guidance = {
+                summary: "Workspace identity verified. Call get_run_context to load memory & guardrails, or search_tools to discover capabilities.",
+                nextToolCalls: [
+                    {
+                        tool: "get_run_context",
+                        input: { action: "inspect" },
+                        when: "Before planning actions, to load active memory defaults and guardrails",
+                    },
+                    {
+                        tool: "search_tools",
+                        input: { query: "" },
+                        when: "To discover available Instant, Connected App, and Cloud Infrastructure tools",
+                    },
+                ],
+            };
+            break;
+        case "search_tools": {
+            const firstSlug = Array.isArray(obj.tools) && obj.tools[0]?.slug
+                ? String(obj.tools[0].slug)
+                : "<tool_slug>";
+            guidance = {
+                summary: `Found ${Array.isArray(obj.tools) ? obj.tools.length : 0} matching tools. Call inspect_tool to check inputSchema or plan_action to create an execution plan.`,
+                nextToolCalls: [
+                    {
+                        tool: "inspect_tool",
+                        input: { tool_slug: firstSlug },
+                        when: "To inspect required parameters and risk level before planning",
+                    },
+                    {
+                        tool: "plan_action",
+                        input: {
+                            tool_slug: firstSlug,
+                            input: {},
+                            reason: "Execute user request",
+                        },
+                        when: "When you have the required input parameters ready",
+                    },
+                ],
+            };
+            break;
+        }
+        case "inspect_tool": {
+            const slug = String(obj.slug || toolArgs.tool_slug || "<tool_slug>");
+            guidance = {
+                summary: `Inspected ${slug} (risk=${String(obj.riskLevel || "read")}). Call plan_action with input matching inputSchema.`,
+                nextToolCalls: [
+                    {
+                        tool: "plan_action",
+                        input: {
+                            tool_slug: slug,
+                            input: {},
+                            reason: `Execute ${slug}`,
+                        },
+                        when: "Next, to evaluate workspace guardrails and obtain a plan_id",
+                    },
+                ],
+            };
+            break;
+        }
+        case "start_connection": {
+            const provider = String(obj.providerSlug || toolArgs.provider || "<provider>");
+            guidance = {
+                summary: obj.redirectUrl
+                    ? `Share ${String(obj.redirectUrl)} with the user so they can authorize ${provider}, then call wait_for_connection.`
+                    : `Connection status for ${provider}: ${String(obj.status || "active")}.`,
+                nextToolCalls: [
+                    {
+                        tool: "wait_for_connection",
+                        input: { provider, timeout_seconds: 30 },
+                        when: "While the user completes the browser OAuth flow",
+                    },
+                ],
+            };
+            break;
+        }
+        case "wait_for_connection": {
+            const provider = String(obj.provider || toolArgs.provider || "<provider>");
+            guidance = obj.connected
+                ? {
+                    summary: `${provider} is connected and active. Proceed to plan_action or execute_<riskLevel>.`,
+                    nextToolCalls: [
+                        {
+                            tool: "plan_action",
+                            input: {
+                                tool_slug: `app.${provider}.`,
+                                input: {},
+                                reason: "Execute connected app action",
+                            },
+                            when: "Now that OAuth connection is active",
+                        },
+                    ],
+                }
+                : {
+                    summary: `Still awaiting user OAuth completion for ${provider}. Ask the user to open ${String(obj.redirectUrl || "the authorization URL")} and call wait_for_connection again.`,
+                    nextToolCalls: [
+                        {
+                            tool: "wait_for_connection",
+                            input: { provider, timeout_seconds: 30 },
+                            when: "After the user finishes authorizing in their browser",
+                        },
+                    ],
+                };
+            break;
+        }
+        case "get_plan": {
+            const plan = obj.plan || obj;
+            const planId = String(plan?.id || toolArgs.plan_id || "<plan_id>");
+            const risk = String(plan?.riskLevel || "read");
+            const status = String(obj.approvalStatus || plan?.approvalStatus || "auto_approved");
+            guidance =
+                status === "approved" || status === "auto_approved"
+                    ? {
+                        summary: `Plan ${planId} is ${status}. Call execute_${risk} to run it now.`,
+                        nextToolCalls: [
+                            {
+                                tool: `execute_${risk}`,
+                                input: { plan_id: planId },
+                                when: "Immediately; plan is approved",
+                            },
+                        ],
+                    }
+                    : {
+                        summary: `Plan ${planId} is ${status}. Share the approval link with the user and wait for approval before executing.`,
+                        nextToolCalls: [
+                            {
+                                tool: "get_plan",
+                                input: {
+                                    plan_id: planId,
+                                    wait_for_approval: true,
+                                    timeout_seconds: 25,
+                                },
+                                when: "While waiting for the workspace owner to click Approve",
+                            },
+                        ],
+                    };
+            break;
+        }
+        case "execute_read":
+        case "execute_write":
+        case "execute_admin":
+        case "execute_financial":
+        case "execute_provisioning":
+        case "execute_destructive": {
+            const runId = String(obj.run?.id || obj.receipt?.runId || obj.receipt?.id || "<run_id>");
+            guidance = {
+                summary: `Execution completed (${String(obj.run?.status || "succeeded")}). Call get_receipt to verify the cryptographic Ed25519 receipt if needed.`,
+                nextToolCalls: [
+                    {
+                        tool: "get_receipt",
+                        input: { receipt_id: runId },
+                        when: "To verify the signed receipt and governance decision record",
+                    },
+                ],
+            };
+            break;
+        }
+        case "get_run_context":
+        case "set_guardrail":
+        case "configure_guardrails": {
+            guidance = {
+                summary: "Workspace context, memory defaults, and guardrails updated/loaded. Use plan_action to propose governed actions or get_run_context with action='set_guardrail'|'remember'|'forget' to update workspace state.",
+                nextToolCalls: [
+                    {
+                        tool: "search_tools",
+                        input: { query: "" },
+                        when: "To find tools matching the user's goal",
+                    },
+                    {
+                        tool: "plan_action",
+                        input: {
+                            tool_slug: "<tool_slug>",
+                            input: {},
+                            reason: "Planned action under active workspace guardrails",
+                        },
+                        when: "To evaluate guardrails and prepare an action for execution",
+                    },
+                ],
+            };
+            break;
+        }
+        default:
+            break;
+    }
+    if (guidance) {
+        return {
+            ...obj,
+            llmGuidance: guidance,
+        };
+    }
+    return output;
+}