@tryarcanist/cli 0.1.165 → 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

@@ -7,6 +7,11 @@ import { Command } from "commander";
 // src/api.ts
 import { createRequire } from "module";
 
+// ../../shared/utils/errors.ts
+function stringifyError(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
 // ../../shared/utils/url.ts
 function normalizeBaseUrl(url) {
   return url.replace(/\/+$/, "");
@@ -122,7 +127,7 @@ async function apiRequest(config, path, init) {
       headers
     });
   } catch (err) {
-    throw new CliError("server", `Network error: ${err instanceof Error ? err.message : String(err)}`);
+    throw new CliError("server", `Network error: ${stringifyError(err)}`);
   }
   if (!res.ok) {
     const body = await res.text().catch(() => "");
@@ -504,6 +509,12 @@ var AGENT_RUNTIME_BACKENDS = [
   CLAUDE_CODE_AGENT_RUNTIME_BACKEND,
   OPENCODE_AGENT_RUNTIME_BACKEND
 ];
+var AGENT_RUNTIME_BACKEND_NAMES = {
+  [CODEX_AGENT_RUNTIME_BACKEND]: "Codex",
+  [CLAUDE_CODE_AGENT_RUNTIME_BACKEND]: "Claude Code",
+  // "opencode" is intentionally lowercase to match the project's brand name.
+  [OPENCODE_AGENT_RUNTIME_BACKEND]: "opencode"
+};
 function isAgentRuntimeBackend(value) {
   return AGENT_RUNTIME_BACKENDS.includes(value);
 }
@@ -536,7 +547,9 @@ var AnthropicModel = {
   Sonnet46: "claude-sonnet-4-6"
 };
 var BasetenModel = {
-  Glm47: "glm-4.7"
+  Glm47: "glm-4.7",
+  GptOss120B: "gpt-oss-120b",
+  KimiK27Code: "kimi-k2.7-code"
 };
 var MODEL_PROVIDERS_SET = /* @__PURE__ */ new Set([
   "openai",
@@ -707,6 +720,33 @@ var MODEL_REGISTRY = [
     providerModelId: "zai-org/GLM-4.7",
     pricing: { inputPerMillion: 0.6, outputPerMillion: 2.2, cacheReadPerMillion: 0.12 },
     sessionStart: { eligible: true, isDefault: true }
+  },
+  {
+    id: BasetenModel.GptOss120B,
+    name: "GPT OSS 120B",
+    provider: "baseten",
+    backends: [OPENCODE_AGENT_RUNTIME_BACKEND],
+    contextWindow: 128e3,
+    // Verified 2026-07-04 against Baseten Model APIs docs and model library:
+    // wire id `openai/gpt-oss-120b`, 128k served context/output, OpenAI SDK
+    // compatible, Apache 2.0, tool calling supported for all Model APIs.
+    providerModelId: "openai/gpt-oss-120b",
+    pricing: { inputPerMillion: 0.1, outputPerMillion: 0.5 },
+    sessionStart: { eligible: true }
+  },
+  {
+    id: BasetenModel.KimiK27Code,
+    name: "Kimi K2.7 Code",
+    provider: "baseten",
+    backends: [OPENCODE_AGENT_RUNTIME_BACKEND],
+    contextWindow: 262e3,
+    // Verified 2026-07-04 against Baseten Model APIs docs, model library, and
+    // changelog: wire id `moonshotai/Kimi-K2.7-Code`, 262k served
+    // context/output, OpenAI SDK compatible, MIT license, tool calling
+    // supported for all Model APIs.
+    providerModelId: "moonshotai/Kimi-K2.7-Code",
+    pricing: { inputPerMillion: 0.95, outputPerMillion: 4, cacheReadPerMillion: 0.16 },
+    sessionStart: { eligible: true }
   }
 ];
 var MODEL_PROVIDER_NAMES = {
@@ -1006,7 +1046,7 @@ async function automationApiFetchText(config, path, init) {
 }
 function mapAutomationApiError(err) {
   if (!(err instanceof ApiError)) {
-    return err instanceof CliError ? err : new CliError("server", err instanceof Error ? err.message : String(err));
+    return err instanceof CliError ? err : new CliError("server", stringifyError(err));
   }
   const parsed = parseApiErrorBody2(err.body);
   const serverCode = parsed?.error;
@@ -1053,6 +1093,19 @@ function sleep(ms) {
 }
 
 // ../../shared/session/phase.ts
+var PHASES = [
+  "idle",
+  "running",
+  "waiting_for_input",
+  "finalizing",
+  "review_listening",
+  "completed",
+  "superseded",
+  "blocked",
+  "failed",
+  "stopped",
+  "archived"
+];
 var TERMINAL_PHASES_ARRAY = [
   "completed",
   "superseded",
@@ -1186,7 +1239,7 @@ async function resolveUploadedFileOptions(files) {
       try {
         return { name, content: await readFile(path, "utf8") };
       } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
+        const message = stringifyError(err);
         throw new CliError("user", `Failed to read uploaded file ${path}: ${message}`);
       }
     })
@@ -2162,6 +2215,7 @@ var ERROR_CODES = [
   "api_error",
   "config_error",
   "failed_edits",
+  "memory_enforcement_failed",
   "failure_loop_suspected",
   "empty_completion",
   "followup_not_started",
@@ -2202,6 +2256,7 @@ var ERROR_CODE_LABELS = {
   api_error: "Provider API error",
   config_error: "Configuration error",
   failed_edits: "Edit failure",
+  memory_enforcement_failed: "Memory enforcement failed",
   failure_loop_suspected: "Suspected failure loop",
   empty_completion: "Empty completion",
   followup_not_started: "Follow-up did not start",
@@ -2245,19 +2300,7 @@ function formatSessionErrorMessage(error, code) {
 // src/utils/session-output.ts
 var SHORT_SESSION_ID_LENGTH = 8;
 var PROMPT_LABEL_MAX_CHARS = 80;
-var VALID_PHASES = /* @__PURE__ */ new Set([
-  "idle",
-  "running",
-  "waiting_for_input",
-  "finalizing",
-  "review_listening",
-  "completed",
-  "superseded",
-  "blocked",
-  "failed",
-  "stopped",
-  "archived"
-]);
+var VALID_PHASES = new Set(PHASES);
 var VALID_SANDBOX_SUBSTATES = /* @__PURE__ */ new Set(["creating", "reconnecting", "stopping", "none"]);
 var VALID_STOP_MODES = /* @__PURE__ */ new Set(["user", "resumable", "none"]);
 var VALID_FINALIZING_STEPS = /* @__PURE__ */ new Set(["post_execution", "publishing", "none"]);
@@ -2526,7 +2569,7 @@ function parseJsonObject(value) {
     const parsed = JSON.parse(value);
     return parsed && typeof parsed === "object" ? parsed : {};
   } catch (err) {
-    throw new Error(`Malformed SSE JSON payload: ${err instanceof Error ? err.message : String(err)}`);
+    throw new Error(`Malformed SSE JSON payload: ${stringifyError(err)}`);
   }
 }
 function formatPromptLabel(promptId, promptLabels) {
@@ -2612,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) {
@@ -2706,9 +2774,7 @@ async function watchCommand(sessionId, options, command) {
     try {
       promptLabels = await fetchPromptLabels(config, sessionId);
     } catch (err) {
-      console.error(
-        `Warning: failed to fetch prompt labels for session ${sessionId}: ${err instanceof Error ? err.message : String(err)}`
-      );
+      console.error(`Warning: failed to fetch prompt labels for session ${sessionId}: ${stringifyError(err)}`);
     }
   }
   const renderState = {
@@ -2889,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);
@@ -2969,7 +3016,7 @@ async function createCommand(repoUrl, promptArg, options, command) {
   } catch (err) {
     throw new CliError(
       err instanceof CliError ? err.code : "server",
-      `Session created (${sessionId}) but prompt failed: ${err instanceof Error ? err.message : String(err)}`,
+      `Session created (${sessionId}) but prompt failed: ${stringifyError(err)}`,
       {
         exitCode: err instanceof CliError ? err.exitCode : void 0,
         hint: `Retry with: arcanist sessions send ${sessionId} --prompt-stdin`,
@@ -3222,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";
@@ -3763,7 +3941,7 @@ function git(args) {
   try {
     return execFileSync("git", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
   } catch (err) {
-    throw new CliError("user", `git ${args.join(" ")} failed: ${err instanceof Error ? err.message : String(err)}`);
+    throw new CliError("user", `git ${args.join(" ")} failed: ${stringifyError(err)}`);
   }
 }
 function currentRepo() {
@@ -4346,9 +4524,7 @@ async function sessionEventsCommand(sessionId, options, command) {
     return;
   }
   const promptLabels = await fetchPromptLabels(config, sessionId).catch((err) => {
-    console.error(
-      `Warning: failed to fetch prompt labels for session ${sessionId}: ${err instanceof Error ? err.message : String(err)}`
-    );
+    console.error(`Warning: failed to fetch prompt labels for session ${sessionId}: ${stringifyError(err)}`);
     return /* @__PURE__ */ new Map();
   });
   const state = { promptLabels, toolCalls: /* @__PURE__ */ new Map() };
@@ -4643,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",
@@ -4668,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.165",
+  "version": "0.1.167",
   "description": "CLI for Arcanist — create and manage coding agent sessions",
   "type": "module",
   "bin": {