@decocms/mesh-sdk 1.2.1 → 1.2.2

package/src/lib/usage.ts

@@ -0,0 +1,161 @@
+/**
+ * Usage utilities for extracting cost and token stats from AI provider metadata.
+ *
+ * Supports provider-specific cost extraction (e.g., OpenRouter)
+ * and aggregation of usage across messages or streaming steps.
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface UsageData {
+  inputTokens?: number;
+  outputTokens?: number;
+  reasoningTokens?: number;
+  totalTokens?: number;
+  providerMetadata?: {
+    [key: string]: unknown;
+  };
+}
+
+export interface UsageStats {
+  inputTokens: number;
+  outputTokens: number;
+  reasoningTokens: number;
+  totalTokens: number;
+  cost: number;
+}
+
+type ProviderCostExtractor = (
+  providerMetadata: NonNullable<UsageData["providerMetadata"]>,
+) => number | null;
+
+// ============================================================================
+// Provider-specific cost extractors
+// ============================================================================
+
+/**
+ * Registry of provider-specific cost extractors.
+ * Each extractor attempts to get the cost from provider metadata.
+ */
+const PROVIDER_COST_EXTRACTORS: Record<string, ProviderCostExtractor> = {
+  openrouter: (providerMetadata) => {
+    const openrouter = providerMetadata?.openrouter;
+    if (
+      typeof openrouter === "object" &&
+      openrouter !== null &&
+      "usage" in openrouter &&
+      typeof openrouter.usage === "object" &&
+      openrouter.usage !== null &&
+      "cost" in openrouter.usage &&
+      typeof openrouter.usage.cost === "number"
+    ) {
+      return openrouter.usage.cost;
+    }
+    return null;
+  },
+};
+
+// ============================================================================
+// Cost extraction
+// ============================================================================
+
+/**
+ * Extract cost from usage metadata by checking all known provider formats.
+ */
+export function getCostFromUsage(usage: UsageData | null | undefined): number {
+  if (!usage?.providerMetadata) {
+    return 0;
+  }
+
+  for (const extractor of Object.values(PROVIDER_COST_EXTRACTORS)) {
+    const cost = extractor(usage.providerMetadata);
+    if (cost !== null) {
+      return cost;
+    }
+  }
+
+  return 0;
+}
+
+// ============================================================================
+// Provider metadata sanitization
+// ============================================================================
+
+const ALLOWED_PROVIDER_FIELDS = ["usage", "cost", "model"] as const;
+
+/**
+ * Sanitize provider metadata to prevent leaking sensitive data.
+ * Only allows whitelisted fields: usage, cost, model.
+ */
+export function sanitizeProviderMetadata(
+  metadata: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined {
+  if (!metadata) return undefined;
+
+  const sanitized: Record<string, unknown> = {};
+  for (const provider in metadata) {
+    const providerData = metadata[provider];
+    if (typeof providerData === "object" && providerData !== null) {
+      const safeData: Record<string, unknown> = {};
+      for (const field of ALLOWED_PROVIDER_FIELDS) {
+        if (field in providerData) {
+          safeData[field] = (providerData as Record<string, unknown>)[field];
+        }
+      }
+      sanitized[provider] = safeData;
+    }
+  }
+  return Object.keys(sanitized).length > 0 ? sanitized : undefined;
+}
+
+// ============================================================================
+// Usage accumulation
+// ============================================================================
+
+/**
+ * Create an empty UsageStats object.
+ */
+export function emptyUsageStats(): UsageStats {
+  return {
+    inputTokens: 0,
+    outputTokens: 0,
+    reasoningTokens: 0,
+    totalTokens: 0,
+    cost: 0,
+  };
+}
+
+/**
+ * Accumulate a step's usage into an existing UsageStats total.
+ * Returns a new UsageStats object (immutable).
+ */
+export function addUsage(
+  accumulated: UsageStats,
+  stepUsage: UsageData | null | undefined,
+): UsageStats {
+  if (!stepUsage) return accumulated;
+
+  return {
+    inputTokens: accumulated.inputTokens + (stepUsage.inputTokens ?? 0),
+    outputTokens: accumulated.outputTokens + (stepUsage.outputTokens ?? 0),
+    reasoningTokens:
+      accumulated.reasoningTokens + (stepUsage.reasoningTokens ?? 0),
+    totalTokens: accumulated.totalTokens + (stepUsage.totalTokens ?? 0),
+    cost: accumulated.cost + getCostFromUsage(stepUsage),
+  };
+}
+
+/**
+ * Calculate aggregated usage stats from an array of messages.
+ * Each message is expected to have an optional `metadata.usage` field.
+ */
+export function calculateUsageStats(
+  messages: Array<{ metadata?: { usage?: UsageData } }>,
+): UsageStats {
+  return messages.reduce<UsageStats>(
+    (acc, message) => addUsage(acc, message.metadata?.usage),
+    emptyUsageStats(),
+  );
+}

package/src/plugins/index.ts

@@ -0,0 +1,15 @@
+// Plugin context provider and hook
+export {
+  PluginContextProvider,
+  usePluginContext,
+  type PluginContextProviderProps,
+  type UsePluginContextOptions,
+} from "./plugin-context-provider";
+
+// Topbar portal system
+export {
+  TopbarPortal,
+  TopbarPortalProvider,
+  useTopbarPortalTargets,
+  type TopbarSide,
+} from "./topbar-portal";

package/src/plugins/plugin-context-provider.tsx

@@ -0,0 +1,99 @@
+/**
+ * Plugin Context Provider
+ *
+ * React context provider and hook for accessing plugin context.
+ * Moved from @decocms/bindings to @decocms/mesh-sdk to consolidate
+ * all plugin-facing React components in one package.
+ */
+
+import { createContext, useContext, type ReactNode } from "react";
+import type {
+  Binder,
+  PluginContext,
+  PluginContextPartial,
+} from "@decocms/bindings";
+
+// Internal context stores the partial version (nullable connection fields)
+// The hook return type depends on the options passed
+const PluginContextInternal = createContext<PluginContextPartial | null>(null);
+
+export interface PluginContextProviderProps<TBinding extends Binder> {
+  value: PluginContext<TBinding> | PluginContextPartial<TBinding>;
+  children: ReactNode;
+}
+
+/**
+ * Provider component for plugin context.
+ * Used by the mesh app layout to provide context to plugin routes.
+ */
+export function PluginContextProvider<TBinding extends Binder>({
+  value,
+  children,
+}: PluginContextProviderProps<TBinding>) {
+  return (
+    <PluginContextInternal.Provider value={value as PluginContextPartial}>
+      {children}
+    </PluginContextInternal.Provider>
+  );
+}
+
+/**
+ * Options for usePluginContext hook.
+ */
+export interface UsePluginContextOptions {
+  /**
+   * Set to true when calling from an empty state component.
+   * This returns nullable connection fields since no valid connection exists.
+   */
+  partial?: boolean;
+}
+
+/**
+ * Hook to access the plugin context with typed tool caller.
+ *
+ * @template TBinding - The binding type for typed tool calls
+ * @param options - Optional settings
+ * @param options.partial - Set to true in empty state components where connection may not exist
+ * @throws Error if used outside of PluginContextProvider
+ * @throws Error if connection is null but partial option is not set
+ *
+ * @example
+ * ```tsx
+ * // In route component (connection guaranteed by layout)
+ * const { toolCaller, connection } = usePluginContext<typeof REGISTRY_APP_BINDING>();
+ * const result = await toolCaller("COLLECTION_REGISTRY_APP_LIST", { limit: 20 });
+ *
+ * // In empty state component (no connection available)
+ * const { session, org } = usePluginContext<typeof REGISTRY_APP_BINDING>({ partial: true });
+ * ```
+ */
+export function usePluginContext<TBinding extends Binder = Binder>(options: {
+  partial: true;
+}): PluginContextPartial<TBinding>;
+export function usePluginContext<
+  TBinding extends Binder = Binder,
+>(): PluginContext<TBinding>;
+export function usePluginContext<TBinding extends Binder = Binder>(
+  options?: UsePluginContextOptions,
+): PluginContext<TBinding> | PluginContextPartial<TBinding> {
+  const context = useContext(PluginContextInternal);
+  if (!context) {
+    throw new Error(
+      "usePluginContext must be used within a PluginContextProvider",
+    );
+  }
+
+  // If partial mode, return as-is with nullable fields
+  if (options?.partial) {
+    return context as PluginContextPartial<TBinding>;
+  }
+
+  // Otherwise, assert that connection exists (routes should always have one)
+  if (!context.connectionId || !context.connection || !context.toolCaller) {
+    throw new Error(
+      "usePluginContext requires a valid connection. Use { partial: true } in empty state components.",
+    );
+  }
+
+  return context as PluginContext<TBinding>;
+}

package/src/plugins/topbar-portal.tsx

@@ -0,0 +1,118 @@
+/**
+ * Topbar Portal
+ *
+ * A React portal-based system for rendering content into the project topbar
+ * from anywhere in the component tree (including plugin routes).
+ *
+ * Uses createPortal so that portaled content preserves the source tree's
+ * React context -- plugin context, query client, etc. all work naturally.
+ *
+ * Usage:
+ *
+ * 1. The app wraps its layout with <TopbarPortalProvider>
+ * 2. ProjectTopbar calls useTopbarPortalTargets() and attaches callback refs to slot divs
+ * 3. Plugin components render <TopbarPortal side="right">...</TopbarPortal>
+ */
+
+import { createContext, useContext, useState, type ReactNode } from "react";
+import { createPortal } from "react-dom";
+
+export type TopbarSide = "left" | "center" | "right";
+
+interface TopbarPortalContextValue {
+  /** Current DOM elements for each slot (null until ProjectTopbar mounts) */
+  leftEl: HTMLDivElement | null;
+  centerEl: HTMLDivElement | null;
+  rightEl: HTMLDivElement | null;
+  /** Callback refs for ProjectTopbar to register slot elements */
+  setLeftEl: (el: HTMLDivElement | null) => void;
+  setCenterEl: (el: HTMLDivElement | null) => void;
+  setRightEl: (el: HTMLDivElement | null) => void;
+}
+
+const TopbarPortalContext = createContext<TopbarPortalContextValue | null>(
+  null,
+);
+
+/**
+ * Provider that manages the portal target DOM elements for the three topbar slots.
+ * Place this in the layout tree so it wraps both the topbar and the content area.
+ */
+export function TopbarPortalProvider({ children }: { children: ReactNode }) {
+  const [leftEl, setLeftEl] = useState<HTMLDivElement | null>(null);
+  const [centerEl, setCenterEl] = useState<HTMLDivElement | null>(null);
+  const [rightEl, setRightEl] = useState<HTMLDivElement | null>(null);
+
+  return (
+    <TopbarPortalContext.Provider
+      value={{ leftEl, centerEl, rightEl, setLeftEl, setCenterEl, setRightEl }}
+    >
+      {children}
+    </TopbarPortalContext.Provider>
+  );
+}
+
+/**
+ * Hook used by the ProjectTopbar component to get callback refs for the portal target divs.
+ * Returns stable callback refs that register/unregister the DOM elements in the provider.
+ */
+export function useTopbarPortalTargets() {
+  const ctx = useContext(TopbarPortalContext);
+
+  const leftRef = (el: HTMLDivElement | null) => ctx?.setLeftEl(el);
+  const centerRef = (el: HTMLDivElement | null) => ctx?.setCenterEl(el);
+  const rightRef = (el: HTMLDivElement | null) => ctx?.setRightEl(el);
+
+  if (!ctx) return null;
+
+  return { leftRef, centerRef, rightRef };
+}
+
+/**
+ * Portal component that renders children into one of the topbar slots.
+ *
+ * Because this uses React createPortal, the children maintain the React context
+ * of the component that renders <TopbarPortal> -- not the topbar's context.
+ * This means plugin context (connection, toolCaller, etc.) is available.
+ *
+ * @example
+ * ```tsx
+ * import { TopbarPortal, usePluginContext } from "@decocms/mesh-sdk/plugins";
+ *
+ * function MyPluginPage() {
+ *   const { toolCaller } = usePluginContext<typeof MY_BINDING>();
+ *
+ *   return (
+ *     <>
+ *       <TopbarPortal side="right">
+ *         <Button onClick={() => toolCaller("SOME_TOOL", {})}>
+ *           Action
+ *         </Button>
+ *       </TopbarPortal>
+ *       <div>Page content...</div>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function TopbarPortal({
+  side,
+  children,
+}: {
+  side: TopbarSide;
+  children: ReactNode;
+}) {
+  const ctx = useContext(TopbarPortalContext);
+  if (!ctx) return null;
+
+  const el =
+    side === "left"
+      ? ctx.leftEl
+      : side === "center"
+        ? ctx.centerEl
+        : ctx.rightEl;
+
+  if (!el) return null;
+
+  return createPortal(children, el);
+}

package/src/types/ai-providers.ts

@@ -0,0 +1,68 @@
+// ============================================================================
+// AI Provider Types — shared between server tool output and client hooks
+// ============================================================================
+
+export const PROVIDER_IDS = [
+  "deco",
+  "anthropic",
+  "openrouter",
+  "google",
+  "claude-code",
+] as const;
+
+export type ProviderId = (typeof PROVIDER_IDS)[number];
+
+/** All known model capability tokens. Sourced from OpenRouter modality strings. */
+export const MODEL_CAPABILITIES = [
+  "text",
+  "image",
+  "vision",
+  "audio",
+  "video",
+  "file",
+  "reasoning",
+] as const;
+
+export type ModelCapability = (typeof MODEL_CAPABILITIES)[number];
+
+export interface AiProviderModelLimits {
+  contextWindow: number;
+  /** Null means the provider does not advertise a specific cap. */
+  maxOutputTokens: number | null;
+}
+
+export interface AiProviderModelCosts {
+  input: number;
+  output: number;
+}
+
+export interface AiProviderModel {
+  providerId: ProviderId;
+  modelId: string;
+  title: string;
+  description: string | null;
+  logo: string | null;
+  capabilities: ModelCapability[];
+  limits: AiProviderModelLimits | null;
+  costs: AiProviderModelCosts | null;
+  /** Client-side only — the credential key ID used to fetch this model. */
+  keyId?: string;
+}
+
+export interface AiProviderKey {
+  id: string;
+  providerId: ProviderId;
+  label: string;
+  createdBy: string;
+  createdAt: string;
+}
+
+export interface AiProviderInfo {
+  id: ProviderId;
+  name: string;
+  description: string;
+  logo?: string | null;
+  supportedMethods: ("api-key" | "oauth-pkce")[];
+  supportsTopUp?: boolean;
+  supportsCredits?: boolean;
+}

package/src/types/connection.ts

@@ -5,6 +5,7 @@
  * Uses snake_case field names matching the database schema directly.
  */
 
+import { ToolSchema } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 
 /**
@@ -23,13 +24,26 @@ const OAuthConfigSchema = z.object({
 export type OAuthConfig = z.infer<typeof OAuthConfigSchema>;
 
 /**
- * Tool definition schema from MCP discovery
+ * JSON-Schema-safe JSON Schema object.
+ *
+ * The MCP SDK's ToolSchema uses z.custom() (AssertObjectSchema) for property
+ * values inside inputSchema/outputSchema. Zod 4's toJSONSchema() cannot
+ * represent z.custom(), throwing "Custom types cannot be represented in JSON
+ * Schema". We override only these two fields with a safe equivalent so that
+ * all other ToolSchema fields (name, annotations, execution, icons, _meta, …)
+ * still flow through automatically when the MCP SDK is updated.
  */
-const ToolDefinitionSchema = z.object({
-  name: z.string(),
-  description: z.string().optional(),
-  inputSchema: z.record(z.string(), z.unknown()),
-  outputSchema: z.record(z.string(), z.unknown()).optional(),
+const JsonSchemaObjectSchema = z
+  .object({
+    type: z.literal("object"),
+    properties: z.record(z.string(), z.unknown()).optional(),
+    required: z.array(z.string()).optional(),
+  })
+  .catchall(z.unknown());
+
+const ToolDefinitionSchema = ToolSchema.extend({
+  inputSchema: JsonSchemaObjectSchema,
+  outputSchema: JsonSchemaObjectSchema.optional(),
 });
 
 export type ToolDefinition = z.infer<typeof ToolDefinitionSchema>;
@@ -152,20 +166,24 @@ export const ConnectionCreateDataSchema = ConnectionEntitySchema.omit({
   tools: true,
   bindings: true,
   status: true,
-}).partial({
-  id: true,
-  description: true,
-  icon: true,
-  app_name: true,
-  app_id: true,
-  connection_url: true,
-  connection_token: true,
-  connection_headers: true,
-  oauth_config: true,
-  configuration_state: true,
-  configuration_scopes: true,
-  metadata: true,
-});
+})
+  .partial({
+    id: true,
+    description: true,
+    icon: true,
+    app_name: true,
+    app_id: true,
+    connection_url: true,
+    connection_token: true,
+    connection_headers: true,
+    oauth_config: true,
+    configuration_state: true,
+    configuration_scopes: true,
+    metadata: true,
+  })
+  .extend({
+    icon: z.string().nullish(),
+  });
 
 export type ConnectionCreateData = z.infer<typeof ConnectionCreateDataSchema>;
 

package/src/types/decopilot-events.ts

@@ -0,0 +1,128 @@
+/**
+ * Decopilot SSE Event Types
+ *
+ * Canonical type definitions for thread statuses and decopilot SSE events.
+ * Shared between server (emitter) and client (consumer) for full type safety.
+ */
+
+// ============================================================================
+// Thread Status
+// ============================================================================
+
+/** Persisted thread statuses (written to DB). */
+export const THREAD_STATUSES = [
+  "in_progress",
+  "requires_action",
+  "failed",
+  "completed",
+] as const;
+export type ThreadStatus = (typeof THREAD_STATUSES)[number];
+
+/**
+ * Display statuses include "expired" — a virtual status computed at read time
+ * for threads stuck in "in_progress" beyond a timeout threshold.
+ * Never persisted to DB, but appears in API responses and UI.
+ */
+export const THREAD_DISPLAY_STATUSES = [...THREAD_STATUSES, "expired"] as const;
+export type ThreadDisplayStatus = (typeof THREAD_DISPLAY_STATUSES)[number];
+
+// ============================================================================
+// SSE Event Type Constants
+// ============================================================================
+
+export const DECOPILOT_EVENTS = {
+  STEP: "decopilot.step",
+  FINISH: "decopilot.finish",
+  THREAD_STATUS: "decopilot.thread.status",
+} as const;
+
+export type DecopilotEventType =
+  (typeof DECOPILOT_EVENTS)[keyof typeof DECOPILOT_EVENTS];
+
+export const ALL_DECOPILOT_EVENT_TYPES: DecopilotEventType[] =
+  Object.values(DECOPILOT_EVENTS);
+
+// ============================================================================
+// Event Payloads (discriminated union on `type`)
+// ============================================================================
+
+interface BaseDecopilotEvent {
+  id: string;
+  source: "decopilot";
+  /** Thread ID this event relates to */
+  subject: string;
+  time: string;
+}
+
+export interface DecopilotStepEvent extends BaseDecopilotEvent {
+  type: typeof DECOPILOT_EVENTS.STEP;
+  data: { stepCount: number };
+}
+
+export interface DecopilotFinishEvent extends BaseDecopilotEvent {
+  type: typeof DECOPILOT_EVENTS.FINISH;
+  data: { status: ThreadStatus };
+}
+
+export interface DecopilotThreadStatusEvent extends BaseDecopilotEvent {
+  type: typeof DECOPILOT_EVENTS.THREAD_STATUS;
+  data: { status: ThreadStatus };
+}
+
+export type DecopilotSSEEvent =
+  | DecopilotStepEvent
+  | DecopilotFinishEvent
+  | DecopilotThreadStatusEvent;
+
+/** Map from event type string → typed payload (useful for generic handlers) */
+export interface DecopilotEventMap {
+  [DECOPILOT_EVENTS.STEP]: DecopilotStepEvent;
+  [DECOPILOT_EVENTS.FINISH]: DecopilotFinishEvent;
+  [DECOPILOT_EVENTS.THREAD_STATUS]: DecopilotThreadStatusEvent;
+}
+
+// ============================================================================
+// Server-side Factories (create typed events for SSEHub.emit)
+// ============================================================================
+
+export function createDecopilotStepEvent(
+  threadId: string,
+  stepCount: number,
+): DecopilotStepEvent {
+  return {
+    id: crypto.randomUUID(),
+    type: DECOPILOT_EVENTS.STEP,
+    source: "decopilot",
+    subject: threadId,
+    data: { stepCount },
+    time: new Date().toISOString(),
+  };
+}
+
+export function createDecopilotFinishEvent(
+  threadId: string,
+  status: ThreadStatus,
+): DecopilotFinishEvent {
+  return {
+    id: crypto.randomUUID(),
+    type: DECOPILOT_EVENTS.FINISH,
+    source: "decopilot",
+    subject: threadId,
+    data: { status },
+    time: new Date().toISOString(),
+  };
+}
+
+export function createDecopilotThreadStatusEvent(
+  threadId: string,
+  status: ThreadStatus,
+): DecopilotThreadStatusEvent {
+  return {
+    id: crypto.randomUUID(),
+    type: DECOPILOT_EVENTS.THREAD_STATUS,
+    source: "decopilot",
+    subject: threadId,
+    data: { status },
+    time: new Date().toISOString(),
+  };
+}