Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

15.4 KB
Raw Blame
/**
 * magmux's input gate, translated (architecture-v2 §3.1, Revision 1).
 *
 * magmux 0.16 owns input readiness for a declared Claude Code pane: a gated `send` waits
 * for the box, types, verifies the box holds exactly the text, presses Enter and answers
 * once, when it has attributable evidence (magmux README "Claude Code panes: the input
 * gate"). Its reply vocabulary (codes, reasons, `typed`, `accept`, `evidence`,
 * `retypeCause`) is third-party; this module is the one place that reads it.
 *
 * Pure: no I/O, no clock, no policy. `classifySendReply` only TRANSLATES a reply into the
 * closed `SendOutcome` union; what to do about each outcome (retry, ctrl-u, fail) is the
 * admission loop's switch in `PaneSession`. Values copied from magmux v0.16.0 (4c6060c):
 * `protocol/sendbudget.go`, `protocol/reasons.go`, `mux/inputgate_send.go`. A pin bump
 * re-diffs those three, the two "unknown whether" strings, and the `list` binding fields.
 */

import type { MagmuxReply } from "./magmux-client.js";

// ── dialogs and readiness ────────────────────────────────────────────────────

/** The dialog kinds magmux names after `dialog:` (protocol/reasons.go). */
export type GateDialogKind =
  | "permission"
  | "question"
  | "plan"
  | "select"
  | "trust"
  | "bypass"
  | "api_key"
  | "onboarding";

const DIALOG_KINDS: ReadonlySet<string> = new Set<GateDialogKind>([
  "permission",
  "question",
  "plan",
  "select",
  "trust",
  "bypass",
  "api_key",
  "onboarding",
]);

/** Boot dialogs: questions for the human. claudish never accepts one and never Escapes one. */
export const BOOT_DIALOG_KINDS: ReadonlySet<GateDialogKind> = new Set<GateDialogKind>([
  "trust",
  "bypass",
  "api_key",
  "onboarding",
]);

const DIALOG_PREFIX = "dialog:";

/** `dialog:<kind>` → the kind; null for any other reason and for a kind magmux added later. */
export function dialogKindOf(reason: string | null | undefined): GateDialogKind | null {
  if (!reason?.startsWith(DIALOG_PREFIX)) return null;
  const kind = reason.slice(DIALOG_PREFIX.length);
  return DIALOG_KINDS.has(kind) ? (kind as GateDialogKind) : null;
}

/**
 * One reading of `list` → pane 0's `input`, the gate's published view (refreshed at 4 Hz,
 * advisory: every send decides on its own fresh reads). The view is computed with
 * `Types: true` (controller_claude.go:411), so `ready` already means the box is EMPTY and
 * `reason === "box_not_empty"` means it holds text with nothing else in the way.
 * `boxHasText` and `dismissable` are undocumented and `omitempty`; they are not read
 * (R1.5.1).
 */
export interface GateInput {
  ready: boolean;
  /**
   * `starting` | `terminal_not_ready` | `no_input_box` | `box_not_empty` | `vim_mode` |
   * `dialog:<kind>` | `typing_in_progress`, raw; null when ready (magmux omits it).
   */
  reason: string | null;
  /** parsed from `dialog:<kind>`; an unknown kind is null and `reason` keeps the raw value */
  dialog: GateDialogKind | null;
  detail: string | null;
  /** the caller's clock at the `list` reply */
  receivedAt: number;
}

/** How magmux bound pane 0 to a transcript. `unbound`: a field is absent, or `bound` is unknown. */
export type GateBindingKind = "named" | "prompt" | "mtime" | "unbound";

/**
 * Pane 0's transcript binding as `list` echoes it (R1.0, requested of magmux as M12).
 * v0.16.0 publishes none of these fields, so every 0.16.0 pane reads `unbound`, which the
 * binding check (commit 3) refuses.
 */
export interface GateBinding {
  bound: GateBindingKind;
  /** the `bound` value as sent, for the `input_gate_unbound` detail; null when absent */
  boundRaw: string | null;
  sessionId: string | null;
  transcriptPath: string | null;
}

function str(v: unknown): string | null {
  return typeof v === "string" && v !== "" ? v : null;
}

function record(v: unknown): Record<string, unknown> | null {
  return v !== null && typeof v === "object" && !Array.isArray(v)
    ? (v as Record<string, unknown>)
    : null;
}

/** Pane 0's row of a `list` (or `results`) result. Found by its `pane` field: ids are sparse. */
function paneZero(listResult: unknown): Record<string, unknown> | null {
  const panes = record(listResult)?.panes;
  if (!Array.isArray(panes)) return null;
  for (const p of panes) {
    const row = record(p);
    if (row?.pane === 0) return row;
  }
  return null;
}

/** null: no pane 0, or pane 0 is not gated (magmux omits `input` then). */
export function parseGateInput(listResult: unknown, now: number): GateInput | null {
  const input = record(paneZero(listResult)?.input);
  if (!input || typeof input.ready !== "boolean") return null;
  const reason = input.ready ? null : str(input.reason);
  return {
    ready: input.ready,
    reason,
    dialog: dialogKindOf(reason),
    detail: str(input.detail),
    receivedAt: now,
  };
}

/** Why pane 0 is gated: `direct` (a visible `claude` launch), `declared` (`--controller`); null: not gated. */
export function gateBasisOf(listResult: unknown): "direct" | "declared" | null {
  const basis = paneZero(listResult)?.gateBasis;
  return basis === "direct" || basis === "declared" ? basis : null;
}

/**
 * null: no pane 0. Otherwise the binding: `unbound` when `bound`, `sessionId` or
 * `transcriptPath` is missing, or `bound` is unknown (R1.8, U4). A row claiming
 * `bound: "named"` without a session id or path binds nothing; `boundRaw` keeps the claim.
 */
export function parseGateBinding(listResult: unknown): GateBinding | null {
  const row = paneZero(listResult);
  if (!row) return null;
  const boundRaw = str(row.bound);
  const sessionId = str(row.sessionId);
  const transcriptPath = str(row.transcriptPath);
  let bound: GateBindingKind = "unbound";
  if (sessionId && transcriptPath) {
    if (boundRaw === "named" || boundRaw === "prompt" || boundRaw === "mtime") bound = boundRaw;
  }
  return { bound, boundRaw, sessionId, transcriptPath };
}

// ── the send reply ───────────────────────────────────────────────────────────

/** `not_accepted` reasons. `text_mismatch`/`empty_box`: Enter NOT pressed; the other two: it was. */
export type NotAcceptedReason = "text_mismatch" | "empty_box" | "still_in_box" | "unconfirmed";

/** The loss signal behind magmux's one automatic retype (inputgate_send.go:67-78). */
export type RetypeCause = "terminal_reset" | "never_drawn";

/**
 * The phrase both "it is unknown whether the text was submitted" `text_mismatch` details
 * carry (inputgate_send.go:884 leftBox, :893 convMoved). magmux 0.17.0 answers M11 with the
 * machine field `maybeSubmitted: true` on both; this prose is read only for a reply that
 * lacks the field.
 */
export const MAYBE_SUBMITTED_MARKER = "check the conversation before sending";

/**
 * Every gated-send reply, closed (§3.1 as revised by R1.1-R1.3).
 *
 * - `accepted`: Enter was pressed, by magmux (`enterByMagmux`) or, for
 *   `submitted_by_other`, by another writer, and evidence appeared. `evidence:
 *   "transcript"` is not attributable to this pane until the binding check passes (§5.6).
 * - `in_box`: a TYPE send (no Enter) verified in the box.
 * - `busy`: Enter NOT pressed. `typed`: the text (or part) may be in the box.
 * - `not_accepted`: `maybeSubmitted` only on the two "unknown whether" `text_mismatch`
 *   variants (R1.3); `typed` as magmux reported it.
 * - `bad_request`: nothing written.
 * - `reply_lost`: written; the delivery carries on and its outcome is unknown.
 * - `unsent`: never written.
 * - `pane_gone`: the pane is dead or closed; `typed` if it died partway through the send.
 * - `unexpected`: any other code, or an `ok` this module cannot read (an ungated reply,
 *   an unknown `accept`, an accept with no evidence).
 */
export type SendOutcome =
  | {
      kind: "accepted";
      accept: "confirmed" | "resent_enter" | "submitted_by_other";
      evidence: "history" | "transcript";
      /** the reply's `enter`: on a gated reply, whether MAGMUX pressed Enter */
      enterByMagmux: boolean;
      retyped: boolean;
      /** null iff not retyped; `unknown` for a retype with an absent or unrecognised cause */
      retypeCause: RetypeCause | "unknown" | null;
      dismissed: string[];
      waitedMs: number;
      verified: string | null;
    }
  | {
      kind: "in_box";
      retyped: boolean;
      retypeCause: RetypeCause | "unknown" | null;
      waitedMs: number;
      verified: string | null;
    }
  | { kind: "busy"; reason: string; dialog: GateDialogKind | null; typed: boolean }
  | {
      kind: "not_accepted";
      reason: NotAcceptedReason;
      maybeSubmitted: boolean;
      typed: boolean;
      detail: string;
    }
  | { kind: "bad_request"; error: string }
  | { kind: "reply_lost"; code: "client_timeout" | "client_lost" | "timeout" }
  | { kind: "unsent"; code: "client_closed" | "no_client" }
  | { kind: "pane_gone"; code: "pane_dead" | "no_such_pane"; typed: boolean }
  | { kind: "unexpected"; code: string; error: string };

export type SendOutcomeKind = SendOutcome["kind"];

/** Exhaustiveness check for a `switch` over a closed union. */
export function assertNever(x: never): never {
  throw new Error(`unreachable: ${JSON.stringify(x)}`);
}

function retypeOf(result: Record<string, unknown>): {
  retyped: boolean;
  retypeCause: RetypeCause | "unknown" | null;
} {
  if (result.retyped !== true) return { retyped: false, retypeCause: null };
  const cause = result.retypeCause;
  return {
    retyped: true,
    retypeCause: cause === "terminal_reset" || cause === "never_drawn" ? cause : "unknown",
  };
}

function okOutcome(result: Record<string, unknown>): SendOutcome {
  const { retyped, retypeCause } = retypeOf(result);
  const waitedMs = typeof result.waitedMs === "number" ? result.waitedMs : 0;
  const verified = str(result.verified);
  const accept = result.accept;
  if (accept === "in_box") return { kind: "in_box", retyped, retypeCause, waitedMs, verified };
  if (accept === undefined) {
    return {
      kind: "unexpected",
      code: "ungated_reply",
      error: "ok with no accept: the pane is not gated",
    };
  }
  if (accept !== "confirmed" && accept !== "resent_enter" && accept !== "submitted_by_other") {
    return {
      kind: "unexpected",
      code: "unknown_accept",
      error: `accept ${JSON.stringify(accept)}`,
    };
  }
  const evidence = result.evidence;
  if (evidence !== "history" && evidence !== "transcript") {
    return {
      kind: "unexpected",
      code: "unknown_evidence",
      error: `accept ${accept} with evidence ${JSON.stringify(evidence)}`,
    };
  }
  const dismissed = Array.isArray(result.dismissed)
    ? result.dismissed.filter((d): d is string => typeof d === "string")
    : [];
  return {
    kind: "accepted",
    accept,
    evidence,
    enterByMagmux: result.enter === true,
    retyped,
    retypeCause,
    dismissed,
    waitedMs,
    verified,
  };
}

function notAcceptedOutcome(r: Extract<MagmuxReply, { ok: false }>): SendOutcome {
  const typed = r.typed === true;
  switch (r.reason) {
    case "text_mismatch":
      return {
        kind: "not_accepted",
        reason: "text_mismatch",
        // The field is the contract (magmux 0.17.0, M11). The text match is a fallback for a
        // reply without the field, so a magmux that predates it is not read as "not submitted".
        maybeSubmitted: r.maybeSubmitted === true || r.error.includes(MAYBE_SUBMITTED_MARKER),
        typed,
        detail: r.error,
      };
    case "empty_box":
    case "still_in_box":
    case "unconfirmed":
      return {
        kind: "not_accepted",
        reason: r.reason,
        maybeSubmitted: false,
        typed,
        detail: r.error,
      };
    default:
      // Whether Enter was pressed is unknown for a reason this module has never seen.
      return {
        kind: "unexpected",
        code: `not_accepted:${r.reason ?? ""}`,
        error: r.error,
      };
  }
}

/** One reply to a gated `send` → claudish's outcome. Translation only; no policy. */
export function classifySendReply(r: MagmuxReply): SendOutcome {
  if (r.ok) return okOutcome(record(r.result) ?? {});
  switch (r.code) {
    case "busy": {
      // An unknown reason stays `busy` with the raw value: Enter was not pressed either way.
      const reason = r.reason ?? "";
      return { kind: "busy", reason, dialog: dialogKindOf(reason), typed: r.typed === true };
    }
    case "not_accepted":
      return notAcceptedOutcome(r);
    case "bad_request":
      return { kind: "bad_request", error: r.error };
    case "client_timeout":
    case "client_lost":
    case "timeout":
      return { kind: "reply_lost", code: r.code };
    case "client_closed":
    case "no_client":
      return { kind: "unsent", code: r.code };
    case "pane_dead":
    case "no_such_pane":
      return { kind: "pane_gone", code: r.code, typed: r.typed === true };
    default:
      return { kind: "unexpected", code: r.code, error: r.error };
  }
}

// ── how long a gated send can take (protocol.SendBudget at 4c6060c) ──────────

export const SEND_READY_WAIT_DEFAULT_MS = 10_000;
export const SEND_READY_WAIT_MAX_MS = 60_000;
const SEND_TYPED_CHUNK_RUNES = 32;
const SEND_TYPED_CHUNK_GAP_MS = 8;
const SEND_KEY_GAP_MS = 20;
const SEND_SETTLE_MS = 150;
/** The verify's minimum window, which the `readyTimeoutMs` deadline never cuts. */
const SEND_VERIFY_MIN_MS = 1_200;
const SEND_VERIFY_STEP_MS = 40;
const SEND_GATE_CHECK_COST_MS = 2;
const SEND_ACCEPT_WINDOW_MS = 2_000;
const SEND_ACCEPT_WINDOWS = 3;
const SEND_BUDGET_SLACK_MS = 2_000;

/** `readyTimeoutMs` → the readiness deadline: ≤ 0 is the default, above the max is clamped. */
export function readyWaitMs(readyTimeoutMs: number): number {
  if (readyTimeoutMs <= 0) return SEND_READY_WAIT_DEFAULT_MS;
  return Math.min(readyTimeoutMs, SEND_READY_WAIT_MAX_MS);
}

/** Writes a typed send makes: runs of ≤ 32 runes, and one per newline (`\n`, `\r\n`, `\r`). */
export function typedWriteCount(text: string): number {
  const rs = Array.from(text);
  let n = 0;
  let run = 0;
  for (let i = 0; i < rs.length; i++) {
    const r = rs[i];
    if (r === "\r" || r === "\n") {
      if (r === "\r" && rs[i + 1] === "\n") i++;
      if (run > 0) {
        n++;
        run = 0;
      }
      n++;
    } else {
      run++;
      if (run === SEND_TYPED_CHUNK_RUNES) {
        n++;
        run = 0;
      }
    }
  }
  return run > 0 ? n + 1 : n;
}

/**
 * magmux's upper bound on one gated send, from when it starts running: the readiness wait
 * once, the per-attempt typing + settle + minimum verify + one late verify read twice (for
 * the one retype), and the three acceptance windows for a submit. `keys` counts named keys,
 * a final Enter key included (an upper bound either way). `typed` defaults to true:
 * every claudish send is typed (R1.2), and only the Go test table needs it false.
 * Drift from magmux is safe in direction: an under-estimate becomes `reply_lost`, never a
 * second copy.
 */
export function sendBudgetMs(s: {
  readyTimeoutMs: number;
  text: string;
  keys: number;
  submit: boolean;
  typed?: boolean;
}): number {
  let attempt = 0;
  if (s.typed ?? true)
    attempt += typedWriteCount(s.text) * (SEND_TYPED_CHUNK_GAP_MS + SEND_GATE_CHECK_COST_MS);
  attempt += s.keys * (SEND_KEY_GAP_MS + SEND_GATE_CHECK_COST_MS);
  attempt += SEND_SETTLE_MS + SEND_VERIFY_MIN_MS + SEND_VERIFY_STEP_MS;
  const accept = s.submit ? SEND_ACCEPT_WINDOWS * SEND_ACCEPT_WINDOW_MS : 0;
  return readyWaitMs(s.readyTimeoutMs) + 2 * attempt + accept + SEND_BUDGET_SLACK_MS;
}