@dench.com/cli 3.6.4-staging.377 → 3.6.6-staging.386

package/README.md

@@ -465,3 +465,19 @@ Commands that need to impersonate a specific agent (`dench memory`,
 (`dench signin`) — the unified API key is org-scoped and cannot speak
 as a single agent. Those commands return a clear "agent session
 required" error in API-key mode.
+
+### Focused workspace context
+
+`dench context --instructions` reads explicit IDENTITY, RULES and TOOLS notes,
+plus document availability/revisions. It does not load business profiles,
+personal profiles or aggregate memory. Fetch only what the task needs:
+
+```sh
+dench context --sections organisation,user,memory --json
+```
+
+Section names are `identity`, `organisation`, `user`, `memory`, `rules`, and
+`tools`. Multiple names use one query. The existing `organisation show`,
+`user show`, and `mem show` commands use the same saved documents; reading never
+fills profiles or writes memory. Personal USER context is unavailable to shared
+channel sessions. `dench context --json` keeps its existing workspace overview.

package/agent-config.ts

@@ -215,22 +215,16 @@ async function handleSimpleMagicFile(
 ): Promise<void> {
   const sub = args[0];
   if (!sub || sub === "show") {
-    const config = await loadAgentConfig(ctx);
-    const value =
-      opts.field === "memoryAggregate"
-        ? config.agentConfig.memoryAggregate
-        : opts.field === "toolsNotes"
-          ? config.agentConfig.toolsNotes
-          : opts.field === "identity"
-            ? config.agentConfig.identity
-            : opts.field === "organisation"
-              ? config.agentConfig.organisation
-              : null;
-    if (opts.perMember) {
-      out(ctx, config.userProfile?.content ?? "(empty)");
-      return;
-    }
-    out(ctx, value?.content ?? "(empty)");
+    const context = (await runQuery(
+      ctx,
+      makeFunctionReference<"query">("functions/agentConfig:workspaceContext"),
+      { sections: [opts.label] },
+    )) as { documents: Array<{ name: string; content?: string }> };
+    out(
+      ctx,
+      context.documents.find((document) => document.name === opts.label)
+        ?.content || "(empty)",
+    );
     return;
   }
   if (sub === "edit" || sub === "set") {

package/app-sdk.d.ts

@@ -497,10 +497,17 @@ export interface ApiRequests {
     organizationId?: string;
     newOrganizationName?: string;
   };
+  /** Read selected scoped workspace documents and a compact context index without writes. — `dench context --sections` — GET /api/v1/context/sections */
+  "workspace.context.sections": {
+    organizationId?: string;
+    sections?: Array<"identity" | "organisation" | "user" | "memory" | "rules" | "tools">;
+  };
   /** Return the current Dench workspace context for the bearer. — `dench context` — GET /api/v1/context */
   "workspace.context": Record<string, unknown>;
   /** Return the current workspace's standing instructions for external agents. — `dench context --instructions` — GET /api/v1/context/instructions */
-  "workspace.instructions": Record<string, unknown>;
+  "workspace.instructions": {
+    organizationId?: string;
+  };
   /** Return workspace and agent status. — `dench status` — GET /api/v1/status */
   "workspace.status": Record<string, unknown>;
   /** List agents visible in the workspace status payload. — `dench agents` — GET /api/v1/agents */
@@ -2172,6 +2179,116 @@ export interface ApiRequests {
     /** Identity id, sender email, or domain (deletes every sender on the domain). Permanent: re-adding requires re-verification. */
     identity: string;
   };
+  /** Create an editable Dench email draft and synchronize its selected native mailbox asynchronously. Use a stable requestId for retries. — `dench email draft create` — POST /api/v1/email/drafts */
+  "email.drafts.create": {
+    organizationId?: string;
+    threadId?: string;
+    mailbox?: string;
+    requestId: string;
+    to?: {
+      email: string;
+      name?: string;
+    }[];
+    cc?: {
+      email: string;
+      name?: string;
+    }[];
+    bcc?: {
+      email: string;
+      name?: string;
+    }[];
+    subject?: string;
+    htmlBody?: string;
+    textBody?: string;
+    attachments?: {
+      storageId: string;
+      name: string;
+      contentType: string;
+      size: number;
+    }[];
+  };
+  /** Read an email draft, eligible senders and provider sync status. — `dench email draft show` — GET /api/v1/email/drafts/{draftId} */
+  "email.drafts.get": {
+    draftId: string;
+  };
+  /** List native mailboxes this caller may use. — `dench email draft senders` — GET /api/v1/email/drafts/senders */
+  "email.drafts.senders": {
+    organizationId?: string;
+  };
+  /** Save draft content using expectedRevision; sender changes require a new draft after provider binding. — `dench email draft update` — PATCH /api/v1/email/drafts/{draftId} */
+  "email.drafts.update": {
+    draftId: string;
+    expectedRevision: number;
+    patch: {
+      mailboxAccountId?: string;
+      to?: {
+        email: string;
+        name?: string;
+      }[];
+      cc?: {
+        email: string;
+        name?: string;
+      }[];
+      bcc?: {
+        email: string;
+        name?: string;
+      }[];
+      subject?: string;
+      htmlBody?: string;
+      textBody?: string;
+      attachments?: {
+        storageId: string;
+        name: string;
+        contentType: string;
+        size: number;
+      }[];
+    };
+  };
+  /** Send the current Dench draft revision through its native mailbox. Repeated requests share a durable receipt. — `dench email draft send` — POST /api/v1/email/drafts/{draftId}/send */
+  "email.drafts.send": {
+    draftId: string;
+    expectedRevision: number;
+    requestId?: string;
+  };
+  /** Upload attachment bytes authorized against this draft before adding its storage reference. — `dench email draft attach` — POST /api/v1/email/drafts/{draftId}/attachments */
+  "email.drafts.upload": {
+    draftId: string;
+    name: string;
+    contentType: string;
+    contentBase64: string;
+  };
+  /** Load the selected mailbox signature for explicit visible insertion. — `dench email draft signature` — GET /api/v1/email/drafts/{draftId}/signature */
+  "email.drafts.signature": {
+    draftId: string;
+  };
+  /** Send through a native Gmail or Outlook mailbox with a durable request receipt. Only use for an explicit send request. — `dench email send --mailbox` — POST /api/v1/email/native/send */
+  "email.native.send": {
+    organizationId?: string;
+    threadId?: string;
+    mailbox?: string;
+    requestId: string;
+    to?: {
+      email: string;
+      name?: string;
+    }[];
+    cc?: {
+      email: string;
+      name?: string;
+    }[];
+    bcc?: {
+      email: string;
+      name?: string;
+    }[];
+    subject?: string;
+    htmlBody?: string;
+    textBody?: string;
+    attachments?: {
+      storageId: string;
+      name: string;
+      contentType: string;
+      size: number;
+    }[];
+  };
   /** Send one raw email (no campaign): to/cc/bcc, custom from-name and reply-to, optional reply threading via replyToMessageId. — `dench email send` — POST /api/v1/email/send */
   "email.send": {
     /** Verified sender mailbox. */
@@ -3017,17 +3134,25 @@ export interface ApiRequests {
   /** Create a tool OAuth connection link. Slack is in-house, never a third-party connection: for toolkit slack the CLI prints the first-party install URL (/api/slack/install?slug=<workspace>, org admin) instead of calling this endpoint. — `dench tool connect` — POST /api/v1/tools/connections */
   "tool.connect": {
     /** Toolkit slug, e.g. github, gmail, stripe. */
-    toolkit: string;
+    toolkit?: string;
+    toolkit_slug?: string;
     /** Optional OAuth callback URL. */
     callback_url?: string;
+    /** Native OAuth return path within the workspace. */
+    returnTo?: string;
   };
   /** Search for external tool actions. — `dench tool search` — POST /api/v1/tools/search */
   "tool.search": {
-    queries: {
+    queries?: {
       /** Natural-language use case. */
       use_case: string;
       known_fields?: string;
     }[];
+    query?: string;
+    toolkit?: string;
+    toolkit_slug?: string;
+    limit?: number;
+    important?: boolean;
     session?: {
       id?: string;
       generate_id?: boolean;
@@ -3045,6 +3170,8 @@ export interface ApiRequests {
     /** Tool arguments object. */
     arguments?: Record<string, unknown>;
     account?: string;
+    connected_account_id?: string;
+    approvalId?: string;
   };
   /** Disconnect an external tool account. — `dench tool disconnect` — DELETE /api/v1/tools/connections/{connectionId} */
   "tool.disconnect": {
@@ -3374,6 +3501,7 @@ export interface ApiResponses {
       sessionExpiresAt?: number;
     };
   };
+  "workspace.context.sections": Record<string, unknown>;
   "workspace.context": {
     workspace: {
       id: string;
@@ -5319,6 +5447,54 @@ export interface ApiResponses {
       disabled: boolean;
     }[];
   };
+  "email.drafts.create": {
+    ok: boolean;
+    kind: "email";
+    draftId: string;
+    syncStatus: string;
+    revision: number;
+    [key: string]: unknown;
+  };
+  "email.drafts.get": {
+    ok: boolean;
+    kind: "email";
+    draftId: string;
+    syncStatus: string;
+    revision: number;
+    [key: string]: unknown;
+  };
+  "email.drafts.senders": Record<string, unknown>[];
+  "email.drafts.update": {
+    ok: boolean;
+    kind: "email";
+    draftId: string;
+    syncStatus: string;
+    revision: number;
+    [key: string]: unknown;
+  };
+  "email.drafts.send": {
+    ok: boolean;
+    kind: "email";
+    draftId: string;
+    syncStatus: string;
+    revision: number;
+    [key: string]: unknown;
+  };
+  "email.drafts.upload": {
+    storageId: string;
+    name: string;
+    contentType: string;
+    size: number;
+  };
+  "email.drafts.signature": Record<string, unknown>;
+  "email.native.send": {
+    ok: boolean;
+    kind: "email";
+    draftId: string;
+    syncStatus: string;
+    revision: number;
+    [key: string]: unknown;
+  };
   "email.send": {
     ok: boolean;
     /** Dench message id for `dench email message status`. */
@@ -6567,6 +6743,14 @@ export interface ApiResponses {
     /** OAuth URL the user opens to finish connecting. */
     redirect_url?: string;
     connection_id?: string;
+    redirectUrl?: string;
+    link?: string;
+    artifact?: {
+      kind: "connect";
+      data: {
+        toolkit: string;
+      };
+    };
     [key: string]: unknown;
   };
   "tool.search": {
@@ -6592,10 +6776,13 @@ export interface ApiResponses {
     /** Tool slug -> schema with gateway-added execution_ref for tool.run. */
     tool_schemas?: Record<string, Record<string, unknown>>;
     /** Tool-router session; reuse session.id for follow-up calls. */
-    session: {
+    session?: {
       id: string;
       [key: string]: unknown;
     };
+    items?: Record<string, unknown>[];
+    nativeAvailable?: boolean;
+    available?: boolean;
     execution_ref_version?: number;
     [key: string]: unknown;
   };
@@ -7810,6 +7997,22 @@ export type DenchApiTree = {
       /** Submit a campaign for approval or sending. (`dench email campaign submit`) */
       submit(args: Req<"email.campaign.submit">): Promise<Res<"email.campaign.submit">>;
     };
+    drafts: {
+      /** Create an editable Dench email draft and synchronize its selected native mailbox asynchronously. Use a stable requestId for retries. (`dench email draft create`) */
+      create(args: Req<"email.drafts.create">): Promise<Res<"email.drafts.create">>;
+      /** Read an email draft, eligible senders and provider sync status. (`dench email draft show`) */
+      get(args: Req<"email.drafts.get">): Promise<Res<"email.drafts.get">>;
+      /** Send the current Dench draft revision through its native mailbox. Repeated requests share a durable receipt. (`dench email draft send`) */
+      send(args: Req<"email.drafts.send">): Promise<Res<"email.drafts.send">>;
+      /** List native mailboxes this caller may use. (`dench email draft senders`) */
+      senders(args?: Req<"email.drafts.senders">): Promise<Res<"email.drafts.senders">>;
+      /** Load the selected mailbox signature for explicit visible insertion. (`dench email draft signature`) */
+      signature(args: Req<"email.drafts.signature">): Promise<Res<"email.drafts.signature">>;
+      /** Save draft content using expectedRevision; sender changes require a new draft after provider binding. (`dench email draft update`) */
+      update(args: Req<"email.drafts.update">): Promise<Res<"email.drafts.update">>;
+      /** Upload attachment bytes authorized against this draft before adding its storage reference. (`dench email draft attach`) */
+      upload(args: Req<"email.drafts.upload">): Promise<Res<"email.drafts.upload">>;
+    };
     identity: {
       /** Begin the full Dench sender verification flow for a sending identity. (`dench email identity verify`) */
       beginVerification(args: Req<"email.identity.beginVerification">): Promise<Res<"email.identity.beginVerification">>;
@@ -7838,6 +8041,10 @@ export type DenchApiTree = {
       /** List recent raw email messages for the workspace. (`dench email message list`) */
       list(args?: Req<"email.message.list">): Promise<Res<"email.message.list">>;
     };
+    native: {
+      /** Send through a native Gmail or Outlook mailbox with a durable request receipt. Only use for an explicit send request. (`dench email send --mailbox`) */
+      send(args: Req<"email.native.send">): Promise<Res<"email.native.send">>;
+    };
     /** Send one raw email (no campaign): to/cc/bcc, custom from-name and reply-to, optional reply threading via replyToMessageId. (`dench email send`) */
     send(args: Req<"email.send">): Promise<Res<"email.send">>;
     sequence: {
@@ -8126,8 +8333,13 @@ export type DenchApiTree = {
       /** List artifacts for the authenticated workspace. (`dench artifacts`) */
       list(args?: Req<"workspace.artifacts.list">): Promise<Res<"workspace.artifacts.list">>;
     };
-    /** Return the current Dench workspace context for the bearer. (`dench context`) */
-    context(args?: Req<"workspace.context">): Promise<Res<"workspace.context">>;
+    context: {
+      /** Return the current Dench workspace context for the bearer. (`dench context`) */
+      (args?: Req<"workspace.context">): Promise<Res<"workspace.context">>;
+      $call(args?: Req<"workspace.context">): Promise<Res<"workspace.context">>;
+      /** Read selected scoped workspace documents and a compact context index without writes. (`dench context --sections`) */
+      sections(args?: Req<"workspace.context.sections">): Promise<Res<"workspace.context.sections">>;
+    };
     /** Return the current workspace's standing instructions for external agents. (`dench context --instructions`) */
     instructions(args?: Req<"workspace.instructions">): Promise<Res<"workspace.instructions">>;
     /** Return workspace and agent status. (`dench status`) */
@@ -8555,6 +8767,22 @@ export interface DenchCampaigns {
 }
 
 export interface DenchEmail {
+  /** Create a native mailbox draft with a stable request receipt. Permission: `email:write`. Wraps `email.drafts.create`. */
+  createDraft(draft: Req<"email.drafts.create">): Promise<Res<"email.drafts.create">>;
+  /** Read a native email draft and sync status. Permission: `email:read`. Wraps `email.drafts.get`. */
+  draft(draftId: string): Promise<Res<"email.drafts.get">>;
+  /** Save the next email draft revision. Permission: `email:write`. Wraps `email.drafts.update`. */
+  updateDraft(input: Req<"email.drafts.update">): Promise<Res<"email.drafts.update">>;
+  /** Send the frozen native email draft revision. Permission: `email:write`. Wraps `email.drafts.send`. */
+  sendDraft(input: Req<"email.drafts.send">): Promise<Res<"email.drafts.send">>;
+  /** List eligible native mailboxes. Permission: `email:read`. Wraps `email.drafts.senders`. */
+  senders(opts?: Req<"email.drafts.senders">): Promise<Res<"email.drafts.senders">>;
+  /** Upload attachment bytes for a native draft. Permission: `email:write`. Wraps `email.drafts.upload`. */
+  uploadAttachment(input: Req<"email.drafts.upload">): Promise<Res<"email.drafts.upload">>;
+  /** Load the selected mailbox signature for visible insertion. Permission: `email:read`. Wraps `email.drafts.signature`. */
+  signature(draftId: string): Promise<Res<"email.drafts.signature">>;
+  /** Explicitly send through a native Gmail or Outlook mailbox. Permission: `email:write`. Wraps `email.native.send`. */
+  sendFromMailbox(message: Req<"email.native.send">): Promise<Res<"email.native.send">>;
   /** Send one email from a verified identity. Permission: `email:write`. Wraps `email.send`. */
   send(message: Req<"email.send">): Promise<Res<"email.send">>;
   /** Sent messages. Permission: `email:read`. Wraps `email.message.list`. */

package/crm.ts

@@ -1063,6 +1063,15 @@ const api = {
   },
 };
 
+/** These read commands have local, command-specific help (no runtime needed). */
+export function isCrmReadHelpRequest(args: readonly string[]): boolean {
+  const command = args.find((arg) => arg !== "--json");
+  return (
+    (command === "query" || command === "aggregate") &&
+    (args.includes("--help") || args.includes("-h"))
+  );
+}
+
 export async function runCrmCommand(opts: {
   convex: ConvexHttpClient;
   args: string[];
@@ -1088,6 +1097,21 @@ export async function runCrmCommand(opts: {
     crmHelp();
     return;
   }
+  if (isCrmReadHelpRequest(opts.args)) {
+    if (subcommand === "query") {
+      console.log(`Usage: dench crm query <object> [--where '<JSON>'] [--select Name,Email] [--sort -Score] [--limit N] [--json]
+  --page [--cursor '<continueCursor>']  Return {page,isDone,continueCursor} in index order; omit --sort.
+  --assigned-to me|unassigned|<userId|email> (or --mine) [--assignee-field <Field>]
+  Default limit: 100. Maximum: 1000 for a one-shot array, 100 for a cursor page.
+  Continue cursor pages until isDone, including empty filtered pages.
+Example: dench crm query company --where '{"Status":"New"}' --select Name --limit 25 --json`);
+    } else {
+      console.log(`Usage: dench crm aggregate <object> --field <Field> [--sum <NumberField>] [--json]
+  Count rows per value of --field. --sum also totals a number field within each bucket.
+Example: dench crm aggregate deal --field Stage --sum Amount --json`);
+    }
+    return;
+  }
   switch (subcommand) {
     case "objects":
       return await runObjectsCommand(ctx);
@@ -2391,37 +2415,92 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
   switch (verb) {
     case "list": {
       const objectName = shift(ctx.args, "object name");
+      const withMeta = hasFlag(ctx.args, "--with-meta");
+      const cursorSpecified = ctx.args.includes("--cursor");
+      const cursor = getFlag(ctx.args, "--cursor");
+      if (cursorSpecified && (!cursor?.trim() || cursor.startsWith("--")))
+        throw new CrmCliError(
+          "--cursor requires a non-empty continuation cursor.",
+        );
+      const assigneeScopeArgs = resolveAssigneeScopeFlags(ctx.args);
       const limit = resolveLimitFlag(ctx.args, {
         defaultValue: 100,
-        cap: 1000,
+        cap:
+          withMeta && assigneeScopeArgs.assignedTo !== undefined ? 100 : 1000,
         command: "crm entries list",
+        ...(withMeta
+          ? {
+              fullDatasetHint:
+                "Continue with --with-meta --cursor '<continueCursor>' when a cursor is returned.",
+            }
+          : {}),
       });
-      const withMeta = hasFlag(ctx.args, "--with-meta");
-      const assigneeScopeArgs = resolveAssigneeScopeFlags(ctx.args);
+      if (cursor !== undefined && !withMeta) {
+        throw new CrmCliError(
+          "--cursor requires --with-meta on crm entries list.",
+        );
+      }
       assertNoUnknownFlags(ctx.args, "crm entries list");
-      const entries = await callQuery(ctx, api.entries.list, {
-        objectName,
-        limit: limit.effective,
-        ...assigneeScopeArgs,
-      });
       if (!withMeta) {
         // Bare-array output: the clamp warning already went to stderr
         // (stdout must stay a valid JSON array in --json mode).
-        out(ctx, entries);
+        out(
+          ctx,
+          await callQuery(ctx, api.entries.list, {
+            objectName,
+            limit: limit.effective,
+            ...assigneeScopeArgs,
+          }),
+        );
         return;
       }
-      const object = (await callQuery(ctx, api.objects.get, {
-        name: objectName,
-      })) as { entryCount?: number } | null;
-      const returnedCount = Array.isArray(entries) ? entries.length : 0;
-      const totalCount =
-        typeof object?.entryCount === "number"
-          ? object.entryCount
-          : returnedCount;
+      // Catalog counts include hidden and unassigned records. Only the
+      // readable page can tell us whether this caller has a continuation.
+      const [result, object] = (await Promise.all([
+        assigneeScopeArgs.assignedTo !== undefined
+          ? callQuery(ctx, api.query.scanEntries, {
+              objectName,
+              dsl: { limit: limit.effective },
+              paginationOpts: {
+                cursor: cursor ?? null,
+                numItems: limit.effective,
+              },
+              ...assigneeScopeArgs,
+            })
+          : callQuery(ctx, api.entries.listPage, {
+              objectName,
+              limit: limit.effective,
+              ...(cursor !== undefined ? { cursor } : {}),
+            }),
+        callQuery(ctx, api.objects.get, { name: objectName }),
+      ])) as [
+        {
+          page?: unknown[];
+          isDone?: boolean;
+          continueCursor?: string | null;
+          truncated?: boolean;
+        } | null,
+        { entryCount?: number; visibility?: string } | null,
+      ];
+      const entries = Array.isArray(result?.page) ? result.page : [];
+      const isDone =
+        typeof result?.isDone === "boolean" ? result.isDone : null;
+      const truncated = result?.truncated === true;
+      const continueCursor =
+        isDone === false ? result?.continueCursor || null : null;
+      const hasMore = continueCursor
+        ? true
+        : isDone === true && !truncated
+          ? false
+          : null;
       out(ctx, {
         objectName,
-        totalCount,
-        returnedCount,
+        totalCount:
+          typeof object?.entryCount === "number" ? object.entryCount : null,
+        totalCountScope: "object",
+        visibility: object?.visibility ?? null,
+        returnedCount: entries.length,
+        returnedCountScope: "readable",
         limit: limit.effective,
         ...(limit.clamped
           ? {
@@ -2431,7 +2510,10 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
               },
             }
           : {}),
-        hasMore: totalCount > returnedCount,
+        hasMore,
+        isDone,
+        truncated,
+        continueCursor,
         entries,
       });
       return;
@@ -4785,8 +4867,12 @@ Fields (columns):
       Update the color (e.g. "#3b82f6") for an existing enum option.
 
 Entries (rows):
-  dench crm entries list <object> [--limit N] [--with-meta] [--json]
+  dench crm entries list <object> [--limit N] [--with-meta [--cursor '<continueCursor>']] [--json]
       [--assigned-to me|unassigned|<userId|email> | --mine] [--assignee-field <Field>]
+      --with-meta includes readable pagination; totalCount is the entire object's catalog count,
+      not a readable or assigned total. Continue only when continueCursor is returned, preserving filters.
+      Scoped reads may be truncated with no cursor (hasMore: null); repeating the same call will not advance.
+      Assigned metadata pages cap at 100 rows; other list reads cap at 1000.
   dench crm entries get <object> <entryId> [--with-context]   (--with-context appends the newest activity + notes)
   dench crm entries sync-history <object> <entryId> [--status]
       Queue a full, paged pull of the record's email history from every