linear-sdk-cli 0.1.0

package/src/bin/linear.ts

@@ -0,0 +1,97 @@
+#!/usr/bin/env bun
+/**
+ * CLI entry point + central error boundary. All commands throw; failures —
+ * including commander's own parse/usage errors — are normalized here into the
+ * error envelope and a stable exit code.
+ */
+
+import { CommanderError } from "commander";
+import { createProgram, parsedGlobalOptions, usageHint, suppressedHelp } from "../cli.js";
+import { Output } from "../output/format.js";
+import { CliError, ExitCode, normalizeError } from "../lib/errors.js";
+import { commandPath } from "../lib/options.js";
+import { isDebugEnabled, shouldUseColor } from "../output/color.js";
+
+// `linear schema | head -2` is a reader that stops early, and stdout closing
+// under us is that reader's business, not an error: exit quietly, as every
+// well-behaved Unix filter does. Without a listener Bun surfaces the EPIPE as
+// an unhandled stream error — a raw stack dump on stderr and exit 1.
+for (const stream of [process.stdout, process.stderr]) {
+  stream.on("error", (err: NodeJS.ErrnoException) => {
+    if (err.code === "EPIPE") process.exit(0);
+    throw err;
+  });
+}
+
+const program = createProgram();
+
+program.parseAsync(process.argv).catch((err) => {
+  // Help/version are normal terminations that commander already wrote to stdout.
+  if (err instanceof CommanderError) {
+    if (err.exitCode === 0) process.exit(0);
+  }
+
+  // A group invoked bare (`linear notification`) is commander asking to show
+  // that group's help and exit non-zero. It wrote the help to the stderr we
+  // route through here, so print exactly that for a human — an envelope
+  // wrapping thirty lines of usage is not an error message — and the one-line
+  // usage error under --json.
+  if (err instanceof CommanderError && err.code === "commander.help") {
+    const help = suppressedHelp(program);
+    if (help && parsedGlobalOptions(program).json !== true) {
+      process.stderr.write(help.text);
+      process.exit(ExitCode.Usage);
+    }
+  }
+
+  const cliError = err instanceof CommanderError ? fromCommander(err) : normalizeError(err);
+
+  // Format the error the way the user asked for the output — from the globals
+  // commander parsed, so every spelling it accepts (`-j`, `-jq`, `--json`)
+  // reaches the envelope. Errors go to stderr, so that stream's TTY-ness decides
+  // colour, not stdout's.
+  const globals = parsedGlobalOptions(program);
+  const json = globals.json === true;
+  const out = new Output({
+    json,
+    color: shouldUseColor({
+      disabled: globals.noAnsi,
+      json,
+      isTTY: process.stderr.isTTY === true,
+    }),
+    quiet: globals.quiet === true,
+    debug: isDebugEnabled(globals.debug),
+    isTTY: process.stderr.isTTY === true,
+  });
+  out.error(cliError);
+  process.exit(cliError.exitCode);
+});
+
+/**
+ * Commander's own failures as CliErrors. A parse failure gets a pointer at the
+ * failing command's `--help` — the string form of what `.showHelpAfterError()`
+ * would print, if commander's stderr were not routed through here.
+ */
+function fromCommander(err: CommanderError): CliError {
+  if (err.code === "commander.help") {
+    const help = suppressedHelp(program);
+    const path = help ? commandPath(help.command) : "linear";
+    return new CliError(
+      "Missing subcommand.",
+      "usage",
+      err.code,
+      `Run '${path} --help' to see the commands.`,
+    );
+  }
+  return new CliError(
+    stripErrorPrefix(err.message).replace(/\.?$/, "."),
+    "usage",
+    err.code,
+    usageHint(program),
+  );
+}
+
+/** Commander prefixes messages with "error: "; drop it for our envelope. */
+function stripErrorPrefix(message: string): string {
+  return message.replace(/^error:\s*/i, "");
+}

package/src/cli.ts

@@ -0,0 +1,232 @@
+/**
+ * Root commander program: registers global options and all command groups.
+ * Kept free of side effects so it can be imported by tests and the bin entry.
+ */
+
+import { Command } from "commander";
+import { addGlobalOptions, globalOptionKeys, unknownCommand, commandPath } from "./lib/options.js";
+import { registerMeta } from "./commands/meta.js";
+import { registerApi } from "./commands/api.js";
+import { registerCompletion } from "./commands/completion.js";
+import { registerIssue, renderIssueDetail } from "./commands/issue.js";
+import { registerAgentSession } from "./commands/agent-session.js";
+import { registerAttach } from "./commands/attach.js";
+import { registerTeam } from "./commands/team.js";
+import { registerProject } from "./commands/project.js";
+import { registerProjectUpdate } from "./commands/project-update.js";
+import { registerMilestone } from "./commands/milestone.js";
+import { registerCycle } from "./commands/cycle.js";
+import { registerUser } from "./commands/user.js";
+import { registerLabel } from "./commands/label.js";
+import { registerState } from "./commands/state.js";
+import { registerComment } from "./commands/comment.js";
+import { registerDocument } from "./commands/document.js";
+import { registerAttachment } from "./commands/attachment.js";
+import { registerFavorite } from "./commands/favorite.js";
+import { registerInitiative } from "./commands/initiative.js";
+import { registerInitiativeUpdate } from "./commands/initiative-update.js";
+import { registerRoadmap } from "./commands/roadmap.js";
+import { registerNotification } from "./commands/notification.js";
+import { registerOrganization } from "./commands/organization.js";
+import { registerWebhook } from "./commands/webhook.js";
+import { registerOpen } from "./commands/open.js";
+import { registerCommands, registerSchema } from "./commands/discover.js";
+import { Context, type GlobalOptions } from "./context.js";
+import { currentIssueId } from "./git.js";
+import { getIssueDetail } from "./services/issue.js";
+import { usageError } from "./lib/errors.js";
+import packageJson from "../package.json" with { type: "json" };
+
+/** One version source for the package, both binaries, and programmatic use. */
+export const VERSION = packageJson.version;
+
+export function createProgram(): Command {
+  const program = new Command();
+
+  program
+    .name("linear")
+    .description("Ergonomic command-line interface for Linear, built on @linear/sdk")
+    .version(VERSION, "-V, --version", "output the version number")
+    .enablePositionalOptions()
+    // A stray word at the root is an unknown command, and the root action says
+    // so (with a guess). Left to commander it was "too many arguments. Expected
+    // 0 arguments but got 2: issues, list." — true, and no help at all.
+    .allowExcessArguments();
+
+  addGlobalOptions(program);
+
+  // Phase 0: meta + escape hatch + completion.
+  registerMeta(program);
+  registerApi(program);
+  registerCompletion(program);
+  registerOpen(program);
+  // Phase 1: issues. Agent sessions live on issues, so their group is mounted
+  // under `issue` (`linear issue agent-session …`); so is file upload
+  // (`linear issue attach <issue> <file...>`, TES-602).
+  registerIssue(program);
+  registerAgentSession(program.commands.find((c) => c.name() === "issue")!);
+  registerAttach(program.commands.find((c) => c.name() === "issue")!);
+  // Phase 2: teams, projects, milestones, cycles.
+  registerTeam(program);
+  registerProject(program);
+  registerProjectUpdate(program);
+  registerMilestone(program);
+  registerCycle(program);
+  // Phase 3: users, labels, workflow states, comments, documents, attachments, favorites.
+  registerUser(program);
+  registerLabel(program);
+  registerState(program);
+  registerComment(program);
+  registerDocument(program);
+  registerAttachment(program);
+  registerFavorite(program);
+  // Phase 4: initiatives, roadmaps, notifications, organization, webhooks.
+  registerInitiative(program);
+  registerInitiativeUpdate(program);
+  registerRoadmap(program);
+  registerNotification(program);
+  registerOrganization(program);
+  registerWebhook(program);
+
+  // Discovery commands need the fully-built program tree, so register them last.
+  registerCommands(program);
+  registerSchema(program);
+
+  // Bare `linear` (no subcommand): show the current branch's issue if one can
+  // be inferred. With no inferable id: human mode shows help; --json fails with
+  // a usage error (so a bare `linear --json` never emits non-JSON to stdout).
+  // When an id IS inferred, the output matches `issue view <id>` exactly.
+  program.action(async (_opts: unknown, command: Command) => {
+    if (command.args.length > 0) throw unknownCommand(command, command.args[0]!);
+    const ctx = new Context(command.optsWithGlobals() as GlobalOptions);
+    const id = currentIssueId();
+    if (!id) {
+      if (ctx.output.json) {
+        throw usageError(
+          "No issue id inferred from the current branch. Pass an issue id or run `linear --help`.",
+        );
+      }
+      command.help();
+      return;
+    }
+    const detail = await getIssueDetail(ctx.client, id);
+    await renderIssueDetail(ctx, detail, true);
+  });
+
+  // Make global options usable in any position (e.g. `linear whoami --json`),
+  // not just before the subcommand. Commander's optsWithGlobals() correctly
+  // prefers an explicitly-set value over a child default, so this is safe.
+  applyGlobalOptionsToAll(program);
+
+  // Route commander's own parse/usage failures through our central error
+  // boundary (so they honor the JSON envelope + exit codes) instead of letting
+  // commander call process.exit with plain text. Its error text is suppressed;
+  // bin/linear.ts re-emits via the Output layer.
+  configureErrorHandling(program);
+
+  return program;
+}
+
+/**
+ * The global options as commander actually parsed them, read back off the
+ * command tree after `parseAsync` has thrown.
+ *
+ * The error boundary has no Context to ask — the failure may have happened
+ * before any action ran — so it used to re-parse `process.argv` by hand with
+ * `argv.includes("--json")`. That check did not know the `-j` alias, bundled
+ * short flags (`-jq`) or any other spelling commander accepts, so `linear issue
+ * view NOPE-1 -j` printed a plaintext error while `--json` printed the
+ * envelope: an unparseable error stream for exactly the callers the envelope
+ * exists for. Commander has already parsed whatever it got to before failing
+ * (a bad option is reported only after the whole argument list is scanned), so
+ * the boundary reads that instead of parsing again. Every global is registered
+ * on every command and stored under the same key, so the flag is found
+ * wherever on the command path it was given.
+ */
+export function parsedGlobalOptions(program: Command): GlobalOptions {
+  const keys = globalOptionKeys();
+  const merged: Record<string, unknown> = {};
+  const visit = (cmd: Command): void => {
+    for (const key of keys) {
+      if (cmd.getOptionValueSource(key) === "cli") merged[key] = cmd.getOptionValue(key);
+    }
+    for (const sub of cmd.commands) visit(sub);
+  };
+  visit(program);
+  return merged as GlobalOptions;
+}
+
+function applyGlobalOptionsToAll(cmd: Command): void {
+  for (const sub of cmd.commands) {
+    // addGlobalOptions skips any global the command already declares itself, so
+    // this is idempotent and never clobbers a command-specific version (the
+    // repeatable `--team` on the issue queries).
+    addGlobalOptions(sub);
+    applyGlobalOptionsToAll(sub);
+  }
+}
+
+/**
+ * The commands whose own parse failed, so the boundary can point at the right
+ * `--help`. Commander calls `outputError` on the command that detected the
+ * problem, synchronously, just before it throws — that is the only place the
+ * failing command is known, since `CommanderError` does not carry it.
+ * `.showHelpAfterError()` used to be configured for this and did nothing: the
+ * suppressed `writeErr` below swallowed the help it would have printed.
+ */
+const failedCommands = new WeakSet<Command>();
+
+/**
+ * What commander wrote to stderr for a command — help, when a group is
+ * invoked bare. `linear notification` used to print `error: (outputHelp)` and
+ * nothing else: commander sends the group's help to `writeErr` and asks for a
+ * non-zero exit, and `writeErr` was a no-op. The boundary prints this instead.
+ */
+const suppressedStderr = new WeakMap<Command, string>();
+
+function configureErrorHandling(cmd: Command): void {
+  cmd.exitOverride();
+  // Route commander's stderr through here rather than to the terminal: the
+  // boundary decides what to print (the envelope, or the buffered help).
+  // Help/version requested by the user use writeOut (stdout) and are intact.
+  cmd.configureOutput({
+    writeErr: (str) => {
+      suppressedStderr.set(cmd, (suppressedStderr.get(cmd) ?? "") + str);
+    },
+    outputError: () => {
+      failedCommands.add(cmd);
+    },
+  });
+  for (const sub of cmd.commands) configureErrorHandling(sub);
+}
+
+/** The command that last wrote to (suppressed) stderr, and what it wrote. */
+export function suppressedHelp(program: Command): { command: Command; text: string } | undefined {
+  const find = (cmd: Command): { command: Command; text: string } | undefined => {
+    for (const sub of cmd.commands) {
+      const hit = find(sub);
+      if (hit) return hit;
+    }
+    const text = suppressedStderr.get(cmd);
+    return text ? { command: cmd, text } : undefined;
+  };
+  return find(program);
+}
+
+/**
+ * `Run 'linear issue create --help' for usage.` for the command whose parse
+ * failed, or nothing if none did (an error thrown by an action is not a parse
+ * error and needs no such hint).
+ */
+export function usageHint(program: Command): string | undefined {
+  const find = (cmd: Command): Command | undefined => {
+    if (failedCommands.has(cmd)) return cmd;
+    for (const sub of cmd.commands) {
+      const hit = find(sub);
+      if (hit) return hit;
+    }
+    return undefined;
+  };
+  const failed = find(program);
+  return failed ? `Run '${commandPath(failed)} --help' for usage.` : undefined;
+}

package/src/client.ts

@@ -0,0 +1,172 @@
+/**
+ * LinearClient factory + a thin retry wrapper for rate limits.
+ */
+
+import { LinearClient } from "@linear/sdk";
+import type { ResolvedConfig } from "./config.js";
+import { authError, normalizeError, CliError } from "./lib/errors.js";
+
+export function createClient(config: ResolvedConfig): LinearClient {
+  if (!config.apiKey) {
+    // Surface the precise credential-selection error (ambiguous / unstored
+    // workspace) only now, when a client is actually required.
+    throw (
+      config.apiKeyError ??
+      authError("No API key found. Set LINEAR_API_KEY, pass --api-key, or run `linear auth login`.")
+    );
+  }
+  return new LinearClient({ apiKey: config.apiKey });
+}
+
+/**
+ * The longest single wait `withRetry` will honour. Linear's request quota
+ * resets hourly, so a `Retry-After` can be in the thousands of seconds; a CLI
+ * that silently sleeps that long looks hung (and an agent's tool call just
+ * times out). Beyond this we fail fast with the reset time in the message so
+ * the caller can schedule instead of wait.
+ */
+export const MAX_RETRY_WAIT_MS = 30_000;
+
+export interface RetryOptions {
+  /** Retries after the first attempt for a rate limit (default 3). */
+  retries?: number;
+  /** Retries for a connection that was never opened (default 1). */
+  networkRetries?: number;
+  /** Backoff base when the response carries no Retry-After (default 500 ms). */
+  baseDelayMs?: number;
+  /** Longest single wait honoured (default MAX_RETRY_WAIT_MS). */
+  maxWaitMs?: number;
+  /** Clock seam for tests. */
+  sleep?: (ms: number) => Promise<void>;
+  /**
+   * Where the one-line "retrying in Ns" note goes. Defaults to the reporter
+   * installed with `setRetryReporter` (stderr); `null` silences it.
+   */
+  report?: ((line: string) => void) | null;
+}
+
+type Reporter = (line: string) => void;
+
+/** Plain stderr line — status, never data, so it cannot pollute `--json` stdout. */
+const stderrReporter: Reporter = (line) => {
+  process.stderr.write(line + "\n");
+};
+
+let retryReporter: Reporter | null = stderrReporter;
+
+/**
+ * Install the sink for retry status lines. The Context wires this to its
+ * `Output.info` so `--quiet` is honoured; until then (and for library callers)
+ * the default writes to stderr. Pass `null` to silence.
+ */
+export function setRetryReporter(fn: Reporter | null): void {
+  retryReporter = fn;
+}
+
+/**
+ * Transport failures where the request provably never reached Linear, so a
+ * retry cannot duplicate a mutation. `ETIMEDOUT`/`ECONNRESET` are NOT here:
+ * the request may have been sent, and `withRetry` wraps creates.
+ */
+const NEVER_SENT = new Set(["ConnectionRefused", "ECONNREFUSED", "ENOTFOUND", "EAI_AGAIN"]);
+
+/**
+ * Execute a Linear call, retrying on rate-limit with exponential backoff and
+ * normalizing any failure into a CliError. Used to wrap every service call.
+ *
+ * A 429 is safe to retry unconditionally (the request was rejected, not run).
+ * A connection that was refused or a name that did not resolve is retried once
+ * for the same reason. Anything else — including 5xx, which for a mutation may
+ * or may not have executed — is thrown as-is.
+ */
+export async function withRetry<T>(fn: () => Promise<T>, opts: RetryOptions = {}): Promise<T> {
+  const retries = opts.retries ?? 3;
+  const networkRetries = opts.networkRetries ?? 1;
+  const base = opts.baseDelayMs ?? 500;
+  const maxWait = opts.maxWaitMs ?? MAX_RETRY_WAIT_MS;
+  const sleep = opts.sleep ?? delay;
+  const report = opts.report === undefined ? retryReporter : opts.report;
+  let attempt = 0;
+  for (;;) {
+    try {
+      return await fn();
+    } catch (err) {
+      const normalized = normalizeError(err);
+      const kind = retryKind(normalized);
+      const budget = kind === "rate_limited" ? retries : kind === "network" ? networkRetries : 0;
+      if (!kind || attempt >= budget) throw normalized;
+      attempt++;
+      const hinted = kind === "rate_limited" ? retryAfterMs(err) : undefined;
+      const wait = hinted ?? base * 2 ** (attempt - 1);
+      if (wait > maxWait) throw waitTooLong(normalized, wait);
+      report?.(
+        `${kind === "rate_limited" ? "rate limited" : "connection failed"}; retrying in ${formatSeconds(wait)} (attempt ${attempt}/${budget})`,
+      );
+      await sleep(wait);
+    }
+  }
+}
+
+function retryKind(err: CliError): "rate_limited" | "network" | undefined {
+  if (err.code === "rate_limited") return "rate_limited";
+  if (err.code === "network") {
+    const code = (err.detail as { code?: unknown } | undefined)?.code;
+    if (typeof code === "string" && NEVER_SENT.has(code)) return "network";
+  }
+  return undefined;
+}
+
+/**
+ * Fail fast instead of sleeping past the cap: keep the `rate_limited` code (so
+ * the exit code stays 5 and a script can key on it) and say when the quota
+ * resets, so the caller can schedule the retry.
+ */
+function waitTooLong(err: CliError, waitMs: number): CliError {
+  const at = new Date(Date.now() + waitMs);
+  return new CliError(
+    `Rate limited by Linear; the quota resets in ${formatSeconds(waitMs)} (at ${at.toLocaleTimeString()}). Retry after that.`,
+    "rate_limited",
+    err.detail,
+  );
+}
+
+/**
+ * The server's Retry-After, in ms. Read from the SDK's parsed `retryAfter`
+ * (seconds) or the raw header, which may be seconds or an HTTP-date.
+ */
+export function retryAfterMs(err: unknown): number | undefined {
+  const e = err as { retryAfter?: unknown; raw?: { response?: { headers?: any } } } | undefined;
+  const headers = e?.raw?.response?.headers;
+  const value = headers?.get?.("retry-after") ?? headers?.["retry-after"] ?? e?.retryAfter;
+  if (value === undefined || value === null || value === "") return undefined;
+  const secs = Number(value);
+  if (Number.isFinite(secs)) return Math.max(0, secs * 1000);
+  const at = Date.parse(String(value));
+  return Number.isFinite(at) ? Math.max(0, at - Date.now()) : undefined;
+}
+
+function formatSeconds(ms: number): string {
+  const secs = ms / 1000;
+  if (secs >= 3600) return `${(secs / 3600).toFixed(1).replace(/\.0$/, "")}h`;
+  if (secs >= 60) return `${Math.round(secs / 60)}m`;
+  return `${secs < 10 ? secs.toFixed(1).replace(/\.0$/, "") : Math.round(secs)}s`;
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * `conn.fetchNext()` behind `withRetry`, for pagination loops: page 1 of every
+ * listing is already wrapped at its call site, but each later page is its own
+ * request and can be rate limited on its own. `collect()` should advance with
+ * `conn = await fetchNextWithRetry(conn)` rather than a bare `fetchNext()`.
+ */
+export function fetchNextWithRetry<C extends { fetchNext: () => Promise<C> }>(
+  conn: C,
+  opts?: RetryOptions,
+): Promise<C> {
+  return withRetry(() => conn.fetchNext(), opts);
+}
+
+export { CliError };

package/src/commands/agent-session.ts

@@ -0,0 +1,121 @@
+/**
+ * `linear issue agent-session` — the sessions Linear's agent integrations open
+ * on issues. Mounted under `issue` (from cli.ts) because a session lives on an
+ * issue: `list` reads the issue from its argument or the current branch like
+ * every other `issue` subcommand, and `--all-issues` widens to the workspace.
+ */
+
+import { Command, Option } from "commander";
+import { action } from "../lib/action.js";
+import { usageError } from "../lib/errors.js";
+import { currentIssueId } from "../git.js";
+import type { Context } from "../context.js";
+import * as svc from "../services/agent-session.js";
+import type { Column } from "../output/table.js";
+
+const ROW_COLUMNS: Column<svc.AgentSessionRow>[] = [
+  { key: "status", header: "Status", value: (r) => r.status, max: 13 },
+  { key: "agent", header: "Agent", value: (r) => r.agent?.displayName ?? "—", max: 20 },
+  { key: "issue", header: "Issue", value: (r) => r.issue?.identifier ?? "—" },
+  { key: "createdAt", header: "Created", value: (r) => r.createdAt.slice(0, 10) },
+  {
+    key: "summary",
+    header: "Summary",
+    value: (r) => r.summary?.replace(/\n/g, " ") ?? "—",
+    max: 60,
+  },
+  { key: "id", header: "ID", value: (r) => r.id },
+];
+
+export function registerAgentSession(issue: Command): void {
+  const group = issue
+    .command("agent-session")
+    .description("Inspect the agent sessions on an issue");
+
+  // list --------------------------------------------------------------------
+  group
+    .command("list [issue]")
+    .alias("ls")
+    .description("List an issue's agent sessions (newest first)")
+    .addOption(
+      new Option("--status <status>", "only sessions in this status").choices([
+        ...svc.AGENT_SESSION_STATUSES,
+      ]),
+    )
+    .option("--all-issues", "every session in the workspace, ignoring the issue")
+    .addHelpText(
+      "after",
+      [
+        "",
+        "Examples:",
+        "  linear issue agent-session list TES-123",
+        "  linear issue agent-session list --all-issues --status awaitingInput",
+        "  linear issue agent-session list TES-123 --json | jq -r '.[].id'",
+      ].join("\n"),
+    )
+    .action(
+      action(async (ctx: Context, opts, issueArg?: string) => {
+        const filters = { status: opts.status };
+        let rows: svc.AgentSessionRow[];
+        if (opts.allIssues) {
+          if (issueArg !== undefined) {
+            throw usageError("Pass either an issue or --all-issues, not both.");
+          }
+          rows = await svc.listAllAgentSessions(ctx.client, ctx.limit, filters);
+        } else {
+          const id = issueArg ?? currentIssueId();
+          if (!id) {
+            throw usageError(
+              "No issue id given and none could be inferred from the current branch. " +
+                "Pass an issue, or --all-issues for the whole workspace.",
+            );
+          }
+          rows = await svc.listIssueAgentSessions(ctx.client, id, ctx.limit, filters);
+        }
+        ctx.output.list(rows, ROW_COLUMNS, rows);
+      }),
+    );
+
+  // view --------------------------------------------------------------------
+  group
+    .command("view <id>")
+    .alias("show")
+    .description("Show an agent session and its activity")
+    .action(
+      action(async (ctx: Context, _opts, id: string) => {
+        const d = await svc.getAgentSessionDetail(ctx.client, id);
+        ctx.output.detail(d, [
+          ["Session", d.id],
+          ["Status", d.status],
+          ["Agent", d.agent ? `${d.agent.name} (${d.agent.displayName})` : null],
+          ["Creator", d.creator ? `${d.creator.name} (${d.creator.displayName})` : null],
+          ["Issue", d.issue ? `${d.issue.identifier}  ${d.issue.title}` : null],
+          ["Created", d.createdAt],
+          ["Started", d.startedAt],
+          ["Ended", d.endedAt],
+          [
+            "Dismissed",
+            d.dismissedAt
+              ? `${d.dismissedAt}${d.dismissedBy ? ` by ${d.dismissedBy.displayName}` : ""}`
+              : null,
+          ],
+          ["External link", d.externalLink],
+          ["URL", d.url],
+          ["Summary", d.summary ? `\n${d.summary}` : null],
+          ["Activity", d.activities.length ? `\n${renderActivities(d)}` : null],
+        ]);
+      }),
+    );
+}
+
+/** `- <time> <type>: <one line>` per activity, oldest first, plus a truncation note. */
+function renderActivities(d: svc.AgentSessionDetail): string {
+  const lines = d.activities.map((a) => {
+    const when = a.createdAt.slice(11, 19);
+    const text =
+      a.action !== null ? `${a.action}${a.parameter ? `: ${a.parameter}` : ""}` : (a.body ?? "");
+    return `- ${when} ${a.type}: ${text.replace(/\s*\n\s*/g, " ")}`;
+  });
+  if (d.activitiesTruncated) lines.push(`… more activities not shown (use --json)`);
+  return lines.join("\n");
+}