@dench.com/cli 3.6.5-staging.384 → 3.7.0-staging.387

package/email.ts

@@ -1,17 +1,20 @@
 import { createHash, createHmac, randomUUID } from "node:crypto";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { basename, extname, join } from "node:path";
-import type { ConvexHttpClient } from "convex/browser";
+import { ConvexHttpClient } from "convex/browser";
 import { makeFunctionReference } from "convex/server";
+import { EMAIL_INBOX_HELP, runEmailInboxCommand } from "./email-inbox";
 import {
   assertNoUnknownFlags,
   getFlag,
   hasFlag,
+  isHelpRequest,
   parseJson,
 } from "./lib/cli-args";
 import { denchConfigDirectory } from "./lib/config-path.mjs";
+import { waitForNativeEmail } from "./lib/native-email-wait";
 
-type EmailCliContext = {
+export type EmailCliContext = {
   convex: ConvexHttpClient;
   args: string[];
   jsonOutput: boolean;
@@ -19,9 +22,21 @@ type EmailCliContext = {
   bearerToken?: string;
   gatewayBaseUrl?: string;
   gatewayHeaders?: Record<string, string>;
+  /** Injectable read transport; it must honor the supplied observation deadline. */
+  readNativeReceipt?: (
+    draftId: string,
+    signal: AbortSignal,
+  ) => Promise<unknown>;
 };
 
-class EmailCliError extends Error {}
+class EmailCliError extends Error {
+  constructor(
+    message: string,
+    readonly code = "invalid_arguments",
+  ) {
+    super(message);
+  }
+}
 
 type JsonRecord = Record<string, unknown>;
 
@@ -48,6 +63,7 @@ function requireBearerToken(ctx: EmailCliContext): string {
   if (!token) {
     throw new EmailCliError(
       "No Dench credential found. Set DENCH_API_KEY or run `dench signin`.",
+      "login_required",
     );
   }
   return token;
@@ -59,6 +75,7 @@ async function callGateway(
   path: string,
   body?: JsonRecord,
 ) {
+  if (method === "POST") assertEmailArgs(ctx);
   const baseUrl = resolveGatewayBaseUrl(ctx);
   const response = await fetch(`${baseUrl}${path}`, {
     method,
@@ -74,6 +91,7 @@ async function callGateway(
   if (!response.ok) {
     throw new EmailCliError(
       `Email service returned ${response.status}: ${text.slice(0, 500)}`,
+      "upstream_failed",
     );
   }
   const payload = text ? JSON.parse(text) : {};
@@ -85,6 +103,7 @@ async function callMutation(
   name: string,
   args: JsonRecord,
 ) {
+  assertEmailArgs(ctx);
   const ref = makeFunctionReference<"mutation">(name);
   return await ctx.convex.mutation(ref, {
     ...args,
@@ -105,6 +124,7 @@ async function callAction(
   name: string,
   args: JsonRecord,
 ) {
+  assertEmailArgs(ctx);
   const ref = makeFunctionReference<"action">(name);
   return await ctx.convex.action(ref, {
     ...args,
@@ -362,17 +382,20 @@ function toRecipients(rows: JsonRecord[]) {
   });
 }
 
-export function emailHelp() {
-  console.log(`dench email — outbound email from a connected inbox (or Dench Emailing Service)
+export function emailHelpText() {
+  return `dench email — outbound email from a connected inbox (or Dench Emailing Service)
 
 Usage:
+${EMAIL_INBOX_HELP}
   dench email draft create --to <email> --subject <subject> --text <body> [--mailbox <id/email>] [--request-id <id>] [--json]
   dench email draft show <id> [--json]
-  dench email draft update|send <id> --revision <n> [--json]
+  dench email draft update <id> --revision <n> [--to <email>] [--subject <subject>] [--text <body>] [--mailbox <id>] [--json]
+  dench email draft send <id> --revision <n> [--request-id <id>] [--wait <seconds>|--no-wait] [--json]
+  dench email draft senders [--json]  # available Gmail/Outlook mailboxes
   dench email draft attach <id> --revision <n> --file <path> [--content-type <mime>] [--json]  # up to 5 MB/file
   dench email draft signature <id> [--json]  # read signature HTML; insert visibly into the body
   # Identical native create/send invocations reuse a saved request ID. Use --request-id <new-id> for another identical email.
-  dench email send --mailbox <id/email> --to <email> --subject <subject> --text <body> [--request-id <id>] [--json]
+  dench email send --to <email> [--subject <subject>] (--text <body> | --html <body> | --text-file <path> | --html-file <path>) [--mailbox <id/email>] [--cc <emails>] [--bcc <emails>] [--request-id <id>] [--wait <seconds>|--no-wait] [--json]  # native default; observe the same receipt for 10s by default (--wait 0..60)
   dench email identity verify --from founder@example.com [--private] [--json]
   dench email identity verify --domain example.com [--from founder@example.com] [--private] [--json]
   dench email identity list [--domain example.com] [--json]
@@ -443,10 +466,15 @@ Email + LinkedIn multichannel sequences (see \`dench campaign\` — the fuller s
   dench email multichannel enroll-from-object --sequence <id> --object lead --entries id1,id2 [--email-field Email] [--linkedin-field "POC LinkedIn URL"] [--relation-field Contact] [--reverse] [--allow-duplicates] [--json]
   dench email multichannel launch --sequence <id> [--ack-linkedin-risk] [--json]
   dench email multichannel pause|resume|archive --sequence <id> [--json]
-  (see \`dench campaign help\` for the same campaigns with schedule, view-based add, launch checks and the Now/Next feed)`);
+  (see \`dench campaign help\` for the same campaigns with schedule, view-based add, launch checks and the Now/Next feed)`;
 }
 
 export async function runEmailCommand(ctx: EmailCliContext): Promise<void> {
+  if (isHelpRequest(ctx.args)) {
+    const { commandHelp } = await import("./lib/command-help");
+    console.log(commandHelp(["email", ...ctx.args], emailHelpText()));
+    return;
+  }
   ctx.args = ctx.args.flatMap((arg) => {
     const split = arg.startsWith("--") ? arg.indexOf("=") : -1;
     return split > 2 ? [arg.slice(0, split), arg.slice(split + 1)] : [arg];
@@ -454,7 +482,11 @@ export async function runEmailCommand(ctx: EmailCliContext): Promise<void> {
   ctx.jsonOutput = hasFlag(ctx.args, "--json") || ctx.jsonOutput;
   const group = ctx.args.shift();
   if (!group || group === "help" || group === "--help" || group === "-h") {
-    emailHelp();
+    console.log(emailHelpText());
+    return;
+  }
+  if (group === "inbox") {
+    await runEmailInboxCommand(ctx);
     return;
   }
   if (group === "draft") {
@@ -524,14 +556,20 @@ function parseAddressList(
 }
 
 async function runSend(ctx: EmailCliContext) {
-  if (ctx.args.includes("--mailbox")) {
+  const wait = waitFlag(ctx.args);
+  if (!ctx.args.includes("--from")) {
     const content = {
       ...(await draftContent(ctx)),
-      mailbox: requiredFlag(ctx.args, "--mailbox"),
+      mailbox: getFlag(ctx.args, "--mailbox"),
       threadId: getFlag(ctx.args, "--thread") ?? process.env.DENCH_THREAD_ID,
       mode: "send",
     };
-    const payload = await createNativeEmail(ctx, content);
+    if (!Array.isArray(content.to) || content.to.length === 0)
+      throw new EmailCliError("Sending requires --to <email>");
+    const created = await createNativeEmail(ctx, content);
+    const payload = wait
+      ? await observeNativeEmail(ctx, created, wait)
+      : created;
     out(ctx, payload, JSON.stringify(payload, null, 2));
     return;
   }
@@ -575,6 +613,50 @@ async function runSend(ctx: EmailCliContext) {
   );
 }
 
+function waitFlag(args: string[]): number {
+  const noWait = hasFlag(args, "--no-wait");
+  const raw = getFlag(args, "--wait");
+  if (raw !== undefined && noWait)
+    throw new EmailCliError("Use --wait or --no-wait, not both");
+  const seconds = raw === undefined ? 10 : Number(raw);
+  if (
+    raw?.trim() === "" ||
+    !Number.isFinite(seconds) ||
+    seconds < 0 ||
+    seconds > 60
+  )
+    throw new EmailCliError(
+      "--wait must be a finite number of seconds from 0 to 60",
+    );
+  return noWait ? 0 : seconds * 1000;
+}
+
+function observeNativeEmail(
+  ctx: EmailCliContext,
+  receipt: unknown,
+  waitMs: number,
+) {
+  return waitForNativeEmail(
+    receipt,
+    ctx.readNativeReceipt ??
+      ((draftId, signal) => {
+        const reader = new ConvexHttpClient(ctx.convex.url, {
+          logger: false,
+          fetch: new Proxy(fetch, {
+            apply(target, _receiver, [input, init]) {
+              return target(input, { ...init, signal });
+            },
+          }),
+        });
+        return reader.query(
+          makeFunctionReference<"query">("functions/emailDrafts:get"),
+          { draftId, sessionToken: ctx.sessionToken },
+        );
+      }),
+    waitMs,
+  );
+}
+
 /** Persist before HTTP. Identical invocations recover the same request even
  * after the CLI process dies; an explicit new --request-id starts another email. */
 async function createNativeEmail(ctx: EmailCliContext, content: JsonRecord) {
@@ -615,7 +697,7 @@ async function createNativeEmail(ctx: EmailCliContext, content: JsonRecord) {
 }
 
 function assertEmailArgs(ctx: EmailCliContext) {
-  assertNoUnknownFlags(ctx.args, "dench email");
+  assertNoUnknownFlags(ctx.args, "email");
   if (ctx.args.length)
     throw new EmailCliError(`Unexpected argument: ${ctx.args[0]}`);
 }
@@ -671,6 +753,7 @@ async function runDraft(ctx: EmailCliContext) {
             draftId,
           });
   } else if (sub === "update" || sub === "send") {
+    const wait = sub === "send" ? waitFlag(ctx.args) : 0;
     const draftId = draftIdArg(ctx);
     const expectedRevision = revisionArg(ctx);
     const args =
@@ -690,6 +773,7 @@ async function runDraft(ctx: EmailCliContext) {
           };
     assertEmailArgs(ctx);
     result = await callMutation(ctx, `functions/emailDrafts:${sub}`, args);
+    if (wait) result = await observeNativeEmail(ctx, result, wait);
   } else if (sub === "attach") {
     const draftId = draftIdArg(ctx);
     const expectedRevision = revisionArg(ctx);
@@ -1146,6 +1230,8 @@ async function runCampaign(ctx: EmailCliContext) {
   const sub = ctx.args.shift();
   if (sub === "create") {
     const sender = await campaignSenderArgs(ctx);
+    const scheduledAt = getFlag(ctx.args, "--scheduled-at");
+    const maxRecipients = getFlag(ctx.args, "--max-recipients");
     const payload = await callMutation(
       ctx,
       "functions/emailCampaigns:createCampaign",
@@ -1153,12 +1239,8 @@ async function runCampaign(ctx: EmailCliContext) {
         name: requiredFlag(ctx.args, "--name"),
         ...sender,
         templateId: requiredFlag(ctx.args, "--template"),
-        scheduledAt: getFlag(ctx.args, "--scheduled-at")
-          ? Date.parse(requiredFlag(ctx.args, "--scheduled-at"))
-          : undefined,
-        maxRecipients: getFlag(ctx.args, "--max-recipients")
-          ? Number(requiredFlag(ctx.args, "--max-recipients"))
-          : undefined,
+        scheduledAt: scheduledAt ? Date.parse(scheduledAt) : undefined,
+        maxRecipients: maxRecipients ? Number(maxRecipients) : undefined,
       },
     );
     out(
@@ -1377,7 +1459,7 @@ async function runSequence(ctx: EmailCliContext) {
         ...sender,
         replyToMode: getFlag(ctx.args, "--reply-to-mode"),
         stopOnReply,
-        stopOnClick: getFlag(ctx.args, "--stop-on-click") !== undefined,
+        stopOnClick: hasFlag(ctx.args, "--stop-on-click"),
       },
     );
     out(
@@ -1426,7 +1508,7 @@ async function runSequence(ctx: EmailCliContext) {
     const payload = await callQuery(
       ctx,
       "functions/emailSequences:listSequences",
-      { includeArchived: getFlag(ctx.args, "--all") !== undefined },
+      { includeArchived: hasFlag(ctx.args, "--all") },
     );
     out(ctx, payload, JSON.stringify(payload, null, 2));
     return;

package/lib/api-schemas.ts

@@ -57,6 +57,48 @@ const nativeEmailCreate = z.object({
   requestId: z.string(),
   ...nativeEmailContent,
 });
+const inboxHeader = z.object({
+  messageHandle: z.string(),
+  threadHandle: z.string(),
+  mailboxId: z.string(),
+  from: nativeEmailRecipient,
+  to: z.array(nativeEmailRecipient),
+  subject: z.string(),
+  at: z.number(),
+  dateSource: z.enum(["sentAt", "createdAt"]),
+  direction: z.enum(["inbound", "outbound"]),
+  status: z.string(),
+  hasAttachments: z.boolean(),
+  headersTruncated: z.boolean(),
+});
+const inboxCoverage = z.object({
+  source: z.literal("synced"),
+  scope: z.literal("mailbox_linked_messages"),
+  mailboxId: z.string(),
+  mailboxEmail: z.string(),
+  mailboxStatus: z.string(),
+  ingestionMode: z.string(),
+  phase: z.string(),
+  syncStatus: z.string().nullable(),
+  lastPolledAt: z.number().nullable(),
+  lastBackfillCompletedAt: z.number().nullable(),
+  oldestSeenAt: z.number().nullable(),
+  backfillStatus: z.string().nullable(),
+  backfillCapped: z.boolean(),
+  providerComplete: z.literal(false),
+  privacyLimited: z.boolean(),
+});
+const inboxPaging = {
+  limit: z.coerce.number().int().min(1).max(50).optional(),
+  cursor: z.string().optional(),
+};
+const inboxPage = z.object({
+  page: z.array(inboxHeader),
+  continueCursor: z.string().nullable(),
+  isDone: z.boolean(),
+  coverage: inboxCoverage,
+  order: z.literal("sentAt_desc_then_undated"),
+});
 const nativeEmailReceipt = z
   .object({
     ok: z.boolean(),
@@ -2118,7 +2160,7 @@ const composioToolRun = z.object({
   tool_slug: z
     .string()
     .optional()
-    .describe("Tool slug, e.g. GMAIL_FETCH_EMAILS."),
+    .describe("Tool slug, e.g. SLACK_LIST_CHANNELS."),
   arguments: z
     .record(z.string(), z.unknown())
     .optional()
@@ -3392,8 +3434,34 @@ export const requestSchemas: Record<string, ZodTypeAny> = {
       )
       .optional(),
   }),
+  "email.inbox.search": z.object({
+    ...inboxPaging,
+    mailbox: z.string().optional(),
+    from: z.string().min(1).max(500).optional(),
+    to: z.string().min(1).max(500).optional(),
+    subject: z.string().min(1).max(500).optional(),
+    after: z.coerce
+      .number()
+      .optional()
+      .describe(
+        "Inclusive Unix milliseconds; missing sentAt falls back to createdAt.",
+      ),
+    before: z.coerce
+      .number()
+      .optional()
+      .describe("Exclusive Unix milliseconds."),
+    direction: z.enum(["inbound", "outbound"]).optional(),
+  }),
+  "email.inbox.thread": z.object({ ...inboxPaging, threadHandle: z.string() }),
+  "email.inbox.message": z.object({
+    messageHandle: z.string(),
+    format: z.enum(["text", "html"]).optional(),
+    maxBytes: z.coerce.number().int().min(1).max(100000).optional(),
+  }),
   "email.drafts.create": nativeEmailCreate,
-  "email.native.send": nativeEmailCreate,
+  "email.native.send": nativeEmailCreate.extend({
+    to: z.array(nativeEmailRecipient).min(1),
+  }),
   "email.drafts.get": z.object({ draftId: z.string() }),
   "email.drafts.senders": z.object({ organizationId: z.string().optional() }),
   "email.drafts.update": z.object({
@@ -3536,6 +3604,7 @@ export const requestSchemas: Record<string, ZodTypeAny> = {
 
   // CRM objects
   "crm.objects.list": noInput,
+  "crm.objects.listCompact": noInput,
   "crm.objects.get": z.object({ name: z.string() }),
   "crm.objects.create": z.object({
     name: z.string().describe("Object name (lowercased, singular)."),
@@ -3631,6 +3700,7 @@ export const requestSchemas: Record<string, ZodTypeAny> = {
 
   // CRM fields
   "crm.fields.list": z.object({ objectName: z.string() }),
+  "crm.fields.listCompact": z.object({ objectName: z.string() }),
   "crm.fields.create": z.object({
     objectName: z.string(),
     name: z.string(),
@@ -4163,6 +4233,18 @@ export const requestSchemas: Record<string, ZodTypeAny> = {
         "Number field to total per bucket (e.g. Amount grouped by Stage). Exact at any table size.",
       ),
   }),
+  "crm.search.page": z.object({
+    text: z.string().describe("Full-text query over readable entries."),
+    objectName: z.string().optional(),
+    select: z.array(z.string().min(1)).min(1).max(30).optional(),
+    limit: z.coerce.number().int().min(1).max(100).optional(),
+    cursor: z
+      .string()
+      .optional()
+      .describe(
+        "Use the preceding continueCursor, with the same query and projection.",
+      ),
+  }),
   "crm.search": z.object({
     text: z.string().describe("Full-text query."),
     objectName: z.string().optional().describe("Omit to search org-wide."),
@@ -5157,6 +5239,24 @@ export const responseSchemas: Record<string, ZodTypeAny> = {
 
   // Workspace orientation
   "workspace.context.sections": z.object({}).passthrough(),
+  "email.inbox.search": inboxPage,
+  "email.inbox.thread": inboxPage,
+  "email.inbox.message": z.object({
+    header: inboxHeader,
+    coverage: inboxCoverage,
+    body: z.object({
+      format: z.enum(["text", "html"]),
+      content: z.string(),
+      truncated: z.boolean(),
+      totalBytes: z.number(),
+    }),
+    recipients: z.object({
+      to: z.array(nativeEmailRecipient),
+      cc: z.array(nativeEmailRecipient),
+      bcc: z.array(nativeEmailRecipient),
+      truncated: z.boolean(),
+    }),
+  }),
   "email.drafts.create": nativeEmailReceipt,
   "email.drafts.get": nativeEmailReceipt,
   "email.drafts.update": nativeEmailReceipt,
@@ -5283,6 +5383,18 @@ export const responseSchemas: Record<string, ZodTypeAny> = {
 
   // CRM objects
   "crm.objects.list": z.array(crmObjectDoc),
+  "crm.objects.listCompact": z.array(
+    z.object({
+      _id: z.string(),
+      name: z.string(),
+      displayName: z.string(),
+      description: z.string().optional(),
+      entryCount: z.number().nullable(),
+      countScope: z.enum(["workspace", "private_unknown"]),
+      visibility: z.enum(["workspace", "owner_only", "owner_plus_members"]),
+      archived: z.boolean(),
+    }),
+  ),
   "crm.objects.get": crmObjectDoc.nullable(),
   "crm.objects.create": z.object({ id: z.string() }),
   "crm.objects.update": okResponse,
@@ -5337,6 +5449,20 @@ export const responseSchemas: Record<string, ZodTypeAny> = {
 
   // CRM fields
   "crm.fields.list": z.array(crmFieldDoc),
+  "crm.fields.listCompact": z.array(
+    z.object({
+      _id: z.string(),
+      name: z.string(),
+      type: z.string(),
+      required: z.boolean(),
+      readOnly: z.boolean(),
+      defaultValue: z.string().optional(),
+      enumValues: z.array(z.string()).optional(),
+      enumMultiple: z.boolean(),
+      relatedObjectId: z.string().optional(),
+      relationshipType: z.string().optional(),
+    }),
+  ),
   "crm.fields.create": z.object({ id: z.string() }),
   "crm.fields.update": okResponse,
   "crm.fields.delete": okResponse,
@@ -5493,6 +5619,16 @@ export const responseSchemas: Record<string, ZodTypeAny> = {
       sumNumber: z.number().optional(),
     }),
   ),
+  "crm.search.page": z.object({
+    page: z.array(
+      z.object({ _id: z.string(), objectId: z.string(), data: fieldsMap }),
+    ),
+    isDone: z.boolean(),
+    continueCursor: z.string().nullable(),
+    returnedCount: z.number(),
+    selectedFields: z.array(z.string()).nullable(),
+    completeness: z.literal("page"),
+  }),
   "crm.search": z.array(
     z
       .object({
@@ -6217,6 +6353,12 @@ export const convexExtras: Record<string, ConvexExtras> = {
 // ---------------------------------------------------------------------------
 
 export const requestExamples: Record<string, unknown> = {
+  "email.native.send": {
+    requestId: "send-intro-001",
+    to: [{ email: "ada@example.com", name: "Ada" }],
+    subject: "Introduction",
+    textBody: "Hello Ada",
+  },
   "campaigns.accounts.linkedin": {},
   "campaigns.create": {
     name: "Founder outreach",
@@ -6470,11 +6612,11 @@ export const requestExamples: Record<string, unknown> = {
     input_images_base64: ["iVBORw0KGgoAAAANSUhEUg..."],
   },
   "tool.search": {
-    queries: [{ use_case: "fetch the 10 most recent emails" }],
+    queries: [{ use_case: "list Slack channels" }],
   },
   "tool.run": {
-    tool_slug: "GMAIL_FETCH_EMAILS",
-    arguments: { max_results: 10 },
+    tool_slug: "SLACK_LIST_CHANNELS",
+    arguments: { limit: 10 },
   },
   "crm.people.search": {
     titles: ["Head of Sales"],
@@ -8019,18 +8161,18 @@ export const responseExamples: Record<string, unknown> = {
     error: null,
     results: [
       {
-        use_case: "fetch recent emails",
-        primary_tool_slugs: ["GMAIL_FETCH_EMAILS"],
-        toolkits: ["gmail"],
+        use_case: "list Slack channels",
+        primary_tool_slugs: ["SLACK_LIST_CHANNELS"],
+        toolkits: ["slack"],
       },
     ],
     toolkit_connection_statuses: [
-      { toolkit: "gmail", has_active_connection: true },
+      { toolkit: "slack", has_active_connection: true },
     ],
     tool_schemas: {
-      GMAIL_FETCH_EMAILS: {
-        toolkit: "gmail",
-        tool_slug: "GMAIL_FETCH_EMAILS",
+      SLACK_LIST_CHANNELS: {
+        toolkit: "slack",
+        tool_slug: "SLACK_LIST_CHANNELS",
         execution_ref: "eyJzZXNzaW9uIjoi...",
         execution_ref_version: 1,
       },
@@ -8039,11 +8181,11 @@ export const responseExamples: Record<string, unknown> = {
     execution_ref_version: 1,
   },
   "tool.run": {
-    data: { messages: [{ id: "msg01", subject: "Quick intro" }] },
+    data: { channels: [{ id: "C_EXAMPLE", name: "general" }] },
     error: null,
     log_id: "log_exec_01",
     execution_mode: "gateway_tool_router",
-    tool_slug: "GMAIL_FETCH_EMAILS",
+    tool_slug: "SLACK_LIST_CHANNELS",
     tool_router_session_id: "trs_abc123",
   },
   "tool.disconnect": { id: "ca_github01", deleted: true },

package/lib/app-sdk-catalog.generated.ts

@@ -141,6 +141,7 @@ export const APP_SDK_OPERATIONS: readonly AppSdkOperationInfo[] = [
   {"id":"chat.send","group":"chat","summary":"Send a message to an existing chat thread.","cli":"dench chat send","method":"POST","path":"/chat/threads/{threadId}/messages","permission":"ai:chat","pathParams":["threadId"]},
   {"id":"chat.follow","group":"chat","summary":"Follow a live chat response stream.","cli":"dench chat follow","method":"GET","path":"/chat/threads/{threadId}/stream","permission":"ai:chat","pathParams":["threadId"]},
   {"id":"crm.objects.list","group":"crm","summary":"List CRM objects.","cli":"dench crm objects list","method":"GET","path":"/crm/objects","permission":"crm:read","pathParams":[]},
+  {"id":"crm.objects.listCompact","group":"crm","summary":"List names, display labels, visibility and workspace counts without internal state.","cli":"dench crm objects list --compact","method":"GET","path":"/crm/catalog/objects","permission":"crm:read","pathParams":[]},
   {"id":"crm.objects.get","group":"crm","summary":"Get a CRM object.","cli":"dench crm objects get","method":"GET","path":"/crm/objects/{name}","permission":"crm:read","pathParams":["name"]},
   {"id":"crm.objects.create","group":"crm","summary":"Create a CRM object.","cli":"dench crm objects create","method":"POST","path":"/crm/objects","permission":"crm:write","pathParams":[]},
   {"id":"crm.objects.update","group":"crm","summary":"Update a CRM object.","cli":"dench crm objects update","method":"PATCH","path":"/crm/objects/{name}","permission":"crm:write","pathParams":["name"]},
@@ -165,6 +166,7 @@ export const APP_SDK_OPERATIONS: readonly AppSdkOperationInfo[] = [
   {"id":"crm.sidebar.groups.move-item","group":"crm","summary":"Move a sidebar row into a group (groupId set) or back to the top level (groupId null). Open to any member.","cli":"dench crm sidebar group add","method":"POST","path":"/crm/sidebar/groups/move","permission":"crm:write","pathParams":[]},
   {"id":"crm.sidebar.pins.set","group":"crm","summary":"Pin (pinned true) or unpin a Library row — or a whole group — on the home-level Pinned shortcut strip (the \"tab on the left\"). Does not move the row inside Library. Workspace-shared; open to any member.","cli":"dench crm sidebar pin","method":"POST","path":"/crm/sidebar/pins","permission":"crm:write","pathParams":[]},
   {"id":"crm.fields.list","group":"crm","summary":"List fields for a CRM object, including read-only calculation metadata.","cli":"dench crm fields list","method":"GET","path":"/crm/objects/{objectName}/fields","permission":"crm:read","pathParams":["objectName"]},
+  {"id":"crm.fields.listCompact","group":"crm","summary":"List field names, types and effective constraints without indexing or enrichment internals.","cli":"dench crm fields list --compact","method":"GET","path":"/crm/catalog/objects/{objectName}/fields","permission":"crm:read","pathParams":["objectName"]},
   {"id":"crm.fields.create","group":"crm","summary":"Create a CRM field or read-only campaign activity boolean column.","cli":"dench crm fields create","method":"POST","path":"/crm/objects/{objectName}/fields","permission":"crm:write","pathParams":["objectName"]},
   {"id":"crm.fields.update","group":"crm","summary":"Update a CRM field or change/explicitly clear an existing campaign calculation.","cli":"dench crm fields update","method":"PATCH","path":"/crm/objects/{objectName}/fields/{fieldName}","permission":"crm:write","pathParams":["objectName","fieldName"]},
   {"id":"crm.fields.delete","group":"crm","summary":"Delete a CRM field.","cli":"dench crm fields delete","method":"DELETE","path":"/crm/objects/{objectName}/fields/{fieldName}","permission":"crm:write","pathParams":["objectName","fieldName"]},
@@ -237,6 +239,7 @@ export const APP_SDK_OPERATIONS: readonly AppSdkOperationInfo[] = [
   {"id":"crm.sql","group":"crm","summary":"Run CRM SQL-compatible query.","cli":"dench crm sql","method":"POST","path":"/crm/sql","permission":"crm:read","pathParams":[]},
   {"id":"crm.aggregate","group":"crm","summary":"Aggregate CRM entries.","cli":"dench crm aggregate","method":"POST","path":"/crm/aggregate","permission":"crm:read","pathParams":[]},
   {"id":"crm.search","group":"crm","summary":"Search CRM entries.","cli":"dench crm search","method":"GET","path":"/crm/search","permission":"crm:read","pathParams":[]},
+  {"id":"crm.search.page","group":"crm","summary":"Search bounded pages of readable CRM entries, optionally projecting cells. Always follow continueCursor until isDone.","cli":"dench crm search --page","method":"GET","path":"/crm/search/page","permission":"crm:read","pathParams":[]},
   {"id":"crm.statuses.list","group":"crm","summary":"List CRM statuses.","cli":"dench crm statuses list","method":"GET","path":"/crm/objects/{objectName}/statuses","permission":"crm:read","pathParams":["objectName"]},
   {"id":"crm.statuses.set","group":"crm","summary":"Set CRM statuses.","cli":"dench crm statuses set","method":"PUT","path":"/crm/objects/{objectName}/statuses","permission":"crm:write","pathParams":["objectName"]},
   {"id":"crm.batch","group":"crm","summary":"Apply a CRM batch.","cli":"dench crm batch","method":"POST","path":"/crm/batch","permission":"crm:write","pathParams":[]},
@@ -315,6 +318,9 @@ export const APP_SDK_OPERATIONS: readonly AppSdkOperationInfo[] = [
   {"id":"email.identity.disable","group":"email","summary":"Soft-disable a sender (or every sender on a domain) for the workspace; sends are blocked until restored.","cli":"dench email identity disable","method":"POST","path":"/email/sending-identities/{identity}/disable","permission":"email:write","pathParams":["identity"]},
   {"id":"email.identity.restore","group":"email","summary":"Restore a previously disabled sender for the workspace.","cli":"dench email identity restore","method":"POST","path":"/email/sending-identities/{identity}/restore","permission":"email:write","pathParams":["identity"]},
   {"id":"email.identity.delete","group":"email","summary":"Permanently delete a sender (or every sender on a domain) from the workspace; re-adding it requires verification from scratch.","cli":"dench email identity delete","method":"DELETE","path":"/email/sending-identities/{identity}","permission":"email:write","pathParams":["identity"]},
+  {"id":"email.inbox.search","group":"email","summary":"Search authorized synced mailbox headers with bounded cursor pagination. isDone covers stored records, not provider completeness.","cli":"dench email inbox search","method":"GET","path":"/email/inbox/search","permission":"email:read","pathParams":[]},
+  {"id":"email.inbox.thread","group":"email","summary":"Read a bounded page of synced headers using an exact thread handle from inbox search; bodies remain on demand.","cli":"dench email inbox thread","method":"GET","path":"/email/inbox/threads/{threadHandle}","permission":"email:read","pathParams":["threadHandle"]},
+  {"id":"email.inbox.message","group":"email","summary":"Read a bounded stored body using an exact message handle from inbox search; rechecks mailbox and record privacy.","cli":"dench email inbox message","method":"GET","path":"/email/inbox/messages/{messageHandle}","permission":"email:read","pathParams":["messageHandle"]},
   {"id":"email.drafts.create","group":"email","summary":"Create an editable Dench email draft and synchronize its selected native mailbox asynchronously. Use a stable requestId for retries.","cli":"dench email draft create","method":"POST","path":"/email/drafts","permission":"email:write","pathParams":[]},
   {"id":"email.drafts.get","group":"email","summary":"Read an email draft, eligible senders and provider sync status.","cli":"dench email draft show","method":"GET","path":"/email/drafts/{draftId}","permission":"email:read","pathParams":["draftId"]},
   {"id":"email.drafts.senders","group":"email","summary":"List native mailboxes this caller may use.","cli":"dench email draft senders","method":"GET","path":"/email/drafts/senders","permission":"email:read","pathParams":[]},
@@ -322,8 +328,8 @@ export const APP_SDK_OPERATIONS: readonly AppSdkOperationInfo[] = [
   {"id":"email.drafts.send","group":"email","summary":"Send the current Dench draft revision through its native mailbox. Repeated requests share a durable receipt.","cli":"dench email draft send","method":"POST","path":"/email/drafts/{draftId}/send","permission":"email:write","pathParams":["draftId"]},
   {"id":"email.drafts.upload","group":"email","summary":"Upload attachment bytes authorized against this draft before adding its storage reference.","cli":"dench email draft attach","method":"POST","path":"/email/drafts/{draftId}/attachments","permission":"email:write","pathParams":["draftId"]},
   {"id":"email.drafts.signature","group":"email","summary":"Load the selected mailbox signature for explicit visible insertion.","cli":"dench email draft signature","method":"GET","path":"/email/drafts/{draftId}/signature","permission":"email:read","pathParams":["draftId"]},
-  {"id":"email.native.send","group":"email","summary":"Send through a native Gmail or Outlook mailbox with a durable request receipt. Only use for an explicit send request.","cli":"dench email send --mailbox","method":"POST","path":"/email/native/send","permission":"email:write","pathParams":[]},
-  {"id":"email.send","group":"email","summary":"Send one raw email (no campaign): to/cc/bcc, custom from-name and reply-to, optional reply threading via replyToMessageId.","cli":"dench email send","method":"POST","path":"/email/send","permission":"email:write","pathParams":[]},
+  {"id":"email.native.send","group":"email","summary":"Send through a native Gmail or Outlook mailbox with a durable request receipt. Only use for an explicit send request.","cli":"dench email send [--mailbox <id/email>]","method":"POST","path":"/email/native/send","permission":"email:write","pathParams":[]},
+  {"id":"email.send","group":"email","summary":"Send one raw email (no campaign): to/cc/bcc, custom from-name and reply-to, optional reply threading via replyToMessageId.","cli":"dench email send --from <verified-email>","method":"POST","path":"/email/send","permission":"email:write","pathParams":[]},
   {"id":"email.message.get","group":"email","summary":"Read a raw email message's status and open/click counters.","cli":"dench email message status","method":"GET","path":"/email/messages/{messageId}","permission":"email:read","pathParams":["messageId"]},
   {"id":"email.message.list","group":"email","summary":"List recent raw email messages for the workspace.","cli":"dench email message list","method":"GET","path":"/email/messages","permission":"email:read","pathParams":[]},
   {"id":"email.template.create","group":"email","summary":"Create a managed email campaign template.","cli":"dench email template create","method":"POST","path":"/email/templates","permission":"email:write","pathParams":[]},
@@ -459,7 +465,7 @@ export const APP_SDK_OPERATIONS: readonly AppSdkOperationInfo[] = [
   {"id":"agentConfig.user.show","group":"agent-config","summary":"Read USER.md.","cli":"dench user show","method":"GET","path":"/agent-config/user","permission":"agent-config:read","pathParams":[]},
   {"id":"agentConfig.user.edit","group":"agent-config","summary":"Update USER.md.","cli":"dench user edit","method":"PUT","path":"/agent-config/user","permission":"agent-config:write","pathParams":[]},
   {"id":"agentConfig.tools.show","group":"agent-config","summary":"Read tool notes.","cli":"dench tools show","method":"GET","path":"/agent-config/tools","permission":"agent-config:read","pathParams":[]},
-  {"id":"agentConfig.tools.edit","group":"agent-config","summary":"Update tool notes.","cli":"dench tools notes-edit","method":"PUT","path":"/agent-config/tools","permission":"agent-config:write","pathParams":[]},
+  {"id":"agentConfig.tools.edit","group":"agent-config","summary":"Update tool notes.","cli":"dench tools edit","method":"PUT","path":"/agent-config/tools","permission":"agent-config:write","pathParams":[]},
   {"id":"agentConfig.mem.show","group":"agent-config","summary":"Read aggregate memory.","cli":"dench mem show","method":"GET","path":"/agent-config/mem","permission":"agent-config:read","pathParams":[]},
   {"id":"agentConfig.mem.edit","group":"agent-config","summary":"Update aggregate memory.","cli":"dench mem set","method":"PUT","path":"/agent-config/mem","permission":"agent-config:write","pathParams":[]},
   {"id":"agentConfig.bootstrap.show","group":"agent-config","summary":"Read bootstrap state.","cli":"dench bootstrap status","method":"GET","path":"/agent-config/bootstrap","permission":"agent-config:read","pathParams":[]},

package/lib/bundled-references.ts

@@ -0,0 +1,17 @@
+import bundle from "./references.generated.json";
+
+export const referenceRevision = bundle.revision;
+const files: Record<string, { sha256: string; content: string }> = bundle.files;
+export function getBundledReference(path: string): string | undefined {
+  return Object.hasOwn(files, path) ? files[path].content : undefined;
+}
+export function bundledReferenceIndex() {
+  return {
+    revision: referenceRevision,
+    references: Object.entries(files).map(([path, file]) => ({
+      path,
+      sha256: file.sha256,
+      bytes: new TextEncoder().encode(file.content).byteLength,
+    })),
+  };
+}