ccdeck 3.43.4 → 3.44.0

package/src/server/skill-hook.mjs

@@ -0,0 +1,162 @@
+// Whether the deck may add the UserPromptExpansion hook that Skill activity
+// counts typed slash commands with (#2181) — and, until somebody asks for it,
+// the answer is no.
+//
+// WHY THIS ENTRY IS GATED HARDER THAN STOPFAILURE. A hook event name Claude
+// Code does not know is not skipped by every version. Up to 2.1.100 it made
+// Claude Code ignore the WHOLE settings.json — the user's permissions, env,
+// model and every hook in it, ours included — without a word on screen. 2.1.101
+// changed that ("an unrecognized hook event name in settings.json no longer
+// causes the entire file to be ignored", Claude Code's CHANGELOG.md, 2.1.101).
+// UserPromptExpansion itself arrived later still: the first npm release whose
+// CLI carries the name, and whose Agent SDK lists it in HOOK_EVENTS, is 2.1.116
+// (2.1.114 has neither, and there is no 2.1.115). Checked offline against the
+// published packages, with a scratch config holding the deck's own entry shape:
+//
+//   2.1.100  the whole file ignored — no hook fired, no env applied
+//   2.1.101  the file read, the entry ignored
+//   2.1.114  the file read, the entry ignored
+//   2.1.116  the file read, the entry fired on a typed custom command
+//
+// So the gate is the later of the two: 2.1.116, which is where the entry is
+// both harmless and useful. Below it the entry buys nothing, and below 2.1.101
+// it costs the user every setting they have.
+//
+// WHAT HAS TO BE TRUE before the entry is written:
+//   - the deck was started with AGENTS_DECK_SKILL_HOOK=1 — never by default;
+//   - at least one Claude Code was found, the way the deck finds `claude`: the
+//     candidate list (claude-dir.mjs) and AGENTS_DECK_CLAUDE;
+//   - EVERY one found says which version it is, and every one is 2.1.116 or
+//     newer. An old CLI anywhere on the machine still reads the same file, and
+//     one that will not say its version is treated as an old one.
+// A version is read off disk first (claude-dir.mjs, no child process). Only
+// for an install whose layout does not name one — a wrapper script, an unusual
+// prefix — and only once the user has opted in, is that binary asked
+// `--version`, by its full path and as argv, and believed only when it answers
+// the way Claude Code does: `<x.y.z> (Claude Code)`.
+//
+// Every boot re-decides. A machine that stops passing — the opt-in removed, a
+// Claude Code rolled back, a second, older one installed — has the entry taken
+// back out by the next start (installer.mjs), and the user's own
+// UserPromptExpansion hooks are left where they are.
+import { claudeCodeInstalls, claudeVersionAtLeast } from "./claude-dir.mjs";
+import { run } from "./exec.mjs";
+
+export const USER_PROMPT_EXPANSION = "UserPromptExpansion";
+
+/** The first Claude Code that knows the event: 2.1.116 (npm). */
+export const USER_PROMPT_EXPANSION_SINCE = "2.1.116";
+
+/** The first Claude Code that skips an unknown hook event instead of ignoring
+ *  the whole settings.json: 2.1.101 (CHANGELOG.md). */
+export const UNKNOWN_EVENT_TOLERATED_SINCE = "2.1.101";
+
+/** The gate: a version that is past both of the above. */
+export const SKILL_HOOK_SINCE = claudeVersionAtLeast(USER_PROMPT_EXPANSION_SINCE, UNKNOWN_EVENT_TOLERATED_SINCE)
+  ? USER_PROMPT_EXPANSION_SINCE
+  : UNKNOWN_EVENT_TOLERATED_SINCE;
+
+/** Set to "1" to ask for the entry. Anything else, or nothing, is no. */
+export const SKILL_HOOK_ENV = "AGENTS_DECK_SKILL_HOOK";
+
+/** Whether the person starting the deck asked for the entry. Only the exact
+ *  string "1": a typo or a "true" does not turn it on. */
+export function skillHookOptedIn(env = process.env) {
+  return env?.[SKILL_HOOK_ENV] === "1";
+}
+
+/** A `--version` that is not quick is not Claude Code's fast path. */
+const PROBE_TIMEOUT_MS = 5_000;
+
+/** What Claude Code prints for `--version`, e.g. `2.1.116 (Claude Code)`. A
+ *  first line in any other shape — a wrapper's own version, an error, an
+ *  update notice — is no answer. */
+const VERSION_LINE_RE = /^(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]*)?) \(Claude Code\)$/;
+
+/** The version in Claude Code's own `--version` output, or undefined. */
+export function parseClaudeVersionOutput(text) {
+  const first = String(text ?? "").split(/\r?\n/).map(l => l.trim()).find(l => l !== "");
+  const m = first === undefined ? null : VERSION_LINE_RE.exec(first);
+  return m ? m[1] : undefined;
+}
+
+async function askVersion(runImpl, bin, timeout) {
+  try {
+    const r = await runImpl(bin, ["--version"], { timeout });
+    return r?.ok ? parseClaudeVersionOutput(r.stdout) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The decision, and why:
+ *
+ *   { install: false, state: "off",     reason: "not-enabled" }
+ *   { install: false, state: "skipped", reason: "no-claude" | "version-unknown" | "too-old", versions }
+ *   { install: true,  state: "on",      versions }
+ *
+ * `versions` is what was found, in the order found, with `null` for an install
+ * that did not say. `since` is the gate. Never throws: a probe that fails is a
+ * version that is unknown, which is a refusal.
+ *
+ * Every dependency is injected so the suite can lay out any machine: `installs`
+ * is claudeCodeInstalls()'s answer, `runImpl` is exec.mjs's run.
+ */
+export async function skillHookDecision({
+  env = process.env,
+  optedIn = skillHookOptedIn(env),
+  installs,
+  runImpl = run,
+  timeout = PROBE_TIMEOUT_MS,
+} = {}) {
+  const since = SKILL_HOOK_SINCE;
+  // Off is decided before anything is looked at: a deck that was not asked
+  // spends nothing on the question, and spawns nothing.
+  if (!optedIn) return { install: false, state: "off", reason: "not-enabled", since, versions: [] };
+  let found;
+  try {
+    found = Array.isArray(installs) ? [...installs] : claudeCodeInstalls();
+  } catch {
+    found = [];
+  }
+  // AGENTS_DECK_CLAUDE is the other way the deck finds `claude` — the sign-in
+  // and the account panel run it ahead of the candidate list
+  // (claude-identity.mjs) — so it is one more Claude Code that reads this
+  // settings.json. Its layout is not read: it is asked.
+  const configured = typeof env?.AGENTS_DECK_CLAUDE === "string" ? env.AGENTS_DECK_CLAUDE.trim() : "";
+  if (configured && !found.some(i => i.bin === configured)) found.push({ bin: configured, version: undefined });
+  if (found.length === 0) return { install: false, state: "skipped", reason: "no-claude", since, versions: [] };
+  const versions = [];
+  for (const { bin, version } of found) {
+    const v = version ?? (typeof bin === "string" && bin ? await askVersion(runImpl, bin, timeout) : undefined);
+    versions.push(v ?? null);
+  }
+  if (versions.some(v => v === null)) return { install: false, state: "skipped", reason: "version-unknown", since, versions };
+  if (!versions.every(v => claudeVersionAtLeast(v, since))) {
+    return { install: false, state: "skipped", reason: "too-old", since, versions };
+  }
+  return { install: true, state: "on", since, versions };
+}
+
+/**
+ * The boot report's row for the entry — `{ ok, detail }` — or null when there
+ * is nothing to say, which is the default: nobody asked for it, and a deck
+ * that was not asked prints exactly what it printed before. `dash` is the
+ * screen's own (bin/cli/screen.js), so the line carries no punctuation a
+ * legacy console cannot draw.
+ */
+export function skillHookStatus(decision, dash = "-") {
+  if (!decision || decision.state === "off") return null;
+  const found = (decision.versions ?? []).map(v => v ?? "unknown").join(", ");
+  if (decision.state === "on") return { ok: true, detail: `on ${dash} counts typed slash commands (Claude Code ${found})` };
+  const why = {
+    "no-claude": "no Claude Code found",
+    "version-unknown": `a Claude Code here does not say its version (found: ${found})`,
+    "too-old": `needs Claude Code ${decision.since} or newer everywhere (found: ${found})`,
+    "settings-shape": "the hooks in settings.json are not in a shape the deck can add to",
+    "backup-failed": "settings.json could not be backed up first",
+    raced: "settings.json changed while installing; the next start tries again",
+  }[decision.reason] ?? "not allowed";
+  return { ok: false, detail: `not installed ${dash} ${why}` };
+}

package/src/server/stop-continue-gate.d.mts

@@ -0,0 +1,8 @@
+import type { StopFacts } from "./stop-failure.mjs";
+export interface LoginEvidence { ok: boolean; at: number; room: boolean | null }
+export type GateReason = "no-login" | "before-stop" | "no-room";
+export interface Gate { ready: boolean; reason: GateReason | null }
+export const CONTINUE_PROMPT: string;
+export const REPEAT_HOLD_MS: number;
+export function loginEvidence(reading: unknown): LoginEvidence | null;
+export function continueGate(stop: Pick<StopFacts, "kind" | "at"> | null | undefined, login: LoginEvidence | null | undefined): Gate;

package/src/server/stop-continue-gate.mjs

@@ -0,0 +1,77 @@
+// When a turn that stopped on an expired login or a usage limit may be run
+// again (#2193), read once for both halves of the deck: the page draws the
+// Continue button from it, and the server refuses a press — and holds back the
+// automatic continue — on the same answer. The page imports this file the way
+// it imports stop-failure.mjs, so the two cannot come to disagree about one
+// stop.
+//
+// WHAT COUNTS AS "A WORKING LOGIN IS ACTIVE AGAIN". The deck's newest reading
+// of the active account's usage (quota.mjs), taken AFTER the stop and without
+// an error. That reading is made with the very credentials a session uses —
+// Claude Code's own token, `claude --print /usage`, or claude-swap's copy of
+// the active account — so a login that is still dead cannot produce one, and
+// one from before the stop says nothing about the login now. A switch of
+// account invalidates the reading, so the next one is about the new account.
+//
+// And the account has to have room: a working login on an account at 100% of
+// its 5-hour or 7-day window would stop the turn again on a usage limit at its
+// first request.
+//
+// Pure. Nothing here reads a clock, a file or a process.
+
+/** What the deck sends a background session to continue the turn that
+ *  failed: Claude Code's own words for it, the default of
+ *  CLAUDE_CODE_RESUME_PROMPT (code.claude.com/docs/en/env-vars), which is what
+ *  Claude Code sends when it continues an interrupted turn by itself. */
+export const CONTINUE_PROMPT = "Continue from where you left off.";
+
+/**
+ * A session the deck continued automatically, which then stops again on a
+ * login or a limit inside this window, is not continued automatically again
+ * until somebody acts on it — a prompt typed into it, or a press of Continue.
+ * That is the loop the setting must never become: a login that works for one
+ * request and dies on the next would otherwise be continued, stop, and be
+ * continued again for as long as the deck runs.
+ */
+export const REPEAT_HOLD_MS = 60 * 60_000;
+
+/**
+ * The quota reading as the gate reads it: `{ ok, at, room }`, or null when
+ * there is no reading at all.
+ *
+ *   ok    the reading is a real one, not a failure to read
+ *   at    when its numbers were collected — the reading's own clock, which is
+ *         the one that can be compared with a stop's (a reading the deck is
+ *         only holding over is still as old as it says)
+ *   room  both of the account's windows are under 100%, or null when the
+ *         reading names neither
+ */
+export function loginEvidence(reading) {
+  if (!reading || typeof reading !== "object") return null;
+  const at = Number(reading.fetchedAt);
+  const when = Number.isFinite(at) && at > 0 ? at : 0;
+  if (reading.ok !== true || !when) return { ok: false, at: when, room: null };
+  const pcts = [reading.session5hPct, reading.week7dPct].filter(v => typeof v === "number" && Number.isFinite(v));
+  return { ok: true, at: when, room: pcts.length ? pcts.every(p => p < 100) : null };
+}
+
+/**
+ * Whether the turn `stop` ended may be continued now, and when not, why:
+ *
+ *   "no-login"     there is no working reading of the active account at all
+ *   "before-stop"  the newest one was taken before the stop, so it cannot say
+ *                  the login works now
+ *   "no-room"      it works, and its 5-hour or 7-day window is full
+ *
+ * An API error that is neither — an overloaded server, a refused request — is
+ * not about the login, so nothing here holds it back. The automatic continue
+ * never acts on one (stop-continue.mjs); a press may.
+ */
+export function continueGate(stop, login) {
+  if (!stop || typeof stop !== "object") return { ready: false, reason: "no-login" };
+  if (stop.kind !== "login" && stop.kind !== "usage-limit") return { ready: true, reason: null };
+  if (!login || !login.ok) return { ready: false, reason: "no-login" };
+  if (!(login.at > stop.at)) return { ready: false, reason: "before-stop" };
+  if (login.room === false) return { ready: false, reason: "no-room" };
+  return { ready: true, reason: null };
+}