@dench.com/cli 2.3.1 → 2.4.0

package/crm.ts

@@ -88,6 +88,7 @@ type CrmCliContext = {
    * organization context.
    */
   sessionToken?: string;
+  runId?: string;
   enrichmentGateway?: Pick<EnrichmentGatewayOptions, "apiKey" | "baseUrl">;
 };
 
@@ -296,6 +297,7 @@ async function applyBatchOpsInChunks(
     const chunkKey = chunkIdempotencyKey(idempotencyKey, chunkIndex);
     await callMutation(ctx, api.batch.apply, {
       ops: chunk,
+      ...runContextArgs(ctx),
       ...(chunkKey ? { idempotencyKey: chunkKey } : {}),
       ...(allowUnknown ? { allowUnknown: true } : {}),
     });
@@ -303,6 +305,10 @@ async function applyBatchOpsInChunks(
   return chunks.length;
 }
 
+function runContextArgs(ctx: CrmCliContext): Record<string, string> {
+  return ctx.runId ? { runId: ctx.runId } : {};
+}
+
 /**
  * Fetch the canonical field names for an object. Best-effort: returns
  * `null` (rather than throwing) on any failure so the caller falls back
@@ -574,6 +580,11 @@ const api = {
       "functions/crm/entries:bulkDelete",
     ),
   },
+  history: {
+    listForEntry: makeFunctionReference<"query">(
+      "functions/crm/history:listForEntry",
+    ),
+  },
   cells: {
     get: makeFunctionReference<"query">("functions/crm/cells:get"),
     set: makeFunctionReference<"mutation">("functions/crm/cells:set"),
@@ -641,6 +652,7 @@ export async function runCrmCommand(opts: {
     args,
     jsonOutput,
     sessionToken: opts.sessionToken,
+    runId: process.env.DENCH_RUN_ID?.trim() || undefined,
     enrichmentGateway: opts.enrichmentGateway,
   };
   const subcommand = args.shift();
@@ -657,6 +669,8 @@ export async function runCrmCommand(opts: {
       return await runFieldsCommand(ctx);
     case "entries":
       return await runEntriesCommand(ctx);
+    case "history":
+      return await runHistoryCommand(ctx);
     case "cells":
       return await runCellsCommand(ctx);
     case "query":
@@ -1335,6 +1349,7 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
         await callMutation(ctx, api.entries.create, {
           objectName,
           data,
+          ...runContextArgs(ctx),
           ...(allowUnknown ? { allowUnknown: true } : {}),
         }),
       );
@@ -1392,6 +1407,7 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
           objectName,
           entryId: entryId as any,
           data,
+          ...runContextArgs(ctx),
           ...(allowUnknown ? { allowUnknown: true } : {}),
         }),
       );
@@ -1438,6 +1454,7 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
         ctx,
         await callMutation(ctx, api.entries.remove, {
           entryId: entryId as any,
+          ...runContextArgs(ctx),
         }),
       );
       return;
@@ -1452,6 +1469,7 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
         ctx,
         await callMutation(ctx, api.entries.bulkDelete, {
           entryIds: entryIds as any,
+          ...runContextArgs(ctx),
         }),
       );
       return;
@@ -1461,6 +1479,27 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
   }
 }
 
+async function runHistoryCommand(ctx: CrmCliContext): Promise<void> {
+  const objectName = shift(ctx.args, "object name");
+  const entryId = shift(ctx.args, "entry id");
+  const includeSystem = hasFlag(ctx.args, "--include-system");
+  const limit = parseInt(getFlag(ctx.args, "--limit") ?? "50", 10);
+  const cursor = getFlag(ctx.args, "--cursor");
+  assertNoUnknownFlags(ctx.args, "crm history");
+  out(
+    ctx,
+    await callQuery(ctx, api.history.listForEntry, {
+      objectName,
+      entryId,
+      includeSystem,
+      paginationOpts: {
+        numItems: Number.isFinite(limit) ? Math.min(Math.max(limit, 1), 100) : 50,
+        cursor: cursor ?? null,
+      },
+    }),
+  );
+}
+
 async function runCellsCommand(ctx: CrmCliContext): Promise<void> {
   const verb = ctx.args.shift();
   switch (verb) {
@@ -1492,6 +1531,7 @@ async function runCellsCommand(ctx: CrmCliContext): Promise<void> {
           entryId: entryId as any,
           fieldName,
           value,
+          ...runContextArgs(ctx),
         }),
       );
       return;
@@ -1538,6 +1578,7 @@ async function runCellsCommand(ctx: CrmCliContext): Promise<void> {
           entryId: entryId as any,
           fieldName,
           value,
+          ...runContextArgs(ctx),
         }),
       );
       return;
@@ -1664,6 +1705,7 @@ async function runBatchCommand(ctx: CrmCliContext): Promise<void> {
     ctx,
     await callMutation(ctx, api.batch.apply, {
       ops: ops as any,
+      ...runContextArgs(ctx),
       ...(idempotencyKey ? { idempotencyKey } : {}),
     } as any),
   );
@@ -1804,6 +1846,7 @@ async function runTransactionCommand(ctx: CrmCliContext): Promise<void> {
         ctx,
         await callMutation(ctx, api.transaction.commit, {
           txnId: txnId as any,
+          ...runContextArgs(ctx),
         }),
       );
       return;
@@ -1859,6 +1902,7 @@ async function runTransactionCommand(ctx: CrmCliContext): Promise<void> {
           ctx,
           await callMutation(ctx, api.transaction.commit, {
             txnId: begun.txnId as any,
+            ...runContextArgs(ctx),
           }),
         );
       } else {
@@ -2637,6 +2681,7 @@ async function runPeopleCommand(ctx: CrmCliContext): Promise<void> {
         await callMutation(ctx, api.entries.create, {
           objectName: "people",
           data,
+          ...runContextArgs(ctx),
         }),
       );
       return;
@@ -2701,6 +2746,7 @@ async function runCompaniesCommand(ctx: CrmCliContext): Promise<void> {
         await callMutation(ctx, api.entries.create, {
           objectName: "company",
           data,
+          ...runContextArgs(ctx),
         }),
       );
       return;
@@ -2895,6 +2941,7 @@ Fields (columns):
 Entries (rows):
   dench crm entries list <object> [--limit N] [--with-meta] [--json]
   dench crm entries get <object> <entryId>
+  dench crm history <object> <entryId> [--include-system] [--limit N] [--cursor CURSOR] [--json]
   dench crm entries create <object> --data '{"Field":"Value",...}'    (alias: --fields) [--allow-unknown]
   dench crm entries create-many <object> --data '[{"Field":"Value",...}]' [--file rows.json] [--idempotency-key <key>] [--allow-unknown]
   dench crm entries update <object> <entryId> --data '{...}'           (alias: --fields) [--allow-unknown]

package/dench.ts

@@ -163,6 +163,14 @@ const api = {
         "functions/agentWorkspace:whatCanIDoHere",
       ),
     },
+    agentConfig: {
+      workspaceInstructions: makeFunctionReference<"query">(
+        "functions/agentConfig:workspaceInstructions",
+      ),
+      devWorkspaceInstructions: makeFunctionReference<"query">(
+        "functions/agentConfig:devWorkspaceInstructions",
+      ),
+    },
     files: {
       listTree: makeFunctionReference<"query">("functions/files:listTree"),
       deleteFile: makeFunctionReference<"mutation">(
@@ -450,7 +458,8 @@ Usage:
   dench use <session-key-or-workspace-slug> [--host <host>] [--json]
   dench logout [session-key-or-workspace-slug] [--session <key-or-scope>] [--host <host>] [--all] [--json]
   dench backend [show|set|clear] [<production|staging|local|<url>>] [--json]
-  dench context [--json]
+  dench context [--instructions] [--json]
+  dench instructions [--json]
   dench status [--mine|--self] [--json]
   dench memory search "query" [--limit 8] [--json]
   dench memory save <key> "text" [--kind fact|decision|preference|goal|tool_note|other] [--tags a,b] [--sensitivity normal|broad|sensitive] [--scope user|org] [--json]
@@ -682,10 +691,14 @@ function contextHelp() {
   console.log(`Dench context
 
 Usage:
-  dench context [--json]
+  dench context [--instructions] [--json]
+  dench instructions [--json]
 
 Shows the current workspace, current agent, assigned tasks, pending approvals
 requested by this agent, connected apps when available, and useful next commands.
+
+Use --instructions (or dench instructions) to print the standing workspace
+instructions external agents should treat as system-level guidance.
 `);
 }
 
@@ -2900,6 +2913,24 @@ function formatContext(context: JsonRecord) {
   return lines.join("\n");
 }
 
+async function buildWorkspaceInstructionsContext(
+  runtime: Awaited<ReturnType<typeof getRuntime>>,
+) {
+  if (runtime.mode === "dev") {
+    return (await runtime.client.query(
+      api.functions.agentConfig.devWorkspaceInstructions,
+      runtime.workspaceArgs,
+    )) as JsonRecord;
+  }
+  if (runtime.mode !== "session" && runtime.mode !== "apiKey") {
+    throw loginRequiredError("dench context --instructions");
+  }
+  return (await runtime.client.query(
+    api.functions.agentConfig.workspaceInstructions,
+    { sessionToken: runtime.sessionToken },
+  )) as JsonRecord;
+}
+
 async function devOverview(runtime: Awaited<ReturnType<typeof getRuntime>>) {
   if (runtime.mode !== "dev") {
     throw new Error("Not in dev mode");
@@ -4355,6 +4386,22 @@ async function main() {
     return;
   }
 
+  if (command === "context" && args.includes("--instructions")) {
+    const instructions = await buildWorkspaceInstructionsContext(runtime);
+    print(
+      json ? instructions : (stringField(instructions, "instructions") ?? ""),
+    );
+    return;
+  }
+
+  if (command === "instructions") {
+    const instructions = await buildWorkspaceInstructionsContext(runtime);
+    print(
+      json ? instructions : (stringField(instructions, "instructions") ?? ""),
+    );
+    return;
+  }
+
   if (command === "context") {
     const context = await buildContext(runtime);
     print(json ? context : formatContext(context));

package/lib/api-schemas.ts

@@ -340,6 +340,18 @@ const workspaceStatusPayload = z
     "Workspace orientation payload shared by /context, /status, /agents, and /approvals.",
   );
 
+const workspaceInstructionsResponse = z.object({
+  instructions: z
+    .string()
+    .describe(
+      "Markdown standing instructions for external agents connected to this workspace.",
+    ),
+  workspace: z.object({
+    name: z.string(),
+    slug: z.string().optional(),
+  }),
+});
+
 const memoryDoc = z
   .object({
     _id: z.string(),
@@ -1183,6 +1195,7 @@ export const requestSchemas: Record<string, ZodTypeAny> = {
 
   // Workspace
   "workspace.context": noInput,
+  "workspace.instructions": noInput,
   "workspace.status": noInput,
   "workspace.agents": noInput,
   "workspace.approvals.list": noInput,
@@ -1909,6 +1922,7 @@ export const responseSchemas: Record<string, ZodTypeAny> = {
 
   // Workspace orientation
   "workspace.context": workspaceStatusPayload,
+  "workspace.instructions": workspaceInstructionsResponse,
   "workspace.status": workspaceStatusPayload,
   "workspace.agents": workspaceStatusPayload,
   "workspace.approvals.list": workspaceStatusPayload,
@@ -2757,6 +2771,11 @@ export const responseExamples: Record<string, unknown> = {
     },
   },
   "workspace.context": workspaceStatusExample,
+  "workspace.instructions": {
+    workspace: { name: "Acme", slug: "acme" },
+    instructions:
+      "# Dench Workspace Instructions\n\nWorkspace: Acme (acme)\n\n## Identity\nYou are Dench...",
+  },
   "workspace.status": workspaceStatusExample,
   "workspace.agents": workspaceStatusExample,
   "workspace.approvals.list": workspaceStatusExample,

package/lib/command-registry.ts

@@ -245,6 +245,18 @@ const rawApiOperations = [
     responseSchema: anyResponse,
     backend: convex("query", "functions/agentWorkspace:whatCanIDoHere"),
   }),
+  op({
+    id: "workspace.instructions",
+    group: "workspace",
+    summary:
+      "Return the current workspace's standing instructions for external agents.",
+    cli: "dench context --instructions",
+    method: "GET",
+    path: "/context/instructions",
+    requestSchema: noBody,
+    responseSchema: anyResponse,
+    backend: convex("query", "functions/agentConfig:workspaceInstructions"),
+  }),
   op({
     id: "workspace.status",
     group: "workspace",
@@ -704,6 +716,37 @@ const rawApiOperations = [
     responseSchema: anyResponse,
     backend: convex("query", "functions/crm/entries:get"),
   }),
+  op({
+    id: "crm.entries.history",
+    group: "crm",
+    summary: "List a CRM entry's audit history.",
+    cli: "dench crm history",
+    method: "GET",
+    path: "/crm/objects/{objectName}/entries/{entryId}/history",
+    requestSchema: noBody,
+    responseSchema: anyResponse,
+    backend: {
+      ...convex("query", "functions/crm/history:listForEntry"),
+      transformArgs: (input) => {
+        const limit =
+          typeof input.limit === "number"
+            ? Math.min(Math.max(Math.floor(input.limit), 1), 100)
+            : 50;
+        return {
+          objectName: input.objectName,
+          entryId: input.entryId,
+          includeSystem: input.includeSystem === true,
+          paginationOpts: {
+            numItems: limit,
+            cursor:
+              typeof input.cursor === "string" && input.cursor.length > 0
+                ? input.cursor
+                : null,
+          },
+        };
+      },
+    },
+  }),
   op({
     id: "crm.entries.create",
     group: "crm",
@@ -713,7 +756,9 @@ const rawApiOperations = [
     path: "/crm/objects/{objectName}/entries",
     requestSchema: anyObject,
     responseSchema: anyResponse,
-    backend: convex("mutation", "functions/crm/entries:create"),
+    backend: convex("mutation", "functions/crm/entries:create", "bearer", {
+      includeRunId: true,
+    }),
   }),
   op({
     id: "crm.entries.createMany",
@@ -724,7 +769,9 @@ const rawApiOperations = [
     path: "/crm/objects/{objectName}/entries/batch",
     requestSchema: anyObject,
     responseSchema: anyResponse,
-    backend: convex("mutation", "functions/crm/entries:createMany"),
+    backend: convex("mutation", "functions/crm/entries:createMany", "bearer", {
+      includeRunId: true,
+    }),
   }),
   op({
     id: "crm.entries.update",
@@ -735,7 +782,9 @@ const rawApiOperations = [
     path: "/crm/objects/{objectName}/entries/{entryId}",
     requestSchema: anyObject,
     responseSchema: anyResponse,
-    backend: convex("mutation", "functions/crm/entries:update"),
+    backend: convex("mutation", "functions/crm/entries:update", "bearer", {
+      includeRunId: true,
+    }),
   }),
   op({
     id: "crm.entries.updateMany",
@@ -746,7 +795,9 @@ const rawApiOperations = [
     path: "/crm/objects/{objectName}/entries/batch",
     requestSchema: anyObject,
     responseSchema: anyResponse,
-    backend: convex("mutation", "functions/crm/batch:apply"),
+    backend: convex("mutation", "functions/crm/batch:apply", "bearer", {
+      includeRunId: true,
+    }),
   }),
   op({
     id: "crm.entries.delete",
@@ -757,7 +808,9 @@ const rawApiOperations = [
     path: "/crm/objects/{objectName}/entries/{entryId}",
     requestSchema: anyObject,
     responseSchema: anyResponse,
-    backend: convex("mutation", "functions/crm/entries:remove"),
+    backend: convex("mutation", "functions/crm/entries:remove", "bearer", {
+      includeRunId: true,
+    }),
   }),
   op({
     id: "crm.entries.bulkDelete",
@@ -768,7 +821,9 @@ const rawApiOperations = [
     path: "/crm/objects/{objectName}/entries/delete",
     requestSchema: anyObject,
     responseSchema: anyResponse,
-    backend: convex("mutation", "functions/crm/entries:bulkDelete"),
+    backend: convex("mutation", "functions/crm/entries:bulkDelete", "bearer", {
+      includeRunId: true,
+    }),
   }),
 
   op({
@@ -791,7 +846,9 @@ const rawApiOperations = [
     path: "/crm/objects/{objectName}/entries/{entryId}/fields/{fieldName}",
     requestSchema: anyObject,
     responseSchema: anyResponse,
-    backend: convex("mutation", "functions/crm/cells:set"),
+    backend: convex("mutation", "functions/crm/cells:set", "bearer", {
+      includeRunId: true,
+    }),
   }),
   op({
     id: "crm.cells.setMany",
@@ -802,7 +859,9 @@ const rawApiOperations = [
     path: "/crm/cells/batch",
     requestSchema: anyObject,
     responseSchema: anyResponse,
-    backend: convex("mutation", "functions/crm/cells:setMany"),
+    backend: convex("mutation", "functions/crm/cells:setMany", "bearer", {
+      includeRunId: true,
+    }),
   }),
   op({
     id: "crm.cells.append",
@@ -813,7 +872,9 @@ const rawApiOperations = [
     path: "/crm/objects/{objectName}/entries/{entryId}/fields/{fieldName}/append",
     requestSchema: anyObject,
     responseSchema: anyResponse,
-    backend: convex("mutation", "functions/crm/cells:append"),
+    backend: convex("mutation", "functions/crm/cells:append", "bearer", {
+      includeRunId: true,
+    }),
   }),
 
   op({
@@ -891,7 +952,9 @@ const rawApiOperations = [
     path: "/crm/batch",
     requestSchema: anyObject,
     responseSchema: anyResponse,
-    backend: convex("mutation", "functions/crm/batch:apply"),
+    backend: convex("mutation", "functions/crm/batch:apply", "bearer", {
+      includeRunId: true,
+    }),
   }),
   op({
     id: "crm.transaction.begin",
@@ -924,7 +987,9 @@ const rawApiOperations = [
     path: "/crm/transactions/{txnId}/commit",
     requestSchema: anyObject,
     responseSchema: anyResponse,
-    backend: convex("mutation", "functions/crm/transaction:commit"),
+    backend: convex("mutation", "functions/crm/transaction:commit", "bearer", {
+      includeRunId: true,
+    }),
   }),
   op({
     id: "crm.transaction.abort",

package/lib/enrichment-gateway.ts

@@ -1325,6 +1325,17 @@ async function buildGatewayError(
       { status: response.status, code },
     );
   }
+  if (
+    response.status === 402 ||
+    code === "on_demand_disabled" ||
+    code === "insufficient_credits" ||
+    code === "spend_limit_reached"
+  ) {
+    return new EnrichmentGatewayError(
+      upstreamMessage ?? "AI credits exhausted.",
+      { status: response.status, code },
+    );
+  }
 
   const detail = upstreamMessage || rawText || response.statusText;
   const truncated = detail.length > 500 ? `${detail.slice(0, 500)}...` : detail;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dench.com/cli",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "description": "Dench agent workspace CLI. v2 unifies auth behind `dench signin`; the legacy `dench login` / `dench onboard` / `dench setup` / `dench what-can-i-do` / `dench register` commands now error with a redirect.",
   "type": "module",
   "bin": {