@impulselab/hepha 0.1.0

package/dist/index.js

@@ -0,0 +1,1349 @@
+#!/usr/bin/env node
+
+// src/lib/config.ts
+import {
+  chmodSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync
+} from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+
+// src/lib/errors.ts
+var CliError = class extends Error {
+  exitCode;
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+  }
+};
+
+// src/lib/is-http-url.ts
+function isHttpUrl(value) {
+  try {
+    const parsed = new URL(value);
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+// src/lib/config.ts
+var CONFIG_PATH = join(homedir(), ".hepha", "config.json");
+var DEFAULT_BASE_URL = "https://hephaistos.impulselab.ai";
+function readFileAsObject() {
+  try {
+    const parsed = JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return {};
+    }
+    return parsed;
+  } catch {
+    return {};
+  }
+}
+function readString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function readUser(value) {
+  if (!value || typeof value !== "object") {
+    return void 0;
+  }
+  const candidate = value;
+  const user = {
+    id: readString(candidate.id),
+    name: readString(candidate.name),
+    email: readString(candidate.email)
+  };
+  return user.id && user.name && user.email ? { id: user.id, name: user.name, email: user.email } : void 0;
+}
+function readHttpUrl(value) {
+  const raw = readString(value);
+  return raw && isHttpUrl(raw) ? raw : void 0;
+}
+function isSameOrigin(a, b) {
+  try {
+    return new URL(a).origin === new URL(b).origin;
+  } catch {
+    return false;
+  }
+}
+var config = {
+  path: CONFIG_PATH,
+  load() {
+    const stored = readFileAsObject();
+    const storedBaseUrl = readHttpUrl(stored.baseUrl);
+    const override = readString(process.env.HEPHA_URL);
+    if (override && !readHttpUrl(override)) {
+      throw new CliError(
+        `HEPHA_URL is not a valid http(s) URL: "${override}".`,
+        2
+      );
+    }
+    const baseUrl = readHttpUrl(override) ?? storedBaseUrl ?? DEFAULT_BASE_URL;
+    const token = storedBaseUrl && isSameOrigin(storedBaseUrl, baseUrl) ? readString(stored.token) : void 0;
+    const user = token ? readUser(stored.user) : void 0;
+    return {
+      baseUrl,
+      ...token ? { token } : {},
+      ...user ? { user } : {}
+    };
+  },
+  save(next) {
+    mkdirSync(dirname(CONFIG_PATH), { recursive: true, mode: 448 });
+    writeFileSync(CONFIG_PATH, `${JSON.stringify(next, null, 2)}
+`, {
+      mode: 384
+    });
+    chmodSync(CONFIG_PATH, 384);
+  },
+  clear() {
+    rmSync(CONFIG_PATH, { force: true });
+  }
+};
+
+// src/lib/api.ts
+function authHeaders(as) {
+  if (as) {
+    return { authorization: `Bearer ${as.token}` };
+  }
+  const apiKey = process.env.HEPHA_API_KEY;
+  if (apiKey) {
+    return { "x-api-key": apiKey };
+  }
+  const token = process.env.HEPHA_TOKEN ?? config.load().token;
+  if (token) {
+    return { authorization: `Bearer ${token}` };
+  }
+  throw new CliError(
+    "Not signed in. Run `hepha login`, or set HEPHA_API_KEY to act as an agent."
+  );
+}
+function messageFrom(status, payload) {
+  if (payload && typeof payload === "object" && "message" in payload) {
+    const message = payload.message;
+    if (typeof message === "string" && message.length > 0) {
+      return message;
+    }
+  }
+  if (status === 401) {
+    return "Unauthorized \u2014 your credential is missing, expired or revoked.";
+  }
+  return `Request failed with status ${status}.`;
+}
+async function api(path, options = {}) {
+  const baseUrl = options.as?.baseUrl ?? config.load().baseUrl;
+  const url = new URL(`${baseUrl.replace(/\/$/, "")}/api/v1${path}`);
+  for (const [key, value] of Object.entries(options.query ?? {})) {
+    if (value !== void 0) {
+      url.searchParams.set(key, String(value));
+    }
+  }
+  const headers = {
+    ...authHeaders(options.as),
+    ...options.body === void 0 ? {} : { "content-type": "application/json" }
+  };
+  let response;
+  try {
+    response = await fetch(url, {
+      method: options.method ?? "GET",
+      headers,
+      ...options.body === void 0 ? {} : { body: JSON.stringify(options.body) }
+    });
+  } catch (cause) {
+    throw new CliError(
+      `Cannot reach ${baseUrl}. Set HEPHA_URL if the platform lives elsewhere. (${String(cause)})`
+    );
+  }
+  const text = await response.text();
+  let payload = null;
+  if (text) {
+    try {
+      payload = JSON.parse(text);
+    } catch {
+      throw new CliError(
+        `${url.origin} answered ${response.status} with a non-JSON body. Is HEPHA_URL pointing at a Hephaistos deployment?`
+      );
+    }
+  }
+  if (!response.ok) {
+    throw new CliError(messageFrom(response.status, payload));
+  }
+  return payload;
+}
+
+// src/lib/args.ts
+var BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["json", "follow", "help", "all", "quiet"]);
+var args = {
+  parse(argv) {
+    const parsed = {
+      positional: [],
+      flags: {},
+      repeated: {},
+      booleans: /* @__PURE__ */ new Set()
+    };
+    let flagsEnded = false;
+    for (let index = 0; index < argv.length; index += 1) {
+      const token = argv[index];
+      if (!flagsEnded && token === "--") {
+        flagsEnded = true;
+        continue;
+      }
+      if (flagsEnded || !token.startsWith("--")) {
+        parsed.positional.push(token);
+        continue;
+      }
+      const withoutDashes = token.slice(2);
+      const equalsAt = withoutDashes.indexOf("=");
+      let name;
+      let value;
+      if (equalsAt >= 0) {
+        name = withoutDashes.slice(0, equalsAt);
+        value = withoutDashes.slice(equalsAt + 1);
+      } else {
+        name = withoutDashes;
+        const next = argv[index + 1];
+        if (!BOOLEAN_FLAGS.has(name) && next !== void 0 && !next.startsWith("--")) {
+          value = next;
+          index += 1;
+        }
+      }
+      if (value === void 0) {
+        if (!BOOLEAN_FLAGS.has(name)) {
+          throw new CliError(`--${name} expects a value.`, 2);
+        }
+        parsed.booleans.add(name);
+        continue;
+      }
+      parsed.flags[name] = value;
+      (parsed.repeated[name] ??= []).push(value);
+    }
+    return parsed;
+  },
+  required(parsed, index, name) {
+    const value = parsed.positional[index];
+    if (!value) {
+      throw new CliError(`Missing <${name}>.`, 2);
+    }
+    return value;
+  },
+  number(parsed, name) {
+    const raw = parsed.flags[name];
+    if (raw === void 0) {
+      return void 0;
+    }
+    const trimmed = raw.trim();
+    const value = Number(trimmed);
+    if (trimmed === "" || !Number.isFinite(value)) {
+      throw new CliError(`--${name} expects a number.`, 2);
+    }
+    return value;
+  }
+};
+
+// src/lib/output.ts
+var COLORS = {
+  reset: "\x1B[0m",
+  dim: "\x1B[2m",
+  bold: "\x1B[1m",
+  red: "\x1B[31m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  blue: "\x1B[34m",
+  magenta: "\x1B[35m"
+};
+var STATUS_COLORS = {
+  running: "blue",
+  provisioning: "blue",
+  queued: "dim",
+  created: "dim",
+  delivering: "blue",
+  verifying: "blue",
+  waiting_human: "yellow",
+  awaiting_approval: "yellow",
+  completed: "green",
+  failed: "red",
+  killed: "red",
+  abstained: "yellow"
+};
+function supportsColor() {
+  return process.stdout.isTTY === true && process.env.NO_COLOR === void 0;
+}
+var out = {
+  json(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}
+`);
+  },
+  line(text = "") {
+    process.stdout.write(`${text}
+`);
+  },
+  error(text) {
+    process.stderr.write(`${out.paint(`error: ${out.safe(text)}`, "red")}
+`);
+  },
+  paint(text, color) {
+    if (!supportsColor()) {
+      return text;
+    }
+    return `${COLORS[color] ?? ""}${text}${COLORS.reset}`;
+  },
+  /**
+   * Neutralise terminal control sequences in text the platform gives us.
+   *
+   * Transcript content, PR titles and question bodies carry model output, tool
+   * output and repository contents — none of it trusted. Printed raw, an ESC
+   * sequence could repaint or erase what the user already read, or emit an OSC
+   * 8 hyperlink pointing somewhere else entirely. Newlines and tabs survive;
+   * every other C0/C1 control does not. (`--json` is unaffected: JSON.stringify
+   * already escapes control characters.)
+   */
+  safe(text) {
+    return text.replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, "");
+  },
+  /** `safe`, flattened to one line — anything going into a table cell. */
+  cell(text) {
+    return out.safe(text).replace(/\s+/g, " ").trim();
+  },
+  status(status) {
+    return out.paint(status, STATUS_COLORS[status] ?? "reset");
+  },
+  /** Left-aligned two-column block — the shape used by every list command. */
+  table(rows) {
+    if (rows.length === 0) {
+      return;
+    }
+    const widths = rows[0].map(
+      (_, column) => Math.max(...rows.map((row) => stripAnsi(row[column] ?? "").length))
+    );
+    for (const row of rows) {
+      const line = row.map((cell, column) => {
+        const padding = widths[column] - stripAnsi(cell).length;
+        return column === row.length - 1 ? cell : cell + " ".repeat(padding);
+      }).join("  ");
+      out.line(line.trimEnd());
+    }
+  }
+};
+function stripAnsi(text) {
+  return text.replace(/\u001b\[\d+m/g, "");
+}
+
+// src/commands/approvals.ts
+async function approvalsCommand(parsed) {
+  const action = parsed.positional[0] ?? "list";
+  const asJson = parsed.booleans.has("json");
+  if (action === "list") {
+    const result = await api("/approvals");
+    if (asJson) {
+      out.json(result);
+      return;
+    }
+    if (result.items.length === 0) {
+      out.line("No guardrail waiting on you.");
+      return;
+    }
+    out.table(
+      result.items.map((item) => [
+        out.cell(item.id),
+        out.cell(item.guardrailKind),
+        out.cell(item.repoName ?? "\u2014"),
+        out.cell(item.summary)
+      ])
+    );
+    return;
+  }
+  const guardrailId = args.required(parsed, 1, "guardrailRequestId");
+  if (action === "show") {
+    const detail = await api(
+      `/approvals/${guardrailId}`
+    );
+    if (asJson) {
+      out.json(detail);
+      return;
+    }
+    out.line(
+      `${out.paint(out.cell(detail.guardrailKind), "bold")}  ${detail.status}`
+    );
+    out.line(out.safe(detail.summary));
+    out.line();
+    out.json(detail.payload);
+    return;
+  }
+  if (action === "approve") {
+    const result = await api(
+      `/approvals/${guardrailId}/approve`,
+      { method: "POST", body: {} }
+    );
+    if (asJson) {
+      out.json(result);
+      return;
+    }
+    out.line(`${out.paint("\u2713", "green")} Approved ${out.cell(guardrailId)}`);
+    return;
+  }
+  if (action === "reject") {
+    const mode = parsed.flags.mode ?? "rework";
+    if (mode !== "rework" && mode !== "terminate") {
+      throw new CliError("--mode expects rework or terminate.", 2);
+    }
+    if (mode === "rework" && !parsed.flags.feedback) {
+      throw new CliError(
+        "--feedback is required with --mode rework: the agent needs to know what to change.",
+        2
+      );
+    }
+    const result = await api(
+      `/approvals/${guardrailId}/reject`,
+      {
+        method: "POST",
+        body: {
+          mode,
+          ...parsed.flags.feedback ? { feedback: parsed.flags.feedback } : {}
+        }
+      }
+    );
+    if (asJson) {
+      out.json(result);
+      return;
+    }
+    out.line(
+      `${out.paint("\u2713", "green")} Rejected ${out.cell(guardrailId)} (${mode})`
+    );
+    return;
+  }
+  throw new CliError(`Unknown approvals command "${action}".`, 2);
+}
+
+// src/commands/catalog.ts
+async function catalogCommand(topic, parsed) {
+  const asJson = parsed.booleans.has("json");
+  if (topic === "repos") {
+    const result = await api("/repos");
+    if (asJson) {
+      out.json(result);
+      return;
+    }
+    for (const repo of result.repos) {
+      out.line(out.cell(repo));
+    }
+    return;
+  }
+  if (topic === "branches") {
+    const repoFullName = args.required(parsed, 0, "owner/repo");
+    const segments = repoFullName.split("/");
+    const [owner, repo] = segments;
+    if (segments.length !== 2 || !owner || !repo) {
+      throw new CliError(
+        `Expected a repository as "owner/repo", got "${repoFullName}".`,
+        2
+      );
+    }
+    const result = await api(
+      `/repos/${owner}/${repo}/branches`
+    );
+    if (asJson) {
+      out.json(result);
+      return;
+    }
+    if (!result.result) {
+      throw new CliError(`No GitHub installation covers ${repoFullName}.`);
+    }
+    for (const branch of result.result.branches) {
+      out.line(
+        branch === result.result.defaultBranch ? `${out.cell(branch)} ${out.paint("(default)", "dim")}` : out.cell(branch)
+      );
+    }
+    return;
+  }
+  if (topic === "models") {
+    const result = await api("/models");
+    if (asJson) {
+      out.json(result);
+      return;
+    }
+    out.line(out.paint("harnesses", "dim"));
+    for (const harness of result.harnesses) {
+      out.line(`  ${out.cell(harness)}`);
+    }
+    out.line();
+    out.line(out.paint("gateway models", "dim"));
+    for (const model of result.gatewayModels) {
+      out.line(`  ${out.cell(model.id)}`);
+    }
+    return;
+  }
+  if (topic === "skills") {
+    const result = await api("/skills");
+    if (asJson) {
+      out.json(result);
+      return;
+    }
+    out.table(
+      result.skills.map((skill) => [
+        out.cell(skill.id),
+        out.cell(skill.name),
+        out.cell(skill.description ?? "")
+      ])
+    );
+    return;
+  }
+  throw new CliError(`Unknown catalog topic "${topic}".`, 2);
+}
+
+// src/commands/help.ts
+var HELP = `hepha \u2014 orchestrate Hephaistos sessions from a terminal or an agent.
+
+USAGE
+  hepha <command> [args] [--flags]
+
+THE LOOP
+  hepha run "<prompt>" --repo owner/repo --follow
+      Start a session and follow it until it finishes or asks you something.
+      Exit 0 completed \xB7 3 waiting on a human \xB7 1 failed.
+  hepha questions list [--session <id>]
+  hepha questions answer <batchId> --option <questionId>=1,2 --text <questionId>="\u2026"
+  hepha approvals list | show <id> | approve <id> | reject <id> --mode rework --feedback "\u2026"
+
+SESSIONS
+  hepha sessions list [--status active|waiting|done] [--repo owner/repo]
+                      [--page N] [--limit N] [--all]
+  hepha sessions get <id>
+  hepha sessions logs <id> [--after <sequence>] [--follow]
+  hepha sessions send <id> "<message>"
+  hepha sessions pause|resume|kill|archive <id> [--reason "\u2026"]
+  hepha sessions checks|pr|verify <id>
+
+CATALOG
+  hepha repos
+  hepha branches <owner/repo>
+  hepha models
+  hepha skills
+
+AUTH
+  hepha login [--url https://\u2026]     Device authorization: approve it in a browser.
+  hepha logout
+  hepha whoami
+  hepha keys list
+  hepha keys create <name> [--scope sessions:read]\u2026 [--expires-in-days 90]
+  hepha keys revoke <keyId>
+
+ENVIRONMENT
+  HEPHA_API_KEY   Act as an agent. Takes precedence over a stored login.
+  HEPHA_TOKEN     A device-flow session token, instead of ~/.hepha/config.json.
+  HEPHA_URL       Platform base URL.
+
+GLOBAL FLAGS
+  --json          Machine-readable output on stdout. Every command that
+                  returns data honours it; login is interactive and does not.
+
+`;
+function helpCommand() {
+  const baseUrl = config.load().baseUrl.replace(/\/$/, "");
+  out.line(`${HELP}Full reference: ${baseUrl}/api/v1/docs`);
+}
+
+// src/commands/keys.ts
+async function keysCommand(parsed) {
+  const action = parsed.positional[0] ?? "list";
+  const asJson = parsed.booleans.has("json");
+  if (action === "list") {
+    const result = await api("/keys");
+    if (asJson) {
+      out.json(result);
+      return;
+    }
+    if (result.keys.length === 0) {
+      out.line("No keys. Create one with `hepha keys create <name>`.");
+      return;
+    }
+    out.table([
+      [
+        out.paint("ID", "dim"),
+        out.paint("NAME", "dim"),
+        out.paint("PREFIX", "dim"),
+        out.paint("SCOPES", "dim")
+      ],
+      ...result.keys.map((key) => [
+        out.cell(key.id),
+        out.cell(key.name ?? "\u2014"),
+        out.cell(key.start ?? "\u2014"),
+        key.scopes.join(" ")
+      ])
+    ]);
+    return;
+  }
+  if (action === "create") {
+    const name = args.required(parsed, 1, "name");
+    const scopes = parsed.repeated.scope;
+    const expiresInDays = args.number(parsed, "expires-in-days");
+    const created = await api("/keys", {
+      method: "POST",
+      body: {
+        name,
+        ...scopes && scopes.length > 0 ? { scopes } : {},
+        ...expiresInDays !== void 0 ? { expiresInDays } : {}
+      }
+    });
+    if (asJson) {
+      out.json(created);
+      return;
+    }
+    out.line(
+      `${out.paint("\u2713", "green")} Created "${out.cell(created.name ?? name)}"`
+    );
+    out.line();
+    out.line(`  ${out.paint(created.key, "bold")}`);
+    out.line();
+    out.line(
+      out.paint(
+        "  Copy it now \u2014 it is hashed at rest and never shown again.",
+        "dim"
+      )
+    );
+    out.line(out.paint(`  Scopes: ${created.scopes.join(" ")}`, "dim"));
+    return;
+  }
+  if (action === "revoke") {
+    const keyId = args.required(parsed, 1, "keyId");
+    const result = await api(`/keys/${keyId}`, {
+      method: "DELETE"
+    });
+    if (asJson) {
+      out.json(result);
+      return;
+    }
+    out.line(`${out.paint("\u2713", "green")} Revoked ${out.cell(keyId)}`);
+    return;
+  }
+  throw new CliError(`Unknown keys command "${action}".`, 2);
+}
+
+// src/commands/login.ts
+import { createAuthClient } from "better-auth/client";
+import { deviceAuthorizationClient } from "better-auth/client/plugins";
+
+// ../../packages/database/constants.ts
+var USER_ROLES = {
+  ADMIN: "admin",
+  MEMBER: "member"
+};
+var ALL_USER_ROLES = Object.values(USER_ROLES);
+var API_SCOPES = [
+  "sessions:read",
+  "sessions:write",
+  "questions:read",
+  "questions:answer",
+  "approvals:read",
+  "catalog:read",
+  "pull_requests:read"
+];
+var DEFAULT_API_SCOPES = API_SCOPES.filter(
+  (scope) => scope.endsWith(":read")
+);
+var DEVICE_AUTHORIZATION = {
+  /** Only these clients may open a device flow. */
+  CLIENT_IDS: ["hepha-cli"],
+  /** Lifetime of an unapproved user code. */
+  EXPIRES_IN: "15m",
+  /** Minimum delay the CLI must wait between two token polls. */
+  INTERVAL: "5s",
+  /** Page a human visits to approve a pending device. */
+  VERIFICATION_PATH: "/device"
+};
+
+// src/lib/open-browser.ts
+import { spawn } from "child_process";
+function openBrowser(url) {
+  const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const commandArgs = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    const child = spawn(command, commandArgs, {
+      stdio: "ignore",
+      detached: true
+    });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
+}
+
+// src/commands/login.ts
+var CLIENT_ID = DEVICE_AUTHORIZATION.CLIENT_IDS[0];
+function sleep(seconds) {
+  return new Promise((resolve) => setTimeout(resolve, seconds * 1e3));
+}
+async function loginCommand(parsed) {
+  const requested = parsed.flags.url?.trim();
+  if (requested && !isHttpUrl(requested)) {
+    throw new CliError(`--url is not a valid http(s) URL: "${requested}".`, 2);
+  }
+  const baseUrl = (requested ?? config.load().baseUrl).replace(/\/$/, "");
+  const authClient = createAuthClient({
+    baseURL: baseUrl,
+    plugins: [deviceAuthorizationClient()]
+  });
+  const { data: device, error: deviceError } = await authClient.device.code({
+    client_id: CLIENT_ID,
+    scope: "openid profile email"
+  });
+  if (deviceError || !device) {
+    throw new CliError(
+      deviceError?.error_description ?? `Could not start a device login against ${baseUrl}.`
+    );
+  }
+  const verificationUrl = device.verification_uri_complete ?? device.verification_uri;
+  out.line();
+  out.line(`  Code   ${out.paint(out.cell(device.user_code), "bold")}`);
+  out.line(`  Open   ${out.cell(verificationUrl)}`);
+  out.line();
+  out.line(out.paint("  Waiting for approval\u2026", "dim"));
+  openBrowser(verificationUrl);
+  let interval = device.interval ?? 5;
+  const deadline = Date.now() + (device.expires_in ?? 900) * 1e3;
+  while (Date.now() < deadline) {
+    await sleep(interval);
+    const { data: token, error } = await authClient.device.token({
+      grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+      device_code: device.device_code,
+      client_id: CLIENT_ID
+    });
+    if (token?.access_token) {
+      const identity = await api("/me", {
+        as: { baseUrl, token: token.access_token }
+      });
+      config.save({
+        baseUrl,
+        token: token.access_token,
+        user: {
+          id: identity.user.id,
+          name: identity.user.name,
+          email: identity.user.email
+        }
+      });
+      out.line();
+      out.line(
+        `${out.paint("\u2713", "green")} Signed in as ${identity.user.email} on ${baseUrl}`
+      );
+      out.line(out.paint(`  Session stored in ${config.path}`, "dim"));
+      return;
+    }
+    if (!error) {
+      continue;
+    }
+    switch (error.error) {
+      case "authorization_pending":
+        continue;
+      case "slow_down":
+        interval += 5;
+        continue;
+      case "access_denied":
+        throw new CliError("Access denied \u2014 the request was rejected.");
+      default:
+        throw new CliError(
+          error.error_description || "Device authorization failed."
+        );
+    }
+  }
+  throw new CliError("The code expired before it was approved. Try again.");
+}
+
+// src/commands/logout.ts
+function logoutCommand(parsed) {
+  config.clear();
+  if (parsed.booleans.has("json")) {
+    out.json({ signedOut: true });
+    return;
+  }
+  out.line("Signed out.");
+}
+
+// src/commands/questions.ts
+function printBatch(batch) {
+  out.line(
+    `${out.paint(out.cell(batch.sessionTitle), "bold")}  ${out.paint(`round ${batch.round}`, "dim")}`
+  );
+  out.line(
+    out.paint(
+      `batch ${out.cell(batch.id)} \xB7 session ${out.cell(batch.sessionId)}`,
+      "dim"
+    )
+  );
+  for (const question of batch.questions) {
+    out.line();
+    if (question.header) {
+      out.line(out.paint(out.cell(question.header), "dim"));
+    }
+    out.line(
+      `${out.paint(out.cell(question.id), "dim")} ${out.safe(question.body)}`
+    );
+    if (question.image) {
+      out.line(out.paint(`    (image) ${out.cell(question.image)}`, "dim"));
+    }
+    for (const option of question.options) {
+      const recommended = option.id === question.recommendedOptionId;
+      const label = option.label ? out.cell(option.label) : option.image ? out.paint(`(image) ${out.cell(option.image)}`, "dim") : out.paint("(no label)", "dim");
+      out.line(
+        `    ${out.cell(option.id)}) ${label}${recommended ? out.paint("  \u2190 recommended", "green") : ""}`
+      );
+    }
+    if (question.allowFreeText) {
+      out.line(out.paint("    free text accepted", "dim"));
+    }
+  }
+}
+function collectAnswers(parsed) {
+  if (parsed.flags.answers) {
+    try {
+      return JSON.parse(parsed.flags.answers);
+    } catch {
+      throw new CliError("--answers expects a JSON array.", 2);
+    }
+  }
+  const byQuestion = /* @__PURE__ */ new Map();
+  const put = (pair, apply) => {
+    const equalsAt = pair.indexOf("=");
+    if (equalsAt < 0) {
+      throw new CliError(`Expected <questionId>=<value>, got "${pair}".`, 2);
+    }
+    const questionId = pair.slice(0, equalsAt);
+    const entry = byQuestion.get(questionId) ?? { questionId };
+    apply(entry);
+    byQuestion.set(questionId, entry);
+  };
+  for (const pair of parsed.repeated.option ?? []) {
+    put(pair, (entry) => {
+      entry.selectedOptionIds = pair.slice(pair.indexOf("=") + 1).split(",").map((id) => id.trim()).filter(Boolean);
+    });
+  }
+  for (const pair of parsed.repeated.text ?? []) {
+    put(pair, (entry) => {
+      entry.freeText = pair.slice(pair.indexOf("=") + 1);
+    });
+  }
+  const answers = [...byQuestion.values()];
+  if (answers.length === 0) {
+    throw new CliError(
+      "Nothing to submit. Use --option <questionId>=<ids>, --text <questionId>=<answer>, or --answers <json>.",
+      2
+    );
+  }
+  return answers;
+}
+async function questionsCommand(parsed) {
+  const action = parsed.positional[0] ?? "list";
+  const asJson = parsed.booleans.has("json");
+  if (action === "list") {
+    const path = parsed.flags.session ? `/sessions/${parsed.flags.session}/questions` : "/questions";
+    const result = await api(path);
+    if (asJson) {
+      out.json(result);
+      return;
+    }
+    if (result.items.length === 0) {
+      out.line("Nothing waiting on you.");
+      return;
+    }
+    out.table(
+      result.items.map((batch) => [
+        out.cell(batch.id),
+        out.cell(batch.sessionId),
+        `${batch.questions.length} question(s)`,
+        out.cell(batch.sessionTitle)
+      ])
+    );
+    return;
+  }
+  const batchId = args.required(parsed, 1, "batchId");
+  if (action === "show") {
+    const batch = await api(`/questions/${batchId}`);
+    if (asJson) {
+      out.json(batch);
+      return;
+    }
+    printBatch(batch);
+    return;
+  }
+  if (action === "answer") {
+    const result = await api(
+      `/questions/${batchId}/submit`,
+      { method: "POST", body: { answers: collectAnswers(parsed) } }
+    );
+    if (asJson) {
+      out.json(result);
+      return;
+    }
+    out.line(
+      `${out.paint("\u2713", "green")} Answered ${result.answeredCount} question(s); the session resumes.`
+    );
+    return;
+  }
+  if (action === "cancel") {
+    const result = await api(
+      `/questions/${batchId}/cancel`,
+      { method: "POST", body: {} }
+    );
+    if (asJson) {
+      out.json(result);
+      return;
+    }
+    out.line(
+      'Round cancelled. The session stays parked \u2014 send a message to steer it: `hepha sessions send <id> "\u2026"`'
+    );
+    return;
+  }
+  throw new CliError(`Unknown questions command "${action}".`, 2);
+}
+
+// src/lib/format-event.ts
+function truncate(text, max = 2e3) {
+  const trimmed = out.safe(text).trim();
+  return trimmed.length > max ? `${trimmed.slice(0, max)}\u2026` : trimmed;
+}
+function formatEvent(event) {
+  const part = event.part;
+  switch (part.kind) {
+    case "text":
+      if (part.authorUserId) {
+        return `${out.paint("you", "magenta")}  ${truncate(part.text)}`;
+      }
+      if (part.source) {
+        return out.paint(`system ${truncate(part.text, 400)}`, "dim");
+      }
+      return `${out.paint("agent", "blue")}  ${truncate(part.text)}`;
+    case "reasoning":
+      return out.paint(`think  ${truncate(part.text, 400)}`, "dim");
+    case "tool":
+      return `${out.paint("tool", "dim")}   ${out.cell(part.toolName)} ${out.paint(`(${part.status})`, "dim")}`;
+    case "file_change":
+      return `${out.paint("file", "dim")}   ${part.changeType.padEnd(8)} ${out.cell(part.path)}`;
+    case "question":
+      return out.paint(
+        `ask    question round ${part.questionBatchId} \u2014 answer with \`hepha questions answer ${part.questionBatchId}\``,
+        "yellow"
+      );
+    case "approval":
+      return out.paint(
+        `gate   guardrail ${part.guardrailRequestId} needs a human \u2014 \`hepha approvals show ${part.guardrailRequestId}\``,
+        "yellow"
+      );
+    case "media": {
+      const target = part.url ?? part.pathname;
+      return `${out.paint("media", "dim")}  ${part.mediaType}${part.caption ? ` \u2014 ${out.cell(part.caption)}` : ""}${target ? `
+       ${out.cell(target)}` : ""}`;
+    }
+    case "error":
+      return out.paint(`error  ${truncate(part.message)}`, "red");
+    case "external_event":
+      return `${out.paint("event", "dim")}  ${out.cell(part.title)}${part.conclusion ? ` \u2014 ${out.cell(part.conclusion)}` : ""}`;
+    case "system":
+      return out.paint(`system ${truncate(part.text, 300)}`, "dim");
+    default:
+      return null;
+  }
+}
+
+// src/lib/follow.ts
+var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "killed", "abstained"]);
+var BLOCKED = /* @__PURE__ */ new Set(["waiting_human", "awaiting_approval"]);
+var POLL_SECONDS = 3;
+function sleep2(seconds) {
+  return new Promise((resolve) => setTimeout(resolve, seconds * 1e3));
+}
+async function followSession(sessionId, options = {}) {
+  let cursor = options.after ?? 0;
+  for (; ; ) {
+    const page = await api(
+      `/sessions/${sessionId}/events`,
+      { query: { after: cursor || void 0, limit: 200 } }
+    );
+    for (const event of page.items) {
+      cursor = Math.max(cursor, event.sequence);
+      if (options.quiet) {
+        continue;
+      }
+      const line = formatEvent(event);
+      if (line) {
+        out.line(line);
+      }
+    }
+    if (page.nextCursor !== null) {
+      cursor = Math.max(cursor, page.nextCursor);
+    }
+    if (page.hasMore) {
+      continue;
+    }
+    const session = await api(`/sessions/${sessionId}`);
+    if (TERMINAL.has(session.status) || BLOCKED.has(session.status)) {
+      return session;
+    }
+    await sleep2(POLL_SECONDS);
+  }
+}
+
+// src/lib/print-session.ts
+function printSession(session) {
+  out.line(
+    `${out.paint(out.cell(session.title), "bold")}  ${out.status(session.status)}`
+  );
+  const rows = [["id", out.cell(session.id)]];
+  if (session.statusReason) {
+    rows.push(["reason", out.cell(session.statusReason)]);
+  }
+  if (session.repoFullName) {
+    const branch = session.repos.find(
+      (repo) => repo.repoFullName === session.repoFullName
+    )?.branch;
+    rows.push([
+      "repo",
+      out.cell(session.repoFullName + (branch ? ` @ ${branch}` : ""))
+    ]);
+  }
+  rows.push(["task", session.taskType]);
+  if (session.model) {
+    rows.push(["model", out.cell(session.model)]);
+  }
+  if (session.prUrl) {
+    rows.push([
+      "pr",
+      out.cell(
+        `${session.prUrl}${session.prState ? ` (${session.prState})` : ""}`
+      )
+    ]);
+  }
+  for (const deliverable of session.deliverables) {
+    if (deliverable.url && deliverable.url !== session.prUrl) {
+      rows.push([out.cell(deliverable.type), out.cell(deliverable.url)]);
+    }
+  }
+  out.table(rows.map(([label, value]) => [out.paint(label, "dim"), value]));
+  const steps = session.playbook?.steps ?? [];
+  if (steps.length > 0) {
+    out.line();
+    for (const step of steps) {
+      const done = step.todos.filter(
+        (todo) => todo.status === "completed"
+      ).length;
+      const marker = done === step.todos.length && step.todos.length > 0 ? "\u2713" : "\xB7";
+      out.line(
+        `  ${marker} ${out.cell(step.title)} ${out.paint(`${done}/${step.todos.length}`, "dim")}`
+      );
+    }
+  }
+}
+
+// src/lib/session-outcome.ts
+function sessionOutcome(session) {
+  switch (session.status) {
+    case "completed":
+      return null;
+    case "waiting_human":
+      return new CliError(
+        `Waiting on an answer \u2014 \`hepha questions list --session ${session.id}\``,
+        3
+      );
+    case "awaiting_approval":
+      return new CliError(
+        "Waiting on a guardrail approval \u2014 `hepha approvals list`",
+        3
+      );
+    default:
+      return new CliError(
+        `Session ended ${session.status}${session.statusReason ? `: ${session.statusReason}` : "."}`
+      );
+  }
+}
+
+// src/commands/run.ts
+async function runCommand(parsed) {
+  const prompt = args.required(parsed, 0, "prompt");
+  const asJson = parsed.booleans.has("json");
+  const body = {
+    prompt,
+    ...parsed.flags.title ? { title: parsed.flags.title } : {},
+    ...parsed.flags["task-type"] ? { taskType: parsed.flags["task-type"] } : {},
+    ...parsed.flags.model ? { modelSelection: parsed.flags.model } : {},
+    ...parsed.flags.harness ? { harnessPin: parsed.flags.harness } : {},
+    ...parsed.flags.repo ? { repoFullName: parsed.flags.repo } : {},
+    ...parsed.flags.branch ? { branch: parsed.flags.branch } : {},
+    ...parsed.repeated.skill ? { pinnedSkillIds: parsed.repeated.skill } : {}
+  };
+  const session = await api("/sessions", {
+    method: "POST",
+    body
+  });
+  if (!parsed.booleans.has("follow")) {
+    if (asJson) {
+      out.json(session);
+      return;
+    }
+    printSession(session);
+    out.line();
+    out.line(out.paint(`  hepha sessions logs ${session.id} --follow`, "dim"));
+    return;
+  }
+  if (!asJson) {
+    out.line(out.paint(`session ${session.id}`, "dim"));
+    out.line();
+  }
+  const final = await followSession(session.id, { quiet: asJson });
+  if (asJson) {
+    out.json(final);
+  } else {
+    out.line();
+    printSession(final);
+  }
+  const outcome = sessionOutcome(final);
+  if (outcome) {
+    throw outcome;
+  }
+}
+
+// src/commands/sessions.ts
+var CONTROL_PATHS = {
+  pause: "pause",
+  resume: "resume",
+  kill: "kill",
+  archive: "archive"
+};
+async function listSessions(parsed) {
+  const result = await api("/sessions", {
+    query: {
+      statusGroup: parsed.flags.status,
+      repoFullName: parsed.flags.repo,
+      search: parsed.flags.search,
+      page: args.number(parsed, "page"),
+      limit: args.number(parsed, "limit") ?? 20,
+      scope: parsed.booleans.has("all") ? "all" : void 0
+    }
+  });
+  if (parsed.booleans.has("json")) {
+    out.json(result);
+    return;
+  }
+  if (result.data.length === 0) {
+    out.line("No sessions.");
+    return;
+  }
+  if (result.pagination.hasNextPage) {
+    out.line(
+      out.paint(
+        `page ${result.pagination.page}/${result.pagination.totalPages} \u2014 --page ${result.pagination.page + 1} for more`,
+        "dim"
+      )
+    );
+    out.line();
+  }
+  out.table(
+    result.data.map((session) => [
+      out.cell(session.id),
+      out.status(session.status),
+      out.cell(session.repoFullName ?? "\u2014"),
+      out.cell(session.title)
+    ])
+  );
+}
+async function showLogs(parsed) {
+  const sessionId = args.required(parsed, 1, "sessionId");
+  const asJson = parsed.booleans.has("json");
+  const after = args.number(parsed, "after");
+  if (parsed.booleans.has("follow")) {
+    const session = await followSession(sessionId, {
+      quiet: asJson,
+      ...after !== void 0 ? { after } : {}
+    });
+    if (asJson) {
+      out.json(session);
+    } else {
+      out.line();
+      printSession(session);
+    }
+    const outcome = sessionOutcome(session);
+    if (outcome) {
+      throw outcome;
+    }
+    return;
+  }
+  const page = await api(
+    `/sessions/${sessionId}/events`,
+    {
+      query: {
+        after,
+        limit: args.number(parsed, "limit") ?? 100
+      }
+    }
+  );
+  if (asJson) {
+    out.json(page);
+    return;
+  }
+  for (const event of page.items) {
+    const line = formatEvent(event);
+    if (line) {
+      out.line(line);
+    }
+  }
+  if (page.hasMore && page.nextCursor !== null) {
+    out.line();
+    out.line(
+      out.paint(
+        `more events \u2014 hepha sessions logs ${sessionId} --after ${page.nextCursor}`,
+        "dim"
+      )
+    );
+  }
+}
+async function sessionsCommand(parsed) {
+  const action = parsed.positional[0] ?? "list";
+  const asJson = parsed.booleans.has("json");
+  if (action === "list") {
+    return await listSessions(parsed);
+  }
+  if (action === "logs") {
+    return await showLogs(parsed);
+  }
+  const sessionId = args.required(parsed, 1, "sessionId");
+  if (action === "get") {
+    const session = await api(`/sessions/${sessionId}`);
+    if (asJson) {
+      out.json(session);
+      return;
+    }
+    printSession(session);
+    return;
+  }
+  if (action === "send") {
+    const message = args.required(parsed, 2, "message");
+    const result = await api(
+      `/sessions/${sessionId}/messages`,
+      { method: "POST", body: { message } }
+    );
+    if (asJson) {
+      out.json(result);
+      return;
+    }
+    out.line(
+      result.delivery === "interrupt" ? "Delivered to the running agent." : "Queued \u2014 the agent picks it up at the end of its turn."
+    );
+    return;
+  }
+  if (Object.hasOwn(CONTROL_PATHS, action)) {
+    const session = await api(
+      `/sessions/${sessionId}/${CONTROL_PATHS[action]}`,
+      {
+        method: "POST",
+        body: action === "kill" && parsed.flags.reason ? { reason: parsed.flags.reason } : {}
+      }
+    );
+    if (asJson) {
+      out.json(session);
+      return;
+    }
+    printSession(session);
+    return;
+  }
+  if (action === "checks") {
+    const result = await api(
+      `/sessions/${sessionId}/checks`,
+      { method: "POST", body: {} }
+    );
+    out.json(result);
+    return;
+  }
+  if (action === "pr") {
+    out.json(
+      await api(
+        `/sessions/${sessionId}/pr-checks`
+      )
+    );
+    return;
+  }
+  if (action === "verify") {
+    out.json(
+      await api(
+        `/sessions/${sessionId}/verification`
+      )
+    );
+    return;
+  }
+  throw new CliError(`Unknown sessions command "${action}".`, 2);
+}
+
+// src/commands/whoami.ts
+async function whoamiCommand(parsed) {
+  const identity = await api("/me");
+  if (parsed.booleans.has("json")) {
+    out.json(identity);
+    return;
+  }
+  out.table([
+    [
+      out.paint("user", "dim"),
+      out.cell(`${identity.user.name} <${identity.user.email}>`)
+    ],
+    [out.paint("role", "dim"), out.cell(identity.user.role ?? "member")],
+    [
+      out.paint("auth", "dim"),
+      out.cell(
+        identity.auth.method === "api_key" ? `api key${identity.auth.keyName ? ` "${identity.auth.keyName}"` : ""}` : "session"
+      )
+    ],
+    [out.paint("scopes", "dim"), identity.auth.scopes.join(" ")],
+    [out.paint("url", "dim"), config.load().baseUrl]
+  ]);
+}
+
+// src/index.ts
+var CATALOG_TOPICS = /* @__PURE__ */ new Set(["repos", "branches", "models", "skills"]);
+async function dispatch(command, argv) {
+  const parsed = args.parse(argv);
+  if (parsed.booleans.has("help")) {
+    helpCommand();
+    return;
+  }
+  if (CATALOG_TOPICS.has(command)) {
+    return await catalogCommand(command, parsed);
+  }
+  switch (command) {
+    case "login":
+      return await loginCommand(parsed);
+    case "logout":
+      return logoutCommand(parsed);
+    case "whoami":
+      return await whoamiCommand(parsed);
+    case "keys":
+      return await keysCommand(parsed);
+    case "run":
+      return await runCommand(parsed);
+    case "sessions":
+      return await sessionsCommand(parsed);
+    case "questions":
+      return await questionsCommand(parsed);
+    case "approvals":
+      return await approvalsCommand(parsed);
+    default:
+      helpCommand();
+      throw new CliError(`Unknown command "${command}".`, 2);
+  }
+}
+async function main() {
+  const [command, ...argv] = process.argv.slice(2);
+  if (!command || command === "help" || command === "--help") {
+    helpCommand();
+    return;
+  }
+  await dispatch(command, argv);
+}
+main().catch((error) => {
+  if (error instanceof CliError) {
+    out.error(error.message);
+    process.exit(error.exitCode);
+  }
+  out.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});
+//# sourceMappingURL=index.js.map