@agent-compose/sdk 0.8.2 → 0.8.3

package/src/types/api-conversations.ts

@@ -95,10 +95,36 @@ export interface ConversationRow {
   unreadCount?: number;
 }
 
+/** Agent-author identity decoration (mirrors the server's `agentAuthor`
+ *  on message rows and stream payloads): rows authored by a user's agent
+ *  that is not the conversation's resident agent — the assistant's
+ *  delegated sends, review briefs, and PEER-SESSION messages
+ *  (`sourceChannel: 'session'`). The persona `name` is the author label;
+ *  `avatarSeed` is the agent's own generated orb; the owner names WHOSE
+ *  agent it is. */
+export interface ConversationAgentAuthor {
+  agentId: string;
+  name: string;
+  avatarSeed: string;
+  ownerUserId: string | null;
+  ownerName: string | null;
+}
+
 export interface ConversationMessageRow {
   id: string;
   authorKind: string;
   authorId: string | null;
+  /** The author's display name, resolved server-side — a HUMAN author's
+   *  display name, or an attributable AGENT author's persona name (see
+   *  `agentAuthor`). Null for resident-agent/system rows; absent on older
+   *  servers. */
+  authorLabel?: string | null;
+  /** Sender identity for foreign-agent and peer-session rows — render the
+   *  persona name + its avatarSeed FIRST, before any session/runtime
+   *  fallback (the one resolution order; streamed and settled renders are
+   *  identical). Null/absent on resident-agent, session channel-post, and
+   *  older-server rows. */
+  agentAuthor?: ConversationAgentAuthor | null;
   parts: ConversationMessagePart[];
   threadRootId: string | null;
   reactions: Record<string, string[]>;
@@ -115,6 +141,12 @@ export interface ConversationMessageRow {
    *  rows to the session (title + runtime mark), never a resident agent.
    *  Null once the session is deleted; absent on older servers. */
   sourceSessionId?: string | null;
+  /** THE ORIGIN SURFACE (ADR-0073 §6.5): the ingress the row arrived over —
+   *  'sms' / 'phone' / 'voice' on inbound user rows, 'assistant' on
+   *  delegated sends, 'session' on peer session→session messages (whose
+   *  author identity rides `agentAuthor`). Null/absent = an ordinary
+   *  in-app send or an older server. */
+  sourceChannel?: "sms" | "phone" | "voice" | "assistant" | "session" | null;
   /** Set on a session-transcript row RELAYED from a channel mention
    *  (ADR-0057 Seam 3) — the channel it arrived from. Null once the
    *  channel is deleted; absent on older servers. */
@@ -133,9 +165,44 @@ export interface ConversationsPage {
 /** Sessions page — each row additionally carries its resident
  *  executor substrate (ADR-0037 §8): `"cloud"` = persistent server-side
  *  sandbox (pickers render the ☁ marker), `"local"` = bridge daemon,
- *  null = no durable session record yet. */
+ *  null = no durable session record yet — and, on diff-review spawns,
+ *  `reviewOf`: the session this row was born to REVIEW (id + its current
+ *  alias/title; a deleted reviewed conversation degrades to a bare id
+ *  ref). Null/absent for ordinary sessions and older servers. */
 export interface SessionsPage {
-  conversations: Array<ConversationRow & { sessionExecutor: "local" | "cloud" | null }>;
+  conversations: Array<ConversationRow & {
+    sessionExecutor: "local" | "cloud" | null;
+    reviewOf?: { conversationId: string; alias: string | null; title: string | null; head?: string | null } | null;
+  }>;
+  next_cursor: string | null;
+}
+
+/** One 15-minute sandbox perf rollup bucket from
+ *  GET /conversations/:id/perf-history (session_perf_rollups). Null
+ *  utilization fields = the guest never reported that resource in the
+ *  bucket — never zero-filled. */
+export interface SessionPerfBucket {
+  /** Start of the bucket, ISO 8601. */
+  bucket_start: string;
+  /** Guest samples folded into the bucket (turn + sweep lanes). */
+  samples: number;
+  cpu_busy_p50: number | null;
+  cpu_busy_p95: number | null;
+  mem_used_p50: number | null;
+  mem_used_p95: number | null;
+  disk_used_p95: number | null;
+  load1_max: number | null;
+  /** Seconds within the bucket any resource sat ≥90% (capped at 900). */
+  saturated_seconds: number;
+  vcpu: number | null;
+  provider: string;
+}
+
+/** Newest-first, keyset-paginated (house list envelope). */
+export interface SessionPerfHistoryPage {
+  object: "list";
+  data: SessionPerfBucket[];
+  has_more: boolean;
   next_cursor: string | null;
 }
 
@@ -165,6 +232,10 @@ export interface ConversationDetail {
    *  with a drive branch and a resolvable factory; null/absent = main
    *  only (read loosely — older servers omit it). */
   sessionDrive?: { factorySlug: string; branch: string } | null;
+  /** THE REVIEWER MARKER (diff-review spawns): non-null ⇒ this session was
+   *  born to review that conversation's diff. Null for ordinary sessions;
+   *  absent on older servers (read loosely). */
+  sessionReviewOf?: string | null;
   viewerLastReadAt: string | null;
   /** The caller's role in this conversation (ADR-0045) — drives client
    *  affordances only; the server remains the authority on every action.
@@ -181,6 +252,11 @@ export interface ConversationDetail {
    *  `messages`. Seed the stream's first `Last-Event-ID` from it instead of
    *  0 (0 replays the entire history). Absent on older servers. */
   streamCursor?: number;
+  /** Windowed hydrate (2026-08-17): `messages` is the NEWEST window
+   *  (default 50; `limit` caps at 200). Non-null = older transcript
+   *  exists — page it with `GET /conversations/:id/messages?before=` +
+   *  this opaque cursor. Absent on older servers. */
+  olderCursor?: string | null;
   messages: ConversationMessageRow[];
 }
 
@@ -391,6 +467,13 @@ export interface SessionChangeSet {
   truncated: boolean;
   /** Open `factory_file_conflicts` rows from this session's prior merges. */
   openConflicts: number;
+  /** Graph plane only (additive — absent elsewhere): the opaque cursor for
+   *  the NEXT page of `changes` — pass it back as `after` on
+   *  `getSessionChanges`. Null = last page. */
+  nextAfter?: string | null;
+  /** The serving plane (additive): `"graph"` when the change set is served
+   *  from the commit graph (paginated, head-anchored); absent = legacy. */
+  plane?: "graph";
   /** MERGE GATE (merge-gate spec, additive — absent on older servers):
    *  null = ungated. Present: whether THIS caller's merge lands directly
    *  (`canMerge` — an owner or named approver) or stages a kind='merge'
@@ -417,6 +500,22 @@ export interface SessionChangeSet {
   reviewEnabled?: boolean;
   reviewSessionConversationId?: string | null;
   reviewSessionActive?: boolean;
+  /** BOUND (additive): the bound review session — the FOLLOW-UP LOOP's
+   *  driver — exists and is not ended (a parked reviewer between turns is
+   *  bound but not active). Not publish rights: every reviewer of the
+   *  diff owns its own document; concurrent reviewers are first-class,
+   *  bounded at spawn (`reviewer_cap`). */
+  reviewSessionBound?: boolean;
+  /** The AUTOMATIC follow-up loop (additive): armed (default true) + how
+   *  many automatic rounds ran since the last human-triggered review
+   *  (hard cap 2; a manual re-review resets it). */
+  reviewAutoFollowup?: boolean;
+  reviewAutoRounds?: number;
+  /** The OPT-IN main-advance auto-rebase reflex (additive — absent on
+   *  older servers; default OFF): armed ⇒ when main moves and a preflight
+   *  proves the fold clean, the platform rebases this session's branch
+   *  from main headlessly. Toggled via `setSessionAutoRebase`. */
+  autoRebaseFromMain?: boolean;
   /** STRUCTURED review suggestions beside the notes (additive — absent on
    *  older servers): individually actionable {id, path, title, rationale,
    *  patch} entries the review session wrote back, status-stamped
@@ -429,6 +528,34 @@ export interface SessionChangeSet {
    *  (`mergeable` false, merge 409s `fork_branch_unmergeable`), and it is
    *  refused as a review target (409 `review_of_review`). */
   reviewOfConversationId?: string | null;
+  /** PER-REVIEWER review documents (additive — absent on older servers;
+   *  owner ask 2026-08-22): EVERY reviewer's published document for this
+   *  diff, newest publish first — parallel reviewers each own one. The
+   *  flat `reviewNotes`/`reviewSuggestions` above are derived aggregates
+   *  (the primary document's notes; the reviewer-stamped union); this is
+   *  the grouped truth the review panel renders. Page 1 only — cursor
+   *  pages serve an empty array. */
+  reviewDocuments?: SessionReviewDocument[];
+}
+
+/** One reviewer's published review document
+ *  (`SessionChangeSet.reviewDocuments`). `stale` compares the head this
+ *  document was published against with the served diff. */
+export interface SessionReviewDocument {
+  reviewerConversationId: string;
+  /** The reviewer session's @alias / title, when its conversation still
+   *  exists (a deleted reviewer degrades to the bare id). */
+  reviewerAlias: string | null;
+  reviewerTitle: string | null;
+  notes: string;
+  suggestions: ReviewSuggestion[];
+  /** ISO timestamp of this document's last publish. */
+  publishedAt: string;
+  /** The diff head published against (null = pre-stamp reviewer). */
+  signature: string | null;
+  /** Display form of `signature` ("head cd741f27"). */
+  headShort: string | null;
+  stale: boolean;
 }
 
 /** One STRUCTURED, individually actionable suggestion a review session
@@ -449,6 +576,48 @@ export interface ReviewSuggestion {
    *  the session branch), `"rejected"`, or `"stale"` (an accept found the
    *  file drifted since review; nothing was written). */
   status: "proposed" | "accepted" | "rejected" | "stale";
+  /** REVIEWER IDENTITY (additive — present on the flat
+   *  `SessionChangeSet.reviewSuggestions` union; owner ask 2026-08-22):
+   *  which reviewer's document this entry came from. Ids are unique only
+   *  PER REVIEWER — the decide-one route takes `reviewerConversationId`
+   *  when two reviewers reused an id (409 `ambiguous_suggestion`
+   *  otherwise). */
+  reviewerConversationId?: string;
+  reviewerAlias?: string | null;
+}
+
+/** One suggestion in the review write-back (`publishReviewNotes` /
+ *  `agentc review publish`): `ReviewSuggestion` minus `status` — the server
+ *  stamps every stored entry `"proposed"`, so a reviewer can never claim
+ *  acceptance. `path` must name a file in the change set (refused
+ *  otherwise). */
+export interface ReviewSuggestionInput {
+  id: string;
+  path: string;
+  title: string;
+  rationale: string;
+  patch: string;
+}
+
+/** `POST /conversations/:id/review-notes` — the review session publishing
+ *  its whole review document (full replace: notes AND suggestions
+ *  together). Gated to the bound review session's own toolbelt key. */
+export interface ReviewNotesPublished {
+  ok: true;
+}
+
+/** `POST /conversations/:id/review-git-credential` — one fresh short-lived
+ *  credential for the review git remote, minted per git operation by the
+ *  sandbox's credential helper (`agentc review git-credential`). Gated to
+ *  the review session's own toolbelt key; never stored, never reused. */
+export interface ReviewGitCredential {
+  /** The stable, credential-free remote URL (`https://host/git/<disk>`). */
+  url: string;
+  username: string;
+  password: string;
+  /** ISO timestamp the credential expires — informational (the helper
+   *  mints anew per operation). */
+  expiresAt: string;
 }
 
 /** `POST /conversations/:id/changes/suggestions/:suggestionId/decide` —
@@ -459,6 +628,9 @@ export interface ReviewSuggestionDecision {
   conversationId: string;
   id: string;
   status: ReviewSuggestion["status"];
+  /** PER-REVIEWER documents (additive): whose document the decided
+   *  suggestion lives in — null on older servers / legacy ids. */
+  reviewerConversationId?: string | null;
 }
 
 /** `POST /conversations/:id/changes/suggestions/decide-all` — every stored
@@ -466,7 +638,7 @@ export interface ReviewSuggestionDecision {
 export interface ReviewSuggestionDecisions {
   object: "review_suggestion_decisions";
   conversationId: string;
-  results: Array<{ id: string; status: ReviewSuggestion["status"] }>;
+  results: Array<{ id: string; status: ReviewSuggestion["status"]; reviewerConversationId?: string | null }>;
 }
 
 /** `GET /conversations/:id/changes/stats` — the changes chip's aggregate
@@ -554,6 +726,81 @@ export interface SessionDiscardReport {
   discarded: true;
 }
 
+/** One row of the conflict preflight (`GET /conversations/:id/changes/preflight`)
+ *  — the branch-side change decorated with the REAL merge's own per-file
+ *  disposition, computed report-only: `fastForward` lands as-is (main
+ *  untouched at the path), `skip` is already-equal on both sides,
+ *  `conflict` would 409 the merge today. `autoMerge` is the legacy plane's
+ *  clean-diff3 class — never emitted on the graph plane. */
+export interface SessionPreflightFileRow {
+  path: string;
+  kind: "add" | "modify" | "delete";
+  disposition: "fastForward" | "autoMerge" | "conflict" | "skip";
+  /** Set on `conflict` rows only. */
+  conflictReason: "same_region" | "binary" | "delete_vs_edit" | null;
+}
+
+/** `GET /conversations/:id/changes/preflight` — see conflicts AHEAD of the
+ *  merge: report-only, no writes, no locks. `unavailable` = no cheap head
+ *  anchors (legacy plane, unbranched) or the classification faulted — the
+ *  caller degrades honestly, never fake zeros. `pending` = a cold compute
+ *  outlived the first-response deadline; poll again to collect it. */
+export type SessionChangePreflight =
+  | { object: "session_change_preflight"; conversationId: string; state: "unavailable" }
+  | {
+      object: "session_change_preflight"; conversationId: string; state: "pending";
+      base: string; oursHead: string; theirsHead: string;
+    }
+  | {
+      object: "session_change_preflight"; conversationId: string; state: "ok";
+      branch: string;
+      base: string;
+      /** main's head — the exact commit the dispositions were computed against. */
+      oursHead: string;
+      /** the session branch's head. */
+      theirsHead: string;
+      files: SessionPreflightFileRow[];
+      conflictCount: number;
+      /** Page caps hit — dispositions cover a floor, honestly. */
+      truncated: boolean;
+    };
+
+/** Result of `POST /conversations/:id/changes/rebase` — current main
+ *  folded INTO the session branch (the reverse merge; main untouched).
+ *  `rebased` advanced the branch by one merge commit (`rebaseCommit`)
+ *  and future diffs/merges use the new base. `rebased_with_conflicts`
+ *  folded the clean remainder (`foldCommit`, null when nothing folded) and
+ *  KEPT the branch's version for `conflictPaths` — each is recorded as a
+ *  conflict row and the session was told in-conversation to reconcile. */
+export interface SessionRebaseReport {
+  object: "session_rebase_report";
+  conversationId: string;
+  branch: string;
+  outcome: "noop" | "rebased" | "rebased_with_conflicts";
+  /** main's head at rebase — the branch's new effective base on a clean
+   *  rebase. */
+  mainHead: string;
+  rebaseCommit?: string;
+  foldCommit?: string | null;
+  folded?: { added: number; modified: number; deleted: number; skipped: number };
+  baselineAdvanced?: boolean;
+  /** Capped at 100 on the wire; `conflictCount` is the true total. */
+  conflictPaths?: string[];
+  conflictCount?: number;
+  conflictsTruncated?: boolean;
+  /** True when the gateway truncated its conflict list — the fold was
+   *  skipped whole (an unlisted conflicted path must never be overwritten). */
+  foldSkipped?: boolean;
+}
+
+/** Result of `POST /conversations/:id/changes/autorebase` — the opt-in
+ *  main-advance auto-rebase reflex's new state. */
+export interface SessionAutoRebaseState {
+  object: "session_autorebase";
+  conversationId: string;
+  autoRebaseFromMain: boolean;
+}
+
 /** The sender's page stamp (HUD bar sends) — persisted server-side, never
  *  echoed back on the wire. Mirrors the server's `PageContext` schema. */
 export interface ConversationPageContext {
@@ -672,6 +919,63 @@ export interface SessionChannelMessagePosted {
   threadRootId?: string | null;
 }
 
+/** Result of `POST /session-messages` — one session's agent messaging
+ *  ANOTHER session's conversation (`agentc session message @alias`). Unlike
+ *  a channel post, this DOES wake the target's turn machinery: `turn` is
+ *  the server's verdict ('started' | 'queued' | 'parked' — the agent-to-
+ *  agent exchange damper landed the message without waking anyone). */
+export interface SessionDirectMessageSent {
+  object: "session_message";
+  messageId: string;
+  target: { conversationId: string; alias: string | null; title: string | null };
+  turn: "started" | "queued" | "parked";
+  /** Honest posture line — delivery is not completion. */
+  note: string;
+}
+
+/** One branch claim, as the claim/release routes serialize it. */
+export interface BranchClaimInfo {
+  id: string;
+  branch: string;
+  targetConversationId: string;
+  holderConversationId: string;
+  targetLabel: string;
+  holderLabel: string;
+  reason: string | null;
+  claimedAt: string;
+}
+
+/** Result of `POST /session-branch-claims` — write authority over the
+ *  target session's drive branch transferred to the calling session, plus
+ *  the mount material the CLI uses to FUSE-mount the branch in-guest. */
+export interface BranchClaimGranted {
+  object: "branch_claim";
+  claim: BranchClaimInfo;
+  /** True = the caller already held this claim (re-mint / re-mount path). */
+  reclaimedOwn: boolean;
+  branch: string;
+  token: string;
+  gatewayWsUrl: string;
+  expiresAtS: number;
+  diskId: string;
+}
+
+/** Result of `POST /session-branch-claims/release` (and the human reclaim
+ *  door) — the claims this call closed. */
+export interface BranchClaimsReleased {
+  object: "branch_claim.release";
+  released: BranchClaimInfo[];
+}
+
+/** `GET /conversations/:id/branch-claim` — one session's claim state: the
+ *  live claim ON its branch (null = writable there), and the claims it
+ *  HOLDS on other sessions' branches. */
+export interface BranchClaimState {
+  object: "branch_claim.state";
+  claimedBy: BranchClaimInfo | null;
+  holds: BranchClaimInfo[];
+}
+
 /** One agent on the team, as listed by `GET /api/v1/agents`. Bridge-runtime
  *  rows additionally carry live presence (`online`, from the daemon's
  *  heartbeat within the server's TTL) and the hosting machine's label. */

package/src/types/api-factory.ts

@@ -192,6 +192,48 @@ export interface FactoryFileSearchResult {
   folders_truncated?: boolean;
 }
 
+// ── Factory-file listing (`GET /files` — live index or browse-at-head) ─────
+
+/** One file row of `GET /factories/:slug/files` — the flat recursive
+ *  listing. Same row shape live and at a pinned head; rows arrive
+ *  camelCase on the wire (mirrors `FactoryFileSearchRow`). */
+export interface FactoryFileListRow {
+  id: string;
+  path: string;
+  sizeBytes: number;
+  contentType: string | null;
+  contentHash: string;
+  deletedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface ListFactoryFilesOptions {
+  factorySlug?: string;
+  /** Only paths under this prefix. */
+  prefix?: string;
+  /** Path cursor from a prior page's `nextCursor`. */
+  cursor?: string;
+  limit?: number;
+  /** List AS OF a drive branch (e.g. a session's `session-<uuid>`). */
+  branch?: string;
+  /** Browse-at-head: a retained 64-hex commit of the MAIN drive (or, with
+   *  `branch`, a pin of that graph branch). The server answers 410
+   *  `at_unavailable` for a garbage-collected/unknown head. */
+  at?: string;
+}
+
+/** One page of `GET /factories/:slug/files`. */
+export interface FactoryFileListPage {
+  data: FactoryFileListRow[];
+  hasMore: boolean;
+  /** Pass as `cursor` to fetch the next page; null on the last page. */
+  nextCursor: string | null;
+  /** The pinned head this page was read at — non-null exactly when the
+   *  request carried `at`. `committedAt` is RFC3339 or null (unknown). */
+  at: { head: string; committedAt: string | null } | null;
+}
+
 export interface FactoryFileWriteResult {
   path: string;
   contentHash: string;
@@ -237,6 +279,28 @@ export interface FactoryRow {
   updatedAt:   string;
 }
 
+/** GET /factories/:slug/perf-summary — team-level sandbox perf aggregates
+ *  over a window (session_perf_rollups). Aggregate-only by design: sessions
+ *  are member-gated, so no conversation ids appear here; per-session detail
+ *  is the member-gated perf-history surface. */
+export interface FactoryPerfSummary {
+  /** The aggregated window, ISO 8601. */
+  from: string;
+  to: string;
+  /** Distinct sessions with any rollup bucket in the window. */
+  sessions: number;
+  /** Rollup buckets (15-min) in the window. */
+  buckets: number;
+  /** Guest samples folded into those buckets. */
+  samples: number;
+  cpu_busy_p95_max: number | null;
+  mem_used_p95_max: number | null;
+  disk_used_p95_max: number | null;
+  load1_max: number | null;
+  /** Total seconds any session sat ≥90% on a resource, summed. */
+  saturated_seconds: number;
+}
+
 export interface CreateFactoryInput {
   slug: string;
   name: string;
@@ -285,6 +349,48 @@ export interface SecretListEntry {
   updatedAt: string;
 }
 
+/** One SESSION secret on the wire (metadata only — values are write-only).
+ *  `kind` 'value' = a session-own secret; 'factory' = an attachment by name
+ *  to the session factory's secret tier. `ownerUserId` is the user who set
+ *  it — only the owner or a team admin may replace/remove it. */
+export interface SessionSecretEntry {
+  secretKey: string;
+  kind: "value" | "factory";
+  ownerUserId: string;
+  /** Delivery mode (vault v2): 'injected' = the session env file;
+   *  'brokered' = an egress-ruleset header — the value never enters the
+   *  sandbox (call the host WITHOUT auth headers; the platform adds them). */
+  delivery: "injected" | "brokered";
+  /** Brokered entries: the API host the header rides on. */
+  brokerHost: string | null;
+  /** Non-null = an ephemeral use-and-scrub copy, and when its TTL lapses. */
+  ephemeralExpiresAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** One entry of a session-secret set: a literal value, or a factory
+ *  attachment by name (`source: "factory"`). */
+export type SessionSecretInput =
+  | { key: string; value: string }
+  | { key: string; source: "factory" };
+
+/** A freshly minted vault link (session secret request). `url` is the
+ *  single-use page a session writer opens to provide the named values. */
+export interface SessionSecretRequestCreated {
+  requestId: string;
+  url: string;
+  expiresAt: string;
+}
+
+/** A vault link's polled status. */
+export interface SessionSecretRequestStatus {
+  requestId: string;
+  status: "pending" | "fulfilled" | "cancelled" | "expired";
+  keys: string[];
+  expiresAt: string;
+}
+
 export interface CreateApiKeyInput {
   name?:        string;
   scopes?:      string[];
@@ -355,9 +461,9 @@ export interface UsageResponse {
 
 /** One drive-directory ⇄ GitHub-repo link (`/factories/:slug/repo-links`).
  *  Multi-branch model: ONE link row per (repo, branch); sibling branches
- *  of a repo occupy sibling `base@<branch>` placements. The webhook secret
- *  ref is operator plumbing and never on the wire — `webhookConfigured` /
- *  `webhookVerifiedAt` carry the honest connect status instead. */
+ *  of a repo occupy sibling `base@<branch>` placements. Event delivery is
+ *  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 {
   id:            string;
   factoryId:     string;
@@ -372,11 +478,13 @@ export interface DriveRepoLink {
   connectorGrantId: string | null;
   /** v1 links are always 'write' (the round trip is the feature). */
   access:        "read" | "write";
-  /** A webhook secret exists for this link (registration done). NOT proof
-   *  of delivery — that is `webhookVerifiedAt`. */
-  webhookConfigured: boolean;
-  /** When a signed GitHub delivery last PROVED the webhook delivers; null
-   *  = unproven (the link syncs by poll). */
+  /** HOW events reach this link. "app": the platform GitHub App's own
+   *  registered webhook delivers every installed repo's events (zero
+   *  per-repo setup). "polling": no app webhook configured — the sweep
+   *  alone. */
+  eventDelivery: "app" | "polling";
+  /** When an app-signed GitHub delivery last PROVED event delivery
+   *  reaches this link; null = unproven. */
   webhookVerifiedAt: string | null;
   /** Two-way sync: drive edits under the prefix push back to the tracked
    *  branch. ON by default for new links. */
@@ -400,8 +508,8 @@ export interface DriveRepoLink {
 
 /** Input for `POST /factories/:slug/repo-links`. Requires the drive to be
  *  graph-authoritative (ADR-0058 Phase 4 promoted) — 409 otherwise.
- *  Exactly ONE of `followAllBranches` / `trackedBranches`:
- *  `followAllBranches: true` (the default connect mode) links EVERY
+ *  At most one of `followAllBranches` / `trackedBranches`; omitting BOTH
+ *  is the follow-all default. Follow-all links EVERY
  *  branch — default branch primary at the plain `dirPrefix` — and keeps
  *  following live (new branches auto-link on push, deleted branches
  *  auto-unlink; capped at 100 branches). Explicit `trackedBranches`:

package/src/types/api-runs.ts

@@ -281,6 +281,29 @@ export interface RunFundingResponse {
   };
 }
 
+/** One step's attested platform token totals — `GET
+ *  /workflows/:id/step-usage`. Derived server-side from the spend ledger
+ *  by step time window (steps run serially, so every gateway call falls in
+ *  exactly one). Steps with no ledger rows are absent from the list. */
+export interface RunStepUsage {
+  stepIndex: number;
+  costUsd: number;
+  promptTokens: number;
+  completionTokens: number;
+  cacheReadTokens: number;
+  cacheCreationTokens: number;
+  calls: number;
+}
+
+/** `GET /workflows/:id/step-usage`. Empty `steps` is an honest answer: a
+ *  legacy run with no ledger rows, or a run funded outside the platform
+ *  lane (that money is never metered — ADR-0048). */
+export interface RunStepUsageResponse {
+  object: "run.step_usage";
+  runId: string;
+  steps: RunStepUsage[];
+}
+
 /** One row from the factory runs list (`GET /factories/:slug/runs`) — the
  *  summary shape, a strict subset of what the route returns. */
 export interface RunListEntry {

package/src/types/protocol.ts

@@ -119,6 +119,34 @@ export interface AgentMessagePlan extends AgentMessageBase {
   }[];
 }
 
+/** A harness `<task-notification>` announcing a BACKGROUND task stopped —
+ *  an async Agent spawn finishing, a background command exiting, a workflow
+ *  completing. claude-code injects these as user-role text blocks; the
+ *  normaliser parses them into structure so downstream can complete the
+ *  spawning call's card (status, final report, usage) instead of dropping
+ *  the only completion evidence a background subagent ever emits. Internal
+ *  plumbing in the raw block (output-file paths, resume hints) is
+ *  deliberately NOT forwarded — renderers must never see it. Additive
+ *  kind: existing producers never emit it. */
+export interface AgentMessageTaskNotification extends AgentMessageBase {
+  type: "task_notification";
+  /** The harness's background task id (`<task-id>`). */
+  taskId: string;
+  /** The SPAWNING tool_use id (`<tool-use-id>`) when the notification names
+   *  one — the correlation key back to the Agent/Task call. */
+  toolUseId?: string;
+  /** Terminal status word — "completed" | "failed" | "stopped" | "killed"
+   *  (verbatim from the harness; "finished" when the block carried none). */
+  status: string;
+  /** One-line what-happened ("Agent \"…\" finished"), collapsed + clamped. */
+  summary: string;
+  /** The task's final report (`<result>`), entity-unescaped and clamped.
+   *  Absent when the notification carried none. */
+  report?: string;
+  /** The completion's usage block, when carried. */
+  usage?: { tokens?: number; toolUses?: number; durationMs?: number };
+}
+
 export type AgentMessage =
   | AgentMessageInit
   | AgentMessageText
@@ -130,7 +158,8 @@ export type AgentMessage =
   | AgentMessageError
   | AgentMessageUsage
   | AgentMessageUsageDelta
-  | AgentMessagePlan;
+  | AgentMessagePlan
+  | AgentMessageTaskNotification;
 
 /** Status block the agent emits to signal iteration completion or blockers. */
 export interface AgentStatus {