@tryarcanist/cli 0.1.166 → 0.1.167

package/README.md

@@ -159,12 +159,45 @@ Repeatable `--uploaded-file <path>` flags attach local UTF-8 text files to the p
 
 `--cold` is a deprecated no-op retained for backward compatibility. Sessions always start from a fresh sandbox (the warm sandbox pool was removed), so the flag has no effect.
 
-`--idempotency-key <uuid>` is for manually retrying a create request that may have reached the server. The CLI derives separate session and prompt idempotency keys from the provided value.
+`--idempotency-key <uuid>` is for manually retrying a create request that may have reached the server.
+The CLI derives separate session and prompt idempotency keys from the provided value.
 
 `--onboarding` creates an onboarding session: the agent authors the repo's `.arcanist.json`, `.arcanist/` runtime files, `ARCANIST.md`, and conditionally `.arcanist/sandbox.yaml` + `.arcanist/sandbox.layer.Dockerfile` (when the base sandbox lacks a needed toolchain), proves what it can inside its sandbox, and opens the setup PR ready for review. The onboarding behavior is driven by the bridge's canonical onboarding playbook, not the prompt, so `--onboarding` needs no prompt: `arcanist sessions create <repo> --onboarding --wait`. Any prompt supplied alongside `--onboarding` is ignored. Team use; not part of the external API surface.
 
 JSON mode returns `{sessionId, sessionUrl?, repoUrl, model?, agentRuntimeBackend?, reasoningEffort?, baseBranch?, startBranch?, continuePrUrl?, continueMode?, onboarding?, promptId?}`. `sessionUrl` is emitted only when the server returns it; `agentRuntimeBackend` only when `--backend` is passed. With `--wait`, JSON mode also includes best-effort result fields when available: `prUrl?`, `publishedBranch?`, and `lastBranch?`.
 
+### `arcanist sessions qa <pr-url>`
+
+Starts a QA verification session for an existing GitHub pull request.
+
+```bash
+arcanist sessions qa https://github.com/your-org/your-repo/pull/123
+arcanist sessions qa https://github.com/your-org/your-repo/pull/123 --model gpt-5.4
+arcanist sessions qa https://github.com/your-org/your-repo/pull/123 --backend claude_code --model claude-opus-4-8
+arcanist sessions qa https://github.com/your-org/your-repo/pull/123 --reasoning-effort xhigh
+arcanist sessions qa https://github.com/your-org/your-repo/pull/123 --wait
+arcanist sessions qa https://github.com/your-org/your-repo/pull/123 --idempotency-key 1f0e6f1a-...
+```
+
+The PR URL must be `https://github.com/<owner>/<repo>/pull/<number>`.
+The CLI derives the repo from that URL, creates a QA session with `qa: true` and `targetPrUrl`, then enqueues the verifier prompt.
+Inspect progress with the session URL or the session events stream.
+
+`--backend` picks the agent runtime backend: `codex` (default), `claude_code`, or `opencode`.
+`--model` must be valid for the chosen backend, and the CLI rejects mismatches before any network call.
+When `--model` is omitted, the backend default is used.
+
+`--wait` blocks until the enqueued QA prompt finishes and exits non-zero if the prompt fails.
+JSON mode waits quietly and prints the create payload after the prompt completes successfully.
+`--poll-interval <ms>` tunes completion polling.
+
+`--idempotency-key <uuid>` is for manually retrying a QA request that may have reached the server.
+The CLI derives separate session and prompt idempotency keys from the provided value.
+If session creation succeeds but prompt enqueue fails, retry the same command with the same `--idempotency-key`.
+
+JSON mode returns `{sessionId, sessionUrl?, repoUrl, targetPrUrl, model?, agentRuntimeBackend?, reasoningEffort?, promptId?}`.
+Active-verifier and per-PR run-limit conflicts both use exit code `4`; active-verifier errors include the existing session handle when the server returns it.
+
 ### `arcanist sessions send <session-id> [prompt]`
 
 Sends a follow-up message to an existing session.

package/dist/index.js

@@ -2655,6 +2655,31 @@ function renderWatchEvent(event, state) {
   }
 }
 
+// src/commands/model-options.ts
+function resolveModelAndBackend(options) {
+  let agentRuntimeBackend = CODEX_AGENT_RUNTIME_BACKEND;
+  if (options.backend !== void 0) {
+    if (!isAgentRuntimeBackend(options.backend)) {
+      throw new CliError(
+        "user",
+        `Invalid --backend '${options.backend}'. Expected ${AGENT_RUNTIME_BACKENDS.join(", ")}.`
+      );
+    }
+    agentRuntimeBackend = options.backend;
+  }
+  if (options.model !== void 0) {
+    const normalizedModel = extractModelId(options.model);
+    if (normalizedModel === void 0 || !isSessionStartModelAllowedForBackend(normalizedModel, agentRuntimeBackend)) {
+      const allowed = getSessionStartModelIdsForBackend(agentRuntimeBackend).join(", ");
+      throw new CliError(
+        "user",
+        `Model '${options.model}' is not selectable for backend '${agentRuntimeBackend}'. Allowed: ${allowed}.`
+      );
+    }
+  }
+  return agentRuntimeBackend;
+}
+
 // ../../shared/session/transient-disconnect.ts
 var TRANSIENT_DISCONNECT_VISIBILITY_MS = 15e3;
 function nextDisconnectMask(mask, previous, current, now) {
@@ -2930,26 +2955,7 @@ async function createCommand(repoUrl, promptArg, options, command) {
   const runtime = getRuntimeOptions(command, options);
   assertArcanistSessionMutationAllowed("create");
   const config = requireConfig(runtime);
-  let agentRuntimeBackend = CODEX_AGENT_RUNTIME_BACKEND;
-  if (options.backend !== void 0) {
-    if (!isAgentRuntimeBackend(options.backend)) {
-      throw new CliError(
-        "user",
-        `Invalid --backend '${options.backend}'. Expected ${AGENT_RUNTIME_BACKENDS.join(", ")}.`
-      );
-    }
-    agentRuntimeBackend = options.backend;
-  }
-  if (options.model !== void 0) {
-    const normalizedModel = extractModelId(options.model);
-    if (normalizedModel === void 0 || !isSessionStartModelAllowedForBackend(normalizedModel, agentRuntimeBackend)) {
-      const allowed = getSessionStartModelIdsForBackend(agentRuntimeBackend).join(", ");
-      throw new CliError(
-        "user",
-        `Model '${options.model}' is not selectable for backend '${agentRuntimeBackend}'. Allowed: ${allowed}.`
-      );
-    }
-  }
+  const agentRuntimeBackend = resolveModelAndBackend(options);
   const prompt = options.onboarding ? ONBOARDING_PROMPT : await resolvePromptInput(promptArg, options);
   const waitPollIntervalMs = options.wait ? parsePollInterval(options.pollInterval) : null;
   const repoError = validateRepoUrl(repoUrl);
@@ -3263,6 +3269,137 @@ async function messageCommand(sessionId, promptArg, options = {}, command) {
   console.log(`Message sent to session ${sessionId}.`);
 }
 
+// ../../shared/agent/verify-directive.ts
+var MAX_TARGET_PR_URL_LENGTH = 500;
+function normalizeGithubPullRequestUrl(rawUrl) {
+  if (typeof rawUrl !== "string") return null;
+  const trimmed = rawUrl.trim();
+  if (!trimmed || trimmed.length > MAX_TARGET_PR_URL_LENGTH) return null;
+  let url;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "https:" || url.hostname.toLowerCase() !== "github.com") return null;
+  const pathParts = url.pathname.split("/").filter(Boolean);
+  if (pathParts.length !== 4 || pathParts[2] !== "pull" || !/^\d+$/.test(pathParts[3])) return null;
+  if (!/^[A-Za-z0-9_.-]+$/.test(pathParts[0]) || !/^[A-Za-z0-9_.-]+$/.test(pathParts[1])) return null;
+  return `https://github.com/${pathParts[0]}/${pathParts[1]}/pull/${pathParts[3]}`;
+}
+
+// src/commands/qa.ts
+var QA_PROMPT = "Verify this pull request.";
+function parseCanonicalPrUrl(prUrl) {
+  const targetPrUrl = normalizeGithubPullRequestUrl(prUrl);
+  if (!targetPrUrl) {
+    throw new CliError(
+      "user",
+      `Invalid pull request URL: "${prUrl}". Expected https://github.com/<owner>/<repo>/pull/<number>.`
+    );
+  }
+  const url = new URL(targetPrUrl);
+  const [owner, repo] = url.pathname.split("/").filter(Boolean);
+  return {
+    targetPrUrl,
+    repoUrl: `https://github.com/${owner}/${repo}`
+  };
+}
+function parseCreateConflict(error) {
+  let message = error.message;
+  let sessionId;
+  let sessionUrl;
+  try {
+    const parsed = JSON.parse(error.body);
+    const parsedMessage = typeof parsed.error === "string" ? parsed.error : typeof parsed.error?.message === "string" ? parsed.error.message : void 0;
+    if (parsedMessage) message = parsedMessage;
+    if (typeof parsed.sessionId === "string") sessionId = parsed.sessionId;
+    if (typeof parsed.sessionUrl === "string") sessionUrl = parsed.sessionUrl;
+  } catch {
+  }
+  const location = sessionUrl ? ` (${sessionUrl})` : "";
+  const existing = sessionId ? ` Existing verifier session: ${sessionId}${location}.` : "";
+  return new CliError("conflict", `${message}${existing}`, {
+    hint: error.hint,
+    requestId: error.requestId
+  });
+}
+async function qaCommand(prUrl, options, command) {
+  const runtime = getRuntimeOptions(command, options);
+  assertArcanistSessionMutationAllowed("qa");
+  const config = requireConfig(runtime);
+  const { targetPrUrl, repoUrl } = parseCanonicalPrUrl(prUrl);
+  const agentRuntimeBackend = resolveModelAndBackend(options);
+  const idempotencyKey = options.idempotencyKey ?? randomIdempotencyKey();
+  const sessionIdempotencyKey = `${idempotencyKey}:session`;
+  const promptIdempotencyKey = `${idempotencyKey}:prompt`;
+  const body = {
+    context: { repoUrl },
+    qa: true,
+    targetPrUrl
+  };
+  if (options.model) body.model = options.model;
+  if (options.backend) body.agentRuntimeBackend = agentRuntimeBackend;
+  if (options.reasoningEffort) body.reasoningEffort = options.reasoningEffort;
+  let sessionData;
+  try {
+    sessionData = await apiFetch(config, "/api/sessions", {
+      method: "POST",
+      headers: { "Idempotency-Key": sessionIdempotencyKey },
+      body: JSON.stringify(body)
+    });
+  } catch (err) {
+    if (err instanceof ApiError && err.status === 409) throw parseCreateConflict(err);
+    throw err;
+  }
+  const sessionId = sessionData.sessionId;
+  let promptId;
+  try {
+    const promptData = await apiFetch(config, `/api/sessions/${sessionId}/prompts`, {
+      method: "POST",
+      headers: { "Idempotency-Key": promptIdempotencyKey },
+      body: JSON.stringify({ prompt: QA_PROMPT })
+    });
+    promptId = promptData.prompt?.promptId ?? promptData.prompt?.id;
+  } catch (err) {
+    throw new CliError(
+      err instanceof CliError ? err.code : "server",
+      `QA session created (${sessionId}) but prompt enqueue failed: ${stringifyError(err)}`,
+      {
+        exitCode: err instanceof CliError ? err.exitCode : void 0,
+        hint: `Retry with: arcanist sessions qa ${targetPrUrl} --idempotency-key ${idempotencyKey}`,
+        requestId: err instanceof CliError ? err.requestId : void 0
+      }
+    );
+  }
+  if (options.wait) {
+    const waitPollIntervalMs = parsePollInterval(options.pollInterval);
+    if (!isJson(command, options)) {
+      console.log(`Session: ${sessionId}`);
+      if (sessionData.sessionUrl) console.log(`URL: ${sessionData.sessionUrl}`);
+    }
+    await waitForCreatedPrompt(sessionId, promptId, sessionData.sessionUrl, waitPollIntervalMs, runtime, command);
+    if (!isJson(command, options)) {
+      console.log(`Target PR: ${targetPrUrl}`);
+    }
+  }
+  if (isJson(command, options)) {
+    const output = { sessionId, repoUrl, targetPrUrl };
+    if (sessionData.sessionUrl) output.sessionUrl = sessionData.sessionUrl;
+    if (options.model) output.model = options.model;
+    if (options.backend) output.agentRuntimeBackend = agentRuntimeBackend;
+    if (options.reasoningEffort) output.reasoningEffort = options.reasoningEffort;
+    if (promptId) output.promptId = promptId;
+    writeJson(output);
+    return;
+  }
+  if (options.wait) return;
+  console.log(`Session: ${sessionId}`);
+  if (sessionData.sessionUrl) console.log(`URL: ${sessionData.sessionUrl}`);
+  console.log(`Target PR: ${targetPrUrl}`);
+  console.log(`Follow with: arcanist sessions events ${sessionId} --follow --json`);
+}
+
 // src/commands/sandbox.ts
 import { execFileSync } from "child_process";
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
@@ -4682,6 +4819,25 @@ JSON mode returns {sessionId, promptId?}
 `
   );
 }
+function addQaOptions(cmd) {
+  return cmd.argument("<pr-url>", "GitHub pull request URL to QA").option("--model <model>", "Model to use").option("--backend <backend>", "Agent runtime backend: codex (default), claude_code, or opencode").option("--reasoning-effort <effort>", "Reasoning effort to use for models that support it").option("--wait", "Wait for the QA prompt to finish and exit non-zero if it fails").option(
+    "--poll-interval <ms>",
+    "Polling interval in milliseconds while waiting",
+    String(DEFAULT_WATCH_POLL_INTERVAL_MS)
+  ).option("--idempotency-key <uuid>", "Request idempotency key for safe manual retries").addHelpText(
+    "after",
+    `
+Examples:
+  arcanist sessions qa https://github.com/org/repo/pull/123
+  arcanist sessions qa https://github.com/org/repo/pull/123 --model gpt-5.4 --wait
+  arcanist sessions qa https://github.com/org/repo/pull/123 --idempotency-key 1f0e6f1a-...
+
+JSON:
+JSON mode returns {sessionId, sessionUrl?, repoUrl, targetPrUrl, model?, agentRuntimeBackend?, reasoningEffort?, promptId?}
+  Inspect progress with the session URL or the session events stream.
+`
+  );
+}
 var auth = program.command("auth").description("Authentication commands");
 auth.command("login").description("Authenticate with a personal access token").option("--token-stdin", "Read token from stdin instead of interactive prompt").option("--api-url <url>", "Set custom API URL").addHelpText(
   "after",
@@ -4707,6 +4863,9 @@ addCreateOptions(sessions.command("create").description("Create a session and se
 addSendOptions(sessions.command("send").description("Send a message to an existing session")).action(
   (sessionId, prompt, options, command) => messageCommand(sessionId, prompt, options, command)
 );
+addQaOptions(sessions.command("qa").description("Start a QA verification session for a GitHub pull request")).action(
+  (prUrl, options, command) => qaCommand(prUrl, options, command)
+);
 sessions.command("stop").description("Stop the active run for a session").argument("<session-id>", "Session ID").addHelpText(
   "after",
   `

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryarcanist/cli",
-  "version": "0.1.166",
+  "version": "0.1.167",
   "description": "CLI for Arcanist — create and manage coding agent sessions",
   "type": "module",
   "bin": {