Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
/**
* The frozen mod contract, version 1 — the single source of the wire types that the
* peer's Claude Code mod reads from `team(mode="list"|"status"|"cancel"|"capture"|"resize")`,
* `list_sessions`, `cancel_session`, `capture_session` and `resize_session`.
*
* Pasted verbatim from the session architecture §8 (including CA-12 `contract_version`
* / `capabilities` and CA-13 `run_id`). Fields never change meaning or type within
* version 1; new fields may only be ADDED. `FailureReason` lives here because both
* owners (team and the MCP sessions) produce it.
*/
export const CONTRACT_VERSION = 1;
/** v1 announces exactly these. `resize` is additive: it needs magmux >= 0.15.1. */
export const CAPABILITIES = [
"list",
"status",
"cancel",
"capture",
"capture_since_seq",
"capture_spans",
"resize",
] as const;
export interface ContractMeta {
contract_version: 1;
/** v1: exactly CAPABILITIES */
capabilities: string[];
}
/** Closed set. The mod colours by it. */
export type SlotState =
/** Pane spawned; Claude Code booting, or the prompt the session was CREATED with delivered but not yet
* accepted. A promptless session's first send_input goes AWAITING_INPUT → RUNNING, never back to
* STARTING. Bounded: leaves within 90 s + 30 s. Non-terminal. */
| "STARTING"
/** A turn is in progress: prompt accepted; the model thinking, a tool running, Stop hooks or background
* agents still finishing. Never ended by a timer (team). Non-terminal. */
| "RUNNING"
/** Waiting for text: an interactive create_session between turns (activity null), or a turn blocked on
* a question (activity "AskUserQuestion"). A send_input during a question does NOT answer it: claudish
* presses Esc, which declines the question and interrupts the turn, and the text becomes the next
* prompt. Team slots never stay here. Non-terminal. */
| "AWAITING_INPUT"
/** A permission / plan-approval dialog is showing (only when caller flags override -y). A send_input
* declines it the same way. Same team rule as above. Non-terminal. */
| "AWAITING_PERMISSION"
/** Turn settled with a usable answer (team: passed require_pattern / min_output_bytes), or an
* interactive session whose child exited 0 while idle after /exit or after ≥ 1 settled turn. Terminal. */
| "COMPLETED"
/** The session broke: boot failure, prompt never accepted, task file not fully read, child exited
* (incl. unknown agent), API error, blocked (team), pane lost. Terminal. */
| "FAILED"
/** Stopped by team(mode="cancel") or cancel_session. Terminal. */
| "CANCELLED"
/** create_session timeout_seconds elapsed (team slots never time out). Terminal. */
| "TIMEOUT"
/** Turn settled but the answer is unusable: empty, refused, below min_output_bytes, or
* shape_mismatch. Terminal. */
| "EMPTY";
export const SLOT_STATES: readonly SlotState[] = [
"STARTING",
"RUNNING",
"AWAITING_INPUT",
"AWAITING_PERMISSION",
"COMPLETED",
"FAILED",
"CANCELLED",
"TIMEOUT",
"EMPTY",
];
export const TERMINAL_STATES: readonly SlotState[] = [
"COMPLETED",
"FAILED",
"CANCELLED",
"TIMEOUT",
"EMPTY",
];
export function isTerminalState(s: SlotState): boolean {
return TERMINAL_STATES.includes(s);
}
export type FailureReason =
| "cancelled" // the caller stopped it — a decision, not a fault
| "timeout" // create_session timeout_seconds; team-grid (CLI) pane end
| "boot_timeout" // no REPL prompt within the boot deadline, screen still changing (screen tail in detail)
| "boot_blocked" // a static non-REPL screen that is not a named dialog blocked boot (screen text in detail)
| "first_run_dialog" // a named first-run dialog blocked boot (dialog text in detail)
| "agent_rejected" // the child refused --agent (its own "not found. Available agents" line)
| "prompt_not_accepted" // the first prompt never produced an acceptance witness within the admission bound
| "prompt_not_read" // a file-delivered turn settled without Read returning every line of its task file
| "child_exited" // pane child exited before the turn settled (exit code + last line + screen tail)
| "pane_lost" // the magmux PROCESS died without reporting the pane's exit
| "blocked" // team slot stopped on a question/permission dialog team cannot answer (question in detail)
| "api_error" // the settled turn is an isApiErrorMessage entry (or a screen-mode error row)
| "refused" // the settled turn's stop_reason is "refusal"
| "empty_output"
| "shape_mismatch";
export const FAILURE_REASONS: readonly FailureReason[] = [
"cancelled",
"timeout",
"boot_timeout",
"boot_blocked",
"first_run_dialog",
"agent_rejected",
"prompt_not_accepted",
"prompt_not_read",
"child_exited",
"pane_lost",
"blocked",
"api_error",
"refused",
"empty_output",
"shape_mismatch",
];
/** B — one row per team slot, and the base of every list_sessions row. */
export interface SlotRow {
/** team: anonymised slot id ("01"); session: the session_id */
slot: string;
/** as requested */
model: string;
/** display name of the claudish provider serving it; null until known */
provider: string | null;
state: SlotState;
/** set on FAILED / EMPTY / CANCELLED / TIMEOUT; null otherwise (incl. COMPLETED). One exception: a
* pre-contract state read from disk is FAILED with null (§B) */
reason: FailureReason | null;
/** [additive] one line (≤ 160 chars) saying why `reason`: for api_error the provider's
* `error.message` from the last upstream-error record, else the child's API-error text;
* for any other reason the first line of its detail. null on non-terminal states, on
* COMPLETED, and when nothing readable exists. Never the upstream body. `reasonDetail()` */
reason_detail: string | null;
/** billed input incl. cache reads/writes, main conversation + subagents; null = no source yet */
tokens_in: number | null;
tokens_out: number | null;
/** null = unknown (always null for native Claude routes) */
cost_usd: number | null;
/** includes the child's Read call(s) of a file-delivered prompt */
tool_calls: number;
/** prompts whose turn settled (one per prompt, however many internal loops) */
turns_completed: number;
/** ISO 8601: last screen change or transcript append */
last_activity_at: string | null;
/** seconds since last_activity_at; null in terminal states */
idle_seconds: number | null;
/** RUNNING: tool name, "thinking", "background" (waiting on background agents), or "finishing" (the
* model's message ended; waiting for Claude Code's end-of-turn record, typically while Stop hooks run),
* or "hook" (the turn settled and claudish's session hooks run before the verdict);
* AWAITING_PERMISSION: blocked tool; AWAITING_INPUT on a question: "AskUserQuestion"; otherwise null.
* Treat unknown values as "busy". */
activity: string | null;
/** informational only (do not parse, no verb takes it); null if no pane was ever spawned */
pane: string | null;
/** [additive] the last RECENT_STEP_LIMIT (20) steps of the current turn, oldest first, from the
* main-chain transcript; null before the first step and on rows built from disk. Kept after the
* turn settles until the next turn starts. Each summary is one line (≤ 100 chars), credentials
* masked; never a whole tool input and nothing from a tool result. `pane/slot-steps.ts` */
recent: SlotStep[] | null;
}
/** One step of a slot's turn: an assistant text, thinking or tool_use block. */
export interface SlotStep {
/** ISO 8601: the transcript record's own timestamp */
at: string;
/** "ask" is a tool_use of AskUserQuestion */
kind: "text" | "thinking" | "tool" | "ask";
/** the tool name for "tool" and "ask"; null for "text" and "thinking" */
tool: string | null;
/** text and thinking: the first line; tool: the input naming its target (file_path, the first
* line of a Bash command, pattern, query, url, description) or "" for any other tool; ask: the
* first question */
summary: string;
}
/** list_sessions row = SlotRow + session fields. `slot` equals `session_id`. */
export interface SessionRow extends SlotRow {
session_id: string;
/** ISO */
started_at: string;
/** ISO */
completed_at: string | null;
elapsed_seconds: number;
}
/** A — one team run this server knows. */
export interface TeamRunRow {
/** [CA-13] unique per team(mode="run") start, distinct even when `path` is reused (opaque; format
* `<team_session_id>-<base36 start ms>-<6 hex>`). Same value as the start answer's `run_id`. A judge
* sub-run has its own run_id. */
run_id: string;
/** absolute session directory (the `path` every other team mode takes) */
path: string;
/** "judge" = the judging/ sub-run of a judge or run-and-judge */
kind: "run" | "judge";
/** ISO */
started_at: string;
/** ISO, set when the last slot turned terminal */
finished_at: string | null;
/** run-level, distinct from SlotState: SETTLED ⇔ every slot terminal */
state: "ACTIVE" | "SETTLED";
/** null while ACTIVE; same words as the result card */
outcome: "ok" | "partial" | "all-failed" | null;
/** sorted by slot id */
slots: SlotRow[];
}
/** [CA-12] an object, not a bare array */
export interface TeamListResult extends ContractMeta {
runs: TeamRunRow[];
}
export interface SessionListResult extends ContractMeta {
sessions: SessionRow[];
}
/** team(mode="status") adds these keys to its existing payload. */
export interface TeamStatusAdditions extends ContractMeta {
run: TeamRunRow;
}
/** C */
export interface TeamCancelResult {
/** [CA-13] */
run_id: string;
path: string;
/** changed = this call moved it to CANCELLED */
results: Array<{ slot: string; state: SlotState; changed: boolean }>;
}
export interface SessionCancelResult {
session_id: string;
state: SlotState;
changed: boolean;
}
/** One magmux span run: [col, len, fg, bg, attr]. Colour -1 = default, 0..255 indexed,
* ≥ 16777216 truecolor (`c & 0xFFFFFF`); attr bitmask, 1 = bold. */
export type SpanRun = [col: number, len: number, fg: number, bg: number, attr: number];
/** D */
export interface CaptureResult {
/** claudish-owned. 0 = no frame received yet (lines all ""); ≥ 1 after the first frame; +1 per visible
* change (text, colours, cursor, alt screen, size); never resets for a pane's life */
seq: number;
/** the pane's current width: 160 at launch, then whatever the last resize set */
cols: number;
/** the pane's current height: 50 at launch, then whatever the last resize set */
rows: number;
cursor: { x: number; y: number };
/** exactly `rows` entries, plain text, right-trimmed; Claude Code's screen (no scrollback) */
lines: string[];
/** true = the pane is closed and this is its last screen */
final: boolean;
/** only when spans:true was asked */
spans?: SpanRun[][];
}
export interface CaptureUnchanged {
unchanged: true;
seq: number;
final: boolean;
}
/**
* F — `resize_session`. `cols`/`rows` are the size SET (the request clamped to cols 40–9999,
* rows 24–9999 and at most 4 000 000 cells, magmux's limits: `clampPaneSize`); `changed` = the pane's size moved; `seq` = the screen's seq after the
* resize (the first capture at the new size once `changed`). `pending: true` = the socket
* is reconnecting (or the pane is still starting): the size is stored and applied on the
* reconnect (or at launch). A terminal session answers its last size with `changed:false`.
*/
export interface ResizeResult {
session_id: string;
cols: number;
rows: number;
changed: boolean;
seq: number;
pending?: true;
}
/** F — `team(mode="resize")`: the same answer, addressed by run and slot. */
export interface TeamResizeResult {
run_id: string;
path: string;
slot: string;
cols: number;
rows: number;
changed: boolean;
seq: number;
pending?: true;
}
/** E. `resize_unsupported` and `delivery_unavailable` are emitted only by the resize verbs. */
export interface ContractError {
error: {
code:
| "unknown_run"
| "unknown_slot"
| "unknown_session"
| "invalid_args"
| "resize_unsupported"
| "delivery_unavailable";
message: string;
};
}
export function contractMeta(): ContractMeta {
return { contract_version: CONTRACT_VERSION, capabilities: [...CAPABILITIES] };
}
/**
* A §8 verb's error, thrown by the owners and serialised by the MCP handler as the
* `ContractError` JSON with `isError: true` (§8 E).
*/
export class ContractErrorException extends Error {
constructor(
readonly code: ContractError["error"]["code"],
message: string
) {
super(message);
}
toContractError(): ContractError {
return { error: { code: this.code, message: this.message } };
}
}