Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

33.6 KB
Raw Blame
// SPDX-License-Identifier: FSL-1.1-MIT
// Copyright (c) 2026 Cua AI, Inc.

/**
 * The Space thread wire: types and the mapping from the daemon's tool JSON
 * (snake_case) to the records the screens draw. Carried over unchanged from
 * the web app's `bridge/ops/thread.ts` (CUA-2155, CUA-2262 to CUA-2266), minus
 * its host plumbing: the mapping lives once per client, and a drift test
 * (`__tests__/thread-protocol.test.ts`) runs the same tool JSON through both.
 */

/* ---- The thread as the page reads it (camelCase) ---------------------------------- */

export type ThreadAuthorKind = "person" | "agent" | "system";

/** Who wrote an entry, stamped by the owner daemon from the caller:
 * a relay account id (`owner` on a machine that is not signed in),
 * `agent:<name>`, or `system:<what>`. */
export interface ThreadAuthor {
  kind: ThreadAuthorKind;
  id: string;
  name: string;
  /** An agent's identity when it posted (CUA-2262): its posts keep their mark and owner after it leaves. */
  identity?: MemberIdentity | null;
}

/* ---- Who an agent member is (CUA-2262) ----------------------------------------------- */

export interface MemberRef {
  id: string;
  name: string;
}

/** How an agent member came into the Space. */
export type JoinMethod = "started" | "prompt" | "setup";

/**
 * An agent member's identity. The agent sets its name, its icon and the
 * harness it reports; the owner, the device and how it joined come from the
 * member's record (who added it, the computer whose key redeemed the code),
 * never from the agent, so the app can mark them as checked by Cua.
 */
export interface MemberIdentity {
  /** `space`: started inside the Space; `external`: connected from a computer with `cua join`. */
  origin: "space" | "external";
  /** The unique `@handle` in the Space (the member's name). */
  handle: string;
  /** What the agent calls itself; two members may share it. */
  displayName: string;
  /** Another member uses the same name: the owner shows after the AI tag. */
  collides: boolean;
  /** The agent's own icon: null (its harness's mark), `harness`, or an https URL. It replaces the tile only. */
  icon: string | null;
  /** The harness as the agent reported it (`reported: false`: it didn't say). */
  harness: { id: string; version: string | null; reported: boolean };
  owner: MemberRef;
  /** The computer it posts from (external agents). Never an address or a place. */
  device: MemberRef | null;
  joined: { method: JoinMethod; atMs: number | null; by: MemberRef | null };
  /** `pending`: it redeemed a code and waits for the owner or an admin to let it in. */
  state: "active" | "pending";
  lastSeenMs: number | null;
}

/** A join, a removal, a refused name or a rate limit, on a system note (CUA-2262/2264). */
export interface MemberEvent {
  kind: "member_joined" | "member_removed" | "name_refused" | "rate_limited";
  member: MemberIdentity | null;
  by: MemberRef | null;
}

export type ThreadEntryKind = "message" | "task_update" | "approval" | "answer" | "system" | "join_request";

/** An agent asks to join (CUA-2263): the owner or an admin answers it like an approval. */
export interface JoinRequest {
  member: MemberIdentity | null;
  /** Who can give it tasks once it is in. */
  canTask: "owner" | "members";
  /** As posted (`open`); the answer is a later `answer` entry. */
  state: string;
  codeId: string;
  /** The caller may let it in (the owner and admins, while it is open). */
  youCanAnswer: boolean;
}

/** A task's state, folded from its `task_update` entries. */
export type TaskState = "queued" | "claimed" | "working" | "done" | "failed";

/** A Volume reference: never inline bytes, never a host path. */
export interface ThreadAttachment {
  path: string;
  name: string;
  size: number | null;
  mime: string | null;
}

/** What failed in an agent's turn or start, typed (`cua_agents::failure::Failure`). */
export interface ThreadFailure {
  /** `needs_connect`: no working credential, connect (or reconnect) one; `error`: anything else. */
  class: "needs_connect" | "error";
  /** For `needs_connect`: the Connectors row that fixes it (`anthropic`, `openai`). */
  provider: string | null;
  /** The complete error as the harness or provider said it (for Show details; never the summary). */
  message: string;
  /** Sending the same message again can work. */
  retryable: boolean;
}

export interface ThreadEntry {
  seq: number;
  id: string;
  tsMs: number;
  author: ThreadAuthor;
  kind: ThreadEntryKind;
  text: string;
  /** Member names mentioned with `@name`. */
  mentions: string[];
  replyTo: number | null;
  /** A message that @mentions an agent member is a task for it. */
  task: { to: string; session: number | null } | null;
  attachments: ThreadAttachment[];
  /** An agent asks before it acts. `kind` and `scopeChoices` are the daemon's structured data (`push`, `command`, `network`, `login`, `file`; `once`, `space`): the app builds the buttons from them, never from the agent's text. */
  approval: { action: string; details: string; state: string; card: Record<string, unknown> | null; kind?: string; scopeChoices?: string[] } | null;
  /** Someone answered an approval (`kind: "answer"`); `scope` is what they allowed (`once` or `space`). */
  answer: { approval: number; approve: boolean; note: string | null; scope?: "once" | "space" | null; clientId?: string | null } | null;
  /** The client id a message was posted with, when the daemon echoes one: how an unsent message is found again (an answer carries its own, in `answer.clientId`). */
  clientId?: string | null;
  /** A system note about a task (`task_seq` on a `system` entry): it shows inside that task. */
  noteFor: number | null;
  /** A task moved on (`kind: "task_update"`). */
  update: { task: number; state: TaskState; session: number | null; note: string | null } | null;
  /** A task someone other than the owner gave, run on the owner's provider keys. */
  runsOnKeysOf: { id: string; name: string } | null;
  /** A system note about a member joining, leaving or a refused name (CUA-2262). */
  event: MemberEvent | null;
  /** On a `join_request` entry (CUA-2263). */
  joinRequest?: JoinRequest | null;
  /** What the person was looking at in the Space as they posted (`view`): its desktop or a window. */
  view?: ThreadView | null;
  /** On an agent's reply to a task that failed: what failed, with the complete text. `text` says it in plain words. */
  failure?: ThreadFailure | null;
  /** On the copy of a message that tasks one more agent when it names several (`@a @b`, `@everyone`): the entry it copies. The page draws the original only. */
  fanoutOf?: number | null;
}

/** `thread_post`'s `view` and every entry's: the Space's desktop, or one of its windows (`cua.env.v1.ThreadView`). */
export interface ThreadView {
  kind: "desktop" | "window";
  app: string | null;
  title: string | null;
  windowId: string | null;
}

/** Your role in the Space, as the owner daemon sees you: a guest reads only. */
export type ThreadRole = "owner" | "admin" | "member" | "guest" | "agent";

/** What one agent is doing now, for the thread's live row (`thread_read`'s `live`). */
export interface LiveAgent {
  /** The agent's handle (`@hermes-test`). */
  agent: string;
  /** In a few plain words: `starting`, `installing`, `thinking`, `replying` or `using Bash`. */
  stage: string;
  /** When its oldest open task was given (Unix ms): the working row's clock. */
  sinceMs?: number;
  /** What it has said so far this turn, the whole text each time, while it streams; the reply replaces it. */
  text?: string;
}

/** Every agent with a turn on its way, and a key that changes when any stage does. */
export interface ThreadLive {
  key: string;
  agents: LiveAgent[];
}

export interface ThreadPage {
  entries: ThreadEntry[];
  /** Who is at work now. Absent from a daemon that does not say: nobody. */
  live: ThreadLive;
  /** The last seq this page covers: the next read's `after`. */
  cursor: number;
  caughtUp: boolean;
  /** Entries after the caller's read cursor. */
  unread: number;
  /** The caller's read cursor, when the daemon says it. */
  readSeq: number | null;
  /** The caller's own author id, when the daemon says it (the page's "me"). */
  me: string | null;
  /** Older entries exist before this page (read them with `before`). */
  hasMoreBefore: boolean;
  /** Your role here, when the daemon says it (older daemons: null, read as the owner's). */
  role: ThreadRole | null;
}

/** Who holds one of an agent's rights: a group, or these account ids (besides the owner). */
export type RightHolders = "owner" | "admins" | "members" | string[];

export type AgentRight = "task" | "control" | "approve";

/** Who can give an agent tasks, control it and answer its approvals. */
export type AgentRights = Record<AgentRight, RightHolders>;

/** `working`, `idle`, `waiting`, `paused` or `asleep` (other words pass through). */
export type AgentMemberStatus = string;

export interface AgentMember {
  name: string;
  /** What the Space calls it (`@claude`) when that is not `name` (a second Space's `claude` is stored as `claude-2`). */
  handle?: string;
  /** Harness id (`claude-code`, `hermes`, ...). */
  harness: string;
  status: AgentMemberStatus;
  /** What it is doing, in a few words ("running e2e suite"), when it says. */
  activity: string | null;
  /** For a failed member: what failed, typed, with the complete text. */
  failure?: ThreadFailure | null;
  /** Sessions it runs (P2 shows each). */
  sessions: number;
  /** Its rights (null from a daemon without them: the defaults apply). */
  rights: AgentRights | null;
  /** What you may do with it (null from a daemon without rights: everything). */
  youCan: Record<AgentRight, boolean> | null;
  /** Who took control of it, while someone has. */
  heldBy: string | null;
  /** Who it is: owner, device, how it joined (null from a daemon without it: no owner badge, no card). */
  identity: MemberIdentity | null;
  /** Its DM with you (`overview`, CUA-2266); null when not asked or not said. */
  dm?: AgentDm | null;
  /** What waits for you from it (`overview`): open approvals you may answer, its question to you. */
  needsYou?: NeedsYou[];
  /** Messages waiting behind the turn it is running ("1 queued"). */
  queued?: number;
}

export interface ThreadMembersArgs {
  spaceId: string;
  /** Each agent's DM with you as well (`dm`, `needsYou`). */
  overview?: boolean;
}

/** One agent's DM with you, summed up for the Agents tab. */
export interface AgentDm {
  unread: number;
  last: { seq: number; tsMs: number; text: string; author: ThreadAuthor } | null;
}

export interface NeedsYou {
  seq: number;
  kind: "approval" | "question";
  text: string;
  tsMs: number;
}

/** The defaults a daemon applies when an agent has none set. */
export const DEFAULT_AGENT_RIGHTS: AgentRights = { task: "members", control: "admins", approve: "admins" };

export interface ThreadReadArgs {
  spaceId: string;
  after?: number | null;
  /** Page back: the entries before this seq (the latest `limit` of them). */
  before?: number | null;
  limit?: number | null;
  markRead?: boolean;
  /** Long-poll up to this long (0..25000 ms) for entries after `after`. */
  followMs?: number;
  /** With `followMs`: the `live.key` last seen; the wait also ends when it changes. */
  liveAfter?: string | null;
  /** Only your DM with this agent member (its handle, CUA-2266): paging, `unread` and `markRead` apply to the DM. */
  with?: string | null;
}

export interface ThreadPostArgs {
  spaceId: string;
  text: string;
  replyTo?: number | null;
  /** Answer an approval entry; `scope` `space` allows this kind of action for the Space from now on. */
  answer?: { approval: number; approve: boolean; note?: string | null; scope?: "once" | "space" | null; clientId?: string | null } | null;
  /** The idempotency key of a plain message: the same key from the same author again is the first entry (the daemon's `client_id`). */
  clientId?: string | null;
  /** P2: one session of an agent instead of any free one. */
  toSession?: number | null;
  /** What the person is looking at in the Space as they post (the main view's window), stored with the entry. */
  view?: ThreadView | null;
}

export interface ThreadSetRightsArgs {
  spaceId: string;
  /** The agent member. */
  name: string;
  task?: RightHolders;
  control?: RightHolders;
  approve?: RightHolders;
}

export interface ThreadAgentRemoveArgs {
  spaceId: string;
  /** The agent member's handle. */
  name: string;
}

export interface ThreadAgentAddArgs {
  spaceId: string;
  /** The new member's handle (`a-z`, `0-9`, `.`, `_`, `-`). */
  name: string;
  /** The harness id (`hermes`, `claude-code`, `openai-codex`, ...). */
  harness: string;
  /** The model its next message uses (an open session switches to it before the turn). On a member that exists, it is updated. */
  model?: string;
  /** Keep its run open with the session ready, so a message starts its turn at once. */
  standby?: boolean;
  /** Standing instructions: the first message each run takes carries them in front of its text. */
  brief?: string;
}

export interface ThreadJoinCodeCreateArgs {
  spaceId: string;
  /** Seconds until it expires: 900 to 86400 (default 3600). */
  ttlS?: number;
  /** Who can task the agent: whoever made the code, or members. */
  canTask?: "owner" | "members";
  /** Ask the owner or an admin before it joins. */
  askBeforeJoin?: boolean;
}

/** A new join code: its plaintext is only ever here. */
export interface JoinCode {
  id: string;
  code: string;
  url: string;
  /** The one line to paste into an agent. */
  line: string;
  expiresAtMs: number;
}

export type JoinCodeState = "open" | "pending_approval" | "redeemed" | "denied" | "expired" | "cancelled";

export interface JoinCodeRow {
  id: string;
  createdAtMs: number;
  expiresAtMs: number;
  state: JoinCodeState;
  canTask: "owner" | "members";
  askBeforeJoin: boolean;
  createdBy: MemberRef | null;
  /** The member it made, once used. */
  memberHandle: string | null;
}

export interface ThreadSettings {
  /** "Ask before members' agents join". */
  askBeforeJoin: boolean;
}

export interface ThreadOps {
  "thread.read": { args: ThreadReadArgs; result: ThreadPage };
  "thread.post": { args: ThreadPostArgs; result: ThreadEntry | null };
  "thread.members": { args: ThreadMembersArgs; result: { members: AgentMember[] } };
  "thread.setRights": { args: ThreadSetRightsArgs; result: AgentMember | null };
  /** Starts an agent in the Space (it sleeps until someone @mentions it). */
  "thread.agentAdd": { args: ThreadAgentAddArgs; result: AgentMember | null };
  /** Removes an agent member; a connected agent's key stops at once. */
  "thread.agentRemove": { args: ThreadAgentRemoveArgs; result: null };
  "thread.joinCodeCreate": { args: ThreadJoinCodeCreateArgs; result: JoinCode };
  "thread.joinCodeList": { args: { spaceId: string }; result: { codes: JoinCodeRow[] } };
  "thread.joinCodeCancel": { args: { spaceId: string; id: string }; result: null };
  /** Reads, or with `askBeforeJoin` sets, the Space's thread settings. */
  "thread.settings": { args: { spaceId: string; askBeforeJoin?: boolean }; result: ThreadSettings };
}

export type ThreadOpName = keyof ThreadOps;

export const THREAD_OPERATIONS = [
  "thread.read",
  "thread.post",
  "thread.members",
  "thread.setRights",
  "thread.agentAdd",
  "thread.agentRemove",
  "thread.joinCodeCreate",
  "thread.joinCodeList",
  "thread.joinCodeCancel",
  "thread.settings",
] as const satisfies readonly ThreadOpName[];

export const THREAD_FOLLOW_MAX_MS = 25_000;

/* ---- Operation arguments -> tool arguments ------------------------------------------ */

type Json = Record<string, unknown>;

export function threadReadArgs(a: ThreadReadArgs): Json {
  const out: Json = { space: a.spaceId };
  if (a.after != null) out.after = a.after;
  if (a.before != null) out.before = a.before;
  if (a.limit != null) out.limit = a.limit;
  if (a.markRead) out.mark_read = true;
  if (a.followMs) out.follow_ms = Math.max(0, Math.min(THREAD_FOLLOW_MAX_MS, Math.round(a.followMs)));
  if (a.with) out.with = a.with;
  if (a.liveAfter != null && a.followMs) out.live_after = a.liveAfter;
  return out;
}

export function threadPostArgs(a: ThreadPostArgs): Json {
  const out: Json = { space: a.spaceId, text: a.text };
  if (a.replyTo != null) out.reply_to = a.replyTo;
  if (a.answer) out.answer = { approval: a.answer.approval, approve: a.answer.approve, ...(a.answer.note ? { note: a.answer.note } : {}), ...(a.answer.scope && a.answer.approve ? { scope: a.answer.scope } : {}), ...(a.answer.clientId ? { client_id: a.answer.clientId } : {}) };
  if (a.clientId) out.client_id = a.clientId;
  if (a.toSession != null) out.to_session = a.toSession;
  if (a.view) out.view = threadViewArgs(a.view);
  return out;
}

/** `view` as the tool takes it (snake_case, only the fields there are). */
export function threadViewArgs(v: ThreadView): Json {
  const out: Json = { kind: v.kind };
  if (v.app) out.app = v.app;
  if (v.title) out.title = v.title;
  if (v.windowId) out.window_id = v.windowId;
  return out;
}

/** An entry's `view`, as the tool gives it; null without one. */
export function threadViewFromTool(v: unknown): ThreadView | null {
  const o = obj(v);
  if (!o || (o.kind !== "desktop" && o.kind !== "window")) return null;
  return { kind: o.kind, app: str(o.app) || null, title: str(o.title) || null, windowId: str(o.window_id) || null };
}

export const threadMembersArgs = (a: { spaceId: string }): Json => ({ space: a.spaceId });

/** `agent_members`, with each agent's DM summary when `overview` (CUA-2266). */
export const agentMembersArgs = (a: ThreadMembersArgs): Json => (a.overview ? { space: a.spaceId, overview: true } : { space: a.spaceId });

/** `agent_set_rights` takes the member's name (names are unique per machine), not the Space. */
export function threadSetRightsArgs(a: ThreadSetRightsArgs): Json {
  const out: Json = { name: a.name };
  for (const k of ["task", "control", "approve"] as const) if (a[k] !== undefined) out[k] = a[k];
  return out;
}

/** `agent_remove` takes the member's name (names are unique per machine). */
export const threadAgentRemoveArgs = (a: ThreadAgentRemoveArgs): Json => ({ name: a.name });

/** `agent_add`: a started member of the Space (`agent` is the harness id). */
export const threadAgentAddArgs = (a: ThreadAgentAddArgs): Json => ({
  space: a.spaceId,
  name: a.name,
  agent: a.harness,
  ...(a.model ? { model: a.model } : {}),
  ...(a.standby !== undefined ? { standby: a.standby } : {}),
  ...(a.brief ? { brief: a.brief } : {}),
});

export function threadJoinCodeCreateArgs(a: ThreadJoinCodeCreateArgs): Json {
  const out: Json = { space: a.spaceId };
  if (a.ttlS !== undefined) out.ttl_s = a.ttlS;
  if (a.canTask !== undefined) out.can_task = a.canTask;
  if (a.askBeforeJoin !== undefined) out.ask_before_join = a.askBeforeJoin;
  return out;
}

export const threadJoinCodeListArgs = (a: { spaceId: string }): Json => ({ space: a.spaceId });
export const threadJoinCodeCancelArgs = (a: { spaceId: string; id: string }): Json => ({ space: a.spaceId, id: a.id });

export function threadSettingsArgs(a: { spaceId: string; askBeforeJoin?: boolean }): Json {
  const out: Json = { space: a.spaceId };
  if (a.askBeforeJoin !== undefined) out.ask_before_join = a.askBeforeJoin;
  return out;
}

/** Each operation's daemon tool and arguments: what a native host runs. */
export const THREAD_TOOLS = {
  "thread.read": { tool: "thread_read", args: threadReadArgs },
  "thread.post": { tool: "thread_post", args: threadPostArgs },
  "thread.members": { tool: "agent_members", args: agentMembersArgs },
  "thread.setRights": { tool: "agent_set_rights", args: threadSetRightsArgs },
  "thread.agentAdd": { tool: "agent_add", args: threadAgentAddArgs },
  "thread.agentRemove": { tool: "agent_remove", args: threadAgentRemoveArgs },
  "thread.joinCodeCreate": { tool: "thread_join_code_create", args: threadJoinCodeCreateArgs },
  "thread.joinCodeList": { tool: "thread_join_code_list", args: threadJoinCodeListArgs },
  "thread.joinCodeCancel": { tool: "thread_join_code_cancel", args: threadJoinCodeCancelArgs },
  "thread.settings": { tool: "thread_settings", args: threadSettingsArgs },
} as const satisfies { [K in ThreadOpName]: { tool: string; args: (a: ThreadOps[K]["args"]) => Json } };

/* ---- Tool JSON (snake_case) -> the page's records ------------------------------------ */

const obj = (v: unknown): Json | null => (v && typeof v === "object" && !Array.isArray(v) ? (v as Json) : null);
const str = (v: unknown, d = "") => (typeof v === "string" ? v : d);
const num = (v: unknown): number | null => (typeof v === "number" && Number.isFinite(v) ? v : null);
const strs = (v: unknown) => (Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : []);

const AUTHOR_KINDS: readonly ThreadAuthorKind[] = ["person", "agent", "system"];
const ENTRY_KINDS: readonly ThreadEntryKind[] = ["message", "task_update", "approval", "answer", "system", "join_request"];
const TASK_STATES: readonly TaskState[] = ["queued", "claimed", "working", "done", "failed"];

function author(v: unknown): ThreadAuthor {
  const a = obj(v) ?? {};
  const id = str(a.id);
  const kind = AUTHOR_KINDS.includes(a.kind as ThreadAuthorKind)
    ? (a.kind as ThreadAuthorKind)
    : id.startsWith("agent:")
      ? "agent"
      : id.startsWith("system:")
        ? "system"
        : "person";
  const name = str(a.name) || (kind === "agent" ? id.slice("agent:".length) : id);
  const identity = kind === "agent" ? memberIdentity(a.identity) : null;
  return identity ? { kind, id, name, identity } : { kind, id, name };
}

function ref(v: unknown): MemberRef | null {
  const r = obj(v);
  const id = str(r?.id);
  const name = str(r?.name);
  return r && (id || name) ? { id: id || name, name: name || id } : null;
}

const JOIN_METHODS: readonly JoinMethod[] = ["started", "prompt", "setup"];

/** A member's `identity` (CUA-2262), or null when the daemon sends none or no owner (the badge is never guessed). */
export function memberIdentity(v: unknown): MemberIdentity | null {
  const i = obj(v);
  const owner = ref(i?.owner);
  const handle = str(i?.handle);
  if (!i || !owner || !handle) return null;
  const h = obj(i.harness) ?? {};
  const joined = obj(i.joined) ?? {};
  const icon = str(i.icon);
  return {
    origin: i.origin === "external" ? "external" : "space",
    handle,
    displayName: str(i.display_name) || handle,
    collides: i.collides === true,
    // Only the harness's own mark or an https image: never a page-relative or data URL.
    icon: icon === "harness" || /^https:\/\//i.test(icon) ? icon : null,
    // `reported: false` from a started agent: Cua started it, so the harness is known; from a connected one: it didn't say.
    harness: { id: str(h.id), version: str(h.version) || null, reported: h.reported === true },
    owner,
    device: ref(i.device),
    joined: {
      method: JOIN_METHODS.includes(joined.method as JoinMethod) ? (joined.method as JoinMethod) : i.origin === "external" ? "prompt" : "started",
      atMs: num(joined.at_ms),
      by: ref(joined.by),
    },
    state: i.state === "pending" ? "pending" : "active",
    lastSeenMs: num(i.last_seen_ms),
  };
}

const EVENT_KINDS: readonly MemberEvent["kind"][] = ["member_joined", "member_removed", "name_refused", "rate_limited"];

function memberEvent(v: unknown): MemberEvent | null {
  const e = obj(v);
  if (!e || !EVENT_KINDS.includes(e.kind as MemberEvent["kind"])) return null;
  return { kind: e.kind as MemberEvent["kind"], member: memberIdentity(e.member), by: ref(e.by) };
}

function attachment(v: unknown): ThreadAttachment | null {
  const a = obj(v);
  if (!a) return null;
  const path = str(a.path);
  if (!path) return null;
  return { path, name: str(a.name) || path.slice(path.lastIndexOf("/") + 1), size: num(a.size), mime: str(a.mime) || null };
}

/** One entry of `thread_read`/`thread_post`, as the page reads it. Unknown
 * kinds read as plain messages (a newer daemon's additions still show). */
export function threadEntryFromTool(v: unknown): ThreadEntry | null {
  const e = obj(v);
  const seq = num(e?.seq);
  if (!e || seq === null) return null;
  const task = obj(e.task);
  const approval = obj(e.approval);
  const answer = obj(e.answer);
  const update = obj(e.update);
  const kind = ENTRY_KINDS.includes(e.kind as ThreadEntryKind) ? (e.kind as ThreadEntryKind) : "message";
  const updateState = TASK_STATES.includes(update?.state as TaskState) ? (update!.state as TaskState) : null;
  return {
    seq,
    id: str(e.id) || String(seq),
    tsMs: num(e.ts_ms) ?? 0,
    author: author(e.author),
    kind,
    text: str(e.text),
    mentions: strs(e.mentions),
    replyTo: num(e.reply_to),
    task: task && str(task.to) ? { to: str(task.to), session: num(task.session) } : null,
    noteFor: kind === "system" ? num(e.task_seq) : null,
    attachments: (Array.isArray(e.attachments) ? e.attachments : []).map(attachment).filter((a): a is ThreadAttachment => a !== null),
    approval: approval
      ? {
          action: str(approval.action),
          details: str(approval.details),
          state: str(approval.state, "open"),
          // A card is data only Cua's own host writes: an agent's approval stays text.
          card: author(e.author).kind === "system" ? obj(approval.card) : null,
          ...(str(approval.kind) ? { kind: str(approval.kind) } : {}),
          ...(strs(approval.scope_choices).length ? { scopeChoices: strs(approval.scope_choices).filter((c) => c === "once" || c === "space") } : {}),
        }
      : null,
    answer: answer && num(answer.approval) !== null ? { approval: num(answer.approval)!, approve: answer.approve === true, note: str(answer.note) || null, scope: answer.scope === "space" ? "space" : answer.scope === "once" ? "once" : null, clientId: str(answer.client_id) || null } : null,
    ...(str(e.client_id) ? { clientId: str(e.client_id) } : {}),
    update:
      update && num(update.task) !== null && updateState
        ? { task: num(update.task)!, state: updateState, session: num(update.session), note: str(update.note) || null }
        : null,
    runsOnKeysOf: keyOwner(e.runs_on_keys_of),
    event: kind === "system" ? memberEvent(e.event) : null,
    ...(kind === "join_request" ? { joinRequest: joinRequest(e) } : {}),
    ...(e.view != null ? { view: threadViewFromTool(e.view) } : {}),
    ...(e.failure != null ? { failure: threadFailure(e.failure) } : {}),
    ...(num(e.fanout_of) !== null ? { fanoutOf: num(e.fanout_of) } : {}),
  };
}

/** A typed failure (`failure` of an entry, or of a failed member's status). */
export function threadFailure(v: unknown): ThreadFailure | null {
  const f = obj(v);
  if (!f) return null;
  return {
    class: f.class === "needs_connect" ? "needs_connect" : "error",
    provider: str(f.provider) || null,
    message: str(f.message),
    retryable: f.retryable !== false,
  };
}

function joinRequest(e: Record<string, unknown>): JoinRequest | null {
  const j = obj(e.join_request);
  if (!j) return null;
  return {
    member: memberIdentity(j.member),
    canTask: j.can_task === "members" ? "members" : "owner",
    state: str(j.state, "open"),
    codeId: str(j.code_id),
    youCanAnswer: e.you_can_answer === true,
  };
}

const CODE_STATES: readonly JoinCodeState[] = ["open", "pending_approval", "redeemed", "denied", "expired", "cancelled"];

/** `thread_join_code_create`'s JSON (empty strings for what a daemon left out, as the other mappers do). */
export function joinCodeFromTool(v: unknown): JoinCode {
  const c = obj(v) ?? {};
  return { id: str(c.id), code: str(c.code), url: str(c.url), line: str(c.line), expiresAtMs: num(c.expires_at_ms) ?? 0 };
}

/** `thread_join_code_list`'s JSON (`{codes}` or a bare list). */
export function joinCodesFromTool(v: unknown): { codes: JoinCodeRow[] } {
  const raw = Array.isArray(v) ? v : obj(v)?.codes;
  const codes = (Array.isArray(raw) ? raw : []).flatMap((r): JoinCodeRow[] => {
    const c = obj(r);
    const id = str(c?.id);
    if (!c || !id) return [];
    return [
      {
        id,
        createdAtMs: num(c.created_at_ms) ?? 0,
        expiresAtMs: num(c.expires_at_ms) ?? 0,
        state: CODE_STATES.includes(c.state as JoinCodeState) ? (c.state as JoinCodeState) : "expired",
        canTask: c.can_task === "members" ? "members" : "owner",
        askBeforeJoin: c.ask_before_join === true,
        createdBy: ref(c.created_by),
        memberHandle: str(c.member_handle) || null,
      },
    ];
  });
  return { codes };
}

/** `thread_settings`' JSON. */
export function threadSettingsFromTool(v: unknown): ThreadSettings {
  return { askBeforeJoin: obj(v)?.ask_before_join !== false };
}

/** `agent_add`'s JSON (the row, or `{member}`). */
export function addedMemberFromTool(v: unknown): AgentMember | null {
  const o = obj(v);
  return agentMemberFromTool(o && obj(o.member) ? o.member : v);
}

function keyOwner(v: unknown): { id: string; name: string } | null {
  const k = obj(v);
  const id = str(k?.id);
  return k && id ? { id, name: str(k.name) || id } : null;
}

const ROLES: readonly ThreadRole[] = ["owner", "admin", "member", "guest", "agent"];

function holders(v: unknown): RightHolders | null {
  if (v === "owner" || v === "admins" || v === "members") return v;
  return Array.isArray(v) ? strs(v) : null;
}

function rights(v: unknown): AgentRights | null {
  const r = obj(v);
  if (!r) return null;
  return {
    task: holders(r.task) ?? DEFAULT_AGENT_RIGHTS.task,
    control: holders(r.control) ?? DEFAULT_AGENT_RIGHTS.control,
    approve: holders(r.approve) ?? DEFAULT_AGENT_RIGHTS.approve,
  };
}

function youCan(v: unknown): Record<AgentRight, boolean> | null {
  const y = obj(v);
  return y ? { task: y.task === true, control: y.control === true, approve: y.approve === true } : null;
}

/** `dm` and `needs_you` on an `agent_members {overview}` row (absent otherwise). */
function agentOverview(m: Json): { dm?: AgentDm | null; needsYou?: NeedsYou[] } {
  if (!("dm" in m) && !("needs_you" in m)) return {};
  const d = obj(m.dm);
  const last = obj(d?.last);
  const needs = Array.isArray(m.needs_you) ? m.needs_you : [];
  return {
    dm: d ? { unread: num(d.unread) ?? 0, last: last && num(last.seq) !== null ? { seq: num(last.seq)!, tsMs: num(last.ts_ms) ?? 0, text: str(last.text), author: author(last.author) } : null } : null,
    needsYou: needs.flatMap((n) => {
      const x = obj(n);
      const seq = num(x?.seq);
      if (!x || seq === null || (x.kind !== "approval" && x.kind !== "question")) return [];
      return [{ seq, kind: x.kind, text: str(x.text), tsMs: num(x.ts_ms) ?? 0 }];
    }),
  };
}

/** `thread_read`'s answer. */
export function threadPageFromTool(v: unknown): ThreadPage {
  const p = obj(v) ?? {};
  const entries = (Array.isArray(p.entries) ? p.entries : []).map(threadEntryFromTool).filter((e): e is ThreadEntry => e !== null);
  const last = entries.length ? entries[entries.length - 1]!.seq : 0;
  const me = obj(p.me);
  return {
    entries,
    cursor: num(p.cursor) ?? last,
    caughtUp: p.caught_up !== false,
    unread: num(p.unread) ?? 0,
    readSeq: num(p.read_seq),
    me: (me ? str(me.id) : str(p.me)) || null,
    hasMoreBefore: p.has_more_before === true,
    role: ROLES.includes(p.role as ThreadRole) ? (p.role as ThreadRole) : null,
    live: threadLiveFromTool(p.live),
  };
}

/** `live` of a `thread_read` answer: who is at work and at what stage. */
export function threadLiveFromTool(v: unknown): ThreadLive {
  const o = obj(v) ?? {};
  const agents = (Array.isArray(o.agents) ? o.agents : []).flatMap((a): LiveAgent[] => {
    const r = obj(a);
    const agent = str(r?.agent);
    const stage = str(r?.stage);
    const sinceMs = typeof r?.since_ms === "number" ? r.since_ms : undefined;
    const text = str(r?.text);
    return agent && stage ? [{ agent, stage, ...(sinceMs ? { sinceMs } : {}), ...(text ? { text } : {}) }] : [];
  });
  return { key: str(o.key), agents };
}

/** `thread_post`'s answer: the entry it wrote (bare, or under `entry`). */
export function threadPostFromTool(v: unknown): ThreadEntry | null {
  const p = obj(v);
  return threadEntryFromTool(p && "entry" in p ? p.entry : v);
}

/** `agent_members`' answer (`{members}` or a bare list). */
export function agentMembersFromTool(v: unknown): { members: AgentMember[] } {
  const rows = Array.isArray(v) ? v : Array.isArray(obj(v)?.members) ? (obj(v)!.members as unknown[]) : [];
  return { members: rows.flatMap((r) => agentMember(r)) };
}

/** `agent_set_rights`' answer: the member (with its new rights). */
export function agentMemberFromTool(v: unknown): AgentMember | null {
  return agentMember(v)[0] ?? null;
}

function agentMember(r: unknown): AgentMember[] {
  const m = obj(r);
  const name = str(m?.name);
  if (!m || !name) return [];
  const status = obj(m.status);
  return [
    {
      name,
      ...(str(m.handle) && str(m.handle) !== name ? { handle: str(m.handle) } : {}),
      harness: str(m.harness),
      // `status` is a word, or `{state, activity}`.
      status: (status ? str(status.state) : str(m.status)) || "idle",
      activity: (status ? str(status.activity) : str(m.activity)) || null,
      ...(status && status.failure != null ? { failure: threadFailure(status.failure) } : {}),
      sessions: num(m.sessions) ?? 1,
      rights: rights(m.rights),
      youCan: youCan(m.you_can),
      heldBy: str(obj(m.held_by)?.name) || null,
      identity: memberIdentity(m.identity),
      ...(num(m.queued) ? { queued: num(m.queued)! } : {}),
      ...agentOverview(m),
    },
  ];
}

/* ---- An old daemon ---------------------------------------------------------------------- */

/** The daemon (or this app's SDK) has no thread tools: the SDK's
 * `NotFound("Spaces tool thread_read")`, or the MCP server's
 * `unknown tool thread_read`. A Space that is not there is a different
 * error and still shows. */
export function isMissingThreadTool(e: unknown): boolean {
  const message = e instanceof Error ? e.message : typeof e === "string" ? e : "";
  return /\b(unknown tool|no such tool)\b.*\b(thread_\w+|agent_members)\b|\bspaces tool (thread_\w+|agent_members)\b/i.test(message);
}