@dench.com/cli 2.7.0 → 2.7.2

package/chat-spawn.ts

@@ -108,6 +108,17 @@ function buildStreamUrlByThreadId(host: string, threadId: string): string {
   return `${host.replace(/\/+$/, "")}/api/chat/stream?sessionId=${encodeURIComponent(threadId)}`;
 }
 
+const CHAT_STREAM_RECONNECT_DELAY_MS = 100;
+const CHAT_STREAM_MAX_EMPTY_BACKOFF_MS = 2_000;
+
+function emptyActiveStreamBackoffMs(consecutiveEmptyResponses: number): number {
+  const exponent = Math.max(0, Math.min(consecutiveEmptyResponses - 1, 10));
+  return Math.min(
+    CHAT_STREAM_RECONNECT_DELAY_MS * 2 ** exponent,
+    CHAT_STREAM_MAX_EMPTY_BACKOFF_MS,
+  );
+}
+
 /**
  * Subscribe to the durable chat stream and pretty-print useful chunks
  * until the stream closes. Mirrors the chunk types the chat panel
@@ -131,37 +142,25 @@ async function followStream(args: {
   runId?: string;
   threadId?: string;
 }): Promise<void> {
-  const url = args.runId
+  const baseUrl = args.runId
     ? buildStreamUrlByRunId(args.host, args.runId)
     : args.threadId
       ? buildStreamUrlByThreadId(args.host, args.threadId)
       : null;
-  if (!url) {
+  if (!baseUrl) {
     throw new ChatSpawnError(
       "followStream requires either { runId } or { threadId }",
     );
   }
-  const response = await fetch(url, {
-    method: "GET",
-    headers: {
-      accept: "text/event-stream",
-      authorization: `Bearer ${args.bearerToken}`,
-    },
-  });
-  if (!response.ok || !response.body) {
-    throw new ChatSpawnError(
-      `Failed to open stream: ${response.status} ${response.statusText}`,
-    );
-  }
-
-  const reader = response.body.getReader();
-  const decoder = new TextDecoder();
-  let buffer = "";
   // Tool calls in flight, keyed by toolCallId, so we can render
   // a single line per call ("→ tool_name … done") instead of
   // dumping every chunk verbatim.
   const inFlightTools = new Map<string, { toolName: string }>();
   let textBuffer = "";
+  let segmentWorkflowRunId: string | null = null;
+  let segmentOrdinal: number | null = null;
+  let startIndex = 0;
+  let consecutiveEmptyActiveResponses = 0;
 
   const flushText = () => {
     if (textBuffer) {
@@ -170,104 +169,199 @@ async function followStream(args: {
     }
   };
 
-  const handleChunk = (raw: string) => {
-    if (!raw.startsWith("data:")) return;
-    const data = raw.slice("data:".length).trim();
-    if (!data || data === "[DONE]") return;
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(data);
-    } catch {
-      return;
+  const closeInFlightToolLines = (suffix: string) => {
+    if (inFlightTools.size === 0) return false;
+    process.stdout.write(suffix);
+    inFlightTools.clear();
+    return true;
+  };
+
+  while (true) {
+    const url = new URL(baseUrl);
+    if (startIndex > 0) {
+      url.searchParams.set("startIndex", String(startIndex));
     }
-    if (!parsed || typeof parsed !== "object") return;
-    const c = parsed as {
-      type?: unknown;
-      delta?: unknown;
-      text?: unknown;
-      toolName?: unknown;
-      toolCallId?: unknown;
-      input?: unknown;
-      output?: unknown;
-      errorText?: unknown;
-    };
-    switch (c.type) {
-      case "text-delta":
-      case "reasoning-delta": {
-        if (typeof c.delta === "string") {
-          textBuffer += c.delta;
-        }
-        break;
+    const response: Response = await fetch(url, {
+      method: "GET",
+      headers: {
+        accept: "text/event-stream",
+        authorization: `Bearer ${args.bearerToken}`,
+        ...(segmentWorkflowRunId
+          ? {
+              "x-chat-segment-workflow-run-id": segmentWorkflowRunId,
+            }
+          : {}),
+        ...(segmentOrdinal !== null
+          ? { "x-chat-segment-ordinal": String(segmentOrdinal) }
+          : {}),
+      },
+    });
+    const responseWorkflowRunId: string | null =
+      response.headers.get("x-chat-segment-workflow-run-id") ??
+      response.headers.get("x-workflow-run-id");
+    const rawOrdinal = response.headers.get("x-chat-segment-ordinal");
+    const responseOrdinal =
+      rawOrdinal !== null && Number.isSafeInteger(Number(rawOrdinal))
+        ? Number(rawOrdinal)
+        : null;
+    const segmentChanged =
+      (responseWorkflowRunId !== null &&
+        responseWorkflowRunId !== segmentWorkflowRunId) ||
+      (responseOrdinal !== null && responseOrdinal !== segmentOrdinal);
+    if (segmentChanged) {
+      if (segmentWorkflowRunId !== null || segmentOrdinal !== null) {
+        closeInFlightToolLines(" continued in next segment\n");
       }
-      case "tool-input-start": {
-        flushText();
-        if (
-          typeof c.toolCallId === "string" &&
-          typeof c.toolName === "string"
-        ) {
-          inFlightTools.set(c.toolCallId, { toolName: c.toolName });
-          process.stdout.write(`\n→ ${c.toolName} …`);
-        }
-        break;
+      startIndex = 0;
+      consecutiveEmptyActiveResponses = 0;
+    }
+    segmentWorkflowRunId = responseWorkflowRunId ?? segmentWorkflowRunId;
+    segmentOrdinal = responseOrdinal ?? segmentOrdinal;
+
+    if (response.status === 202) {
+      const retryAfterSeconds = Number(response.headers.get("retry-after"));
+      const retryDelayMs =
+        Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0
+          ? Math.max(50, retryAfterSeconds * 1_000)
+          : 100;
+      await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+      continue;
+    }
+    if (!response.ok || !response.body) {
+      throw new ChatSpawnError(
+        `Failed to open stream: ${response.status} ${response.statusText}`,
+      );
+    }
+
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let responseChunkCount = 0;
+    let gotFinish = false;
+
+    const handleChunk = (raw: string) => {
+      if (!raw.startsWith("data:")) return;
+      const data = raw.slice("data:".length).trim();
+      if (!data || data === "[DONE]") return;
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(data);
+      } catch {
+        return;
       }
-      case "tool-output-available": {
-        flushText();
-        if (typeof c.toolCallId === "string") {
-          const meta = inFlightTools.get(c.toolCallId);
-          inFlightTools.delete(c.toolCallId);
-          process.stdout.write(` done (${meta?.toolName ?? "tool"})\n`);
+      if (!parsed || typeof parsed !== "object") return;
+      responseChunkCount += 1;
+      const c = parsed as {
+        type?: unknown;
+        delta?: unknown;
+        text?: unknown;
+        toolName?: unknown;
+        toolCallId?: unknown;
+        input?: unknown;
+        output?: unknown;
+        errorText?: unknown;
+      };
+      switch (c.type) {
+        case "text-delta":
+        case "reasoning-delta": {
+          if (typeof c.delta === "string") {
+            textBuffer += c.delta;
+          }
+          break;
         }
-        break;
-      }
-      case "tool-output-error": {
-        flushText();
-        if (typeof c.toolCallId === "string") {
-          const meta = inFlightTools.get(c.toolCallId);
-          inFlightTools.delete(c.toolCallId);
-          process.stdout.write(
-            ` error (${meta?.toolName ?? "tool"}): ${
-              typeof c.errorText === "string" ? c.errorText : "unknown"
-            }\n`,
-          );
+        case "tool-input-start": {
+          flushText();
+          if (
+            typeof c.toolCallId === "string" &&
+            typeof c.toolName === "string"
+          ) {
+            inFlightTools.set(c.toolCallId, { toolName: c.toolName });
+            process.stdout.write(`\n→ ${c.toolName} …`);
+          }
+          break;
         }
-        break;
-      }
-      case "finish": {
-        flushText();
-        process.stdout.write("\n");
-        break;
+        case "tool-output-available": {
+          flushText();
+          if (typeof c.toolCallId === "string") {
+            const meta = inFlightTools.get(c.toolCallId);
+            inFlightTools.delete(c.toolCallId);
+            process.stdout.write(` done (${meta?.toolName ?? "tool"})\n`);
+          }
+          break;
+        }
+        case "tool-output-error": {
+          flushText();
+          if (typeof c.toolCallId === "string") {
+            const meta = inFlightTools.get(c.toolCallId);
+            inFlightTools.delete(c.toolCallId);
+            process.stdout.write(
+              ` error (${meta?.toolName ?? "tool"}): ${
+                typeof c.errorText === "string" ? c.errorText : "unknown"
+              }\n`,
+            );
+          }
+          break;
+        }
+        case "finish": {
+          gotFinish = true;
+          flushText();
+          if (!closeInFlightToolLines(" ended\n")) {
+            process.stdout.write("\n");
+          }
+          break;
+        }
+        case "error": {
+          flushText();
+          const msg =
+            typeof c.errorText === "string" ? c.errorText : "stream error";
+          process.stderr.write(`\n[error] ${msg}\n`);
+          break;
+        }
+        default:
+          break;
       }
-      case "error": {
-        flushText();
-        const msg =
-          typeof c.errorText === "string" ? c.errorText : "stream error";
-        process.stderr.write(`\n[error] ${msg}\n`);
-        break;
+    };
+
+    // Read SSE-style chunks. The route uses Vercel AI SDK's
+    // `createUIMessageStreamResponse` which emits `data: {…}\n\n`
+    // lines, so we split on double newlines.
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let nextBreak = buffer.indexOf("\n\n");
+      while (nextBreak !== -1) {
+        const event = buffer.slice(0, nextBreak);
+        buffer = buffer.slice(nextBreak + 2);
+        // Each event may contain multiple `data:` lines.
+        for (const line of event.split("\n")) {
+          if (line.trim().length > 0) handleChunk(line);
+        }
+        nextBreak = buffer.indexOf("\n\n");
       }
-      default:
-        break;
     }
-  };
+    flushText();
+    startIndex += responseChunkCount;
 
-  // Read SSE-style chunks. The route uses Vercel AI SDK's
-  // `createUIMessageStreamResponse` which emits `data: {…}\n\n`
-  // lines, so we split on double newlines.
-  while (true) {
-    const { value, done } = await reader.read();
-    if (done) break;
-    buffer += decoder.decode(value, { stream: true });
-    let nextBreak = buffer.indexOf("\n\n");
-    while (nextBreak !== -1) {
-      const event = buffer.slice(0, nextBreak);
-      buffer = buffer.slice(nextBreak + 2);
-      // Each event may contain multiple `data:` lines.
-      for (const line of event.split("\n")) {
-        if (line.trim().length > 0) handleChunk(line);
-      }
-      nextBreak = buffer.indexOf("\n\n");
+    const streamStatus = response.headers.get("x-workflow-stream-status");
+    const runActive = response.headers.get("X-Run-Active") !== "false";
+    if (gotFinish || !runActive || streamStatus === "terminal") {
+      closeInFlightToolLines(" ended\n");
+      return;
     }
+    // Segment rollover intentionally closes without `finish`; reconnect to
+    // the thread/run route, which resolves the new segment and resets the
+    // durable stream index when the segment identity changes. Empty active
+    // responses can occur during that handoff; back them off so a delayed
+    // rollover cannot turn into a tight polling loop.
+    consecutiveEmptyActiveResponses =
+      responseChunkCount === 0 ? consecutiveEmptyActiveResponses + 1 : 0;
+    const reconnectDelayMs =
+      responseChunkCount === 0
+        ? emptyActiveStreamBackoffMs(consecutiveEmptyActiveResponses)
+        : CHAT_STREAM_RECONNECT_DELAY_MS;
+    await new Promise((resolve) => setTimeout(resolve, reconnectDelayMs));
   }
-  flushText();
 }
 
 function joinPositionalsExceptFlags(args: string[]): string {
@@ -315,17 +409,20 @@ async function runChatNew(ctx: ChatSpawnContext): Promise<void> {
   const payload = result.payload as {
     threadId?: string;
     runId?: string;
+    workflowRunId?: string;
     threadUrl?: string;
     streamUrl?: string;
   } | null;
   out(ctx, payload);
 
-  if (follow && payload?.runId) {
+  if (follow && (payload?.threadId || payload?.workflowRunId)) {
     if (!ctx.jsonOutput) console.error("\n--- following stream ---");
     await followStream({
       host: ctx.runtime.host,
       bearerToken: ctx.runtime.bearerToken,
-      runId: payload.runId,
+      ...(payload.threadId
+        ? { threadId: payload.threadId }
+        : { runId: payload.workflowRunId }),
     });
   }
 }
@@ -371,17 +468,20 @@ async function runChatSend(ctx: ChatSpawnContext): Promise<void> {
   const payload = result.payload as {
     threadId?: string;
     runId?: string;
+    workflowRunId?: string;
     threadUrl?: string;
     streamUrl?: string;
   } | null;
   out(ctx, payload);
 
-  if (follow && payload?.runId) {
+  if (follow && (payload?.threadId || payload?.workflowRunId)) {
     if (!ctx.jsonOutput) console.error("\n--- following stream ---");
     await followStream({
       host: ctx.runtime.host,
       bearerToken: ctx.runtime.bearerToken,
-      runId: payload.runId,
+      ...(payload.threadId
+        ? { threadId: payload.threadId }
+        : { runId: payload.workflowRunId }),
     });
   }
 }
@@ -444,4 +544,4 @@ export async function runChatSpawnCommand(opts: {
   await runChatSend(ctx);
 }
 
-export { ChatSpawnError };
+export { ChatSpawnError, followStream };

package/crm.ts

@@ -90,8 +90,109 @@ type CrmCliContext = {
   sessionToken?: string;
   runId?: string;
   enrichmentGateway?: Pick<EnrichmentGatewayOptions, "apiKey" | "baseUrl">;
+  /** App origin used to build absolute entry deep links (e.g. https://www.dench.com). */
+  host?: string;
+  /** Workspace slug for absolute entry deep links (e.g. dench). */
+  workspaceSlug?: string;
 };
 
+/**
+ * Canonical CRM entry deep links.
+ *
+ * Absolute (shareable): `https://…/<slug>?path=<object>&entry=<object>:<id>`
+ * Relative (in-app):    `/?path=<object>&entry=<object>:<id>`
+ *
+ * Never invent `?object=` or a bare `entry=<id>` without the object prefix.
+ * `view` / `hidden` are optional UI chrome — not part of the canonical link.
+ */
+export function buildCrmEntryDeepLink(args: {
+  host?: string;
+  workspaceSlug?: string;
+  objectName: string;
+  entryId: string;
+}): { href: string; url?: string } {
+  const objectName = args.objectName.trim();
+  const entryId = args.entryId.trim();
+  // Keep a literal `:` between object and id (docs + in-app links); only
+  // encode the segments themselves so Convex ids stay readable.
+  const entryParam = `${encodeURIComponent(objectName)}:${encodeURIComponent(entryId)}`;
+  const pathParam = encodeURIComponent(objectName);
+  const href = `/?path=${pathParam}&entry=${entryParam}`;
+  const slug = args.workspaceSlug?.trim();
+  const host = args.host?.trim();
+  if (!slug || !host) {
+    return { href };
+  }
+  const withProtocol = /^https?:\/\//.test(host) ? host : `https://${host}`;
+  let base: string;
+  try {
+    base = new URL(withProtocol).origin;
+  } catch {
+    return { href };
+  }
+  return {
+    href,
+    url: `${base}/${encodeURIComponent(slug)}?path=${pathParam}&entry=${entryParam}`,
+  };
+}
+
+function entryIdFromUnknown(value: unknown): string | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  const record = value as JsonRecord;
+  for (const key of ["entryId", "id"]) {
+    const candidate = record[key];
+    if (typeof candidate === "string" && candidate.trim()) {
+      return candidate.trim();
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Canonical object name echoed by `entries.get` / `entries.create` /
+ * `batch.apply`. The server resolves display labels, case, and plurals
+ * (`lib/crm/resolveObject.ts`), so the name the caller typed is often NOT
+ * the one the workspace URL resolver matches on — it compares object names
+ * exactly. Always prefer this over the raw CLI argument.
+ */
+function canonicalObjectNameFromUnknown(value: unknown): string | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  const candidate = (value as JsonRecord).objectName;
+  return typeof candidate === "string" && candidate.trim()
+    ? candidate.trim()
+    : undefined;
+}
+
+function withCrmEntryDeepLinks(
+  ctx: CrmCliContext,
+  fallbackObjectName: string,
+  value: unknown,
+): unknown {
+  const entryId = entryIdFromUnknown(value);
+  if (!entryId || !value || typeof value !== "object" || Array.isArray(value)) {
+    return value;
+  }
+  // Older deployments don't echo `objectName`; the raw arg is the only
+  // thing left, and it's correct whenever the caller used the canonical name.
+  const objectName =
+    canonicalObjectNameFromUnknown(value) ?? fallbackObjectName;
+  const links = buildCrmEntryDeepLink({
+    host: ctx.host,
+    workspaceSlug: ctx.workspaceSlug,
+    objectName,
+    entryId,
+  });
+  return {
+    ...(value as JsonRecord),
+    href: links.href,
+    ...(links.url ? { url: links.url } : {}),
+  };
+}
+
 // Adapt the shared helpers to throw CrmCliError so existing call sites
 // don't need to change their try/catch shape.
 class CrmCliError extends Error {}
@@ -291,18 +392,22 @@ async function applyBatchOpsInChunks(
   ops: CrmBatchOp[],
   idempotencyKey: string | undefined,
   allowUnknown = false,
-): Promise<number> {
+): Promise<{ chunks: number; results: unknown[] }> {
   const chunks = chunkArray(ops, CRM_BATCH_CHUNK_SIZE);
+  const results: unknown[] = [];
   for (const [chunkIndex, chunk] of chunks.entries()) {
     const chunkKey = chunkIdempotencyKey(idempotencyKey, chunkIndex);
-    await callMutation(ctx, api.batch.apply, {
+    const batchResult = (await callMutation(ctx, api.batch.apply, {
       ops: chunk,
       ...runContextArgs(ctx),
       ...(chunkKey ? { idempotencyKey: chunkKey } : {}),
       ...(allowUnknown ? { allowUnknown: true } : {}),
-    });
+    })) as { results?: unknown[] } | null | undefined;
+    if (Array.isArray(batchResult?.results)) {
+      results.push(...batchResult.results);
+    }
   }
-  return chunks.length;
+  return { chunks: chunks.length, results };
 }
 
 function runContextArgs(ctx: CrmCliContext): Record<string, string> {
@@ -568,6 +673,20 @@ const api = {
     deleteView: makeFunctionReference<"mutation">(
       "functions/crm/objects:deleteView",
     ),
+    setArchived: makeFunctionReference<"mutation">(
+      "functions/crm/objects:setArchived",
+    ),
+    setViewPinned: makeFunctionReference<"mutation">(
+      "functions/crm/objects:setViewPinned",
+    ),
+  },
+  sidebar: {
+    describe: makeFunctionReference<"query">(
+      "functions/workspaceNav:describeMySidebar",
+    ),
+    reposition: makeFunctionReference<"mutation">(
+      "functions/workspaceNav:repositionMyNavItem",
+    ),
   },
   fields: {
     list: makeFunctionReference<"query">("functions/crm/fields:list"),
@@ -672,6 +791,8 @@ export async function runCrmCommand(opts: {
   args: string[];
   sessionToken?: string;
   enrichmentGateway?: Pick<EnrichmentGatewayOptions, "apiKey" | "baseUrl">;
+  host?: string;
+  workspaceSlug?: string;
 }): Promise<void> {
   const args = [...opts.args];
   const jsonOutput = hasFlag(args, "--json");
@@ -682,6 +803,8 @@ export async function runCrmCommand(opts: {
     sessionToken: opts.sessionToken,
     runId: process.env.DENCH_RUN_ID?.trim() || undefined,
     enrichmentGateway: opts.enrichmentGateway,
+    host: opts.host,
+    workspaceSlug: opts.workspaceSlug,
   };
   const subcommand = args.shift();
   if (!subcommand || subcommand === "help" || subcommand === "--help") {
@@ -693,6 +816,8 @@ export async function runCrmCommand(opts: {
       return await runObjectsCommand(ctx);
     case "views":
       return await runViewsCommand(ctx);
+    case "sidebar":
+      return await runSidebarCommand(ctx);
     case "fields":
       return await runFieldsCommand(ctx);
     case "entries":
@@ -833,6 +958,50 @@ async function runCrmMembersCommand(ctx: CrmCliContext): Promise<void> {
   });
 }
 
+/**
+ * `dench crm sidebar …` — the workspace app rail.
+ *
+ * Row VISIBILITY is team-shared and lives on the CRM records themselves
+ * (`crm objects archive`, `crm views pin/archive`). Row ORDER is a
+ * per-member preference, which is what `move` writes. `list` shows both
+ * halves: the visible rows with their 1-based positions, plus what's
+ * hidden and why.
+ */
+async function runSidebarCommand(ctx: CrmCliContext): Promise<void> {
+  const verb = ctx.args.shift() ?? "list";
+  switch (verb) {
+    case "list": {
+      assertNoUnknownFlags(ctx.args, "crm sidebar list");
+      out(ctx, await callQuery(ctx, api.sidebar.describe, {}));
+      return;
+    }
+    case "move": {
+      const navId = shift(ctx.args, "nav id");
+      const rawPosition = shift(ctx.args, "position");
+      assertNoUnknownFlags(ctx.args, "crm sidebar move");
+      let position: string | number;
+      if (rawPosition === "top" || rawPosition === "bottom") {
+        position = rawPosition;
+      } else {
+        const parsed = Number.parseInt(rawPosition, 10);
+        if (!Number.isFinite(parsed) || parsed < 1) {
+          throw new CrmCliError(
+            `position must be "top", "bottom", or a positive integer, got ${rawPosition}`,
+          );
+        }
+        position = parsed;
+      }
+      out(
+        ctx,
+        await callMutation(ctx, api.sidebar.reposition, { navId, position }),
+      );
+      return;
+    }
+    default:
+      throw new CrmCliError(`Unknown crm sidebar verb: ${verb}`);
+  }
+}
+
 async function runObjectsCommand(ctx: CrmCliContext): Promise<void> {
   const verb = ctx.args.shift();
   switch (verb) {
@@ -902,6 +1071,22 @@ async function runObjectsCommand(ctx: CrmCliContext): Promise<void> {
       out(ctx, await callMutation(ctx, api.objects.remove, { name }));
       return;
     }
+    // Archive is the sidebar's "remove from my rail", NOT a delete: the
+    // table, its rows and every link to it keep working, the row just
+    // moves into the rail's Archived flyout. Team-shared.
+    case "archive":
+    case "unarchive": {
+      const name = shift(ctx.args, "object name");
+      assertNoUnknownFlags(ctx.args, `crm objects ${verb}`);
+      out(
+        ctx,
+        await callMutation(ctx, api.objects.setArchived, {
+          name,
+          archived: verb === "archive",
+        }),
+      );
+      return;
+    }
     default:
       throw new CrmCliError(`Unknown crm objects verb: ${verb ?? "<none>"}`);
   }
@@ -1363,6 +1548,39 @@ async function runViewsCommand(ctx: CrmCliContext): Promise<void> {
       );
       return;
     }
+    // Only `pinned` views render as workspace sidebar rows. Pinning also
+    // clears any archive stamp, since a pinned-but-archived view still
+    // wouldn't show up.
+    case "pin":
+    case "unpin": {
+      const objectName = shift(ctx.args, "object name");
+      const viewName = shift(ctx.args, "view name");
+      assertNoUnknownFlags(ctx.args, `crm views ${verb}`);
+      out(
+        ctx,
+        await callMutation(ctx, api.objects.setViewPinned, {
+          objectName,
+          viewName,
+          pinned: verb === "pin",
+        }),
+      );
+      return;
+    }
+    case "archive":
+    case "unarchive": {
+      const objectName = shift(ctx.args, "object name");
+      const viewName = shift(ctx.args, "view name");
+      assertNoUnknownFlags(ctx.args, `crm views ${verb}`);
+      out(
+        ctx,
+        await callMutation(ctx, api.objects.setArchived, {
+          name: objectName,
+          viewName,
+          archived: verb === "archive",
+        }),
+      );
+      return;
+    }
     default:
       throw new CrmCliError(`Unknown crm views verb: ${verb ?? "<none>"}`);
   }
@@ -1624,10 +1842,14 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
       assertNoUnknownFlags(ctx.args, "crm entries get");
       out(
         ctx,
-        await callQuery(ctx, api.entries.get, {
+        withCrmEntryDeepLinks(
+          ctx,
           objectName,
-          entryId: entryId as any,
-        }),
+          await callQuery(ctx, api.entries.get, {
+            objectName,
+            entryId: entryId as any,
+          }),
+        ),
       );
       return;
     }
@@ -1657,12 +1879,16 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
       // pre-fetch — that would add a round-trip to every create.
       out(
         ctx,
-        await callMutation(ctx, api.entries.create, {
+        withCrmEntryDeepLinks(
+          ctx,
           objectName,
-          data,
-          ...runContextArgs(ctx),
-          ...(allowUnknown ? { allowUnknown: true } : {}),
-        }),
+          await callMutation(ctx, api.entries.create, {
+            objectName,
+            data,
+            ...runContextArgs(ctx),
+            ...(allowUnknown ? { allowUnknown: true } : {}),
+          }),
+        ),
       );
       return;
     }
@@ -1680,7 +1906,7 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
         }),
       );
       await assertKnownDataKeys(ctx, objectName, rows, allowUnknown);
-      const chunks = await applyBatchOpsInChunks(
+      const { chunks, results } = await applyBatchOpsInChunks(
         ctx,
         rows.map((data) => ({
           type: "entries.create",
@@ -1690,7 +1916,41 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
         idempotencyKey,
         allowUnknown,
       );
-      out(ctx, { created: rows.length, chunks });
+      // Only claim per-row links when we actually got a result per row. A
+      // silently-empty `results` is indistinguishable from "this object has
+      // no links" and sends the agent right back to inventing URLs — the
+      // exact failure this command's `url`/`href` output exists to prevent.
+      const linked = results.length;
+      out(ctx, {
+        created: rows.length,
+        chunks,
+        ...(linked > 0
+          ? {
+              results: results.map((result) =>
+                withCrmEntryDeepLinks(ctx, objectName, result),
+              ),
+            }
+          : {}),
+        ...(linked === rows.length
+          ? {}
+          : {
+              linksUnavailable: true,
+              // The recovery path has to be followable. With zero results
+              // there is no entryId to hand to `entries get`, so point at
+              // `entries list` (it returns `id` per row) instead — a hint
+              // the agent can't act on just sends it back to guessing.
+              linksHint:
+                `Got ${linked} link(s) for ${rows.length} row(s). ` +
+                (linked === 0
+                  ? `Run \`dench crm entries list ${objectName} --json\` to get each row's ` +
+                    `\`id\`, then \`dench crm entries get ${objectName} <id> --json\` for its ` +
+                    "canonical url"
+                  : `The rows above carry \`url\`/\`href\`; for the rest run ` +
+                    `\`dench crm entries list ${objectName} --json\` to get their \`id\`, then ` +
+                    `\`dench crm entries get ${objectName} <id> --json\``) +
+                " — do not construct a url by hand.",
+            }),
+      });
       return;
     }
     case "update": {
@@ -1743,7 +2003,7 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
         updates.map((update) => update.data),
         allowUnknown,
       );
-      const chunks = await applyBatchOpsInChunks(
+      const { chunks } = await applyBatchOpsInChunks(
         ctx,
         updates.map((update) => ({
           type: "entries.update",
@@ -1874,7 +2134,7 @@ async function runCellsCommand(ctx: CrmCliContext): Promise<void> {
           data,
         }),
       );
-      const chunks = await applyBatchOpsInChunks(ctx, ops, idempotencyKey);
+      const { chunks } = await applyBatchOpsInChunks(ctx, ops, idempotencyKey);
       out(ctx, { updated: updates.length, entriesUpdated: ops.length, chunks });
       return;
     }
@@ -3287,6 +3547,10 @@ Objects (CRM tables):
       command/API identifier (works on protected objects too).
   dench crm objects rename <from> <to>
   dench crm objects delete <name>
+  dench crm objects archive <name> | unarchive <name>
+      Hides/restores the object's workspace SIDEBAR row. Not a delete —
+      the table, its rows and every link keep working; the row just moves
+      into the rail's Archived flyout. Team-shared.
 
 Views (saved CRM subsets):
   dench crm views list <object> [--json]
@@ -3306,6 +3570,22 @@ Views (saved CRM subsets):
   dench crm views delete <object> <view-name>
       Idempotent; also clears the active-view pointer if it referenced
       the deleted view.
+  dench crm views pin <object> <view-name> | unpin <object> <view-name>
+      Only pinned views render as workspace sidebar rows. Pinning also
+      clears any archive stamp.
+  dench crm views archive <object> <view-name> | unarchive <object> <view-name>
+      Moves the view's sidebar row into the Archived flyout. Unarchiving
+      re-asserts the pin so the row comes back.
+
+Sidebar (the workspace app rail):
+  dench crm sidebar list [--json]
+      Visible rows in order with 1-based positions, plus what's hidden
+      from the rail and why (archived vs. an unpinned view).
+  dench crm sidebar move <nav-id> <top|bottom|N>
+      Reposition one row. Nav ids come from 'sidebar list' — e.g.
+      'crm-object:task', 'crm-view:task:Due%20today', 'crm-people',
+      'automation'. Row ORDER is per-member; row visibility (above) is
+      team-shared.
 
 Fields (columns):
   dench crm fields list <object> [--json]
@@ -3368,6 +3648,18 @@ Entries (rows):
         being silently dropped. Verify names with 'crm fields list <object>'
         first. Pass --allow-unknown to write the raw value anyway, and on
         create the object's required fields must be present.
+        create / get / create-many also return deep links when the
+        workspace slug is known: \`url\` (absolute shareable) and \`href\`
+        (relative in-app). Paste those — never invent \`?object=\` or a
+        bare \`entry=<id>\` without the \`<object>:\` prefix. Canonical form:
+        /<slug>?path=<object>&entry=<object>:<entryId>
+        The link uses the object's CANONICAL name (echoed back as
+        \`objectName\`), not the alias you typed — \`create Tasks\` resolves
+        server-side but only \`task\` opens the record. If a response has no
+        \`url\`/\`href\`, run 'crm entries get <object> <entryId> --json' for
+        one. If create-many reports \`linksUnavailable\`, the unlinked rows
+        have no id in that response — run 'crm entries list <object> --json'
+        to recover their \`id\` first.
 
 Cells (single-field updates):
   dench crm cells get <object> <entryId> <field>
@@ -3393,11 +3685,14 @@ Workspace members (for user-type fields):
       List \`{ userId, role, name, email }\` for every member of the
       current org. Use the userIds when setting \`Owner\`, \`Assignee\`,
       or any other \`user\`-type field so the UI shows a real linked
-      avatar instead of an unlinked literal-string badge. Check the
+      avatar instead of an unlinked literal-string badge. Pass one id for
+      one assignee or a JSON array for multiple assignees; never drop a
+      co-owner from the source data. Check the
       object's actual field names first (\`crm fields list <object>\`) —
       the \`task\` object uses \`Assignee\`, not \`Owner\`, and some
       workspaces rename \`Name\` to \`Title\`:
         dench crm cells set task <entryId> Assignee '"<userId>"'
+        dench crm cells set task <entryId> Assignee '["<userId1>","<userId2>"]'
         dench crm entries create task --data '{"Name":"X","Assignee":"<userId>"}'
 
 Batch:

package/dench.ts

@@ -10,7 +10,7 @@ import {
   writeFile,
 } from "node:fs/promises";
 import { homedir, hostname, userInfo } from "node:os";
-import { basename, join, relative, resolve } from "node:path";
+import { basename, dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ConvexHttpClient } from "convex/browser";
 import { makeFunctionReference } from "convex/server";
@@ -579,6 +579,7 @@ returns ENOSYS on the FUSE-backed volume mount):
   dench files ls <path> [--json]
   dench files mv <src> <dst> [--json]
   dench files rm <path> [--recursive] [--json]
+  dench files download <path> [<local-dest>] [--url] [--json]
 
 Persist scratch -> workspace (cp from /tmp into /workspace + Convex sync):
   dench stage <local-path> [<workspace-dest>] [--clean] [--json]
@@ -3412,19 +3413,151 @@ async function runFilesRm() {
   });
 }
 
+async function writeLocalFileBytes(localPath: string, bytes: Uint8Array) {
+  const parent = dirname(localPath);
+  if (parent && parent !== ".") {
+    await mkdir(parent, { recursive: true });
+  }
+  await writeFile(localPath, bytes);
+}
+
+async function runFilesDownload() {
+  const runtime = await getRuntime();
+  const apiKey = await requireFilesApiKey(runtime, "dench files download");
+  const targetRaw = positional(2);
+  if (!targetRaw) {
+    throw new CliError(
+      "Usage: dench files download <path> [<local-dest>] [--url]",
+      { code: "files_download_usage" },
+    );
+  }
+  const target = normalizeFilesPath(targetRaw);
+  const jsonOut = hasFlag("--json");
+
+  if (hasFlag("--url")) {
+    const url = (await runtime.client.action(
+      api.functions.files.getFileSignedDownloadUrl,
+      { path: target, apiKey } as never,
+    )) as string | null;
+    if (!url) {
+      throw new CliError(`No downloadable bytes for ${target}`, {
+        code: "files_download_url_not_found",
+        nextActions: [
+          "Directories have no signed URL; run `dench files download <dir>` without --url to fetch the tree.",
+          "Run `dench files ls` on the parent directory to confirm the path.",
+        ],
+      });
+    }
+    if (jsonOut) {
+      print({ ok: true, path: target, url, note: "Signed URL expires." });
+    } else {
+      process.stdout.write(`${url}\n`);
+    }
+    return;
+  }
+
+  const self =
+    target === "/"
+      ? null
+      : (await listConvexTreeAt(runtime, apiKey, parentOfPath(target))).find(
+          (row) => row.path === target,
+        );
+  const isDir = target === "/" || self?.isDir === true;
+
+  if (!isDir) {
+    const bytes = await downloadConvexFileBytes(runtime, apiKey, target);
+    if (!bytes) {
+      throw new CliError(`Not found in Convex: ${target}`, {
+        code: "files_download_not_found",
+        nextActions: [
+          "Run `dench files ls` on the parent directory to confirm.",
+          "If the file only exists on the sandbox FS, run `dench fs sync --initial` first.",
+        ],
+      });
+    }
+    let dest = resolve(positional(3) ?? basename(target));
+    const destStat = await stat(dest).catch(() => null);
+    if (destStat?.isDirectory()) {
+      dest = join(dest, basename(target));
+    }
+    await writeLocalFileBytes(dest, bytes);
+    if (jsonOut) {
+      print({ ok: true, path: target, dest, bytes: bytes.byteLength });
+    } else {
+      process.stdout.write(
+        `dench files download: ${target} -> ${dest} (${bytes.byteLength}B)\n`,
+      );
+    }
+    return;
+  }
+
+  // Directory: recreate the tree locally under <local-dest> (defaults to
+  // the directory's basename in the cwd).
+  const destRoot = resolve(
+    positional(3) ?? (target === "/" ? "workspace" : basename(target)),
+  );
+  const rows = await listConvexTreeRecursive(runtime, apiKey, target);
+  const prefixLength = target === "/" ? 1 : target.length + 1;
+  let downloaded = 0;
+  let bytesTotal = 0;
+  const skipped: string[] = [];
+  await mkdir(destRoot, { recursive: true });
+  for (const row of rows) {
+    const rel = row.path.slice(prefixLength);
+    if (!rel) continue;
+    const local = join(destRoot, rel);
+    if (row.isDir) {
+      await mkdir(local, { recursive: true });
+      continue;
+    }
+    const bytes = await downloadConvexFileBytes(runtime, apiKey, row.path);
+    if (!bytes) {
+      skipped.push(row.path);
+      continue;
+    }
+    await writeLocalFileBytes(local, bytes);
+    downloaded += 1;
+    bytesTotal += bytes.byteLength;
+    if (!jsonOut && downloaded % 25 === 0) {
+      process.stdout.write(
+        `dench files download: ${downloaded} files, ${bytesTotal}B…\n`,
+      );
+    }
+  }
+  if (jsonOut) {
+    print({
+      ok: true,
+      path: target,
+      dest: destRoot,
+      files: downloaded,
+      bytes: bytesTotal,
+      skipped,
+    });
+  } else {
+    process.stdout.write(
+      `dench files download: ${downloaded} files (${bytesTotal}B) -> ${destRoot}${
+        skipped.length > 0 ? ` (${skipped.length} skipped)` : ""
+      }\n`,
+    );
+  }
+}
+
 async function runFilesCommand() {
   const sub = positional(1);
   if (!sub || sub === "help" || hasFlag("--help")) {
     process.stdout.write(
       [
-        "dench files <ls|mv|rm> — workspace file ops that update the UI tree",
+        "dench files <ls|mv|rm|download> — workspace file ops that update the UI tree",
         "",
         "  dench files ls [<path>] [--recursive] [--json]",
         "  dench files mv <src> <dst> [--json]",
         "  dench files rm <path> [--recursive] [--json]",
+        "  dench files download <path> [<local-dest>] [--url] [--json]",
         "",
         "Paths are POSIX paths under /workspace; you can pass either form.",
         "These mutate Convex directly (and the daemon syncs to the volume).",
+        "download fetches canonical bytes from Convex (dirs recurse);",
+        "--url prints a short-lived signed URL instead of saving.",
       ].join("\n"),
     );
     return;
@@ -3432,6 +3565,7 @@ async function runFilesCommand() {
   if (sub === "ls") return await runFilesLs();
   if (sub === "mv") return await runFilesMv();
   if (sub === "rm") return await runFilesRm();
+  if (sub === "download") return await runFilesDownload();
   throw new CliError(`Unknown subcommand: dench files ${sub}`, {
     code: "files_unknown_subcommand",
     nextActions: ["Run dench files help for usage."],
@@ -3901,6 +4035,8 @@ async function main() {
         convex: runtime.client,
         args: subArgs,
         sessionToken: encodeDevCrmSessionToken(runtime.workspaceArgs),
+        host: resolveApiHost(LOCAL_HOST),
+        workspaceSlug: runtime.workspaceArgs.workspaceSlug,
         enrichmentGateway: gatewayAuth
           ? {
               apiKey: gatewayAuth.bearerToken,
@@ -3919,6 +4055,11 @@ async function main() {
       convex: authedRuntime.client,
       args: subArgs,
       sessionToken: authedRuntime.sessionToken,
+      host: authedRuntime.host,
+      workspaceSlug:
+        authedRuntime.organization?.slug ??
+        process.env.DENCH_ORG_SLUG?.trim() ??
+        undefined,
       enrichmentGateway: gatewayAuth
         ? {
             apiKey: gatewayAuth.bearerToken,

package/lib/api-schemas.ts

@@ -44,7 +44,7 @@ export const FIELD_TYPES = [
 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.",
+    "Field data type. `relation` needs relatedObjectName + relationshipType; `enum` uses enumValues/enumColors; `user` cells store one member userId or an array of member userIds; long prose belongs in the protected `Notes` richtext field.",
   );
 
 const viewKind = z
@@ -139,12 +139,14 @@ const scheduleSpec = z
 
 const dataMap = z
   .record(z.string(), z.unknown())
-  .describe("Field-name -> value map. Use member userIds for `user` fields.");
+  .describe(
+    "Field-name -> value map. For `user` fields use one member userId or a userId array; preserve every assignee.",
+  );
 
 const cellValue = z
   .unknown()
   .describe(
-    "Cell value. Enum=option string, tags=string array, user=member userId, relation=related entry id, boolean=true/false.",
+    "Cell value. Enum=option string, tags=string array, user=one member userId or a userId array, relation=related entry id, boolean=true/false.",
   );
 
 const enrichmentConfig = z
@@ -2124,8 +2126,14 @@ export const responseSchemas: Record<string, ZodTypeAny> = {
         id: z.string(),
         role: z.enum(["user", "assistant", "system"]),
         createdAt: z.number(),
+        updatedAt: z.number(),
         text: z.string(),
         runId: z.string().nullable(),
+        status: z
+          .enum(["streaming", "complete", "error", "canceled"])
+          .nullable(),
+        revision: z.number(),
+        isDraft: z.boolean(),
       }),
     ),
   }),
@@ -2277,7 +2285,6 @@ export const responseSchemas: Record<string, ZodTypeAny> = {
         _creationTime: z.number(),
         objectId: z.string(),
         data: fieldsMap,
-        searchableText: z.string(),
         sortOrder: z.number(),
         createdAt: z.number(),
         updatedAt: z.number(),
@@ -2796,7 +2803,11 @@ export const requestExamples: Record<string, unknown> = {
   "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" },
+    data: {
+      Name: "Joint review",
+      Assignee: ["user_kumar", "user_mark"],
+      Status: "New",
+    },
   },
   "crm.entries.createMany": {
     entries: [
@@ -2804,7 +2815,7 @@ export const requestExamples: Record<string, unknown> = {
       { Name: "Bob", Email: "bob@example.com" },
     ],
   },
-  "crm.cells.set": { value: "In progress" },
+  "crm.cells.set": { value: ["user_kumar", "user_mark"] },
   "crm.query": {
     objectName: "lead",
     dslJson:
@@ -3125,15 +3136,23 @@ export const responseExamples: Record<string, unknown> = {
         id: "cm_def456",
         role: "user",
         createdAt: 1765526400000,
+        updatedAt: 1765526400000,
         text: "How do we deploy?",
         runId: null,
+        status: "complete",
+        revision: 0,
+        isDraft: false,
       },
       {
         id: "cm_ghi789",
         role: "assistant",
         createdAt: 1765526460000,
+        updatedAt: 1765526460000,
         text: "Push to main; Vercel auto-deploys.",
         runId: "rn_jkl012",
+        status: "complete",
+        revision: 1,
+        isDraft: false,
       },
     ],
   },
@@ -3368,7 +3387,6 @@ export const responseExamples: Record<string, unknown> = {
       _creationTime: 1765526400000,
       objectId: "obj_lead01",
       data: { Name: "Acme Corp", Status: "Qualified" },
-      searchableText: "Acme Corp Qualified",
       sortOrder: 0,
       createdAt: 1765526400000,
       updatedAt: 1765612800000,

package/lib/command-registry.ts

@@ -1961,7 +1961,7 @@ const rawApiOperations = [
     id: "files.downloadUrl",
     group: "files",
     summary: "Get a signed file download URL.",
-    cli: "dench files ls",
+    cli: "dench files download",
     method: "GET",
     path: "/files/download-url",
     requestSchema: noBody,

package/members.ts

@@ -168,7 +168,9 @@ function membersHelp(): void {
 
 Workspace members for the active organization. Use these userIds when
 assigning CRM \`user\`-type cells (e.g. \`Owner\`, \`Assignee\`) so the
-UI shows a real linked avatar instead of an unlinked literal string.
+UI shows real linked avatars instead of unlinked literal strings. Use one id
+for one assignee or a JSON id array for multiple assignees; preserve every
+owner from the source data.
 
 Subcommands:
   dench members list [--json]
@@ -185,6 +187,7 @@ After picking a userId (confirm field names with
 \`dench crm fields list <object>\` — the default \`task\` uses
 \`Assignee\`, not \`Owner\`, and some workspaces rename \`Name\` to \`Title\`):
   dench crm cells set task <entryId> Assignee '"<userId>"'
+  dench crm cells set task <entryId> Assignee '["<userId1>","<userId2>"]'
   dench crm entries create task --data '{"Name":"Ship CRM","Assignee":"<userId>"}'
 
 The server best-effort-resolves a name / email passed to a \`user\`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dench.com/cli",
-  "version": "2.7.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.",
+  "version": "2.7.2",
+  "description": "Dench agent workspace CLI.",
   "type": "module",
   "bin": {
     "dench": "dench",