@decocms/mesh-sdk 1.2.2 → 1.2.3

package/src/types/virtual-mcp.ts

@@ -57,6 +57,85 @@ const VirtualMcpPinnedViewSchema = z.object({
 
 export type VirtualMcpPinnedView = z.infer<typeof VirtualMcpPinnedViewSchema>;
 
+/**
+ * A single tab declared by an agent in `metadata.ui.layout.tabs`. Rendered
+ * after the fixed system tabs (Instructions / Connections / Layout / Env)
+ * in the unified chat layout's right panel.
+ */
+export const VirtualMcpUILayoutTabSchema = z.object({
+  id: z.string().describe("Stable id; used as React key and ?tab= value"),
+  title: z.string().describe("Tab label"),
+  icon: z.string().optional().describe("Optional lucide icon name"),
+  view: z.object({
+    type: z.literal("ext-app"),
+    appId: z.string(),
+    args: z.record(z.string(), z.unknown()).optional(),
+  }),
+});
+
+export type VirtualMcpUILayoutTab = z.infer<typeof VirtualMcpUILayoutTabSchema>;
+
+/**
+ * Layout-specific settings stored under `metadata.ui.layout`. Controls which
+ * main view opens by default and which additional right-panel tabs are
+ * permanently available for the agent.
+ */
+export const VirtualMcpUILayoutSchema = z.object({
+  defaultMainView: z
+    .object({
+      type: z.string(),
+      id: z.string().optional(),
+      toolName: z.string().optional(),
+    })
+    .nullable()
+    .optional(),
+  /**
+   * When true, the chat panel is open alongside the main view on first
+   * load. Ignored when `defaultMainView.type === "chat"` (chat is always
+   * open in that case). Absent / null / false → chat is closed unless the
+   * default view is chat.
+   */
+  chatDefaultOpen: z.boolean().nullable().optional(),
+  tabs: z.array(VirtualMcpUILayoutTabSchema).optional(),
+});
+
+export type VirtualMcpUILayout = z.infer<typeof VirtualMcpUILayoutSchema>;
+
+/**
+ * Tile UI declared by a home agent. When present, the `/$org` home page
+ * renders the resource as an iframe inside the agent's tile (same MCP UI
+ * iframe pattern used for tool results in chat).
+ *
+ * The resource lives on a specific underlying connection — not the virtual
+ * MCP gateway — so we store the source `connectionId` here. The host opens
+ * an MCP client to that connection directly so tool calls from inside the
+ * iframe hit bare tool names (the gateway would otherwise reject calls that
+ * don't carry its namespace prefix).
+ */
+const VirtualMcpHomeTileSchema = z.object({
+  /**
+   * Optional for backward compatibility with tiles saved before this field
+   * existed. The home API drops tiles that don't carry a connectionId (they
+   * can't render correctly without it), but parsing must still succeed so
+   * existing virtual MCPs don't fail output validation on COLLECTION_*_LIST.
+   */
+  connectionId: z
+    .string()
+    .optional()
+    .describe(
+      "Connection that owns the resource — the host opens a direct MCP client to this connection so the iframe can call tools by their bare names.",
+    ),
+  resourceUri: z
+    .string()
+    .describe(
+      "ui:// resource URI exposed by `connectionId`. Read on the home page and rendered via MCPAppRenderer.",
+    ),
+  minHeight: z.number().int().positive().optional(),
+  maxHeight: z.number().int().positive().optional(),
+});
+
+export type VirtualMcpHomeTile = z.infer<typeof VirtualMcpHomeTileSchema>;
+
 /**
  * Virtual MCP UI customization schema
  */
@@ -66,10 +145,311 @@ const VirtualMcpUISchema = z.object({
   icon: z.string().nullable().optional(),
   themeColor: z.string().nullable().optional(),
   pinnedViews: z.array(VirtualMcpPinnedViewSchema).nullable().optional(),
+  layout: VirtualMcpUILayoutSchema.nullable().optional(),
+  /**
+   * Legacy single-tile slot. Still honored by the home-next-actions
+   * endpoint when `homeTiles` is empty/absent. New writes go to
+   * `homeTiles` so agents can surface more than one UI on the home
+   * board.
+   */
+  homeTile: VirtualMcpHomeTileSchema.nullable().optional(),
+  /**
+   * Multiple home tiles per agent. Each entry becomes its own tile on
+   * the org home board, rendered via MCPAppRenderer against the
+   * resource's owning connection.
+   */
+  homeTiles: z.array(VirtualMcpHomeTileSchema).nullable().optional(),
+  /**
+   * Curated list of prompt names to surface on the home board. When
+   * absent / null, the BE falls back to listing every prompt the
+   * agent's gateway exposes (today's behavior). An explicit empty
+   * array means "no prompts" — useful for an agent that only wants to
+   * surface its UI tiles.
+   */
+  homePrompts: z.array(z.string()).nullable().optional(),
 });
 
 export type VirtualMcpUI = z.infer<typeof VirtualMcpUISchema>;
 
+/**
+ * Canonical reader for an agent's pinned home tiles. Prefers the
+ * `homeTiles` array; falls back to the legacy single `homeTile` slot so
+ * agents written before the multi-tile migration still surface their
+ * tile. Returning `[]` (rather than null) keeps callers branchless.
+ */
+export function getHomeTiles(
+  ui: VirtualMcpUI | null | undefined,
+): VirtualMcpHomeTile[] {
+  const arr = ui?.homeTiles;
+  if (Array.isArray(arr) && arr.length > 0) return arr;
+  const legacy = ui?.homeTile;
+  return legacy ? [legacy] : [];
+}
+
+/**
+ * Shell-portable env var name: must start with a letter or underscore and
+ * contain only letters, digits, and underscores. Same shape parse-dotenv
+ * enforces on imports. Single source of truth — the form editor and the
+ * paste flow both validate against this.
+ */
+export const ENV_VAR_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+const envVarKey = z.string().min(1).regex(ENV_VAR_KEY_RE, {
+  message:
+    "Env var key must start with a letter or underscore and contain only letters, digits, and underscores.",
+});
+
+/**
+ * One env var declaration on a virtual MCP. Literal values live inline in
+ * metadata; secret values store a stable secretId that mesh resolves against
+ * the credential vault on every SANDBOX_START. The env var KEY is independent of
+ * the secret's NAME — a single secret can back multiple env keys across
+ * different agents.
+ */
+const RuntimeEnvEntrySchema = z.discriminatedUnion("kind", [
+  z.object({
+    key: envVarKey,
+    kind: z.literal("literal"),
+    value: z.string(),
+  }),
+  z.object({
+    key: envVarKey,
+    kind: z.literal("secret"),
+    secretId: z.string().min(1),
+  }),
+]);
+
+export type RuntimeEnvEntry = z.infer<typeof RuntimeEnvEntrySchema>;
+
+/**
+ * User-pinned runtime configuration stored under `metadata.runtime`. Empty
+ * fields fall back to autodetect on the next SANDBOX_START.
+ */
+const RuntimeMetadataSchema = z.object({
+  selected: z
+    .string()
+    .nullable()
+    .optional()
+    .describe(
+      "User-selected package manager (npm | pnpm | yarn | bun | deno). Null/absent means autodetect on next SANDBOX_START.",
+    ),
+  port: z
+    .string()
+    .nullable()
+    .optional()
+    .describe(
+      "User-selected dev server port as a string (allows '' / null for unset). Null/absent means autodetect.",
+    ),
+  path: z
+    .string()
+    .nullable()
+    .optional()
+    .describe(
+      "Optional path (relative to repo root) to the directory containing package.json. Null/absent means repo root. Forwarded as `application.packageManager.path` to the daemon config.",
+    ),
+  env: z
+    .array(RuntimeEnvEntrySchema)
+    .nullable()
+    .optional()
+    .describe(
+      "Env vars injected on every SANDBOX_START. Literal entries inline their value; secret entries store a secretId that mesh resolves via the credential vault before posting /_sandbox/config.",
+    ),
+});
+
+export type RuntimeMetadata = z.infer<typeof RuntimeMetadataSchema>;
+
+/**
+ * GitHub repository linked to a virtual MCP
+ */
+const GithubRepoSchema = z.object({
+  url: z.string().describe("GitHub repository URL"),
+  owner: z.string().describe("Repository owner"),
+  name: z.string().describe("Repository name"),
+  installationId: z
+    .number()
+    .optional()
+    .describe(
+      "GitHub App installation ID. Absent when the repo was linked without a GitHub connection (public-clone mode).",
+    ),
+  connectionId: z
+    .string()
+    .optional()
+    .describe(
+      "ID of the mcp-github connection used for authentication. Absent for public repos cloned without credentials.",
+    ),
+});
+
+export type GithubRepo = z.infer<typeof GithubRepoSchema>;
+
+/**
+ * A single sandbox record in the per-(user, branch, kind) sandbox map — the
+ * provider-issued handle plus the preview URL the UI renders.
+ *
+ * `sandboxProviderKind` lets the UI construct daemon URLs correctly:
+ *  - cluster: daemon is reached via the mesh proxy; preview URL is the
+ *    per-claim HTTPRoute host (in-cluster) or a local port-forward (kind dev).
+ *  - user-desktop: daemon is reached directly via the user's link binary.
+ *
+ * `previewUrl` is nullable: blank / tool sandboxes (no `workload`, no dev
+ * server) have nothing to render. UI code MUST check before constructing
+ * an iframe URL.
+ */
+export const SandboxRecordSchema = z.object({
+  sandboxHandle: z.string().describe("Provider-specific handle"),
+  previewUrl: z
+    .string()
+    .nullable()
+    .describe(
+      "URL where the sandbox's iframe-proxied UI is served, or null when the sandbox has no dev server (blank / tool sandboxes).",
+    ),
+  sandboxApiUrl: z
+    .string()
+    .nullable()
+    .optional()
+    .describe(
+      "Daemon's public URL — what cluster→daemon RPCs target. Equal to previewUrl for user-desktop; null/absent for the cluster provider (routes through cluster ingress).",
+    ),
+  sandboxProviderKind: z
+    // Canonical set. Migration 092 rewrote every persisted legacy value
+    // ("docker", "agent-sandbox", "desktop", "remote-user", "host",
+    // "freestyle") to a canonical kind, and migration 097 dropped the
+    // retired "local-docker" kind; readers no longer accept those strings —
+    // Zod will reject them at parse time.
+    .enum(["cluster", "user-desktop"])
+    .optional(),
+  createdAt: z
+    .number()
+    .optional()
+    .describe(
+      "Epoch ms the entry was first written by SANDBOX_START. Used by the booting overlay to show a stable elapsed timer that survives browser reloads. Optional for backward compatibility with entries written before this field existed.",
+    ),
+  startedWith: z
+    .object({
+      packageManager: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("metadata.runtime.selected at the time of SANDBOX_START"),
+      port: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("metadata.runtime.port at the time of SANDBOX_START"),
+      path: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("metadata.runtime.path at the time of SANDBOX_START"),
+    })
+    .optional()
+    .describe(
+      "Snapshot of metadata.runtime fields (selected/port/path) used at SANDBOX_START. The Preview tab compares the live metadata.runtime against this to decide if a restart is required to apply changes.",
+    ),
+});
+
+export type SandboxRecord = z.infer<typeof SandboxRecordSchema>;
+
+/**
+ * Strict parser for a single sandbox record. Migration 091 rewrote every
+ * persisted legacy value (`runnerKind`, `vmId`, legacy kind names), so
+ * readers no longer accept those shapes — Zod throws on any leftover.
+ */
+export function parseSandboxRecord(raw: unknown): SandboxRecord {
+  return SandboxRecordSchema.parse(raw);
+}
+
+/** The active sandbox provider kinds. */
+export type SandboxProviderKind = "cluster" | "user-desktop";
+
+/**
+ * Parse a `sandboxMap[user][branch]` cell into the kind-keyed v2 shape.
+ *
+ * Migration 087 rewrote every cell to the 3-level layout
+ * (`sandboxProviderKind → SandboxRecord`) and migration 091 rewrote every
+ * legacy kind value; this reader is now strict — entries that fail to parse
+ * (e.g. a stray cell missing required fields) are skipped, but no legacy
+ * key/value normalization happens.
+ */
+export function parseBranchMap(
+  raw: unknown,
+): Partial<Record<SandboxProviderKind, SandboxRecord>> {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const obj = raw as Record<string, unknown>;
+
+  const out: Partial<Record<SandboxProviderKind, SandboxRecord>> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (!v || typeof v !== "object") continue;
+    if (k !== "cluster" && k !== "user-desktop") {
+      continue;
+    }
+    try {
+      out[k] = SandboxRecordSchema.parse(v);
+    } catch {
+      // Skip malformed entries rather than throw — readers stay forgiving
+      // about unexpected shapes within a known-key cell.
+    }
+  }
+  return out;
+}
+
+/**
+ * Maps a user to their sandbox records per (branch, sandboxProviderKind).
+ * Lookup: sandboxMap[userId][branch][sandboxProviderKind] -> SandboxRecord
+ *
+ * Multiple threads on the same (userId, branch, kind) share one sandbox.
+ * Cloud and local sandboxes can coexist on the same branch as siblings.
+ *
+ * The schema is strict v2. Strict input/output types here are load-bearing
+ * for `useForm<…>(zodResolver(…))` callers, whose generic depends on
+ * `z.input` being identical to `z.output`. A `z.preprocess` here widens
+ * `z.input` to `unknown` and breaks the form.
+ */
+export const SandboxMapSchema = z.record(
+  z.string().describe("userId"),
+  z.record(
+    z.string().describe("branch"),
+    z.record(z.string().describe("sandboxProviderKind"), SandboxRecordSchema),
+  ),
+);
+
+export type SandboxMap = z.infer<typeof SandboxMapSchema>;
+
+/**
+ * Normalize a raw `metadata.sandboxMap` value into v2 shape on read. Use this
+ * in storage adapters BEFORE returning data that will be Zod-validated against
+ * `VirtualMCPEntitySchema` (or any schema embedding `SandboxMapSchema`).
+ *
+ * After migration 091, the stored shape is the strict 3-level
+ * `userId → branch → sandboxProviderKind → SandboxRecord`. Returns `{}` for
+ * missing / malformed input rather than throwing — readers stay forgiving
+ * about unexpected per-row corruption; the strict schema catches any
+ * residual issues at validation time.
+ */
+export function normalizeSandboxMap(raw: unknown): SandboxMap {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const out: SandboxMap = {};
+  for (const [userId, userVal] of Object.entries(
+    raw as Record<string, unknown>,
+  )) {
+    if (!userVal || typeof userVal !== "object" || Array.isArray(userVal)) {
+      continue;
+    }
+    const userOut: SandboxMap[string] = {};
+    for (const [branch, branchVal] of Object.entries(
+      userVal as Record<string, unknown>,
+    )) {
+      const normalized = parseBranchMap(branchVal);
+      if (Object.keys(normalized).length > 0) {
+        userOut[branch] = normalized as SandboxMap[string][string];
+      }
+    }
+    if (Object.keys(userOut).length > 0) {
+      out[userId] = userOut;
+    }
+  }
+  return out;
+}
+
 /**
  * Virtual MCP entity schema - single source of truth
  * Compliant with collections binding pattern
@@ -91,10 +471,7 @@ export const VirtualMCPEntitySchema = z.object({
   // Entity-specific fields
   organization_id: z.string().describe("Organization ID this item belongs to"),
   status: z.enum(["active", "inactive"]).describe("Current status"),
-  subtype: z
-    .enum(["agent", "project"])
-    .nullable()
-    .describe("Virtual MCP subtype for UI presentation"),
+  pinned: z.boolean().describe("Whether this space is pinned to the sidebar"),
   // Metadata (stored in connections.metadata)
   // Normalize null/undefined to { instructions: null } for consistent form tracking
   metadata: z
@@ -111,6 +488,17 @@ export const VirtualMCPEntitySchema = z.object({
       ui: VirtualMcpUISchema.nullable()
         .optional()
         .describe("UI customization settings"),
+      githubRepo: GithubRepoSchema.nullable()
+        .optional()
+        .describe("Linked GitHub repository"),
+      runtime: RuntimeMetadataSchema.nullable()
+        .optional()
+        .describe(
+          "User-pinned runtime config (package manager, dev port). Empty fields = autodetect.",
+        ),
+      sandboxMap: SandboxMapSchema.optional().describe(
+        "Per-user, per-branch sandbox mapping: sandboxMap[userId][branch] -> { sandboxHandle, previewUrl }",
+      ),
     })
     .loose()
     .describe("Metadata"),
@@ -141,10 +529,7 @@ export const VirtualMCPCreateDataSchema = z.object({
     .optional()
     .default("active")
     .describe("Initial status"),
-  subtype: z
-    .enum(["agent", "project"])
-    .optional()
-    .describe("Virtual MCP subtype"),
+  pinned: z.boolean().optional().default(false).describe("Pin to sidebar"),
   metadata: z
     .object({
       instructions: z
@@ -160,6 +545,17 @@ export const VirtualMCPCreateDataSchema = z.object({
       ui: VirtualMcpUISchema.nullable()
         .optional()
         .describe("UI customization settings"),
+      githubRepo: GithubRepoSchema.nullable()
+        .optional()
+        .describe("Linked GitHub repository"),
+      runtime: RuntimeMetadataSchema.nullable()
+        .optional()
+        .describe(
+          "User-pinned runtime config (package manager, dev port). Empty fields = autodetect.",
+        ),
+      sandboxMap: SandboxMapSchema.optional().describe(
+        "Per-user, per-branch sandbox mapping: sandboxMap[userId][branch] -> { sandboxHandle, previewUrl }",
+      ),
     })
     .loose()
     .nullable()
@@ -186,7 +582,7 @@ export const VirtualMCPUpdateDataSchema = z.object({
     .describe("New description (null to clear)"),
   icon: z.string().nullish().describe("New icon URL"),
   status: z.enum(["active", "inactive"]).optional().describe("New status"),
-  subtype: z.enum(["agent", "project"]).optional().describe("New subtype"),
+  pinned: z.boolean().optional().describe("Pin/unpin from sidebar"),
   metadata: z
     .object({
       instructions: z
@@ -202,6 +598,17 @@ export const VirtualMCPUpdateDataSchema = z.object({
       ui: VirtualMcpUISchema.nullable()
         .optional()
         .describe("UI customization settings"),
+      githubRepo: GithubRepoSchema.nullable()
+        .optional()
+        .describe("Linked GitHub repository"),
+      runtime: RuntimeMetadataSchema.nullable()
+        .optional()
+        .describe(
+          "User-pinned runtime config (package manager, dev port). Empty fields = autodetect.",
+        ),
+      sandboxMap: SandboxMapSchema.optional().describe(
+        "Per-user, per-branch sandbox mapping: sandboxMap[userId][branch] -> { sandboxHandle, previewUrl }",
+      ),
     })
     .loose()
     .nullable()