@decocms/mesh-sdk 1.2.1 → 1.2.3

package/src/lib/usage.ts

@@ -0,0 +1,187 @@
+/**
+ * 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;
+  /**
+   * AI SDK normalizes cache token counts across providers via
+   * usage.inputTokenDetails — populated identically by the anthropic,
+   * openai, google and openrouter adapters. `cachedInputTokens` is the
+   * convenience shorthand the AI SDK also surfaces (= cacheReadTokens).
+   */
+  cachedInputTokens?: number;
+  inputTokenDetails?: {
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    noCacheTokens?: number;
+  };
+  providerMetadata?: {
+    [key: string]: unknown;
+  };
+}
+
+export interface UsageStats {
+  inputTokens: number;
+  outputTokens: number;
+  reasoningTokens: number;
+  totalTokens: number;
+  cost: number;
+  /** Tokens read from prompt cache (anthropic / openrouter / openai / google). */
+  cacheReadTokens: number;
+  /** Tokens written to prompt cache (Anthropic only — others auto-cache without separate billing). */
+  cacheWriteTokens: 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,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 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;
+
+  const cacheRead =
+    stepUsage.inputTokenDetails?.cacheReadTokens ??
+    stepUsage.cachedInputTokens ??
+    0;
+  const cacheWrite = stepUsage.inputTokenDetails?.cacheWriteTokens ?? 0;
+
+  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),
+    cacheReadTokens: accumulated.cacheReadTokens + cacheRead,
+    cacheWriteTokens: accumulated.cacheWriteTokens + cacheWrite,
+  };
+}
+
+/**
+ * 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,86 @@
+// ============================================================================
+// AI Provider Types — shared between server tool output and client hooks
+// ============================================================================
+
+export const PROVIDER_IDS = [
+  "deco",
+  "anthropic",
+  "openrouter",
+  "google",
+  "claude-code",
+  "codex",
+  "openai-compatible",
+] 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;
+  /** When true the upstream provider has flagged this model as deprecated. */
+  deprecated?: boolean;
+  /**
+   * When true, this model can ONLY be used through the provider's
+   * `AsyncResearchProvider` capability (e.g. Gemini Deep Research via the
+   * Interactions API). It is unusable as a Thinking/Coding/Fast/Image model
+   * because `streamText` / `generateContent` will reject it. UIs should
+   * restrict it to the deep-research slot.
+   */
+  asyncResearch?: boolean;
+  /** Client-side only — the credential key ID used to fetch this model. */
+  keyId?: string;
+}
+
+export interface AiProviderKey {
+  id: string;
+  providerId: ProviderId;
+  label: string;
+  /**
+   * Frontend preset id (e.g. "litellm", "ollama") for openai-compatible keys
+   * that were created from a branded preset card. Null otherwise.
+   */
+  presetId: string | null;
+  createdBy: string;
+  createdAt: string;
+}
+
+export interface AiProviderInfo {
+  id: ProviderId;
+  name: string;
+  description: string;
+  logo?: string | null;
+  supportedMethods: ("api-key" | "oauth-pkce" | "cli-activate")[];
+  supportsTopUp?: boolean;
+  supportsCredits?: boolean;
+  supportsProvision?: 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>;
@@ -88,6 +102,11 @@ export const ConnectionEntitySchema = z.object({
   icon: z.string().nullable().describe("Icon URL for the connection"),
   app_name: z.string().nullable().describe("Associated app name"),
   app_id: z.string().nullable().describe("Associated app ID"),
+  slug: z
+    .string()
+    .nullable()
+    .optional()
+    .describe("URL-safe slug derived from app_name, connection_url, or title"),
 
   connection_type: z
     .enum(["HTTP", "SSE", "Websocket", "STDIO", "VIRTUAL"])
@@ -152,20 +171,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.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createDecopilotThreadStatusEvent,
+  DECOPILOT_EVENTS,
+} from "./decopilot-events";
+
+describe("createDecopilotThreadStatusEvent", () => {
+  test("carries virtualMcpId, createdBy, and triggerId on data", () => {
+    const e = createDecopilotThreadStatusEvent("task-1", "in_progress", {
+      virtualMcpId: "vm-1",
+      createdBy: "user-1",
+      triggerId: "trig-1",
+    });
+    expect(e.type).toBe(DECOPILOT_EVENTS.THREAD_STATUS);
+    expect(e.subject).toBe("task-1");
+    expect(e.data.status).toBe("in_progress");
+    expect(e.data.virtual_mcp_id).toBe("vm-1");
+    expect(e.data.created_by).toBe("user-1");
+    expect(e.data.trigger_id).toBe("trig-1");
+  });
+
+  test("omits optional fields when not provided", () => {
+    const e = createDecopilotThreadStatusEvent("task-1", "completed");
+    expect(e.data.status).toBe("completed");
+    expect(e.data.virtual_mcp_id).toBeUndefined();
+    expect(e.data.created_by).toBeUndefined();
+    expect(e.data.trigger_id).toBeUndefined();
+  });
+
+  test("preserves explicit null trigger_id (human-initiated thread)", () => {
+    const e = createDecopilotThreadStatusEvent("task-1", "completed", {
+      triggerId: null,
+    });
+    expect(e.data.trigger_id).toBeNull();
+  });
+
+  test("works with only virtualMcpId provided (migration shape)", () => {
+    const e = createDecopilotThreadStatusEvent("task-1", "in_progress", {
+      virtualMcpId: "vm-1",
+    });
+    expect(e.data.virtual_mcp_id).toBe("vm-1");
+    expect(e.data.created_by).toBeUndefined();
+    expect(e.data.trigger_id).toBeUndefined();
+  });
+});
+
+describe("createDecopilotThreadStatusEvent — enriched fields", () => {
+  test("round-trips title, branch, createdAt, updatedAt", () => {
+    const e = createDecopilotThreadStatusEvent("task-1", "in_progress", {
+      virtualMcpId: "vm-1",
+      title: "Refactor login",
+      branch: "feature/login",
+      createdAt: "2026-05-19T00:00:00.000Z",
+      updatedAt: "2026-05-19T00:05:00.000Z",
+    });
+    expect(e.data.title).toBe("Refactor login");
+    expect(e.data.branch).toBe("feature/login");
+    expect(e.data.created_at).toBe("2026-05-19T00:00:00.000Z");
+    expect(e.data.updated_at).toBe("2026-05-19T00:05:00.000Z");
+  });
+
+  test("omits the new fields when not provided", () => {
+    const e = createDecopilotThreadStatusEvent("task-1", "in_progress", {
+      virtualMcpId: "vm-1",
+    });
+    expect(e.data.title).toBeUndefined();
+    expect(e.data.branch).toBeUndefined();
+    expect(e.data.created_at).toBeUndefined();
+    expect(e.data.updated_at).toBeUndefined();
+  });
+
+  test("explicit null branch is preserved", () => {
+    const e = createDecopilotThreadStatusEvent("task-1", "in_progress", {
+      branch: null,
+    });
+    expect(e.data.branch).toBeNull();
+  });
+});