@dench.com/cli 0.3.6 → 0.3.8

package/README.md

@@ -195,11 +195,14 @@ dench crm entries list people
 
 Auth precedence:
 
-1. `--dev` flag → use the dev workspace env (`NEXT_PUBLIC_CONVEX_URL`,
+1. Explicit `--dev` flag → use the dev workspace env (`NEXT_PUBLIC_CONVEX_URL`,
    `DENCH_WORKSPACE`, `DENCH_DEV_AGENT_KEY`).
 2. A locally-stored `dench login` session for the current host.
 3. `DENCH_API_KEY` + `CONVEX_URL` (sandbox / automation path).
-4. `--dev`-style env vars (without the flag).
+
+Plain terminal usage does not silently fall back to dev env vars. Without
+`--dev`, a saved session, or `DENCH_API_KEY` + `CONVEX_URL`, live commands
+return `login_required`.
 
 Commands that need to impersonate a specific agent (`dench memory`,
 `dench task`, `dench claim`, `dench log`, `dench approval request`,

package/agent.ts

@@ -34,6 +34,20 @@ type CliCtx = {
   convex: ConvexHttpClient;
   args: string[];
   jsonOutput: boolean;
+  /**
+   * Bearer token forwarded by the dispatcher in `cli/dench.ts`. Either a
+   * `dch_agent_*` agent session minted by `dench login` or a unified
+   * Dench API key (`DENCH_API_KEY`) when the CLI is running inside a
+   * sandbox. Used by `runAwait` to authenticate against
+   * `runs:getChildRunStatusForCli`.
+   */
+  sessionToken?: string;
+  /**
+   * Convex `runs._id` of the caller's own run, when authenticated via
+   * an API key (sandbox path). Required by `getChildRunStatusForCli`
+   * to scope the API key's reach to a specific organization.
+   */
+  callerRunId?: string;
 };
 
 // Args helpers moved to cli/lib/cli-args.ts; we adapt shift to throw
@@ -137,10 +151,18 @@ async function postJson(
 export async function runAgentCommand(opts: {
   convex: ConvexHttpClient;
   args: string[];
+  sessionToken?: string;
+  callerRunId?: string;
 }): Promise<void> {
   const args = [...opts.args];
   const jsonOutput = hasFlag(args, "--json");
-  const ctx: CliCtx = { convex: opts.convex, args, jsonOutput };
+  const ctx: CliCtx = {
+    convex: opts.convex,
+    args,
+    jsonOutput,
+    sessionToken: opts.sessionToken,
+    callerRunId: opts.callerRunId,
+  };
   const subcommand = args.shift();
   if (!subcommand || subcommand === "help" || subcommand === "--help") {
     agentHelp();
@@ -243,27 +265,81 @@ async function runAwait(ctx: CliCtx): Promise<void> {
       "dench agent await requires --hook <token> or --children <csv>",
     );
   }
-  // Polling fallback: subscribe to runs via Convex realtime would be the
-  // proper implementation; for v1 we poll status fields every 2s.
-  const childIds = childIdsCsv.split(",").map((id) => id.trim()).filter(Boolean);
-  const completed: Record<string, string> = {};
+  if (!ctx.sessionToken) {
+    throw new AgentCliError(
+      "dench agent await --children needs an authenticated session " +
+        "(run `dench login`, or set DENCH_API_KEY in a sandbox)",
+    );
+  }
+
+  const childIds = childIdsCsv
+    .split(",")
+    .map((id) => id.trim())
+    .filter(Boolean);
+  if (childIds.length === 0) {
+    throw new AgentCliError("--children requires at least one run id");
+  }
   const start = Date.now();
   const timeoutMs = parseInt(
     getFlag(ctx.args, "--timeout-ms") ?? "3600000",
     10,
   );
+  const intervalMs = parseInt(
+    getFlag(ctx.args, "--interval-ms") ?? "2000",
+    10,
+  );
+
+  type ChildSnapshot = {
+    runId: string;
+    status: string;
+    summary: string | null;
+    threadId: string | null;
+    terminal: boolean;
+  };
+  const getStatus = makeFunctionReference<"query">(
+    "functions/runs:getChildRunStatusForCli",
+  );
+
+  // Poll each child's status until it reaches a terminal state. The
+  // server uses sessionToken auth (mirrors `dench chat list`) so this
+  // works both for `dch_agent_*` sessions (local dev) and for unified
+  // `DENCH_API_KEY`s (sandbox, must include `--caller-run-id`).
+  const completed: Record<string, ChildSnapshot> = {};
   while (Object.keys(completed).length < childIds.length) {
     if (Date.now() - start > timeoutMs) {
-      throw new AgentCliError("dench agent await timed out");
+      throw new AgentCliError(
+        `dench agent await timed out after ${timeoutMs}ms with ${
+          Object.keys(completed).length
+        }/${childIds.length} children completed`,
+      );
     }
     for (const childId of childIds) {
       if (completed[childId]) continue;
-      // Reading status requires a query; for v1 use a tight loop on the
-      // public runs.getRun. (Wired in P5 once DenchClient lands.)
-      completed[childId] = "pending";
+      try {
+        const snap = (await ctx.convex.query(getStatus, {
+          sessionToken: ctx.sessionToken,
+          runId: ctx.callerRunId ?? undefined,
+          childRunId: childId as never,
+        })) as ChildSnapshot | null;
+        if (snap?.terminal) {
+          completed[childId] = snap;
+        }
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        // Treat "not found" / access errors as terminal-with-error so
+        // we don't poll forever on a typo'd id.
+        completed[childId] = {
+          runId: childId,
+          status: "error",
+          summary: msg,
+          threadId: null,
+          terminal: true,
+        };
+      }
+    }
+    if (Object.keys(completed).length < childIds.length) {
+      await new Promise((resolve) => setTimeout(resolve, intervalMs));
     }
-    await new Promise((resolve) => setTimeout(resolve, 2000));
-    break; // v1 polling stub — placeholder
   }
   out(ctx, { children: completed });
 }
@@ -367,12 +443,18 @@ function agentHelp(): void {
 Spawn a chat-turn workflow (same as the web UI's chat panel):
   dench agent new "<prompt>" [--model <m>] [--file-context <path>] [--visibility private|shared] [--title T] [--yolo] [--follow] [--json]
   dench agent send <thread-id> "<message>" [--model <m>] [--yolo] [--follow] [--json]
-  These are aliases for \`dench chat new\` / \`dench chat send\`.
+  dench agent follow <thread-id> [--json]
+  These are aliases for \`dench chat new\` / \`dench chat send\` / \`dench chat follow\`.
+  Use \`follow\` to tail the live stream of an existing thread (e.g.
+  a subagent spawned by \`spawn_agent\`) without sending a new message.
 
 Subagents (autonomous Long Sessions, NOT chat threads):
   dench agent spawn '<goal>' [--parent-run-id <id>] [--sandbox own|share_parent] [--time-budget-ms N]
   dench agent await --hook <token>
-  dench agent await --children id1,id2,id3 [--timeout-ms N]
+  dench agent await --children id1,id2,id3 [--timeout-ms N] [--interval-ms N]
+                                            (polls runs:getChildRunStatusForCli
+                                             with the active session token until
+                                             every child is terminal)
 
 Peer messaging:
   dench agent message <toRunId> '<text...>' [--from-run-id <id>]

package/chat-spawn.ts

@@ -87,21 +87,47 @@ function buildSpawnUrl(host: string): string {
   return `${host.replace(/\/+$/, "")}/api/chat/cli`;
 }
 
-function buildStreamUrl(host: string, runId: string): string {
+function buildStreamUrlByRunId(host: string, runId: string): string {
   return `${host.replace(/\/+$/, "")}/api/chat/${encodeURIComponent(runId)}/stream`;
 }
 
+function buildStreamUrlByThreadId(host: string, threadId: string): string {
+  return `${host.replace(/\/+$/, "")}/api/chat/stream?sessionId=${encodeURIComponent(threadId)}`;
+}
+
 /**
  * Subscribe to the durable chat stream and pretty-print useful chunks
  * until the stream closes. Mirrors the chunk types the chat panel
  * cares about (text deltas, reasoning, tool input/output, finish).
+ *
+ * Resolves the stream URL from EITHER:
+ *   - `runId` (Workflow SDK run id, returned in `x-workflow-run-id`
+ *     by `POST /api/chat/cli`), via `/api/chat/[runId]/stream`, OR
+ *   - `threadId` (Convex `chatThreads._id`), via
+ *     `/api/chat/stream?sessionId=...` which resolves the active run
+ *     by following `chatThreads.activeRunId → runs.workflowRunId`.
+ *
+ * The thread-id path is what `dench chat follow <threadId>` uses, so
+ * we can tail any live thread (including a subagent created by
+ * `spawn_agent`) without needing to know its workflow run id ahead of
+ * time.
  */
 async function followStream(args: {
   host: string;
   bearerToken: string;
-  runId: string;
+  runId?: string;
+  threadId?: string;
 }): Promise<void> {
-  const url = buildStreamUrl(args.host, args.runId);
+  const url = args.runId
+    ? buildStreamUrlByRunId(args.host, args.runId)
+    : args.threadId
+      ? buildStreamUrlByThreadId(args.host, args.threadId)
+      : null;
+  if (!url) {
+    throw new ChatSpawnError(
+      "followStream requires either { runId } or { threadId }",
+    );
+  }
   const response = await fetch(url, {
     method: "GET",
     headers: {
@@ -342,6 +368,37 @@ async function runChatSend(ctx: ChatSpawnContext): Promise<void> {
   }
 }
 
+/**
+ * `dench chat follow <threadId>` — tail the live stream of an
+ * existing chat thread by Convex thread id.
+ *
+ * Useful for watching a subagent (a child thread spawned by a parent
+ * via `spawn_agent`) live, or for resuming the stream of any chat
+ * thread that's currently in flight. Resolves the active workflow run
+ * server-side via `chatThreads.activeRunId → runs.workflowRunId`, so
+ * the caller doesn't need to know any workflow ids.
+ *
+ * Exits when the stream closes (workflow finishes) or when the user
+ * hits Ctrl-C.
+ */
+async function runChatFollow(ctx: ChatSpawnContext): Promise<void> {
+  const positionals = ctx.args.filter((arg) => !arg.startsWith("--"));
+  const threadId = positionals.shift();
+  if (!threadId) {
+    throw new ChatSpawnError(
+      "Usage: dench chat follow <threadId> [--json]",
+    );
+  }
+  if (!ctx.jsonOutput) {
+    console.error(`--- following stream for thread ${threadId} ---`);
+  }
+  await followStream({
+    host: ctx.runtime.host,
+    bearerToken: ctx.runtime.bearerToken,
+    threadId,
+  });
+}
+
 /**
  * Public entry point invoked by the chat dispatcher in cli/dench.ts
  * (and the agent dispatcher when the user runs `dench agent new` /
@@ -351,7 +408,7 @@ async function runChatSend(ctx: ChatSpawnContext): Promise<void> {
 export async function runChatSpawnCommand(opts: {
   runtime: RuntimeBundle;
   args: string[];
-  subcommand: "new" | "send";
+  subcommand: "new" | "send" | "follow";
 }): Promise<void> {
   const args = [...opts.args];
   const jsonOutput = hasFlag(args, "--json");
@@ -364,6 +421,10 @@ export async function runChatSpawnCommand(opts: {
     await runChatNew(ctx);
     return;
   }
+  if (opts.subcommand === "follow") {
+    await runChatFollow(ctx);
+    return;
+  }
   await runChatSend(ctx);
 }
 

package/chat.ts

@@ -111,7 +111,12 @@ Read messages from a specific past chat thread:
 Spawn a new chat-turn workflow (same agent loop as the web UI):
   dench chat new "<prompt>" [--model <m>] [--file-context <path>] [--visibility private|shared] [--title T] [--yolo] [--follow] [--json]
   dench chat send <thread-id> "<message>" [--model <m>] [--yolo] [--follow] [--json]
-  Aliased as: dench agent new / dench agent send.
+  dench chat follow <thread-id> [--json]
+  dench chat tree [<root-thread-id>] [--limit N] [--json]
+  Aliased as: dench agent new / dench agent send / dench agent follow.
+  Use \`follow\` to tail any live thread by id (e.g. a subagent
+  spawned by another chat). Use \`tree\` to print the parent-child
+  thread hierarchy from a root thread.
 
 Approval policy:
   Without --yolo the workflow uses the workspace policy from
@@ -156,6 +161,8 @@ export async function runChatCommand(opts: {
       return await runChatSearchCommand(ctx);
     case "read":
       return await runChatReadCommand(ctx);
+    case "tree":
+      return await runChatTreeCommand(ctx);
     default:
       throw new ChatCliError(`Unknown chat subcommand: ${subcommand}`);
   }
@@ -214,3 +221,129 @@ async function runChatReadCommand(ctx: ChatCliContext): Promise<void> {
     }),
   );
 }
+
+/**
+ * `dench chat tree [<root-thread-id>] [--limit N] [--json]` — print the
+ * parent-child chat thread hierarchy rooted at the given thread (or
+ * roots = top-level chats if no id is passed).
+ *
+ * Uses `listPastChats` (which already includes nested threads in its
+ * results — `topLevelOnly` is a `listThreads`-only knob) and groups
+ * client-side by `parentThreadId`. With `--json`, prints the raw flat
+ * array; otherwise prints an indented tree with status + a short
+ * summary excerpt for each row.
+ */
+async function runChatTreeCommand(ctx: ChatCliContext): Promise<void> {
+  // Strip flag values from positionals so e.g. `tree --limit 30` doesn't
+  // misinterpret "30" as the rootThreadId. We treat "--key value" as a
+  // pair iff value doesn't itself start with "--".
+  const positionals: string[] = [];
+  for (let i = 0; i < ctx.args.length; i++) {
+    const arg = ctx.args[i];
+    if (arg.startsWith("--")) {
+      const next = ctx.args[i + 1];
+      if (next !== undefined && !next.startsWith("--")) {
+        i += 1; // skip the flag value
+      }
+      continue;
+    }
+    positionals.push(arg);
+  }
+  const rootThreadId = positionals[0]?.trim() || undefined;
+  const limit = parseLimit(getFlag(ctx.args, "--limit")) ?? 200;
+
+  const flat = (await callQuery(ctx, api.listPastChats, {
+    limit,
+    includeArchived: false,
+  })) as Array<{
+    threadId: string;
+    title: string;
+    status: string;
+    parentThreadId: string | null;
+    nestingDepth: number | null;
+    summary: string | null;
+    lastMessageAt: number;
+    createdAt: number;
+    activeRunId: string | null;
+  }>;
+
+  if (ctx.jsonOutput) {
+    out(ctx, flat);
+    return;
+  }
+
+  // Group by parent. Top-level rows = either no parent, or parent
+  // outside the loaded set (so we don't silently swallow children
+  // whose parent fell off the limit window).
+  const ids = new Set(flat.map((t) => t.threadId));
+  const childrenByParent = new Map<string, typeof flat>();
+  const roots: typeof flat = [];
+  for (const thread of flat) {
+    if (thread.parentThreadId && ids.has(thread.parentThreadId)) {
+      let list = childrenByParent.get(thread.parentThreadId);
+      if (!list) {
+        list = [];
+        childrenByParent.set(thread.parentThreadId, list);
+      }
+      list.push(thread);
+      continue;
+    }
+    if (rootThreadId) {
+      if (thread.threadId === rootThreadId) roots.push(thread);
+    } else {
+      roots.push(thread);
+    }
+  }
+  // When the user passed an explicit `rootThreadId` but it didn't
+  // appear in the loaded set (e.g. it sits beyond `--limit`), pull
+  // it on its own so we still surface it as the single root.
+  if (rootThreadId && roots.length === 0) {
+    const explicit = flat.find((t) => t.threadId === rootThreadId);
+    if (explicit) roots.push(explicit);
+  }
+  // Sort children oldest-first within each parent (spawn order),
+  // roots newest-first (most recent root at the top).
+  for (const list of childrenByParent.values()) {
+    list.sort((a, b) => (a.createdAt || a.lastMessageAt) - (b.createdAt || b.lastMessageAt));
+  }
+  roots.sort((a, b) => b.lastMessageAt - a.lastMessageAt);
+
+  if (roots.length === 0) {
+    if (rootThreadId) {
+      console.error(
+        `No thread found with id ${rootThreadId} (or it's outside the limit ` +
+          `${limit} window — increase --limit).`,
+      );
+    } else {
+      console.error("No chat threads in this workspace yet.");
+    }
+    return;
+  }
+
+  const stripe = (s: string, n: number) =>
+    s.length > n ? `${s.slice(0, n - 1)}…` : s;
+  const print = (thread: (typeof flat)[number], depth: number): void => {
+    const indent = "  ".repeat(depth);
+    const branch = depth > 0 ? "└─ " : "";
+    const status =
+      thread.status === "streaming"
+        ? "▸ running"
+        : thread.status === "error"
+          ? "✗ error"
+          : thread.summary
+            ? "✓ done"
+            : "·";
+    process.stdout.write(
+      `${indent}${branch}[${status}] ${stripe(thread.title || "Untitled", 60)}  ` +
+        `(${thread.threadId})\n`,
+    );
+    if (thread.summary) {
+      process.stdout.write(
+        `${indent}${depth > 0 ? "   " : ""}${stripe(thread.summary.replace(/\s+/g, " "), 80)}\n`,
+      );
+    }
+    const direct = childrenByParent.get(thread.threadId) ?? [];
+    for (const child of direct) print(child, depth + 1);
+  };
+  for (const root of roots) print(root, 0);
+}