@agent-compose/sdk 0.8.5 → 0.8.6

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,419 @@ 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;
+  kind: "task" | "question";
+  /** The chat message where the person said it, when the thread agent
+   *  recorded one: the way to the ask. Null otherwise. */
+  messageId: 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";
+
+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; null = the runtime's own default. */
+  model: string | null;
+  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;
+  /** 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;
+}
+
+/** 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;
+}

package/src/types/api-runs.ts

@@ -97,6 +97,11 @@ export interface InvokeInlineAndWaitOptions extends InvokeInlineOptions {
 
 export interface InvokeResult {
   id: string;
+  /** The run is PARKED for its funding plan's reset: the person whose plan
+   *  pays for it has every plan out, so nothing runs until `until`, when it
+   *  starts by itself; `text` is the one line to pass on. Absent for a run
+   *  that boots now. */
+  hold?: { until: string; text: string };
 }
 
 export interface StreamRunLogsOptions {

package/src/types/api-scopes.ts

@@ -36,9 +36,10 @@ export type DocumentCapability = "read" | "write";
 export type TemplateCapability = "read" | "write" | "invoke" | "see_runs";
 
 /** One grant on an artifact scope. `team`/`user` are the editable tiers
- *  carried on a PUT (full-replace); `session`/`project` are DERIVED,
- *  read-only arms that appear only on READ payloads (the routes that manage
- *  them own their mutation — a scope PUT rejects them, 400 `invalid_principal`).
+ *  carried on a PUT (full-replace); `session`/`project`/`conversation`/
+ *  `worker` are DERIVED, read-only arms that appear only on READ payloads
+ *  (the routes that manage them own their mutation — a scope PUT rejects
+ *  them, 400 `invalid_principal`).
  *
  *  Session and project grants carry FIXED capabilities `['read','write']`:
  *  the fs-gateway is concealment-only (no read/write dimension at the mount),
@@ -58,6 +59,30 @@ export type ScopeGrant =
        *  being a project member (share implies unshare). Null only for
        *  transitional/legacy rows. */
       projectObjectId: string | null;
+      /** The people in the project: the row's reach. */
+      memberCount: number;
+      capabilities: string[];
+    }
+  /** A chat's grant (scope-at-birth, documents): reach derives LIVE from the
+   *  chat's tier and member rows. `memberCount` is null for a public channel,
+   *  whose audience is the whole team rather than its member rows. */
+  | {
+      principal: "conversation";
+      conversationId: string;
+      conversationTitle: string | null;
+      memberCount: number | null;
+      capabilities: string[];
+    }
+  /** The grant a chat's WORKER session holds on what it wrote: not a group
+   *  of people. The readers of the chat it works for (`chatId`) reach the
+   *  file through it while the worker's project boundary holds. `title` is
+   *  the work's (the session's) title. */
+  | {
+      principal: "worker";
+      conversationId: string;
+      title: string | null;
+      chatId: string;
+      chatTitle: string | null;
       capabilities: string[];
     };
 
@@ -71,6 +96,10 @@ export interface ArtifactScope {
   /** Templates only — the owning conversation binding (a grant source:
    *  members of that conversation reach the template via their role). */
   conversationId?: string | null;
+  /** Documents only — born of a shared chat's work (Ivy's publish, a
+   *  worker's output for a chat). Such a document is shared by the people
+   *  who can edit it, whoever its owner is; so is one with no owner. */
+  bornOfChatWork?: boolean;
   grants: ScopeGrant[];
 }
 

package/src/types/conversation-stream.ts

@@ -130,6 +130,11 @@ export interface ConversationTurnStateEvent {
   pendingCount: number;
   at: number;
   partial: true;
+  /** The running turn is WRITING words that will be sent — the typing
+   *  indicator's one signal (a running turn that thinks, calls tools,
+   *  reacts or notes is not writing). Absent when the emitter cannot know;
+   *  consumers inherit their previous frame's value, and `idle` resets it. */
+  writing?: boolean;
   /** When the open turn started (ms) — carried by the connect-time
    *  snapshot frame only; absent on live transition frames. */
   startedAt?: number | null;

package/src/types/execution-context.ts

@@ -1,4 +1,4 @@
-/** Shared execution context capabilities for workflow functions and steps. */
+/** Shared execution context capabilities for workflow steps. */
 
 import type { InvokeAndWaitOptions, RunStatus } from "./api-runs.js";
 import type { RequestContext } from "../request-context/request-context.js";

package/src/types/protocol.ts

@@ -74,6 +74,22 @@ export interface AgentMessageError extends AgentMessageBase {
   text: string;
 }
 
+/** One model's share of a harness's turn-end report (claude-code
+ *  `result.modelUsage[<model>]`): the same four token classes as the turn
+ *  totals, plus what the harness reports beside them. `costUsd` is the
+ *  harness's OWN estimate at its price table — never a bill. Fields the
+ *  harness did not report are absent, never zeroed. */
+export interface AgentMessageModelUsage {
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheCreationTokens: number;
+  /** Thinking tokens, already counted inside `outputTokens`. */
+  thinkingTokens?: number;
+  webSearchRequests?: number;
+  costUsd?: number;
+}
+
 export interface AgentMessageUsage extends AgentMessageBase {
   type: "usage";
   inputTokens: number;
@@ -82,6 +98,54 @@ export interface AgentMessageUsage extends AgentMessageBase {
   cacheCreationTokens: number;
   durationMs: number;
   numTurns: number;
+  /** Reasoning tokens, already counted inside `outputTokens` (codex
+   *  `turn.completed.usage.reasoning_output_tokens`). Absent when the
+   *  harness reports no such class. */
+  reasoningOutputTokens?: number;
+  /** Per-model totals the harness reported beside the turn totals
+   *  (claude-code `result.modelUsage`): every model the query pipeline
+   *  called — main loop, subagents, compaction. As the CLI reports them:
+   *  CUMULATIVE for the guest session (a streaming-input or resumed
+   *  session carries its earlier turns), so a per-turn share is the
+   *  difference from the previous report of the same session. Absent when
+   *  the harness reports none. */
+  byModel?: Record<string, AgentMessageModelUsage>;
+  /** The harness's own cost estimate for the same scope as `byModel`
+   *  (claude-code `result.total_cost_usd`): list-price arithmetic, an
+   *  estimate and never a billing statement. */
+  costUsd?: number;
+}
+
+/** The harness's reading of the account's PLAN LIMITS (claude-code
+ *  `rate_limit_event`, emitted whenever its rate-limit information changes
+ *  — subscription-funded sessions only; the headers it reads exist for
+ *  claude.ai plans). `status` is the verdict for the request just made:
+ *  `rejected` means the plan's wall, with `resetsAt` the authoritative
+ *  reset. `window` names which window the verdict speaks for (the CLI's
+ *  `rateLimitType`: five_hour, seven_day, seven_day_opus, …). `utilization`
+ *  is carried only once a window crosses a warning threshold (the CLI omits
+ *  it while plainly allowed), as the CLI reports it — a 0..1 fraction of
+ *  the window. Everything the event did not carry is absent; nothing is
+ *  invented. Additive kind: existing producers never emit it. */
+export interface AgentMessagePlanLimits extends AgentMessageBase {
+  type: "plan_limits";
+  status: "allowed" | "allowed_warning" | "rejected";
+  window?: string;
+  /** ISO time the named window resets. */
+  resetsAt?: string;
+  utilization?: number;
+  /** The warning threshold the window crossed (as the CLI reports it). */
+  surpassedThreshold?: number;
+  /** The plan's extra-usage (overage) lane, when the event spoke of it. */
+  overage?: {
+    status?: "allowed" | "allowed_warning" | "rejected";
+    resetsAt?: string;
+    disabledReason?: string;
+    inUse?: boolean;
+  };
+  /** Which spend limit blocked the request when not the member's own cap. */
+  limitScope?: string;
+  errorCode?: string;
 }
 
 /** LIVE-ONLY incremental usage off the harness's raw provider stream — the
@@ -114,7 +178,8 @@ export interface AgentMessagePlan extends AgentMessageBase {
   type: "plan";
   entries: {
     content: string;
-    priority: "high" | "medium" | "low";
+    /** ACP names one; codex's `--json` plan names none. */
+    priority?: "high" | "medium" | "low";
     status: "pending" | "in_progress" | "completed";
   }[];
 }
@@ -280,6 +345,7 @@ export type AgentMessage =
   | AgentMessageError
   | AgentMessageUsage
   | AgentMessageUsageDelta
+  | AgentMessagePlanLimits
   | AgentMessagePlan
   | AgentMessageTaskNotification
   | AgentMessageTaskProgress

package/src/types/runtime.ts

@@ -256,7 +256,13 @@ export interface ModelExecutionContract {
    *     phase, a spec/transport without stream input, ACP path).
    * Calls are serialized per turn; never throws.
    */
-  injectUserMessage?(text: string): Promise<"delivered" | "pending" | "closed" | "unsupported">;
+  injectUserMessage?(
+    text: string,
+    /** Who the message speaks for when it is not the session user
+     *  (MidTurnEnvelopeOptions): a relayed person, named, or the thread
+     *  agent that owns this worker. */
+    opts?: { relayedFrom?: string | null; fromOwnerAgent?: boolean },
+  ): Promise<"delivered" | "pending" | "closed" | "unsupported">;
   /**
    * Request an in-band STEP INTERRUPT of the currently running turn — the
    * ESC equivalent. Where `injectUserMessage` queues content for the turn
@@ -316,7 +322,7 @@ export interface ModelExecutionContract {
  * The sandbox provider (e.g. "vercel", "e2b") is an infrastructure concern
  * configured via SANDBOX_PROVIDER — not part of the runtime definition.
  * For non-sandbox agents (API calls, etc.) make the call directly in the workflow;
- * spawnAgent is a sandbox concept.
+ * `agent()` is a sandbox concept.
  */
 export interface AgentRuntime<S extends SandboxProvider = SandboxProvider> {
   create(sandbox: S, opts: RuntimeOptions): ModelExecutionContract;

package/src/types/sandbox-environment.ts

@@ -79,8 +79,7 @@ export function defineSandboxEnvironment(
     snapshots: env.snapshots ?? { saveLatest: true },
     // Mark this as an environment build so the server skips the /factory mount
     // for its runs — an env build builds a platform image and never touches the
-    // shared drive; baking a live Archil mount into its snapshot breaks the
-    // re-mount of every workflow that later boots from it (#13).
+    // shared drive, so no live drive mount bakes into its snapshot (#13).
     environmentBuild: true,
   })
     .step({