@agent-compose/sdk 0.8.5 → 0.8.7

package/src/types/api-factory.ts

@@ -102,6 +102,18 @@ export interface RegisterWorkflowInput {
   factoryDrive?: "required" | "none";
   /** Factory slug. Defaults to `"default"`. */
   factorySlug?: string;
+  /** Register INTO a project (`agentc register --project`, ADR-0087): the
+   *  workflow, its schedules and its runs are visible to the project's
+   *  members alone, read live, so leaving the project loses them — the
+   *  registrant included (the workflow belongs to the project, with no
+   *  personal owner). Any member with a write or owner seat in the project
+   *  may register into it on a key that holds `invoke`; the `manage` scope
+   *  is not needed. A read seat is refused (403 `role_read_only`); a
+   *  project the registrant cannot see answers 404 exactly as one that does
+   *  not exist. Omitted, a registration from a terminal or an API key is
+   *  the whole space's and takes `manage` (403 `manage_required`
+   *  otherwise). */
+  projectId?: string;
 }
 
 export interface TemplateRow {
@@ -138,9 +150,10 @@ export interface ListTemplatesOptions {
   factorySlug?: string;
 }
 
-/** One team connector grant, as `GET /api/v1/connectors` returns it (wire
- *  shape verbatim — snake_case). The typed subset the SDK pins; additional
- *  fields flow through untyped. */
+/** One connector grant, as `GET /api/v1/connectors` returns it (wire shape
+ *  verbatim — snake_case): the caller's own grants and the workspace's
+ *  GitHub installations, never a teammate's other accounts. The typed
+ *  subset the SDK pins; additional fields flow through untyped. */
 export interface ConnectorGrantSummary {
   id: string;
   provider: string;
@@ -331,6 +344,8 @@ export interface UpdateFactoryInput {
 
 export interface ScheduleRow {
   id:           string;
+  /** The factory the schedule (and the workflow it fires) lives in. */
+  factoryId:    string;
   name:         string;
   workflowName: string;
   cron:         string;
@@ -396,11 +411,34 @@ export type SessionSecretInput =
  *  single-use page a session writer opens to provide the named values. */
 export interface SessionSecretRequestCreated {
   requestId: string;
-  url: string;
+  /** The single-use link, the owner's to tap. Null on a DEDUPED answer: the
+   *  open ask's link already went out and nothing new exists to send. */
+  url: string | null;
   expiresAt: string;
-  /** True = a standing auto-approve set already filled the request at the
-   *  mint — nothing is pending; source the session env now. */
+  /** True = a standing auto-approve set or this work's grant already filled
+   *  the request at the mint — nothing is pending. */
   autoApproved?: boolean;
+  /** With autoApproved: true = the values are on the session's RUNNING
+   *  machine now (its env file, and its egress ruleset for a brokered key),
+   *  so re-sourcing the session env loads them; false = no machine is
+   *  running or the push failed, and they land when the next turn starts. */
+  loaded?: boolean;
+  /** Set with autoApproved when the grant came from this work's earlier
+   *  worker (the same person's grant, carried with no card): who gave it. */
+  carried?: { grantedByName: string | null };
+  /** True = an OPEN request of the same kind (or the same key set) already
+   *  stood on this session, and this answer IS that request: no new row, no
+   *  new card, nobody asked again. `keys` are the open request's key names,
+   *  the names the values land under; `note` says what to do. */
+  deduped?: boolean;
+  keys?: string[];
+  kind?: VaultRequestKind | null;
+  note?: string;
+  /** Who holds the ask: the thread's agent (it raises the card once), the
+   *  owner's assistant, or nobody (no owner, no agent). */
+  routedTo?: "agent" | "owner" | null;
+  /** A chat's worker: its card is in the chat, where the work was asked for. */
+  card?: "in the chat";
 }
 
 /** What KIND of credential a vault request asks for (advisory): the vault
@@ -408,9 +446,32 @@ export interface SessionSecretRequestCreated {
 export type VaultRequestKind =
   | "login" | "password" | "api_key" | "payment_card" | "env_file" | "note" | "other";
 
+/** How one requested key is delivered to the session: BROKERED — the egress
+ *  edge adds `headerName: [scheme ]<value>` on requests to `host`, and the
+ *  value never enters the machine; INJECTED — the value lands in the session
+ *  env file. An `api_key` request declares one per key. */
+export type VaultKeyShape =
+  | { mode: "brokered"; host: string; headerName: string; scheme?: string }
+  | { mode: "injected" };
+
+/** The STANDING entry a request is for, named by its label and/or (a card)
+ *  its last four digits — at least one. The card and the vault page lead
+ *  with that entry, so the person sees which saved credential is meant. */
+export interface RequestedVaultEntry {
+  label?: string;
+  last4?: string;
+}
+
+/** A saved payment card's receipts: its network (from the number's issuer
+ *  prefix; null when unknown) and its last four. Never more. */
+export interface VaultCardHint {
+  brand: string | null;
+  last4: string;
+}
+
 /** One STANDING vault entry usable for a session (the catalog read,
- *  2026-08-31) — labels, kinds, and field NAMES only; values are write-only
- *  and never on this wire. */
+ *  2026-08-31) — labels, kinds, identifiers and field NAMES only; values
+ *  are write-only and never on this wire. */
 export interface VaultCatalogEntry {
   label: string;
   kind: string;
@@ -419,6 +480,12 @@ export interface VaultCatalogEntry {
   ownerName: string | null;
   projectName: string | null;
   lastUsedAt: string | null;
+  /** The account the entry belongs to, or a card's network and last four
+   *  ("Amex •••• 1002") — how look-alike labels are told apart. Absent on
+   *  an older server. */
+  identifier?: string | null;
+  /** The card's receipts when the entry is a card; null otherwise. */
+  card?: VaultCardHint | null;
 }
 
 /** A vault link's polled status. */
@@ -429,7 +496,7 @@ export interface SessionSecretRequestStatus {
   expiresAt: string;
   /** Cancellation attribution (task #111) — present on cancelled rows:
    *  who ended the ask ('human' = denied; 'agent' = withdrawn) and why. */
-  cancelledVia?: "human" | "agent";
+  cancelledVia?: "human" | "agent" | "thread_agent";
   cancelReason?: string | null;
   /** The denying human's display name (best-effort; 'human' via only). */
   deniedByName?: string | null;
@@ -444,6 +511,8 @@ export interface SessionSecretRequestStatus {
 export interface SessionSecretRequestSummary {
   requestId: string;
   keys: string[];
+  /** What kind of credential the ask is for; null when the requester did not say. */
+  kind: VaultRequestKind | null;
   reason: string | null;
   expiresAt: string;
   createdAt: string;
@@ -451,6 +520,10 @@ export interface SessionSecretRequestSummary {
 
 export interface CreateApiKeyInput {
   name?:        string;
+  /** Omitted → `read` alone (the read-only default). Anything more —
+   *  `invoke`, `manage`, `admin` — is chosen explicitly, and the server
+   *  refuses any scope the minter does not hold (403 `scope_not_held`).
+   *  `events:read` / `events:write` are deprecated but still accepted. */
   scopes?:      string[];
   expiresAt?:   string;
   factorySlug?: string;
@@ -523,6 +596,9 @@ export interface UsageResponse {
  *  app-level (the platform GitHub App's own webhook) or polling — there
  *  is no per-repo webhook setup (retired 2026-08-18). */
 export interface DriveRepoLink {
+  /** Last successful API head read; a deferred attempt does not advance it. */
+  lastHeadObservedAt: string | null;
+  headCheckDeferredUntil: string | null;
   id:            string;
   factoryId:     string;
   /** Linked directory prefix under the drive root (relative, no slashes
@@ -556,7 +632,16 @@ export interface DriveRepoLink {
   autoLinkSkips: Array<{ branch: string; reason: string; at: string }>;
   lastSyncedGitSha:    string | null;
   lastSyncedAcgCommit: string | null;
-  syncState:     "idle" | "syncing" | "pushing" | "error" | "conflict" | "diverged" | "reauth_required";
+  /** 'queued': the branch's first sync (or a full re-ingest) is waiting in
+   *  the ingest queue; `ingestPriority` / `ingestQueueAhead` say where. */
+  syncState:     "idle" | "queued" | "syncing" | "pushing" | "error" | "conflict" | "diverged" | "reauth_required";
+  /** Drain tier while queued (0 foreground, 1 active, 2 background). */
+  ingestPriority:  number | null;
+  ingestQueuedAt:  string | null;
+  /** When a runner started this branch's ingest; null when none runs. */
+  ingestClaimedAt: string | null;
+  /** Queued branches of the same repo ahead of this one (list only). */
+  ingestQueueAhead?: number | null;
   /** Human-readable detail when syncState is 'error' or 'conflict'. */
   syncError:     string | null;
   createdBy:     string | null;

package/src/types/api-projects.ts

@@ -32,6 +32,23 @@ export interface Project {
   role: ProjectRole;
   memberCount: number;
   objectCount: number;
+  /** The overview's words and dates (owner 2026-10-05): a short
+   *  description, and the start and target dates as calendar days
+   *  (`YYYY-MM-DD`); null until someone sets them. */
+  description: string | null;
+  startDate: string | null;
+  targetDate: string | null;
+}
+
+/** What `updateProject` may set: each field absent = untouched, null =
+ *  cleared. `name` and the details need `write`; `visibility` needs a
+ *  project owner or a team admin. */
+export interface ProjectUpdate {
+  name?: string;
+  visibility?: "public" | "private";
+  description?: string | null;
+  startDate?: string | null;
+  targetDate?: string | null;
 }
 
 /** A page of projects, newest-activity first. Cursor-paginated: pass the
@@ -93,6 +110,16 @@ export interface ProjectObjectsPage {
   next_cursor: string | null;
 }
 
+/** How many objects of each kind a project holds for the caller — the
+ *  whole project's counts under the list's own visibility, never a
+ *  page's. `GET /projects/:id/objects/counts`. */
+export interface ProjectObjectCounts {
+  file: number;
+  conversation: number;
+  session: number;
+  folder: number;
+}
+
 /** One file the caller could NOT contribute to a project when adding a
  *  session — only files the caller OWNS are materialized. `path` is present
  *  only when visible to the caller; paths concealed from the caller are
@@ -138,3 +165,453 @@ export interface RefreshProjectObjectResult {
   objects: ProjectObject[];
   skipped: ProjectSkippedFile[];
 }
+
+// ── The project status view (owner 2026-09-27) ─────────────────────────────
+
+/** A person on a project status row, identity merged server-side. `email`
+ *  rides only while they share the workspace with the viewer: the
+ *  dashboard's label rule (name, else email, else "Teammate") picks. */
+export interface ProjectStatusPerson {
+  id: string;
+  name: string | null;
+  email: string | null;
+  image: string | null;
+  avatarUrl: string | null;
+}
+
+/** Whom a thread waits on (owner 2026-10-01: status "is multiplayer, could
+ *  be needs Chris or Westan"; it names people). A plan task that waits on a
+ *  person, as the thread agent wrote it (a teammate, or someone outside by
+ *  name), or a worker's question owed an answer, which waits on the person
+ *  who asked for the work (the thread's opening message), else the last
+ *  person to speak on the thread. */
+export interface ProjectStatusWaitingOn {
+  /** The teammate, when known. */
+  person: ProjectStatusPerson | null;
+  /** How the thread names them: the teammate's name, "Dana's IT team", or
+   *  "an answer" when a worker's question has nobody to wait on yet. */
+  who: string;
+  /** What they will do or answer, in the people's terms. */
+  what: string | null;
+  /** `task`: a plan task waiting on a person; `question`: a worker's
+   *  question owed an answer; `answer`: the thread's own question to a
+   *  person (its raise declared whom it waits on), open until one of them
+   *  answers where Ivy spoke. */
+  kind: "task" | "question" | "answer";
+  /** The chat message where the person said it, when the thread agent
+   *  recorded one, or Ivy's message carrying the thread's question: the way
+   *  to the ask. Null otherwise. */
+  messageId: string | null;
+  /** An answer wait's place: the chat thread Ivy spoke in (null for the
+   *  room's top level). Absent on the other kinds. */
+  threadRootId?: string | null;
+  /** When the thread asked (ISO). Absent on the other kinds. */
+  at?: string | null;
+}
+
+/** Whom a TASK waits on (owner 2026-10-05: a todo may wait on more than one
+ *  person's answer or sign-off): every teammate it names, as people, and
+ *  the words the thread agent (or the person who set it) wrote for whoever
+ *  they are. */
+export interface ThreadStatusWaitingOn {
+  /** The teammates, the one whose act comes first first; empty for a wait
+   *  on someone the workspace cannot name ("Dana's IT team"). */
+  people: ProjectStatusPerson[];
+  /** How the thread names them. */
+  who: string;
+  /** What they will do or answer, in the people's terms; null when a person
+   *  set the wait without saying for what. */
+  what: string | null;
+  /** The chat message where the person said it, when one was recorded. */
+  messageId: string | null;
+}
+
+/** Who a todo is assigned to (owner 2026-10-05, like an issue's assignee):
+ *  Ivy, or one person. Null on the todo = nobody, after a person took the
+ *  assignee off. */
+export type ThreadStatusAssignee = { kind: "ivy" } | ({ kind: "person" } & ProjectStatusPerson);
+
+/** One plan task of a thread, as the thread agent's plan view reads it. */
+export interface ProjectStatusTask {
+  id: string;
+  objective: string;
+  status: "open" | "done";
+  dueAt: string | null;
+  overdue: boolean;
+  /** Open and waiting on a task that is not done. */
+  blocked: boolean;
+  criteria: { met: number; total: number };
+  /** Open and waiting on a person. */
+  waitingOn: ThreadStatusWaitingOn | null;
+  assignee: ThreadStatusAssignee | null;
+}
+
+/** What a thread's workers are doing, from platform rows: `waiting` a
+ *  worker's question is owed an answer; `working` a worker has a live turn;
+ *  `idle` workers exist and none is running; `done` the thread is closed;
+ *  `none` no worker was started. */
+export type ProjectStatusWorker = "working" | "waiting" | "idle" | "done" | "none";
+
+/** One outcome thread born in one of the project's chats. */
+export interface ProjectStatusThread {
+  id: string;
+  title: string;
+  state: "open" | "waiting" | "snoozed" | "closed";
+  note: string | null;
+  /** The chat the thread was born in, and whether it is public or private. */
+  conversation: { id: string; title: string | null; access: "public" | "private" };
+  /** The chat message the thread opened on, for a deep link; null if none. */
+  openingMessageId: string | null;
+  /** Who holds the next move: a person while the thread waits on people,
+   *  else Ivy. */
+  owner: { kind: "ivy" } | ({ kind: "person" } & ProjectStatusPerson);
+  /** The people who spoke on the thread, most recent first. */
+  people: ProjectStatusPerson[];
+  /** The now line: what its running worker is doing (`worker`), else the
+   *  thread agent's note, its own reading of where things stand (`note`);
+   *  null when there is neither. `at` is when the text was set (ISO). */
+  now: { kind: "worker" | "note"; text: string; at: string | null } | null;
+  /** `running`: how many of its workers have a live turn. `line`: while
+   *  `status` is working, the one-line status its running worker set most
+   *  recently ("Reading the Fly logs") and when (ISO); null otherwise. */
+  worker: { status: ProjectStatusWorker; sessions: number; running: number; line: { text: string; at: string } | null };
+  /** Whom the thread waits on, named; empty when it waits on nobody. */
+  waitingOn: ProjectStatusWaitingOn[];
+  /** The next open task deadline, else the thread agent's check-in. */
+  next: { at: string; what: string; kind: "deadline" | "check_in" } | null;
+  progress: { done: number; total: number };
+  tasks: ProjectStatusTask[];
+  overdue: number;
+  blocked: number;
+  unmetCriteria: number;
+  lastMovementAt: string;
+  closedAt: string | null;
+}
+
+/** What moved: a task done, a thread opened or closed, a result or decision
+ *  the thread agent raised to the people, a worker's declared result, or a
+ *  person's answer (`by` names them). */
+export type ProjectStatusActivityKind = "task_done" | "thread_closed" | "thread_opened" | "result" | "decision" | "answer";
+
+export interface ProjectStatusActivity {
+  at: string;
+  kind: ProjectStatusActivityKind;
+  threadId: string;
+  threadTitle: string;
+  text: string;
+  by: ProjectStatusPerson | null;
+}
+
+/** How many live threads wait on one person (or one named outsider). */
+export interface ProjectStatusWaitingCount {
+  person: ProjectStatusPerson | null;
+  who: string;
+  threads: number;
+}
+
+/** The header's counts: "3 in progress, waiting on Chris (2) and Westan (1),
+ *  4 done this week". */
+export interface ProjectStatusCounts {
+  /** Live threads (open, waiting or snoozed). */
+  inProgress: number;
+  /** Threads closed in the last seven days. */
+  doneThisWeek: number;
+  waitingOn: ProjectStatusWaitingCount[];
+}
+
+/** GET /projects/:id/status. `threads` (the live ones) is cursor-paginated
+ *  by last movement; `recentlyClosed` rides the first page only (empty on
+ *  later pages). The project facts (`sources`, `progress`, `dueAt`,
+ *  `nextCheckIn`, `activity`) span every thread the viewer may read, on
+ *  every page. */
+export interface ProjectStatus {
+  project: { id: string; name: string; visibility: "public" | "private"; role: ProjectRole };
+  /** The chats in the project, where its threads are born. */
+  sources: number;
+  progress: { done: number; total: number };
+  /** The latest deadline of an open task: the project's finish line. */
+  dueAt: string | null;
+  nextCheckIn: { at: string; threadId: string; threadTitle: string; conversationId: string; with: ProjectStatusPerson | null } | null;
+  counts: ProjectStatusCounts;
+  threads: ProjectStatusThread[];
+  /** Closed in the last seven days. */
+  recentlyClosed: ProjectStatusThread[];
+  activity: ProjectStatusActivity[];
+  generatedAt: string;
+  next_cursor: string | null;
+}
+
+// ── One thread's status (GET /threads/:id/status) and one chat's work
+//    (GET /conversations/:id/work) ───────────────────────────────────────────
+
+/** A worker's state as the chat's chips say it: working (a live turn, or
+ *  parked on a question), starting (nothing produced yet), done, failed,
+ *  stopped. */
+export type ThreadStatusWorkerState = "starting" | "working" | "done" | "failed" | "stopped";
+
+/** The effort a worker was started with; null = the harness's own default. */
+export type ThreadStatusWorkerEffort = "low" | "medium" | "high" | "xhigh" | "max";
+
+/** What pays for a worker's inference, as its hover card says it (owner
+ *  2026-10-05: a findable detail, never a mark on rows): a person's connected
+ *  plan (the person by id and name only, when the turn named them), platform
+ *  credits, or a connected provider key by its provider family. */
+export type WorkerFunding =
+  | { lane: "subscription"; owner: { id: string; name: string | null } | null }
+  | { lane: "platform" }
+  | { lane: "byok"; provider: string };
+
+export interface ThreadStatusWorker {
+  /** The worker's session (its page is /conversations/:id). */
+  conversationId: string;
+  title: string | null;
+  state: ThreadStatusWorkerState;
+  /** Its one-line status while working; null otherwise. */
+  line: { text: string; at: string } | null;
+  startedAt: string;
+  /** When a settled worker last spoke, or its session ended. */
+  finishedAt: string | null;
+  /** The result it declared, when it did. */
+  result: string | null;
+  /** The question it is parked on, while one is owed. */
+  asking: string | null;
+  /** The model stamped at birth (what it was CONFIGURED to run); null =
+   *  the runtime's own default. */
+  model: string | null;
+  /** The models its turns ACTUALLY ran (owner 2026-10-06: "what model
+   *  actually did the work"), each once in first-seen order — a mid-turn
+   *  switch lists both: the harness's own report (its stream; codex's
+   *  rollout file read at the turn's end), then the metering gateway's
+   *  attested record of the model each platform-funded call went to. Never
+   *  derived from `model`: empty when nothing is on record, and the
+   *  surfaces then say the model isn't known. Absent on older servers. */
+  ranModels?: string[];
+  effort: ThreadStatusWorkerEffort | null;
+  /** The harness it runs ("claude-code", "codex", ...); null when unknown. */
+  runtime: string | null;
+  /** Where it runs: a cloud sandbox or the person's machine; null when
+   *  unknown. */
+  executor: "local" | "cloud" | null;
+  /** When its running turn started (ISO); null while no turn runs. */
+  workingSince: string | null;
+  /** When its newest turn ended (ISO): the moment it stopped, while no turn
+   *  runs. Null while a turn runs, and for a worker that has not run one. */
+  lastTurnEndedAt: string | null;
+  /** Its machine has a live desktop to show (the Desktop pill's own
+   *  verdict, for the session's current machine): the chat draws a door to
+   *  it on the step the worker is on. False for a local session, a machine
+   *  with no GUI, or a session no longer on a machine. */
+  desktopCapable: boolean;
+  /** What pays for it, when the record says (see WorkerFunding); null when
+   *  nothing is on record. Absent on older servers. */
+  funding?: WorkerFunding | null;
+}
+
+/** A message that directed a step: who wrote it and the opening of what
+ *  they said, where it sits (its chat and, for a reply, the root of its
+ *  chat thread; null for the chat's top level) and when. */
+export interface ThreadStatusDirector {
+  messageId: string;
+  conversationId: string;
+  threadRootId: string | null;
+  /** The person who wrote it, as the status wire names people; null for a
+   *  message Ivy wrote. */
+  author: ProjectStatusPerson | null;
+  /** The opening of what they said, in plain words (links read as their
+   *  labels), capped; null when the message shows no words. */
+  excerpt: string | null;
+  /** When it was said (ISO). */
+  at: string;
+}
+
+/** Something a worker produced, filed under the step it was on: a desktop
+ *  screenshot or a capture pushed with a need (`path`, a drive file), or
+ *  its declared result (`text`, its words). */
+export interface ThreadStatusOutput {
+  id: string;
+  kind: "screenshot" | "capture" | "result";
+  /** When it landed (ISO). */
+  at: string;
+  /** The drive path of a picture; null for words. */
+  path: string | null;
+  /** The words: a result's own, a picture's summary. */
+  text: string;
+}
+
+/** What a person did on a todo in the chat's todo view (owner 2026-10-05):
+ *  a comment, or an edit of its assignee, details, status or whom it waits
+ *  on. The todo's Activity, with the platform's own history. */
+export interface ThreadStatusTodoActivity {
+  id: string;
+  /** When (ISO). */
+  at: string;
+  kind: "comment" | "assignee" | "description" | "status" | "waiting_on";
+  /** Who did it; null for a person the workspace cannot name. */
+  by: ProjectStatusPerson | null;
+  /** A comment's words, or the details written; null otherwise. */
+  text: string | null;
+  /** The assignee set (`kind` assignee); null for nobody. */
+  assignee: ThreadStatusAssignee | null;
+  /** The status set (`kind` status). */
+  status: "open" | "in_progress" | "waiting" | "done" | null;
+  /** The people set (`kind` waiting_on). */
+  waitingOn: ProjectStatusPerson[];
+}
+
+/** One step of the thread's plan. */
+export interface ThreadStatusTodo {
+  id: string;
+  objective: string;
+  status: "open" | "done";
+  dueAt: string | null;
+  overdue: boolean;
+  /** Open and waiting on a step that is not done. */
+  blocked: boolean;
+  /** The steps it waits on, by their objective. */
+  blockedOn: string[];
+  /** Open and waiting on people. */
+  waitingOn: ThreadStatusWaitingOn | null;
+  /** Who it is assigned to: Ivy, one person, or nobody (owner 2026-10-05).
+   *  Stored on the server; the plan's default is the first person it waits
+   *  on, else Ivy, and a person's choice stands over the plan's. */
+  assignee: ThreadStatusAssignee | null;
+  /** The details a person wrote on it, plain text with line breaks; null
+   *  when none. */
+  description: string | null;
+  /** What people did on it (edits and comments), oldest first, bounded. */
+  activity: ThreadStatusTodoActivity[];
+  /** Its done criteria, as counts. */
+  criteria: { met: number; total: number };
+  /** The thread's worker on this step (the thread agent's stamp), or null. */
+  workerConversationId: string | null;
+  /** Done, and completed with this note: what it produced, in one line. */
+  result: string | null;
+  /** When a worker was first put on the step (ISO): its own clock in the
+   *  chat, never a worker's turn. Null until then. */
+  startedAt: string | null;
+  /** Done at this moment (ISO): when its check-off lands in the chat. Null
+   *  while open. */
+  completedAt: string | null;
+  /** The messages that directed the step (the request or follow-up that
+   *  added it, then every steer, from another chat thread too), oldest
+   *  first. Empty = the job's request alone. The step's status shows in the
+   *  chat thread of each. */
+  directedBy: ThreadStatusDirector[];
+  /** What the worker produced for the step, newest first (bounded): its
+   *  screenshots and captures, and its declared result. */
+  outputs: ThreadStatusOutput[];
+}
+
+/** One of the last things that happened on the thread: a worker's stream
+ *  event (its type), or the thread's record ("said" for a person's words,
+ *  "raised" for what the agent put to the people, "worker_result", ...). */
+export interface ThreadStatusEvent {
+  at: string;
+  kind: string;
+  text: string;
+  by: ProjectStatusPerson | null;
+}
+
+/** One thread's work, as the card under the message that started it reads
+ *  it: the thread, the root it opened on, the note, its workers and its
+ *  steps. */
+export interface ChatWorkThread {
+  thread: ProjectStatusThread;
+  /** The message the thread opened on, in this chat: the job's request —
+   *  who asked for it, their words, where it sits (the job's started mark
+   *  shows there) and when. Null when the thread opened on no message here
+   *  (the chat shows no card for it, but its workers still count in the
+   *  chat's working status), or the viewer cannot see it. */
+  request: ThreadStatusDirector | null;
+  /** The job's latest place: the newest agent-authored message after the
+   *  request in the request's own chat thread (the thread under a room
+   *  request, or the reply thread the request sits in), else the room's
+   *  newest after it for a room request answered inline. "Jump to latest"
+   *  lands here. Null while nothing has answered; the request is then its
+   *  place. */
+  latestMessageId: string | null;
+  /** The chat thread that latest message sits in (null for the room's top
+   *  level); null with no latest message. */
+  latestThreadRootId: string | null;
+  /** The thread agent's rolling note: where things stand, in its words. */
+  summary: string | null;
+  /** When the thread was opened (ISO): the job's start, the beginning of
+   *  its total time. */
+  openedAt: string;
+  /** Working first, then starting, then what settled (newest first). */
+  workers: ThreadStatusWorker[];
+  /** The plan's steps, in plan order (oldest first). */
+  todos: ThreadStatusTodo[];
+}
+
+export interface ThreadStatus extends ChatWorkThread {
+  events: ThreadStatusEvent[];
+  generatedAt: string;
+}
+
+/** GET /conversations/:id/work: the chat's threads, most recently moved
+ *  first and bounded (the server's CHAT_WORK_THREADS), each with its work.
+ *  404 for a chat the viewer cannot read. */
+export interface ChatWork {
+  threads: ChatWorkThread[];
+  /** The project the chat is filed in, as the viewer may see it; null for
+   *  a chat in none. A todo's Properties name it. */
+  project: { id: string; name: string } | null;
+  generatedAt: string;
+}
+
+/** PATCH /conversations/:id/todos/:todoId (owner 2026-10-05: "change the
+ *  assignee", "write details in here myself"): what a person who can read
+ *  the chat may change on a todo. Each field is optional; one call may
+ *  carry several. Answers the chat's whole work read (ChatWork), so the
+ *  surfaces redraw from one truth. */
+export interface ChatTodoPatch {
+  /** The one assignee: Ivy, a person who can read the chat, or null for
+   *  nobody. */
+  assignee?: { kind: "ivy" } | { kind: "person"; userId: string } | null;
+  /** The details, plain text with line breaks; null or "" clears. */
+  description?: string | null;
+  /** Where it stands, in the plan's own states: open (not started), in
+   *  progress, waiting (on the people given, or the ones it already waits
+   *  on), done. A done todo stays done. */
+  status?: "open" | "in_progress" | "waiting" | "done";
+  /** Whom it waits on: people who can read the chat (several allowed), and
+   *  for what; [] or null clears the wait. */
+  waitingOn?: { userIds: string[]; what?: string | null } | null;
+}
+
+/** POST /conversations/:id/todos/:todoId/comments: a comment on the todo,
+ *  which lands in its Activity and reaches the thread's agent. Answers the
+ *  chat's whole work read. */
+export interface ChatTodoComment {
+  text: string;
+}
+
+// ── The personal status (GET /me/status) ───────────────────────────────────
+
+export interface MeStatusCounts {
+  waitingOnYou: number;
+  inProgress: number;
+  /** The viewer's projects with a relevant live thread. */
+  projects: number;
+  doneThisWeek: number;
+}
+
+/** GET /me/status, for the current workspace: the threads relevant to the
+ *  viewer (they posted, were mentioned, asked, have a to-do, or are in the
+ *  chat), never the whole workspace. `threads` is cursor-paginated by last
+ *  movement; `waitingOnYou`, `recentlyClosed` and `activity` ride the first
+ *  page. The client groups by `chatProjects` (the viewer's project for each
+ *  chat; a chat absent there is in none of theirs). */
+export interface MeStatus {
+  counts: MeStatusCounts;
+  /** Live threads a task of which waits on the viewer, or whose worker's
+   *  question is owed and the viewer asked for the work (else spoke last). */
+  waitingOnYou: ProjectStatusThread[];
+  threads: ProjectStatusThread[];
+  recentlyClosed: ProjectStatusThread[];
+  chatProjects: Array<{ conversationId: string; project: { id: string; name: string } }>;
+  activity: Array<ProjectStatusActivity & { conversationId: string | null }>;
+  generatedAt: string;
+  next_cursor: string | null;
+}