@muxoai/platform 1.4.1 → 1.4.2

package/dist/mcp-schema.d.ts

@@ -1,8 +1,81 @@
+import type { HumanHandoff } from "./types.js";
 export interface McpToolAnnotations {
+    title?: string;
     readOnlyHint: boolean;
     destructiveHint: boolean;
+    idempotentHint?: boolean;
     openWorldHint: boolean;
 }
+export declare const LATEST_MCP_PROTOCOL_VERSION = "2026-07-28";
+export declare const DEFAULT_LEGACY_MCP_PROTOCOL_VERSION = "2025-06-18";
+/**
+ * Dual-era MCP protocol versions supported by Muxo:
+ * - Modern stateless era: 2026-07-28 (SEP-2575 server/discover, SEP-2549 caching, MRTR resultType)
+ * - Legacy session era: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05
+ */
+export declare const SUPPORTED_MCP_PROTOCOL_VERSIONS: readonly ["2026-07-28", "2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+export declare const MCP_ERR_HEADER_MISMATCH = -32020;
+export declare const MCP_ERR_MISSING_REQUIRED_CLIENT_CAPABILITY = -32021;
+export declare const MCP_ERR_UNSUPPORTED_PROTOCOL_VERSION = -32022;
+export declare function isSupportedMcpProtocolVersion(version: unknown): boolean;
+/**
+ * Decodes an MCP Streamable HTTP header value (`Mcp-Name`, `Mcp-Param-*`),
+ * supporting plain ASCII as well as the 2026-07-28 Base64 sentinel format (`=:base64:...:`)
+ * and RFC 2047 `=?utf-8?B?...?=`.
+ */
+export declare function decodeMcpHeaderValue(raw: string): string;
+export interface McpHttpHeaderValidationInput {
+    protocolVersion?: string | null;
+    method?: string | null;
+    name?: string | null;
+}
+export interface McpJsonRpcErrorObject {
+    code: number;
+    message: string;
+    data?: Record<string, unknown>;
+}
+/**
+ * Validates MCP 2026-07-28 Streamable HTTP headers (`MCP-Protocol-Version`, `Mcp-Method`,
+ * `Mcp-Name`) and per-request `params._meta["io.modelcontextprotocol/protocolVersion"]`
+ * against the JSON-RPC request body.
+ *
+ * Returns `-32020 HeaderMismatch` when `Mcp-Method` or `Mcp-Name` conflicts with the body,
+ * and `-32022 UnsupportedProtocolVersion` when an unsupported protocol version is requested.
+ */
+export declare function validateMcpHttpHeadersAndMeta(headers: McpHttpHeaderValidationInput, rpc: unknown): {
+    ok: true;
+    protocolVersion: string;
+} | {
+    ok: false;
+    id: unknown;
+    error: McpJsonRpcErrorObject;
+};
+/**
+ * Builds the canonical MCP 2026-07-28 `server/discover` response (SEP-2575 + SEP-2549).
+ * Includes both top-level `serverInfo`/`instructions` and `_meta["io.modelcontextprotocol/*"]`
+ * so both strict 2026-07-28 validators and dual-era clients succeed.
+ */
+export declare function buildMcpDiscoverResult(serverVersion: string): Record<string, unknown>;
+/**
+ * Canonical MCP Resource Templates (`resources/templates/list`) for parameterized
+ * governance, tool catalog, and skill inspection.
+ */
+export interface McpResourceTemplate {
+    uriTemplate: string;
+    name: string;
+    title: string;
+    description: string;
+    mimeType: string;
+}
+export declare const MUXO_MCP_RESOURCE_TEMPLATES: McpResourceTemplate[];
+/**
+ * Evaluates MCP `completion/complete` requests for prompt arguments and resource templates.
+ */
+export declare function completeMcpArgument(params: Record<string, unknown> | undefined, toolSlugs?: string[]): {
+    values: string[];
+    total: number;
+    hasMore: boolean;
+};
 export interface McpToolSecurityScheme {
     type: "noauth" | "oauth2";
     scopes?: string[];
@@ -23,6 +96,55 @@ export declare const DEFAULT_TOOL_SECURITY_SCHEMES: McpToolSecurityScheme[];
 /** Catalog discovery tools work anonymously and also accept OAuth. */
 export declare const PUBLIC_TOOL_SECURITY_SCHEMES: McpToolSecurityScheme[];
 export declare const PUBLIC_MCP_TOOL_NAMES: ReadonlySet<string>;
+export declare const MUXO_UI_WIDGET_URI = "ui://widget/muxo-card.html";
+export declare const MUXO_UI_MCP_APP_URI = "ui://widget/muxo-app.html";
+/**
+ * Tools whose results represent interactive user-facing milestones (catalog carousel,
+ * OAuth handoff, action plan review/edit, execution receipt, or workspace summary).
+ * Pure data/inspection helpers remain usable without forcing unnecessary widget remounts.
+ */
+export declare const UI_RENDERED_MCP_TOOL_NAMES: ReadonlySet<string>;
+export declare function mcpToolUiMeta(invoking: string, invoked: string, extra?: Record<string, unknown>): Record<string, unknown>;
+export interface OpenAiClientRequestMeta {
+    locale?: string;
+    userAgent?: string;
+    userLocation?: {
+        city?: string;
+        region?: string;
+        country?: string;
+        timezone?: string;
+        longitude?: number;
+        latitude?: number;
+    };
+    subject?: string;
+    session?: string;
+    organization?: string;
+    widgetSessionId?: string;
+}
+/**
+ * Extracts optional OpenAI / MCP Apps client hints from JSON-RPC `params._meta`
+ * (`openai/locale`, `openai/userAgent`, `openai/userLocation`, `openai/subject`,
+ * `openai/session`, `openai/organization`, `openai/widgetSessionId`).
+ * These are best-effort hints and must never be used for authorization decisions.
+ */
+export declare function extractOpenAiClientMeta(params?: Record<string, unknown> | null): OpenAiClientRequestMeta;
+/**
+ * Enriches a tool descriptor for `tools/list` with both top-level `securitySchemes`
+ * and `_meta.securitySchemes` back-compat mirror per the OpenAI Plugin UI reference,
+ * as well as all four standard MCP tool annotations (`readOnlyHint`, `destructiveHint`,
+ * `idempotentHint`, `openWorldHint`).
+ */
+export declare function buildMcpToolDescriptor(tool: McpToolDefinition): McpToolDefinition;
+/**
+ * Builds the `_meta` object returned on `tools/call` results. Delivers widget-only
+ * metadata (`_meta`) without bloating the model-visible conversation transcript.
+ */
+export declare function buildMcpToolResultMeta(toolName: string, params?: Record<string, unknown> | null): Record<string, unknown>;
+/**
+ * Builds the `_meta` object for error tool results, including RFC 7235
+ * `_meta["mcp/www_authenticate"]` when an authentication challenge is required.
+ */
+export declare function buildMcpErrorResultMeta(err: unknown, baseUrl?: string): Record<string, unknown> | undefined;
 /** Stable per-workspace agent identity returned at agent signup on both runtimes. */
 export declare function workspaceAgentDid(workspaceId: string): string;
 /** JSON-RPC methods that anonymous MCP clients may call for discovery. */
@@ -62,7 +184,7 @@ export declare function findMcpSkill<T extends {
     requested: string;
 };
 export declare const APPROVED_PLAN_STATUSES: ReadonlySet<string>;
-export declare const GET_RUN_CONTEXT_ACTIONS: readonly ["inspect", "remember", "recall", "forget", "memory_graph", "set_guardrail", "governance_status", "scan_context", "list_workspaces", "switch_workspace", "onboard_team"];
+export declare const GET_RUN_CONTEXT_ACTIONS: readonly ["inspect", "remember", "recall", "forget", "memory_graph", "set_guardrail", "reset_guardrails", "check_policy", "kill_switch", "governance_status", "scan_context", "list_workspaces", "switch_workspace", "onboard_team"];
 /** Error carrying a structured MCP/REST payload (merged into structuredContent / JSON body). */
 export declare class MuxoToolError extends Error {
     readonly code: string;
@@ -82,6 +204,13 @@ export interface ApprovalGatePlan {
     approvalStatus: string;
 }
 export declare function buildApprovalUrl(baseUrl: string, planId: string): string;
+export declare function buildApprovalHumanHandoff(baseUrl: string, plan: ApprovalGatePlan): HumanHandoff;
+export declare function buildOAuthHumanHandoff(params: {
+    providerSlug: string;
+    providerName?: string;
+    redirectUrl: string | null;
+    instructions?: string;
+}): HumanHandoff;
 /** Structured response returned when execute_<risk> is called on a plan still awaiting approval. */
 export declare function buildApprovalRequiredPayload(baseUrl: string, plan: ApprovalGatePlan): Record<string, unknown>;
 export declare function approvalRequiredError(baseUrl: string, plan: ApprovalGatePlan): MuxoToolError;
@@ -123,3 +252,35 @@ export interface McpHarnessGuidance {
  * (Claude Code, Cursor, Codex, OpenAI MCP, Windsurf) always know the exact next tool call.
  */
 export declare function attachMcpHarnessGuidance<T>(toolName: string, toolArgs: Record<string, unknown>, output: T): T;
+export interface McpUiResourceDescriptor {
+    uri: string;
+    name: string;
+    title: string;
+    description: string;
+    mimeType: string;
+    _meta: Record<string, unknown>;
+}
+/**
+ * Canonical OpenAI Plugin UI (`text/html+skybridge`) & MCP Apps (`text/html;profile=mcp-app`)
+ * widget resource descriptors exposed by `resources/list` and `resources/read`.
+ * Follows:
+ * - https://developers.openai.com/plugins/reference
+ * - https://developers.openai.com/plugins/build/chatgpt-ui
+ * - https://developers.openai.com/plugins/concepts/ui-guidelines
+ */
+export declare const MUXO_UI_CSP_DOMAINS: readonly ["https://api.muxo.ai", "https://muxo.ai", "https://app.muxo.ai"];
+export declare const MUXO_UI_REDIRECT_DOMAINS: readonly ["https://api.muxo.ai", "https://muxo.ai", "https://app.muxo.ai", "https://connect.composio.dev", "https://backend.composio.dev"];
+export declare const MUXO_UI_RESOURCES: McpUiResourceDescriptor[];
+/**
+ * Renders the self-contained OpenAI Plugin UI / MCP App widget HTML (`ui://widget/muxo-card.html`).
+ * Strictly adheres to https://developers.openai.com/plugins/concepts/ui-guidelines:
+ * - System font stack (`-apple-system, BlinkMacSystemFont, "SF Pro Text", "Segoe UI", system-ui, sans-serif`)
+ * - Light & dark mode CSS variables (`window.openai.theme` + `prefers-color-scheme`)
+ * - Brand accent (`#6366F1` light / `#818CF8` dark) only on primary buttons & badges (WCAG AA)
+ * - Monochromatic outlined SVG icons; no duplicate app logo header
+ * - Auto-fitting inline card with no nested scrollbars (`notifyIntrinsicHeight`), max 2 bottom CTAs
+ * - Inline 3–8 card carousel for `search_tools` catalog results
+ * - Inline editable parameter controls for `plan_action` before clicking Execute
+ * - Expand to fullscreen (`requestDisplayMode({ mode: "fullscreen" })`) for rich inspection
+ */
+export declare function renderMuxoUiWidgetHtml(baseUrl?: string): string;