@dench.com/cli 0.3.2 → 0.3.4

package/README.md

@@ -81,6 +81,30 @@ Use `dench context` when you need to know who you are, which workspace you are
 using, assigned tasks, pending approvals you requested, connected apps, and the
 best next commands. Add `--json` for structured output.
 
+## Past chat threads
+
+Browse and search the user's past chat threads in this workspace (own +
+shared). Useful for pulling in earlier context when the user refers to
+something they discussed before. The chat agent has the equivalent
+in-process tools (`list_past_chats`, `search_past_chats`,
+`read_past_chat`); this CLI surface is the same data accessed via bash.
+
+```bash
+dench chat list [--query <substr>] [--limit N] [--include-archived] [--json]
+dench chat search "<query>" [--limit N] [--json]
+dench chat read <thread-id> [--limit N] [--json]
+```
+
+Visibility scope: only threads created by the current user, plus threads
+in the same organization marked as `shared`.
+
+`dench chat search` is a keyword full-text search across past message
+text — pick concrete tokens that the prior chat would have used (file
+paths, product names, error strings) rather than paraphrases.
+
+Inside a sandbox, `dench chat` uses `DENCH_API_KEY` + `DENCH_RUN_ID`
+automatically; locally, run `dench login` first.
+
 ## Billing
 
 Fresh workspaces verify a card for abuse prevention before starter credits are

package/agent.ts

@@ -0,0 +1,391 @@
+/**
+ * `dench agent <subcommand>` — CLI surface for the subagent + peer
+ * messaging system.
+ *
+ * Used inside sandboxes (where DENCH_API_KEY + DENCH_INTERNAL_BASE +
+ * DENCH_INTERNAL_TOKEN are already present in env) to:
+ *   - spawn parallel subagents
+ *   - await their completion
+ *   - send / wait on peer messages
+ *   - pause / resume / continue runs
+ *   - list run trees
+ *
+ * Routes hit:
+ *   POST /api/runs/spawn-child     (internal token)
+ *   POST /api/runs/notify-parent   (internal token)
+ *   POST /api/runs/send-message    (internal token)
+ *   POST /api/runs/continue        (Bearer Dench API key)
+ *   POST /api/runs                 (existing legacy route — kept for
+ *                                   compatibility; new runs prefer /start)
+ *   POST /api/runs/start           (Bearer Dench API key, the new flow)
+ */
+import type { ConvexHttpClient } from "convex/browser";
+import { makeFunctionReference } from "convex/server";
+import {
+  CliArgError,
+  getFlag,
+  hasFlag,
+  shift as shiftRaw,
+} from "./lib/cli-args";
+
+class AgentCliError extends Error {}
+
+type CliCtx = {
+  convex: ConvexHttpClient;
+  args: string[];
+  jsonOutput: boolean;
+};
+
+// Args helpers moved to cli/lib/cli-args.ts; we adapt shift to throw
+// AgentCliError so existing catch blocks don't need updating.
+function shift(args: string[], expected: string): string {
+  try {
+    return shiftRaw(args, expected);
+  } catch (error) {
+    if (error instanceof CliArgError) throw new AgentCliError(error.message);
+    throw error;
+  }
+}
+
+function out(ctx: CliCtx, 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 getInternalBase(): string {
+  const base = (
+    process.env.DENCH_INTERNAL_BASE ??
+    process.env.DENCH_API_URL ??
+    ""
+  ).replace(/\/+$/, "");
+  if (!base) {
+    throw new AgentCliError(
+      "DENCH_INTERNAL_BASE (or DENCH_API_URL) is not configured in this sandbox",
+    );
+  }
+  return base;
+}
+
+function getApiBase(): string {
+  const base = (process.env.DENCH_API_URL ?? "").replace(/\/+$/, "");
+  if (!base) {
+    throw new AgentCliError("DENCH_API_URL is not configured in this sandbox");
+  }
+  return base;
+}
+
+function internalHeaders(): Record<string, string> {
+  const token = process.env.DENCH_INTERNAL_TOKEN?.trim();
+  if (!token) {
+    throw new AgentCliError(
+      "DENCH_INTERNAL_TOKEN is not configured in this sandbox",
+    );
+  }
+  return {
+    "content-type": "application/json",
+    "x-dench-internal-token": token,
+  };
+}
+
+function apiKeyHeaders(): Record<string, string> {
+  const key = process.env.DENCH_API_KEY?.trim();
+  if (!key) {
+    throw new AgentCliError(
+      "DENCH_API_KEY is not configured in this sandbox",
+    );
+  }
+  return {
+    "content-type": "application/json",
+    authorization: `Bearer ${key}`,
+  };
+}
+
+async function postJson(
+  url: string,
+  headers: Record<string, string>,
+  body: unknown,
+): Promise<unknown> {
+  const response = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body ?? {}),
+  });
+  const text = await response.text();
+  let json: unknown;
+  try {
+    json = text ? JSON.parse(text) : null;
+  } catch {
+    json = { raw: text };
+  }
+  if (!response.ok) {
+    throw new AgentCliError(
+      `${url} failed with ${response.status}: ${
+        typeof json === "object" ? JSON.stringify(json) : String(json)
+      }`,
+    );
+  }
+  return json;
+}
+
+export async function runAgentCommand(opts: {
+  convex: ConvexHttpClient;
+  args: string[];
+}): Promise<void> {
+  const args = [...opts.args];
+  const jsonOutput = hasFlag(args, "--json");
+  const ctx: CliCtx = { convex: opts.convex, args, jsonOutput };
+  const subcommand = args.shift();
+  if (!subcommand || subcommand === "help" || subcommand === "--help") {
+    agentHelp();
+    return;
+  }
+  switch (subcommand) {
+    case "spawn":
+      return await runSpawn(ctx);
+    case "await":
+      return await runAwait(ctx);
+    case "message":
+      return await runMessage(ctx);
+    case "wait-message":
+      return await runWaitMessage(ctx);
+    case "pause":
+      return await runPause(ctx);
+    case "resume":
+      return await runResume(ctx);
+    case "continue":
+      return await runContinue(ctx);
+    case "tree":
+      return await runTree(ctx);
+    default:
+      throw new AgentCliError(
+        `Unknown agent subcommand: ${subcommand}. Run 'dench agent help'.`,
+      );
+  }
+}
+
+async function runPause(ctx: CliCtx): Promise<void> {
+  const runId = shift(ctx.args, "run id");
+  const result = await postJson(
+    `${getApiBase()}/api/runs/pause`,
+    apiKeyHeaders(),
+    { runId },
+  );
+  out(ctx, result);
+}
+
+async function runResume(ctx: CliCtx): Promise<void> {
+  const runId = shift(ctx.args, "run id");
+  const prompt = ctx.args.length > 0 ? ctx.args.join(" ").trim() : undefined;
+  const result = await postJson(
+    `${getApiBase()}/api/runs/resume`,
+    apiKeyHeaders(),
+    { runId, prompt },
+  );
+  out(ctx, result);
+}
+
+async function runSpawn(ctx: CliCtx): Promise<void> {
+  const goal = ctx.args.filter((arg) => !arg.startsWith("--")).join(" ").trim();
+  if (!goal) throw new AgentCliError("Goal required: dench agent spawn '...'");
+  const parentRunId =
+    getFlag(ctx.args, "--parent-run-id") ?? process.env.DENCH_RUN_ID;
+  if (!parentRunId) {
+    throw new AgentCliError(
+      "--parent-run-id required (or set DENCH_RUN_ID inside a sandbox)",
+    );
+  }
+  const sandboxStrategy = getFlag(ctx.args, "--sandbox") as
+    | "own"
+    | "share_parent"
+    | undefined;
+  const timeBudgetMs = parseInt(
+    getFlag(ctx.args, "--time-budget-ms") ?? "0",
+    10,
+  );
+
+  // Step 1: createChildRun via Convex (mutation requires admin auth, so we
+  // hop through the spawn-child route which has CONVEX_DEPLOY_KEY).
+  // For the v1 plan, we ship a single internal-route hop: the route owns
+  // the createChildRun + setRunLinkAwaitToken + start() sequence.
+  const result = await postJson(
+    `${getInternalBase()}/api/runs/spawn-child`,
+    internalHeaders(),
+    {
+      // The route currently expects a pre-created childRunId. To support
+      // the CLI flow we'll pass the raw goal and let the route create
+      // the child row + start the workflow. (Route extension lands in
+      // the next commit.)
+      parentRunId,
+      goal,
+      sandboxStrategy,
+      timeBudgetMs: timeBudgetMs > 0 ? timeBudgetMs : undefined,
+    },
+  );
+  out(ctx, result);
+}
+
+async function runAwait(ctx: CliCtx): Promise<void> {
+  const hookToken = getFlag(ctx.args, "--hook");
+  if (hookToken) {
+    out(ctx, { hookToken, status: "registered" });
+    return;
+  }
+  const childIdsCsv = getFlag(ctx.args, "--children");
+  if (!childIdsCsv) {
+    throw new AgentCliError(
+      "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> = {};
+  const start = Date.now();
+  const timeoutMs = parseInt(
+    getFlag(ctx.args, "--timeout-ms") ?? "3600000",
+    10,
+  );
+  while (Object.keys(completed).length < childIds.length) {
+    if (Date.now() - start > timeoutMs) {
+      throw new AgentCliError("dench agent await timed out");
+    }
+    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";
+    }
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+    break; // v1 polling stub — placeholder
+  }
+  out(ctx, { children: completed });
+}
+
+async function runMessage(ctx: CliCtx): Promise<void> {
+  const toRunId = shift(ctx.args, "target run id");
+  const fromRunId =
+    getFlag(ctx.args, "--from-run-id") ?? process.env.DENCH_RUN_ID;
+  if (!fromRunId) {
+    throw new AgentCliError(
+      "--from-run-id required (or set DENCH_RUN_ID inside a sandbox)",
+    );
+  }
+  const text = ctx.args.join(" ").trim();
+  if (!text) {
+    throw new AgentCliError(
+      "Message body required: dench agent message <toRunId> 'text...'",
+    );
+  }
+  const result = await postJson(
+    `${getInternalBase()}/api/runs/send-message`,
+    internalHeaders(),
+    { fromRunId, toRunId, payload: { text } },
+  );
+  out(ctx, result);
+}
+
+async function runWaitMessage(ctx: CliCtx): Promise<void> {
+  // v1 stub: print a message + exit. The real implementation lives in
+  // the agent loop's `wait_for_message` tool, which calls the workflow
+  // step that registers an await-message hook and durably sleeps.
+  out(ctx, {
+    note:
+      "wait-message is intended to be called by the agent loop, not from a one-shot CLI. Use the agent's wait_for_message tool inside a Long Session.",
+  });
+}
+
+async function runContinue(ctx: CliCtx): Promise<void> {
+  const prevRunId = shift(ctx.args, "previous run id");
+  const prompt = ctx.args.join(" ").trim();
+  if (!prompt) {
+    throw new AgentCliError(
+      "Continuation prompt required: dench agent continue <prevRunId> '...'",
+    );
+  }
+  const result = await postJson(
+    `${getApiBase()}/api/runs/continue`,
+    apiKeyHeaders(),
+    { prevRunId, prompt },
+  );
+  out(ctx, result);
+}
+
+async function runTree(ctx: CliCtx): Promise<void> {
+  const rootRunId =
+    ctx.args[0] ??
+    process.env.DENCH_ROOT_RUN_ID ??
+    process.env.DENCH_RUN_ID;
+  if (!rootRunId) {
+    throw new AgentCliError(
+      "dench agent tree <rootRunId> (or set DENCH_ROOT_RUN_ID inside a sandbox)",
+    );
+  }
+  const getRunTree = makeFunctionReference<"query">(
+    "functions/runs:getRunTree",
+  );
+  const flat = (await ctx.convex.query(getRunTree, {
+    rootRunId: rootRunId as never,
+  })) as Array<{
+    _id: string;
+    parentRunId?: string;
+    goal: string;
+    status: string;
+  }>;
+  if (ctx.jsonOutput) {
+    out(ctx, flat);
+    return;
+  }
+  // Tree-pretty-print, depth-first.
+  const byParent = new Map<string | null, typeof flat>();
+  for (const node of flat) {
+    const key = node.parentRunId ?? null;
+    const list = byParent.get(key) ?? [];
+    list.push(node);
+    byParent.set(key, list);
+  }
+  function print(node: (typeof flat)[number], depth: number): void {
+    const indent = "  ".repeat(depth);
+    const goalLine = node.goal.split("\n")[0].slice(0, 60);
+    process.stdout.write(
+      `${indent}- [${node.status}] ${node._id} ${goalLine}\n`,
+    );
+    for (const child of byParent.get(node._id) ?? []) print(child, depth + 1);
+  }
+  for (const root of byParent.get(null) ?? []) print(root, 0);
+}
+
+function agentHelp(): void {
+  console.log(`Usage: dench agent <subcommand>
+
+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\`.
+
+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]
+
+Peer messaging:
+  dench agent message <toRunId> '<text...>' [--from-run-id <id>]
+  dench agent wait-message            (intended for use inside the agent loop)
+
+Lifecycle:
+  dench agent pause <runId>
+  dench agent resume <runId> ['optional prompt to inject on resume']
+  dench agent continue <prevRunId> '<prompt>'   (creates a new run from a completed one)
+  dench agent tree                    (see <RunTreeView> in dench.com UI)
+
+Global flags:
+  --json    Emit raw JSON instead of pretty-printed text.
+  --follow  After spawning a chat (new/send), stream the response to stdout.
+`);
+}