@decocms/mesh-sdk 1.2.1 → 1.2.3

package/src/types/decopilot-events.ts

@@ -0,0 +1,171 @@
+/**
+ * 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;
+    virtual_mcp_id?: string;
+    /** User who created the thread; needed to populate filter-complete cache rows on the client. */
+    created_by?: string;
+    /** Automation trigger id; null for human-initiated, omitted when unknown. */
+    trigger_id?: string | null;
+    /** Thread title at emit time. Absent if caller didn't load the row. */
+    title?: string;
+    /** Branch this thread is pinned to (null when unpinned). Absent if caller didn't load the row. */
+    branch?: string | null;
+    /** Thread creation timestamp. Absent if caller didn't load the row. */
+    created_at?: string;
+    /** Last update timestamp; useful for the client to sort/dedupe. Absent if caller didn't load the row. */
+    updated_at?: string;
+    /** Free-form thread metadata snapshot. The chat UI keys off
+     *  metadata.kind to switch between agent-thread and tool_call_run
+     *  renderings (avatar, message-renderer), so the workflow that
+     *  spawns those threads must include it on the first event or the
+     *  row renders with the wrong icon until a refetch. */
+    metadata?: Record<string, unknown>;
+  };
+}
+
+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(
+  taskId: string,
+  stepCount: number,
+): DecopilotStepEvent {
+  return {
+    id: crypto.randomUUID(),
+    type: DECOPILOT_EVENTS.STEP,
+    source: "decopilot",
+    subject: taskId,
+    data: { stepCount },
+    time: new Date().toISOString(),
+  };
+}
+
+export function createDecopilotFinishEvent(
+  taskId: string,
+  status: ThreadStatus,
+): DecopilotFinishEvent {
+  return {
+    id: crypto.randomUUID(),
+    type: DECOPILOT_EVENTS.FINISH,
+    source: "decopilot",
+    subject: taskId,
+    data: { status },
+    time: new Date().toISOString(),
+  };
+}
+
+export function createDecopilotThreadStatusEvent(
+  taskId: string,
+  status: ThreadStatus,
+  opts?: {
+    virtualMcpId?: string;
+    createdBy?: string;
+    triggerId?: string | null;
+    title?: string;
+    branch?: string | null;
+    createdAt?: string;
+    updatedAt?: string;
+    metadata?: Record<string, unknown>;
+  },
+): DecopilotThreadStatusEvent {
+  return {
+    id: crypto.randomUUID(),
+    type: DECOPILOT_EVENTS.THREAD_STATUS,
+    source: "decopilot",
+    subject: taskId,
+    data: {
+      status,
+      ...(opts?.virtualMcpId !== undefined && {
+        virtual_mcp_id: opts.virtualMcpId,
+      }),
+      ...(opts?.createdBy !== undefined && { created_by: opts.createdBy }),
+      ...(opts?.triggerId !== undefined && { trigger_id: opts.triggerId }),
+      ...(opts?.title !== undefined && { title: opts.title }),
+      ...(opts?.branch !== undefined && { branch: opts.branch }),
+      ...(opts?.createdAt !== undefined && { created_at: opts.createdAt }),
+      ...(opts?.updatedAt !== undefined && { updated_at: opts.updatedAt }),
+      ...(opts?.metadata !== undefined && { metadata: opts.metadata }),
+    },
+    time: new Date().toISOString(),
+  };
+}

package/src/types/index.ts

@@ -19,9 +19,56 @@ export {
   VirtualMCPEntitySchema,
   VirtualMCPCreateDataSchema,
   VirtualMCPUpdateDataSchema,
+  VirtualMcpUILayoutSchema,
+  VirtualMcpUILayoutTabSchema,
   type VirtualMCPEntity,
   type VirtualMCPCreateData,
   type VirtualMCPUpdateData,
   type VirtualMCPConnection,
-  type ToolSelectionMode,
+  type VirtualMcpUILayout,
+  type VirtualMcpUILayoutTab,
+  type VirtualMcpHomeTile,
+  getHomeTiles,
+  type GithubRepo,
+  SandboxMapSchema,
+  type SandboxMap,
+  SandboxRecordSchema,
+  type SandboxRecord,
+  type RuntimeMetadata,
+  type RuntimeEnvEntry,
+  ENV_VAR_KEY_RE,
+  parseSandboxRecord,
+  parseBranchMap,
+  normalizeSandboxMap,
+  type SandboxProviderKind,
 } from "./virtual-mcp";
+
+export {
+  PROVIDER_IDS,
+  MODEL_CAPABILITIES,
+  type ProviderId,
+  type ModelCapability,
+  type AiProviderModel,
+  type AiProviderModelLimits,
+  type AiProviderModelCosts,
+  type AiProviderKey,
+  type AiProviderInfo,
+} from "./ai-providers";
+
+export {
+  THREAD_STATUSES,
+  THREAD_DISPLAY_STATUSES,
+  DECOPILOT_EVENTS,
+  ALL_DECOPILOT_EVENT_TYPES,
+  createDecopilotStepEvent,
+  createDecopilotFinishEvent,
+  createDecopilotThreadStatusEvent,
+  type ThreadStatus,
+  type ThreadDisplayStatus,
+  type DecopilotEventType,
+  type DecopilotStepEvent,
+  type DecopilotFinishEvent,
+  type DecopilotThreadStatusEvent,
+  type DecopilotSSEEvent,
+  type DecopilotEventMap,
+} from "./decopilot-events";

package/src/types/virtual-mcp.test.ts

@@ -0,0 +1,202 @@
+import { describe, expect, it, test } from "bun:test";
+import {
+  VirtualMCPEntitySchema,
+  VirtualMcpUILayoutSchema,
+  VirtualMCPUpdateDataSchema,
+  SandboxRecordSchema,
+  parseSandboxRecord,
+  parseBranchMap,
+} from "./virtual-mcp";
+
+describe("VirtualMcpUILayoutSchema tabs", () => {
+  it("parses a tabs array with ext-app view", () => {
+    const parsed = VirtualMcpUILayoutSchema.parse({
+      tabs: [
+        {
+          id: "analytics",
+          title: "Analytics",
+          icon: "BarChart",
+          view: { type: "ext-app", appId: "app_abc", args: { range: "7d" } },
+        },
+      ],
+      defaultMainView: null,
+    });
+    expect(parsed.tabs).toHaveLength(1);
+    expect(parsed.tabs?.[0]!.view.type).toBe("ext-app");
+    expect(parsed.tabs?.[0]!.view.appId).toBe("app_abc");
+  });
+
+  it("accepts tabs omitted (backwards compatible)", () => {
+    const parsed = VirtualMcpUILayoutSchema.parse({
+      defaultMainView: null,
+    });
+    expect(parsed.tabs).toBeUndefined();
+  });
+
+  it("rejects a tab view with unknown type", () => {
+    const result = VirtualMcpUILayoutSchema.safeParse({
+      tabs: [
+        {
+          id: "bad",
+          title: "Bad",
+          view: { type: "mystery", appId: "app_x" },
+        },
+      ],
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+test("metadata.runtime is typed and round-trips through parse", () => {
+  const parsed = VirtualMCPEntitySchema.parse({
+    id: "x",
+    title: "x",
+    description: null,
+    icon: null,
+    created_at: "t",
+    updated_at: "t",
+    created_by: "u",
+    organization_id: "o",
+    status: "active",
+    pinned: false,
+    metadata: {
+      instructions: null,
+      runtime: { selected: "pnpm", port: "3000" },
+    },
+    connections: [],
+  });
+  expect(parsed.metadata.runtime?.selected).toBe("pnpm");
+  expect(parsed.metadata.runtime?.port).toBe("3000");
+});
+
+test("metadata.runtime accepts null/empty values", () => {
+  const parsed = VirtualMCPEntitySchema.parse({
+    id: "x",
+    title: "x",
+    description: null,
+    icon: null,
+    created_at: "t",
+    updated_at: "t",
+    created_by: "u",
+    organization_id: "o",
+    status: "active",
+    pinned: false,
+    metadata: {
+      instructions: null,
+      runtime: { selected: null, port: null },
+    },
+    connections: [],
+  });
+  expect(parsed.metadata.runtime?.selected).toBeNull();
+  expect(parsed.metadata.runtime?.port).toBeNull();
+});
+
+test("VirtualMCPUpdateDataSchema accepts metadata.runtime", () => {
+  const parsed = VirtualMCPUpdateDataSchema.parse({
+    metadata: { runtime: { selected: "bun", port: null } },
+  });
+  expect(parsed.metadata?.runtime?.selected).toBe("bun");
+  expect(parsed.metadata?.runtime?.port).toBeNull();
+});
+
+test("SandboxRecord.startedWith is optional with nullable packageManager/port/path", () => {
+  const a = SandboxRecordSchema.parse({ sandboxHandle: "v", previewUrl: null });
+  expect(a.startedWith).toBeUndefined();
+  const b = SandboxRecordSchema.parse({
+    sandboxHandle: "v",
+    previewUrl: null,
+    startedWith: { packageManager: "pnpm", port: "3000", path: "apps/web" },
+  });
+  expect(b.startedWith?.packageManager).toBe("pnpm");
+  expect(b.startedWith?.port).toBe("3000");
+  expect(b.startedWith?.path).toBe("apps/web");
+  const c = SandboxRecordSchema.parse({
+    sandboxHandle: "v",
+    previewUrl: null,
+    startedWith: { packageManager: null, port: null, path: null },
+  });
+  expect(c.startedWith?.packageManager).toBeNull();
+  expect(c.startedWith?.port).toBeNull();
+  expect(c.startedWith?.path).toBeNull();
+});
+
+describe("parseBranchMap", () => {
+  test("parses 3-level (kind-keyed) map with canonical kinds", () => {
+    const result = parseBranchMap({
+      cluster: {
+        sandboxHandle: "v1",
+        previewUrl: null,
+        sandboxProviderKind: "cluster",
+      },
+      "user-desktop": {
+        sandboxHandle: "v2",
+        previewUrl: null,
+        sandboxProviderKind: "user-desktop",
+      },
+    });
+    expect(result["cluster"]?.sandboxHandle).toBe("v1");
+    expect(result["user-desktop"]?.sandboxHandle).toBe("v2");
+  });
+
+  test("returns empty object for null/undefined/arrays", () => {
+    expect(parseBranchMap(null)).toEqual({});
+    expect(parseBranchMap(undefined)).toEqual({});
+    expect(parseBranchMap([])).toEqual({});
+  });
+
+  test("skips entries under legacy/retired kind keys", () => {
+    // Migrations 092/097 rewrote/dropped every legacy and retired key; reader
+    // no longer normalizes unknown keys, it just ignores them.
+    const result = parseBranchMap({
+      docker: {
+        sandboxHandle: "v-legacy",
+        previewUrl: null,
+        sandboxProviderKind: "cluster",
+      },
+      "local-docker": {
+        sandboxHandle: "v-retired",
+        previewUrl: null,
+        sandboxProviderKind: "cluster",
+      },
+    });
+    expect(result).toEqual({});
+  });
+});
+
+describe("parseSandboxRecord", () => {
+  test("accepts canonical sandboxProviderKind", () => {
+    const result = parseSandboxRecord({
+      sandboxHandle: "v1",
+      previewUrl: null,
+      sandboxProviderKind: "cluster",
+    });
+    expect(result.sandboxProviderKind).toBe("cluster");
+  });
+
+  test("rejects legacy/retired kind values", () => {
+    expect(() =>
+      parseSandboxRecord({
+        sandboxHandle: "v1",
+        previewUrl: null,
+        sandboxProviderKind: "docker",
+      }),
+    ).toThrow();
+    expect(() =>
+      parseSandboxRecord({
+        sandboxHandle: "v1",
+        previewUrl: null,
+        sandboxProviderKind: "local-docker",
+      }),
+    ).toThrow();
+  });
+
+  test("rejects rows missing `sandboxHandle` (legacy `vmId` no longer accepted)", () => {
+    expect(() =>
+      parseSandboxRecord({
+        vmId: "v-pre-rename",
+        previewUrl: null,
+        sandboxProviderKind: "cluster",
+      }),
+    ).toThrow();
+  });
+});