@dench.com/cli 0.3.2 → 0.3.4

package/chat-spawn.ts

@@ -0,0 +1,370 @@
+/**
+ * `dench chat new` / `dench chat send` — spawn a chat-turn workflow
+ * from the CLI, exactly the same workflow the web UI uses. Threads
+ * created here are visible in `dench chat list` and the UI's chat
+ * thread list immediately, since they go through the same Convex
+ * tables (`chatThreads` + `chatMessages`).
+ *
+ * Aliased as `dench agent new` / `dench agent send` so users who
+ * grep for "agent" find them.
+ *
+ * Both subcommands POST to `/api/chat/cli` (auth: same `dch_agent_*`
+ * session token or Dench API key as the rest of the CLI). The
+ * server creates the thread + queued run, kicks off
+ * `chatTurnWorkflow`, and returns ids + URLs. With `--follow` the
+ * CLI then opens the durable resumable stream
+ * (`/api/chat/[runId]/stream`) and pretty-prints text deltas + tool
+ * calls until the workflow finishes.
+ */
+
+import { hasFlag } from "./lib/cli-args";
+
+class ChatSpawnError extends Error {}
+
+type RuntimeBundle = {
+  host: string;
+  bearerToken: string;
+};
+
+type ChatSpawnContext = {
+  runtime: RuntimeBundle;
+  args: string[];
+  jsonOutput: boolean;
+};
+
+function consumeFlagValue(args: string[], name: string): string | undefined {
+  const idx = args.indexOf(name);
+  if (idx === -1) return undefined;
+  const value = args[idx + 1];
+  args.splice(idx, 2);
+  return value;
+}
+
+function consumeFlag(args: string[], name: string): boolean {
+  const idx = args.indexOf(name);
+  if (idx === -1) return false;
+  args.splice(idx, 1);
+  return true;
+}
+
+function out(ctx: ChatSpawnContext, value: unknown): void {
+  if (ctx.jsonOutput) {
+    console.log(JSON.stringify(value, null, 2));
+    return;
+  }
+  if (value === null || value === undefined) {
+    console.log("(empty)");
+    return;
+  }
+  console.log(JSON.stringify(value, null, 2));
+}
+
+async function postJson(
+  url: string,
+  bearer: string,
+  body: unknown,
+): Promise<{ ok: boolean; status: number; payload: unknown }> {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      accept: "application/json",
+      "content-type": "application/json",
+      authorization: `Bearer ${bearer}`,
+    },
+    body: JSON.stringify(body),
+  });
+  const text = await response.text();
+  let payload: unknown;
+  try {
+    payload = text ? JSON.parse(text) : null;
+  } catch {
+    payload = { raw: text };
+  }
+  return { ok: response.ok, status: response.status, payload };
+}
+
+function buildSpawnUrl(host: string): string {
+  return `${host.replace(/\/+$/, "")}/api/chat/cli`;
+}
+
+function buildStreamUrl(host: string, runId: string): string {
+  return `${host.replace(/\/+$/, "")}/api/chat/${encodeURIComponent(runId)}/stream`;
+}
+
+/**
+ * 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).
+ */
+async function followStream(args: {
+  host: string;
+  bearerToken: string;
+  runId: string;
+}): Promise<void> {
+  const url = buildStreamUrl(args.host, args.runId);
+  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 = "";
+
+  const flushText = () => {
+    if (textBuffer) {
+      process.stdout.write(textBuffer);
+      textBuffer = "";
+    }
+  };
+
+  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;
+    }
+    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;
+      }
+      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;
+      }
+      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": {
+        flushText();
+        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;
+    }
+  };
+
+  // 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");
+    }
+  }
+  flushText();
+}
+
+function joinPositionalsExceptFlags(args: string[]): string {
+  return args.filter((arg) => !arg.startsWith("--")).join(" ").trim();
+}
+
+async function runChatNew(ctx: ChatSpawnContext): Promise<void> {
+  const model = consumeFlagValue(ctx.args, "--model");
+  const fileContextPath = consumeFlagValue(ctx.args, "--file-context");
+  const visibility = consumeFlagValue(ctx.args, "--visibility");
+  const title = consumeFlagValue(ctx.args, "--title");
+  const yolo = consumeFlag(ctx.args, "--yolo");
+  const follow = consumeFlag(ctx.args, "--follow");
+
+  const prompt = joinPositionalsExceptFlags(ctx.args);
+  if (!prompt) {
+    throw new ChatSpawnError(
+      'Usage: dench chat new "<prompt>" [--model M] [--file-context PATH] [--visibility private|shared] [--title T] [--yolo] [--follow] [--json]',
+    );
+  }
+
+  const result = await postJson(
+    buildSpawnUrl(ctx.runtime.host),
+    ctx.runtime.bearerToken,
+    {
+      prompt,
+      model,
+      fileContextPath,
+      visibility,
+      title,
+      yolo,
+    },
+  );
+  if (!result.ok) {
+    const errorMessage =
+      (result.payload as { error?: string } | null)?.error ??
+      `Spawn failed (${result.status})`;
+    throw new ChatSpawnError(errorMessage);
+  }
+
+  const payload = result.payload as {
+    threadId?: string;
+    runId?: string;
+    threadUrl?: string;
+    streamUrl?: string;
+  } | null;
+  out(ctx, payload);
+
+  if (follow && payload?.runId) {
+    if (!ctx.jsonOutput) console.error("\n--- following stream ---");
+    await followStream({
+      host: ctx.runtime.host,
+      bearerToken: ctx.runtime.bearerToken,
+      runId: payload.runId,
+    });
+  }
+}
+
+async function runChatSend(ctx: ChatSpawnContext): Promise<void> {
+  const yolo = consumeFlag(ctx.args, "--yolo");
+  const follow = consumeFlag(ctx.args, "--follow");
+  const model = consumeFlagValue(ctx.args, "--model");
+
+  // First positional = threadId, the rest joined = prompt.
+  const positionals = ctx.args.filter((arg) => !arg.startsWith("--"));
+  const threadId = positionals.shift();
+  if (!threadId) {
+    throw new ChatSpawnError(
+      'Usage: dench chat send <threadId> "<message>" [--model M] [--yolo] [--follow] [--json]',
+    );
+  }
+  const prompt = positionals.join(" ").trim();
+  if (!prompt) {
+    throw new ChatSpawnError(
+      'Missing message body. Usage: dench chat send <threadId> "<message>"',
+    );
+  }
+
+  const result = await postJson(
+    buildSpawnUrl(ctx.runtime.host),
+    ctx.runtime.bearerToken,
+    {
+      threadId,
+      prompt,
+      model,
+      yolo,
+    },
+  );
+  if (!result.ok) {
+    const errorMessage =
+      (result.payload as { error?: string } | null)?.error ??
+      `Send failed (${result.status})`;
+    throw new ChatSpawnError(errorMessage);
+  }
+
+  const payload = result.payload as {
+    threadId?: string;
+    runId?: string;
+    threadUrl?: string;
+    streamUrl?: string;
+  } | null;
+  out(ctx, payload);
+
+  if (follow && payload?.runId) {
+    if (!ctx.jsonOutput) console.error("\n--- following stream ---");
+    await followStream({
+      host: ctx.runtime.host,
+      bearerToken: ctx.runtime.bearerToken,
+      runId: payload.runId,
+    });
+  }
+}
+
+/**
+ * Public entry point invoked by the chat dispatcher in cli/dench.ts
+ * (and the agent dispatcher when the user runs `dench agent new` /
+ * `dench agent send` aliases). The CLI dispatcher resolves the
+ * runtime + bearer token once and hands them in.
+ */
+export async function runChatSpawnCommand(opts: {
+  runtime: RuntimeBundle;
+  args: string[];
+  subcommand: "new" | "send";
+}): Promise<void> {
+  const args = [...opts.args];
+  const jsonOutput = hasFlag(args, "--json");
+  const ctx: ChatSpawnContext = {
+    runtime: opts.runtime,
+    args,
+    jsonOutput,
+  };
+  if (opts.subcommand === "new") {
+    await runChatNew(ctx);
+    return;
+  }
+  await runChatSend(ctx);
+}
+
+export { ChatSpawnError };

package/chat.ts

@@ -0,0 +1,216 @@
+/**
+ * `dench chat <subcommand>` — CLI surface for browsing past chat threads
+ * in the user's workspace.
+ *
+ * Mirrors the `dench crm` pattern: a thin command dispatcher on top of
+ * Convex public queries (`functions/chat:listPastChats`,
+ * `searchPastChats`, `readPastChat`) which themselves enforce the
+ * "own + shared in this org" visibility rule.
+ *
+ * Auth: every call forwards a single bearer token via `sessionToken`
+ * (either a `dch_agent_*` agent session minted by `dench login` or a
+ * unified Dench API key like `DENCH_API_KEY` in a sandbox). When the
+ * caller is using an API key, the server needs a `runId` to resolve
+ * the acting user — the dispatcher in `cli/dench.ts` lifts that from
+ * `DENCH_RUN_ID` and forwards it here so `dench chat` works seamlessly
+ * inside a sandbox without extra flags.
+ *
+ * Subcommands:
+ *   chat list   [--query <substr>] [--limit N] [--include-archived]
+ *   chat search <query>            [--limit N] [--include-current]
+ *   chat read   <thread-id>        [--limit N]
+ */
+import type { ConvexHttpClient } from "convex/browser";
+import { makeFunctionReference } from "convex/server";
+import {
+  CliArgError,
+  getFlag,
+  hasFlag,
+  shift as shiftRaw,
+} from "./lib/cli-args";
+
+type ChatCliContext = {
+  convex: ConvexHttpClient;
+  args: string[];
+  jsonOutput: boolean;
+  sessionToken?: string;
+  runId?: string;
+};
+
+class ChatCliError extends Error {}
+
+function shift(args: string[], expected: string): string {
+  try {
+    return shiftRaw(args, expected);
+  } catch (error) {
+    if (error instanceof CliArgError) throw new ChatCliError(error.message);
+    throw error;
+  }
+}
+
+function parseLimit(raw: string | undefined): number | undefined {
+  if (raw === undefined) return undefined;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new ChatCliError(`Invalid --limit value: ${raw}`);
+  }
+  return Math.floor(parsed);
+}
+
+const api = {
+  listPastChats: makeFunctionReference<"query">(
+    "functions/chat:listPastChats",
+  ),
+  searchPastChats: makeFunctionReference<"query">(
+    "functions/chat:searchPastChats",
+  ),
+  readPastChat: makeFunctionReference<"query">(
+    "functions/chat:readPastChat",
+  ),
+};
+
+function commonArgs(ctx: ChatCliContext) {
+  return {
+    ...(ctx.sessionToken ? { sessionToken: ctx.sessionToken } : {}),
+    ...(ctx.runId ? { runId: ctx.runId } : {}),
+  };
+}
+
+async function callQuery(
+  ctx: ChatCliContext,
+  fn: Parameters<ConvexHttpClient["query"]>[0],
+  args: Record<string, unknown> = {},
+): Promise<unknown> {
+  return ctx.convex.query(fn, { ...args, ...commonArgs(ctx) } as never);
+}
+
+function out(ctx: ChatCliContext, value: unknown): void {
+  if (ctx.jsonOutput) {
+    console.log(JSON.stringify(value, null, 2));
+    return;
+  }
+  if (value === null || value === undefined) {
+    console.log("(empty)");
+    return;
+  }
+  console.log(JSON.stringify(value, null, 2));
+}
+
+function chatHelp(): void {
+  console.log(`Usage: dench chat <subcommand>
+
+List past chat threads (own + shared in this workspace):
+  dench chat list [--query <substr>] [--limit N] [--include-archived] [--json]
+
+Full-text search across past chat messages (own + shared):
+  dench chat search "<query>" [--limit N] [--include-current] [--json]
+
+Read messages from a specific past chat thread:
+  dench chat read <thread-id> [--limit N] [--json]
+
+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.
+
+Approval policy:
+  Without --yolo the workflow uses the workspace policy from
+  /<slug>/settings -> Approvals (master YOLO + per-rule toggles).
+  --yolo overrides for this single chat turn — every approval gate is
+  off, equivalent to flipping the org to YOLO mode for this run.
+
+Auth:
+  Inside a sandbox, this just works — DENCH_API_KEY + DENCH_RUN_ID are
+  used automatically. Locally, run \`dench login\` first.
+
+Global flags:
+  --json    Output raw JSON instead of pretty-printed text.
+  --follow  After spawning, stream the chat response to stdout.
+`);
+}
+
+export async function runChatCommand(opts: {
+  convex: ConvexHttpClient;
+  args: string[];
+  sessionToken?: string;
+  runId?: string;
+}): Promise<void> {
+  const args = [...opts.args];
+  const jsonOutput = hasFlag(args, "--json");
+  const ctx: ChatCliContext = {
+    convex: opts.convex,
+    args,
+    jsonOutput,
+    sessionToken: opts.sessionToken,
+    runId: opts.runId,
+  };
+  const subcommand = args.shift();
+  if (!subcommand || subcommand === "help" || subcommand === "--help") {
+    chatHelp();
+    return;
+  }
+  switch (subcommand) {
+    case "list":
+      return await runChatListCommand(ctx);
+    case "search":
+      return await runChatSearchCommand(ctx);
+    case "read":
+      return await runChatReadCommand(ctx);
+    default:
+      throw new ChatCliError(`Unknown chat subcommand: ${subcommand}`);
+  }
+}
+
+async function runChatListCommand(ctx: ChatCliContext): Promise<void> {
+  const titleQuery = getFlag(ctx.args, "--query");
+  const limit = parseLimit(getFlag(ctx.args, "--limit"));
+  const includeArchived = hasFlag(ctx.args, "--include-archived");
+  out(
+    ctx,
+    await callQuery(ctx, api.listPastChats, {
+      titleQuery,
+      limit,
+      includeArchived,
+    }),
+  );
+}
+
+async function runChatSearchCommand(ctx: ChatCliContext): Promise<void> {
+  const includeCurrent = hasFlag(ctx.args, "--include-current");
+  const limit = parseLimit(getFlag(ctx.args, "--limit"));
+  const queryParts: string[] = [];
+  while (ctx.args.length > 0) {
+    const next = ctx.args.shift();
+    if (next === undefined) break;
+    queryParts.push(next);
+  }
+  const query = queryParts.join(" ").trim();
+  if (!query) {
+    throw new ChatCliError(
+      'Usage: dench chat search "<query>" [--limit N] [--include-current]',
+    );
+  }
+  out(
+    ctx,
+    await callQuery(ctx, api.searchPastChats, {
+      query,
+      limit,
+      // The server defaults excludeThreadId to undefined; the agent path
+      // sets it explicitly. CLI users are not "in" a thread, so we pass
+      // undefined unless --include-current is intentionally set (no-op).
+      ...(includeCurrent ? {} : {}),
+    }),
+  );
+}
+
+async function runChatReadCommand(ctx: ChatCliContext): Promise<void> {
+  const threadId = shift(ctx.args, "thread id");
+  const limit = parseLimit(getFlag(ctx.args, "--limit"));
+  out(
+    ctx,
+    await callQuery(ctx, api.readPastChat, {
+      threadId,
+      limit,
+    }),
+  );
+}