@dench.com/cli 2.1.1 → 2.1.3

package/lib/api-schemas.ts

@@ -0,0 +1,1095 @@
+/**
+ * Deep per-operation request/response schemas for the Dench API v1.
+ *
+ * These are the source of truth for:
+ *   - OpenAPI generation (scripts/generate-openapi.ts) -> interactive
+ *     Mintlify playground parameters, request bodies, and responses.
+ *   - Runtime validation in the API v1 dispatcher.
+ *   - The generated curl guide (public/references/API.md).
+ *
+ * Auth args (`sessionToken` / `apiKey` / `runId`) are intentionally
+ * omitted here: the dispatcher injects them from the bearer token and
+ * `x-dench-run-id` header. Path-parameter fields (e.g. `objectName`,
+ * `entryId`) ARE included so they validate and reach the backend; any
+ * decorative path segment a backend function does not accept is left out
+ * so strict parsing drops it before the Convex call.
+ *
+ * Schemas mirror the real Convex `args` validators and gateway request
+ * shapes. They avoid `.refine()`/`.transform()` so `z.toJSONSchema`
+ * stays lossless for the playground.
+ */
+import { type ZodTypeAny, z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Shared enums + fragments (mirror convex validators)
+// ---------------------------------------------------------------------------
+
+export const FIELD_TYPES = [
+  "text",
+  "email",
+  "phone",
+  "url",
+  "number",
+  "boolean",
+  "date",
+  "richtext",
+  "file",
+  "user",
+  "enum",
+  "relation",
+  "tags",
+  "action",
+] as const;
+
+const fieldType = z
+  .enum(FIELD_TYPES)
+  .describe(
+    "Field data type. `relation` needs relatedObjectName + relationshipType; `enum` uses enumValues/enumColors; `user` cells store a member userId; long prose belongs in the protected `Notes` richtext field.",
+  );
+
+const viewKind = z
+  .enum(["table", "kanban", "calendar", "timeline", "gallery", "list"])
+  .describe("Default view rendered for the object.");
+
+const relationshipType = z
+  .enum(["many_to_one", "many_to_many"])
+  .describe("Relation cardinality for a `relation` field.");
+
+const memoryKind = z
+  .enum([
+    "fact",
+    "decision",
+    "preference",
+    "goal",
+    "tool_note",
+    "other",
+    "convention",
+    "project_context",
+    "agent_lesson",
+    "docs_knowledge",
+    "open_goal",
+  ])
+  .describe("Memory classification.");
+
+const memorySensitivity = z
+  .enum(["normal", "broad", "sensitive"])
+  .describe("Sensitivity tier; `sensitive` memories land in needs-review.");
+
+const memoryVisibility = z
+  .enum(["user", "org"])
+  .describe("Who can see the memory. Defaults to `user`.");
+
+const riskLevel = z.enum(["low", "medium", "high"]).describe("Risk level.");
+
+const approvalDecision = z
+  .enum(["approved", "rejected"])
+  .describe("Human decision for an approval request.");
+
+const signInIntent = z
+  .enum(["join_existing", "create_workspace"])
+  .describe("Whether to join an existing workspace or create a new one.");
+
+const reportType = z
+  .enum(["pie", "bar", "line", "table"])
+  .describe("Chart type for the generated report.");
+
+const reportMetric = z
+  .enum(["count", "sum", "avg", "min", "max"])
+  .describe("Aggregation metric. Defaults to `count`.");
+
+const overlapPolicy = z
+  .enum(["skip", "queue", "kill_old"])
+  .describe(
+    "What to do when a previous run is still active. Defaults to `skip`.",
+  );
+
+const cronTarget = z.literal("chat_turn").describe("Routine run target.");
+
+const scheduleSpec = z
+  .union([
+    z.object({
+      kind: z.literal("every"),
+      everyMs: z
+        .number()
+        .int()
+        .positive()
+        .describe("Interval in milliseconds (1s to 365d)."),
+      anchorMs: z
+        .number()
+        .int()
+        .optional()
+        .describe("Optional anchor timestamp for the recurring fire."),
+    }),
+    z.object({
+      kind: z.literal("cron"),
+      expr: z.string().describe("5-field POSIX cron expression."),
+      tz: z
+        .string()
+        .optional()
+        .describe("IANA timezone, e.g. America/New_York."),
+    }),
+    z.object({
+      kind: z.literal("at"),
+      at: z.string().describe("ISO 8601 timestamp for a one-shot run."),
+    }),
+  ])
+  .describe(
+    "Schedule: recurring (`every`), cron expression, or one-shot (`at`).",
+  );
+
+const dataMap = z
+  .record(z.string(), z.unknown())
+  .describe("Field-name -> value map. Use member userIds for `user` fields.");
+
+const cellValue = z
+  .unknown()
+  .describe(
+    "Cell value. Enum=option string, tags=string array, user=member userId, relation=related entry id, boolean=true/false.",
+  );
+
+const enrichmentConfig = z
+  .object({
+    category: z.enum(["people", "company"]),
+    key: z.string(),
+    apolloPath: z.string(),
+    inputFieldName: z.string().optional(),
+  })
+  .describe(
+    "Enrichment binding that lets the field auto-fill from a provider.",
+  );
+
+const crmOp = z
+  .union([
+    z.object({
+      type: z.literal("entries.create"),
+      objectName: z.string(),
+      data: dataMap,
+    }),
+    z.object({
+      type: z.literal("entries.update"),
+      entryId: z.string(),
+      data: dataMap,
+    }),
+    z.object({
+      type: z.literal("entries.delete"),
+      entryId: z.string(),
+    }),
+  ])
+  .describe("A single CRM batch/transaction operation.");
+
+// ---------------------------------------------------------------------------
+// Response fragments (representative; not exhaustive)
+// ---------------------------------------------------------------------------
+
+const okResponse = z.object({ ok: z.boolean() });
+
+const crmObjectShape = z
+  .object({
+    id: z.string(),
+    name: z.string(),
+    description: z.string().nullable().optional(),
+    icon: z.string().nullable().optional(),
+    immutable: z.boolean().optional(),
+  })
+  .describe("A CRM object (table).");
+
+const crmFieldShape = z
+  .object({
+    id: z.string(),
+    name: z.string(),
+    type: z.enum(FIELD_TYPES),
+    required: z.boolean().optional(),
+    enum_values: z.array(z.string()).nullable().optional(),
+    enum_colors: z.array(z.string()).nullable().optional(),
+    indexed: z.boolean().optional(),
+  })
+  .describe("A CRM field (column).");
+
+const crmEntryShape = z
+  .object({
+    id: z.string(),
+    fields: dataMap,
+    createdAt: z.number().nullable().optional(),
+    updatedAt: z.number().nullable().optional(),
+  })
+  .describe("A materialized CRM entry (row).");
+
+const memberShape = z.object({
+  userId: z.string(),
+  name: z.string().nullable().optional(),
+  email: z.string().nullable().optional(),
+  image: z.string().nullable().optional(),
+  role: z.string().optional(),
+  joinedAt: z.number().optional(),
+});
+
+// ---------------------------------------------------------------------------
+// Gateway request shapes (re-declared without refine/transform)
+// ---------------------------------------------------------------------------
+
+const exaSearch = z.object({
+  query: z.string().describe("Search query."),
+  type: z
+    .enum(["auto", "neural", "fast", "deep", "deep-reasoning", "instant"])
+    .optional(),
+  numResults: z.number().int().min(1).max(100).optional(),
+  category: z
+    .enum([
+      "company",
+      "research paper",
+      "news",
+      "personal site",
+      "financial report",
+      "people",
+    ])
+    .optional(),
+  includeDomains: z.array(z.string()).optional(),
+  excludeDomains: z.array(z.string()).optional(),
+  startPublishedDate: z.string().optional(),
+  endPublishedDate: z.string().optional(),
+  includeText: z.array(z.string()).optional(),
+  excludeText: z.array(z.string()).optional(),
+  userLocation: z.string().optional(),
+  moderation: z.boolean().optional(),
+});
+
+const exaContents = z.object({
+  urls: z.array(z.string()).describe("URLs to fetch (max 10)."),
+  text: z.boolean().optional(),
+  summary: z
+    .object({ query: z.string().optional() })
+    .optional()
+    .describe("Optional per-URL summary."),
+});
+
+const exaAnswer = z.object({
+  query: z.string().describe("Question to answer with web search."),
+  text: z.boolean().optional(),
+  stream: z.boolean().optional(),
+  outputSchema: z.record(z.string(), z.unknown()).optional(),
+});
+
+const imageGenerate = z.object({
+  prompt: z.string().min(1).max(32_000).describe("Image prompt."),
+  size: z.string().optional().describe("e.g. 1024x1024, 1536x1024, auto."),
+  quality: z.enum(["auto", "low", "medium", "high"]).optional(),
+  format: z.enum(["png", "jpeg", "webp"]).optional(),
+  output_compression: z.number().int().min(0).max(100).optional(),
+  background: z.enum(["auto", "opaque", "transparent"]).optional(),
+  savePath: z
+    .string()
+    .optional()
+    .describe("Workspace path to write the image."),
+});
+
+const imageEdit = imageGenerate.extend({
+  input_images_base64: z
+    .array(z.string())
+    .min(1)
+    .max(8)
+    .describe("Base64-encoded source images (1-8)."),
+  mask_base64: z.string().optional().describe("Optional base64 mask image."),
+});
+
+const composioConnect = z.object({
+  toolkit: z
+    .string()
+    .min(1)
+    .describe("Toolkit slug, e.g. github, gmail, stripe."),
+  callback_url: z.string().optional().describe("Optional OAuth callback URL."),
+});
+
+const composioToolSearch = z.object({
+  queries: z
+    .array(
+      z.object({
+        use_case: z.string().min(1).describe("Natural-language use case."),
+        known_fields: z.string().optional(),
+      }),
+    )
+    .min(1)
+    .max(7),
+  session: z
+    .object({ id: z.string().optional(), generate_id: z.boolean().optional() })
+    .optional(),
+  account: z.string().optional(),
+  model: z.string().optional(),
+});
+
+const composioToolRun = z.object({
+  execution_ref: z
+    .string()
+    .optional()
+    .describe(
+      "Execution ref from a prior search, OR pass session_id+tool_slug.",
+    ),
+  session_id: z.string().optional(),
+  tool_slug: z
+    .string()
+    .optional()
+    .describe("Composio tool slug, e.g. GMAIL_FETCH_EMAILS."),
+  arguments: z
+    .record(z.string(), z.unknown())
+    .optional()
+    .describe("Tool arguments object."),
+  account: z.string().optional(),
+});
+
+const peopleSearch = z.object({
+  linkedinUrl: z.string().optional(),
+  fullName: z.string().optional(),
+  firstName: z.string().optional(),
+  lastName: z.string().optional(),
+  keywords: z.string().optional(),
+  companyDomain: z.string().optional(),
+  companyName: z.string().optional(),
+  titles: z.array(z.string()).max(50).optional(),
+  seniorities: z.array(z.string()).max(20).optional(),
+  jobFunctions: z.array(z.string()).max(20).optional(),
+  industries: z.array(z.string()).max(50).optional(),
+  locations: z.array(z.string()).max(50).optional(),
+  headcountRanges: z.array(z.string()).max(20).optional(),
+  exactMatch: z.boolean().optional(),
+  limit: z.number().int().positive().max(100).optional(),
+  offset: z.number().int().nonnegative().optional(),
+  preferCache: z.boolean().optional(),
+});
+
+const companySearch = z.object({
+  domain: z.string().optional(),
+  name: z.string().optional(),
+  linkedinUrl: z.string().optional(),
+  exactMatch: z.boolean().optional(),
+  limit: z.number().int().positive().max(100).optional(),
+  offset: z.number().int().nonnegative().optional(),
+  preferCache: z.boolean().optional(),
+});
+
+// ---------------------------------------------------------------------------
+// Request schemas keyed by operation id
+// ---------------------------------------------------------------------------
+
+export const requestSchemas: Record<string, ZodTypeAny> = {
+  // Auth
+  "auth.signin.create": z.object({
+    codeHash: z.string(),
+    sessionTokenHash: z.string(),
+    agentName: z.string(),
+    agentKind: z.string().describe("Agent kind, normalized to snake_case."),
+    intent: signInIntent,
+    proposedOrganizationName: z
+      .string()
+      .optional()
+      .describe("Required when intent is create_workspace."),
+    requestedOrganizationSelector: z.string().optional(),
+    userAgent: z.string().optional(),
+  }),
+  "auth.signin.poll": z.object({
+    codeHash: z.string(),
+    sessionTokenHash: z.string(),
+  }),
+  "auth.otp.start": z.object({
+    email: z.string().describe("Email to send the code to."),
+  }),
+  "auth.otp.verify": z.object({
+    email: z.string(),
+    code: z.string().describe("6+ digit code from the email."),
+    agentName: z.string(),
+    agentKind: z.string(),
+    sessionTokenHash: z
+      .string()
+      .describe("sha256 hex of the local session token."),
+    intent: signInIntent,
+    proposedOrganizationName: z.string().optional(),
+    organizationSelector: z.string().optional(),
+    userAgent: z.string().optional(),
+  }),
+  "auth.otp.finalize": z.object({
+    authToken: z.string(),
+    organizationId: z
+      .string()
+      .optional()
+      .describe("Provide this OR newOrganizationName."),
+    newOrganizationName: z.string().optional(),
+  }),
+
+  // Workspace
+  "workspace.artifacts.list": z.object({
+    limit: z.coerce.number().int().min(1).max(100).optional(),
+  }),
+  "workspace.suggestedWork.list": z.object({
+    limit: z.coerce.number().int().min(1).max(100).optional(),
+  }),
+
+  // Memory
+  "memory.search": z.object({
+    query: z.string().describe("Full-text query."),
+    limit: z.coerce.number().int().min(1).max(20).optional(),
+  }),
+  "memory.save": z.object({
+    key: z.string().describe("Stable memory key."),
+    kind: memoryKind,
+    text: z.string().describe("Memory body. No secrets or scratch notes."),
+    tags: z.array(z.string()).optional(),
+    sensitivity: memorySensitivity.optional(),
+    visibility: memoryVisibility.optional(),
+    projectId: z.string().optional(),
+    sourceQuote: z.string().optional(),
+    confidence: z.number().optional(),
+    importance: z.number().optional(),
+  }),
+
+  // Approvals
+  "approval.request": z.object({
+    title: z.string().describe("What needs human approval."),
+    reason: z.string().optional(),
+    risk: riskLevel,
+  }),
+  "approval.decide": z.object({
+    approvalId: z.string(),
+    decision: approvalDecision,
+    evidence: z
+      .string()
+      .optional()
+      .describe("Required when the requesting agent records its own decision."),
+  }),
+
+  // Billing
+  "billing.topup": z.object({
+    requestId: z
+      .string()
+      .describe("Idempotency key (1-200 of [A-Za-z0-9:_-])."),
+    amountUsd: z.number().describe("USD amount, $5 to $1000."),
+  }),
+  "billing.upgrade": z.object({
+    tier: z.enum(["pro", "max", "cloud", "desktop", "api"]).optional(),
+    billingCycle: z.enum(["monthly", "yearly"]).optional(),
+    requestId: z.string().optional(),
+    returnPath: z
+      .string()
+      .optional()
+      .describe("Internal return path beginning with /."),
+  }),
+
+  // Chat
+  "chat.list": z.object({
+    titleQuery: z.string().optional(),
+    limit: z.coerce.number().int().min(1).max(100).optional(),
+    includeArchived: z.coerce.boolean().optional(),
+    includeAutomated: z.coerce.boolean().optional(),
+  }),
+  "chat.search": z.object({
+    query: z.string().describe("Full-text query across past messages."),
+    limit: z.coerce.number().int().min(1).max(50).optional(),
+    excludeThreadId: z.string().optional(),
+    includeAutomated: z.coerce.boolean().optional(),
+  }),
+  "chat.read": z.object({
+    threadId: z.string(),
+    limit: z.coerce.number().int().min(1).max(200).optional(),
+  }),
+  "chat.tree": z.object({
+    limit: z.coerce.number().int().min(1).max(100).optional(),
+  }),
+  "chat.rename": z.object({
+    items: z
+      .array(z.object({ threadId: z.string(), title: z.string() }))
+      .min(1)
+      .max(50),
+  }),
+  "chat.delete": z.object({
+    threadIds: z.array(z.string()).min(1).max(25),
+    includeAutomated: z.boolean().optional(),
+  }),
+  "chat.new": z.object({
+    prompt: z.string().describe("The user message that starts the turn."),
+    model: z.string().optional(),
+    fileContextPath: z.string().optional(),
+    visibility: z.enum(["private", "shared"]).optional(),
+    yolo: z
+      .boolean()
+      .optional()
+      .describe("Bypass approval gates for this turn."),
+    title: z.string().optional(),
+  }),
+  "chat.send": z.object({
+    threadId: z.string(),
+    prompt: z.string().describe("The message to append."),
+    model: z.string().optional(),
+    yolo: z.boolean().optional(),
+  }),
+  "chat.follow": z.object({ threadId: z.string() }),
+
+  // CRM objects
+  "crm.objects.get": z.object({ name: z.string() }),
+  "crm.objects.create": z.object({
+    name: z.string().describe("Object name (lowercased, singular)."),
+    description: z.string().optional(),
+    defaultView: viewKind.optional(),
+    icon: z
+      .string()
+      .optional()
+      .describe("Lucide icon name, e.g. users, target."),
+  }),
+  "crm.objects.update": z.object({
+    name: z.string(),
+    description: z.string().optional(),
+    defaultView: viewKind.optional(),
+    icon: z.string().optional(),
+    viewSettings: z.record(z.string(), z.unknown()).optional(),
+    savedViews: z.array(z.record(z.string(), z.unknown())).optional(),
+  }),
+  "crm.objects.rename": z.object({
+    from: z.string().describe("Current object name (path)."),
+    to: z.string().describe("New object name."),
+  }),
+  "crm.objects.delete": z.object({ name: z.string() }),
+
+  // CRM fields
+  "crm.fields.list": z.object({ objectName: z.string() }),
+  "crm.fields.create": z.object({
+    objectName: z.string(),
+    name: z.string(),
+    type: fieldType,
+    required: z.boolean().optional(),
+    defaultValue: z.string().optional(),
+    relatedObjectName: z
+      .string()
+      .optional()
+      .describe("Target object for `relation` fields."),
+    relationshipType: relationshipType.optional(),
+    enumValues: z
+      .array(z.string())
+      .optional()
+      .describe("Options for `enum` fields."),
+    enumColors: z
+      .array(z.string())
+      .optional()
+      .describe("Hex colors aligned to enumValues."),
+    enumMultiple: z.boolean().optional().describe("Allow multi-select enum."),
+    description: z.string().optional(),
+    indexed: z.boolean().optional().describe("Index for filter/search/sort."),
+    enrichment: enrichmentConfig.optional(),
+  }),
+  "crm.fields.update": z.object({
+    objectName: z.string(),
+    fieldName: z.string(),
+    name: z.string().optional().describe("Rename the field."),
+    description: z.string().optional(),
+    required: z.boolean().optional(),
+    enumValues: z
+      .array(z.string())
+      .optional()
+      .describe("Full replacement of options."),
+    enumColors: z.array(z.string()).optional(),
+    enumMultiple: z.boolean().optional(),
+    indexed: z.boolean().optional(),
+    enrichment: enrichmentConfig.optional(),
+    clearEnrichment: z.boolean().optional(),
+  }),
+  "crm.fields.delete": z.object({
+    objectName: z.string(),
+    fieldName: z.string(),
+  }),
+  "crm.fields.reorder": z.object({
+    objectName: z.string(),
+    orderedFieldNames: z
+      .array(z.string())
+      .describe("Field names in desired order."),
+  }),
+  "crm.fields.enum.reorder": z.object({
+    objectName: z.string(),
+    fieldName: z.string(),
+    orderedValues: z
+      .array(z.string())
+      .describe("Exact permutation of existing options."),
+  }),
+  "crm.fields.enum.add": z.object({
+    objectName: z.string(),
+    fieldName: z.string(),
+    value: z.string().describe("Option value to add."),
+    color: z.string().optional().describe("Hex color for the option."),
+    position: z
+      .number()
+      .int()
+      .optional()
+      .describe("0-based insert index; defaults to append."),
+  }),
+  "crm.fields.enum.remove": z.object({
+    objectName: z.string(),
+    fieldName: z.string(),
+    value: z.string(),
+  }),
+  "crm.fields.enum.rename": z.object({
+    objectName: z.string(),
+    fieldName: z.string(),
+    oldValue: z.string().describe("Existing option value (path)."),
+    newValue: z
+      .string()
+      .describe("New option value; migrates entries + statuses."),
+  }),
+  "crm.fields.enum.color": z.object({
+    objectName: z.string(),
+    fieldName: z.string(),
+    value: z.string(),
+    color: z.string().describe("Hex color, e.g. #22c55e."),
+  }),
+
+  // CRM entries
+  "crm.entries.list": z.object({
+    objectName: z.string(),
+    limit: z.coerce.number().int().min(1).max(1000).optional(),
+  }),
+  "crm.entries.get": z.object({
+    objectName: z.string(),
+    entryId: z.string(),
+  }),
+  "crm.entries.create": z.object({
+    objectName: z.string(),
+    data: dataMap,
+  }),
+  "crm.entries.createMany": z.object({
+    objectName: z.string(),
+    entries: z.array(dataMap).max(200).describe("Up to 200 field maps."),
+  }),
+  "crm.entries.update": z.object({
+    objectName: z.string(),
+    entryId: z.string(),
+    data: dataMap,
+  }),
+  "crm.entries.updateMany": z.object({
+    objectName: z.string().describe("Object the entries belong to."),
+    updates: z
+      .array(
+        z
+          .object({
+            entryId: z.string().optional(),
+            id: z.string().optional(),
+            data: dataMap,
+          })
+          .refine((u) => u.entryId || u.id, {
+            message: "Each update must include entryId or id",
+          }),
+      )
+      .max(200)
+      .describe("Per-entry partial updates (entryId or id + data)."),
+  }),
+  "crm.entries.delete": z.object({ entryId: z.string() }),
+  "crm.entries.bulkDelete": z.object({
+    entryIds: z.array(z.string()).max(200),
+  }),
+
+  // CRM cells
+  "crm.cells.get": z.object({
+    objectName: z.string(),
+    entryId: z.string(),
+    fieldName: z.string(),
+  }),
+  "crm.cells.set": z.object({
+    objectName: z.string(),
+    entryId: z.string(),
+    fieldName: z.string(),
+    value: cellValue,
+  }),
+  "crm.cells.setMany": z.object({
+    cells: z
+      .array(
+        z.object({
+          objectName: z.string(),
+          entryId: z.string(),
+          fieldName: z.string(),
+          value: cellValue,
+        }),
+      )
+      .max(200),
+  }),
+  "crm.cells.append": z.object({
+    objectName: z.string(),
+    entryId: z.string(),
+    fieldName: z.string(),
+    value: cellValue,
+  }),
+
+  // CRM query
+  "crm.query": z.object({
+    objectName: z.string(),
+    dsl: z
+      .object({
+        filter: z.record(z.string(), z.unknown()).optional(),
+        select: z.array(z.string()).optional(),
+        sort: z.string().optional().describe("e.g. -Score,Name (- = desc)."),
+        limit: z.number().int().optional(),
+      })
+      .optional()
+      .describe("Query DSL. Bare equality only; use dslJson for $-operators."),
+    dslJson: z
+      .string()
+      .optional()
+      .describe(
+        "JSON string of the DSL when filters use operators like $gt/$in/$contains/$and/$or.",
+      ),
+  }),
+  "crm.sql": z.object({
+    objectName: z.string(),
+    dsl: z.record(z.string(), z.unknown()).optional(),
+    dslJson: z.string().optional(),
+  }),
+  "crm.aggregate": z.object({
+    objectName: z.string(),
+    fieldName: z.string().describe("Field to bucket by."),
+  }),
+  "crm.search": z.object({
+    text: z.string().describe("Full-text query."),
+    objectName: z.string().optional().describe("Omit to search org-wide."),
+    limit: z.coerce.number().int().min(1).max(100).optional(),
+  }),
+
+  // CRM statuses
+  "crm.statuses.list": z.object({ objectName: z.string() }),
+  "crm.statuses.set": z.object({
+    objectName: z.string(),
+    statuses: z.array(
+      z.object({
+        name: z.string(),
+        color: z.string().describe("Hex color."),
+        sortOrder: z.number().optional(),
+        isDefault: z.boolean().optional(),
+      }),
+    ),
+  }),
+
+  // CRM batch + transactions
+  "crm.batch": z.object({
+    ops: z.array(crmOp).max(200),
+    idempotencyKey: z.string().optional(),
+  }),
+  "crm.transaction.begin": z.object({}),
+  "crm.transaction.add": z.object({ txnId: z.string(), op: crmOp }),
+  "crm.transaction.commit": z.object({ txnId: z.string() }),
+  "crm.transaction.abort": z.object({ txnId: z.string() }),
+  "crm.transaction.inspect": z.object({ txnId: z.string() }),
+
+  // CRM docs / actions / reports / enrich / members
+  "crm.docs.create": z.object({
+    title: z.string(),
+    filePath: z.string(),
+    icon: z.string().optional(),
+    coverImage: z.string().optional(),
+    parentId: z.string().optional(),
+    parentObjectName: z.string().optional(),
+    entryId: z.string().optional(),
+  }),
+  "crm.docs.link": z.object({
+    filePath: z.string(),
+    objectName: z.string().optional(),
+    entryId: z.string().optional(),
+  }),
+  "crm.actions.list": z.object({ entryId: z.string() }),
+  "crm.actions.run": z.object({
+    actionId: z.string(),
+    fieldId: z.string(),
+    entryId: z.string(),
+  }),
+  "crm.reports.generate": z.object({
+    objectName: z.string(),
+    type: reportType,
+    groupByField: z.string(),
+    metric: reportMetric.optional(),
+    metricField: z.string().optional(),
+  }),
+  "crm.enrich.cell": z.object({
+    objectName: z.string(),
+    entryId: z.string(),
+    fieldName: z.string(),
+    provider: z.string().optional().describe("Defaults to auto."),
+  }),
+  "crm.enrich.object": z.object({
+    objectName: z.string(),
+    fieldName: z.string(),
+    provider: z.string().optional(),
+    missingOnly: z
+      .boolean()
+      .optional()
+      .describe("Only enrich empty cells. Defaults true."),
+  }),
+  "crm.people.search": peopleSearch,
+  "crm.companies.search": companySearch,
+
+  // Routines
+  "cron.list": z.object({ enabledOnly: z.coerce.boolean().optional() }),
+  "cron.history": z.object({
+    limit: z.coerce.number().int().min(1).max(200).optional(),
+  }),
+  "cron.get": z.object({ jobId: z.string() }),
+  "cron.create": z.object({
+    name: z.string(),
+    prompt: z.string().describe("Agent goal/message for each run."),
+    schedule: scheduleSpec,
+    description: z.string().optional(),
+    overlapPolicy: overlapPolicy.optional(),
+    enabled: z.boolean().optional(),
+    deleteAfterRun: z.boolean().optional(),
+    target: cronTarget.optional(),
+  }),
+  "cron.update": z.object({
+    jobId: z.string(),
+    name: z.string().optional(),
+    prompt: z.string().optional(),
+    schedule: scheduleSpec.optional(),
+    description: z.string().optional(),
+    overlapPolicy: overlapPolicy.optional(),
+    enabled: z.boolean().optional(),
+    deleteAfterRun: z.boolean().optional(),
+    target: cronTarget.optional(),
+  }),
+  "cron.delete": z.object({ jobId: z.string() }),
+  "cron.enable": z.object({ jobId: z.string() }),
+  "cron.disable": z.object({ jobId: z.string() }),
+  "cron.run": z.object({ jobId: z.string() }),
+  "cron.runs": z.object({
+    jobId: z.string(),
+    limit: z.coerce.number().int().min(1).max(200).optional(),
+  }),
+
+  // Files
+  "files.list": z.object({
+    prefix: z.string().optional().describe("Directory path, defaults to /."),
+    slug: z.string().optional(),
+  }),
+  "files.downloadUrl": z.object({ path: z.string() }),
+  "files.delete": z.object({ path: z.string() }),
+  "files.move": z.object({
+    from: z.string().describe("Source workspace path."),
+    to: z.string().describe("Destination workspace path."),
+  }),
+  "files.stage": z.object({
+    files: z
+      .array(
+        z.object({
+          path: z.string(),
+          text: z.string().optional(),
+          base64: z.string().optional(),
+        }),
+      )
+      .optional()
+      .describe("Files to write. Each needs text or base64."),
+    path: z.string().optional().describe("Single-file shortcut."),
+    text: z.string().optional(),
+    base64: z.string().optional(),
+    lastModifiedBy: z.string().optional(),
+  }),
+
+  // Agent config
+  "agentConfig.identity.edit": z.object({ content: z.string() }),
+  "agentConfig.organisation.edit": z.object({ content: z.string() }),
+  "agentConfig.user.edit": z.object({ content: z.string() }),
+  "agentConfig.tools.edit": z.object({ content: z.string() }),
+  "agentConfig.mem.edit": z.object({
+    content: z.string(),
+    append: z.boolean().optional(),
+  }),
+  "agentConfig.bootstrap.complete": z.object({
+    completed: z.boolean().optional(),
+  }),
+  "agentConfig.bootstrap.template": z.object({ content: z.string() }),
+  "agentConfig.model.default": z.object({
+    modelId: z.string().nullable().describe("Model id, or null to clear."),
+  }),
+  "agentConfig.model.thread": z.object({
+    threadId: z.string(),
+    modelId: z.string().nullable(),
+  }),
+  "agentConfig.daily.show": z.object({
+    date: z.string().describe("YYYY-MM-DD."),
+  }),
+
+  // Gateway: search + images + tools
+  "search.web": exaSearch,
+  "search.contents": exaContents,
+  "search.answer": exaAnswer,
+  "image.generate": imageGenerate,
+  "image.edit": imageEdit,
+  "tool.connect": composioConnect,
+  "tool.search": composioToolSearch,
+  "tool.run": composioToolRun,
+  "tool.disconnect": z.object({ connectionId: z.string() }),
+};
+
+// ---------------------------------------------------------------------------
+// Response schemas keyed by operation id (representative subset)
+// ---------------------------------------------------------------------------
+
+export const responseSchemas: Record<string, ZodTypeAny> = {
+  "crm.objects.list": z.array(crmObjectShape),
+  "crm.objects.get": crmObjectShape.nullable(),
+  "crm.objects.create": z.object({ id: z.string() }),
+  "crm.objects.update": okResponse,
+  "crm.objects.rename": okResponse,
+  "crm.objects.delete": okResponse,
+  "crm.fields.list": z.array(crmFieldShape),
+  "crm.fields.create": z.object({ id: z.string() }),
+  "crm.fields.enum.add": z.object({
+    ok: z.boolean(),
+    enumValues: z.array(z.string()),
+    enumColors: z.array(z.string()),
+    inserted: z.boolean(),
+  }),
+  "crm.fields.enum.color": z.object({
+    ok: z.boolean(),
+    enumColors: z.array(z.string()),
+  }),
+  "crm.entries.list": z.array(crmEntryShape),
+  "crm.entries.get": crmEntryShape.nullable(),
+  "crm.entries.create": z.object({ entryId: z.string() }),
+  "crm.entries.createMany": z.object({
+    results: z.array(z.object({ entryId: z.string() })),
+    count: z.number(),
+  }),
+  "crm.cells.get": cellValue,
+  "crm.aggregate": z.array(
+    z.object({
+      key: z.string(),
+      count: z.number(),
+      sumNumber: z.number().optional(),
+    }),
+  ),
+  "crm.members.list": z.object({
+    members: z.array(memberShape),
+    organizationId: z.string(),
+    organizationSlug: z.string(),
+    organizationName: z.string(),
+  }),
+  "billing.status": z.object({
+    availableCreditsCents: z.number(),
+    billedCents: z.number().optional(),
+    subscriptionStatus: z.string().optional(),
+  }),
+  "approval.request": z.object({ ok: z.boolean(), approvalId: z.string() }),
+  "memory.save": z.object({
+    ok: z.boolean(),
+    memoryId: z.string(),
+    status: z.enum(["active", "needs_review"]),
+  }),
+  "cron.create": z.object({
+    jobId: z.string(),
+    nextFireAt: z.number().optional(),
+  }),
+};
+
+// ---------------------------------------------------------------------------
+// Convex backend extras (fixedArgs / transformArgs) keyed by operation id
+// ---------------------------------------------------------------------------
+
+export type ConvexExtras = {
+  fixedArgs?: Record<string, unknown>;
+  transformArgs?: (input: Record<string, unknown>) => Record<string, unknown>;
+};
+
+export const convexExtras: Record<string, ConvexExtras> = {
+  "cron.enable": { fixedArgs: { enabled: true } },
+  "cron.disable": { fixedArgs: { enabled: false } },
+  "crm.entries.updateMany": {
+    transformArgs: (input) => {
+      const updates = Array.isArray(input.updates) ? input.updates : [];
+      return {
+        ops: updates.map((raw) => {
+          const update = (raw ?? {}) as {
+            entryId?: unknown;
+            id?: unknown;
+            data?: unknown;
+          };
+          return {
+            type: "entries.update",
+            entryId: String(update.entryId ?? update.id ?? ""),
+            data: update.data ?? {},
+          };
+        }),
+      };
+    },
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Curated request examples keyed by operation id (for playground + curl)
+// ---------------------------------------------------------------------------
+
+export const requestExamples: Record<string, unknown> = {
+  "crm.objects.create": {
+    name: "lead",
+    description: "Sales leads",
+    defaultView: "kanban",
+    icon: "target",
+  },
+  "crm.fields.create": {
+    name: "Status",
+    type: "enum",
+    enumValues: ["New", "Working", "Qualified", "Lost"],
+    enumColors: ["#94a3b8", "#3b82f6", "#22c55e", "#ef4444"],
+    indexed: true,
+  },
+  "crm.fields.enum.color": { color: "#22c55e" },
+  "crm.fields.enum.add": { value: "Nurturing", color: "#eab308", position: 2 },
+  "crm.entries.create": {
+    data: { Name: "Ada Lovelace", Email: "ada@example.com", Status: "New" },
+  },
+  "crm.entries.createMany": {
+    entries: [
+      { Name: "Jane", Email: "jane@example.com" },
+      { Name: "Bob", Email: "bob@example.com" },
+    ],
+  },
+  "crm.cells.set": { value: "In progress" },
+  "crm.query": {
+    dslJson:
+      '{"filter":{"Status":"Qualified","Score":{"$gt":50}},"sort":"-Score","limit":50}',
+  },
+  "crm.statuses.set": {
+    statuses: [
+      { name: "New", color: "#94a3b8" },
+      { name: "Working", color: "#3b82f6" },
+      { name: "Qualified", color: "#22c55e", isDefault: true },
+    ],
+  },
+  "crm.batch": {
+    ops: [
+      { type: "entries.create", objectName: "people", data: { Name: "Jane" } },
+    ],
+    idempotencyKey: "import-2026-06-01",
+  },
+  "memory.save": {
+    key: "deployment-policy",
+    kind: "decision",
+    text: "Never deploy without human approval.",
+    tags: ["deployment", "policy"],
+  },
+  "approval.request": {
+    title: "Deploy the new API branch?",
+    reason: "Production deploy changes public behavior.",
+    risk: "high",
+  },
+  "approval.decide": {
+    decision: "approved",
+    evidence: "User said yes in chat",
+  },
+  "chat.new": { prompt: "Summarize the latest CRM changes." },
+  "cron.create": {
+    name: "Daily digest",
+    prompt: "Summarize open CRM tasks.",
+    schedule: { kind: "every", everyMs: 86_400_000 },
+  },
+  "search.web": { query: "latest AI CRM workflows", numResults: 5 },
+  "image.generate": {
+    prompt: "A minimal flat-vector app icon",
+    size: "1024x1024",
+  },
+  "tool.run": {
+    tool_slug: "GMAIL_FETCH_EMAILS",
+    arguments: { max_results: 10 },
+  },
+  "crm.people.search": {
+    titles: ["Head of Sales"],
+    industries: ["SaaS"],
+    limit: 10,
+  },
+  "crm.companies.search": { domain: "example.com" },
+};