@agent-compose/sdk 0.8.2 → 0.8.3

package/dist/runtimes/session-env.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Session env sourcing (session secrets) — the turn-launch half of the
+ * contract. The server writes `$HOME/.agent-compose/session-env.sh` at
+ * sandbox acquire; the detached JSONL launch sources it fresh EVERY turn
+ * via `sessionEnvSourceFragment`. Pinned here:
+ *
+ *   - the fragment sources exactly the configured $HOME-relative path,
+ *     silently, and never fails the turn when the file is absent;
+ *   - hostile/malformed paths (quotes, spaces, `..`, absolute) are DROPPED
+ *     — a bad option must not break the launch or escape $HOME;
+ *   - no option ⇒ empty fragment (local/BYOM runs never read a user's
+ *     dotfiles by surprise).
+ */
+export {};

package/dist/types/api-conversations.d.ts

@@ -92,10 +92,35 @@ export interface ConversationRow {
      *  callers; key callers see 0. */
     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 +140,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. */
@@ -131,13 +162,49 @@ 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;
+        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;
+}
 export interface ConversationDetail {
     conversation: ConversationRow;
     /** Resident executor substrate (ADR-0037 §8): `"local"` = a developer's
@@ -170,6 +237,10 @@ export interface ConversationDetail {
         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.
@@ -190,6 +261,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[];
 }
 /** Input for `createCloudSession` (ADR-0037 Phase 3b / ADR-0055 §9). The
@@ -387,6 +463,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'
@@ -416,6 +499,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
@@ -428,6 +527,33 @@ 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
  *  wrote back beside its notes (`SessionChangeSet.reviewSuggestions`). */
@@ -447,6 +573,45 @@ 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` —
  *  the post-call truth for that suggestion (an accept that found drift
@@ -456,6 +621,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
  *  suggestion's post-call status (only `"proposed"` rows flip). */
@@ -465,6 +633,7 @@ export interface ReviewSuggestionDecisions {
     results: Array<{
         id: string;
         status: ReviewSuggestion["status"];
+        reviewerConversationId?: string | null;
     }>;
 }
 /** `GET /conversations/:id/changes/stats` — the changes chip's aggregate
@@ -556,6 +725,89 @@ export interface SessionDiscardReport {
     newBranch: string;
     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 {
@@ -661,6 +913,62 @@ export interface SessionChannelMessagePosted {
      *  null for a room post. Absent on older servers. */
     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/dist/types/api-factory.d.ts

@@ -180,6 +180,46 @@ export interface FactoryFileSearchResult {
     /** True when more directories matched than the server's folder bound. */
     folders_truncated?: boolean;
 }
+/** 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;
@@ -216,6 +256,27 @@ export interface FactoryRow {
     createdAt: string;
     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;
@@ -257,6 +318,48 @@ export interface SecretListEntry {
     createdAt: string;
     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[];
@@ -320,9 +423,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;
@@ -337,11 +440,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. */
@@ -368,8 +473,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/dist/types/api-runs.d.ts

@@ -262,6 +262,27 @@ export interface RunFundingResponse {
         truncated: boolean;
     };
 }
+/** 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/dist/types/protocol.d.ts

@@ -113,7 +113,38 @@ export interface AgentMessagePlan extends AgentMessageBase {
         status: "pending" | "in_progress" | "completed";
     }[];
 }
-export type AgentMessage = AgentMessageInit | AgentMessageText | AgentMessageTextDelta | AgentMessageThinking | AgentMessageToolUse | AgentMessageToolResult | AgentMessageDone | AgentMessageError | AgentMessageUsage | AgentMessageUsageDelta | AgentMessagePlan;
+/** 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 | AgentMessageTextDelta | AgentMessageThinking | AgentMessageToolUse | AgentMessageToolResult | AgentMessageDone | AgentMessageError | AgentMessageUsage | AgentMessageUsageDelta | AgentMessagePlan | AgentMessageTaskNotification;
 /** Status block the agent emits to signal iteration completion or blockers. */
 export interface AgentStatus {
     summary: string;