@agent-compose/sdk 0.7.0 → 0.8.0

package/src/client.ts

@@ -12,13 +12,108 @@
  */
 
 import { ofetch } from "ofetch";
-import { AgentComposeError } from "./errors.js";
+import { AgentComposeError, parseRetryAfterMs } from "./errors.js";
 import { parseSseStream } from "./sse.js";
-import type { SandboxNetworkPolicy, SandboxSize } from "./sandbox.js";
 import type { RunEvent } from "./types/events.js";
-import type { WorkflowPlan } from "./types/workflow-plan.js";
-import type { SnapshotConfig, IOSchema, ConnectorRequirements, ConnectorOperationTag, InvokePolicy, SandboxResources } from "./types/workflow-metadata.js";
-import type { WorkflowManifest } from "./utils/bundler.js";
+import type { ConversationStreamEvent } from "./types/conversation-stream.js";
+import { normalizeConversationStreamEvent } from "./types/conversation-stream.js";
+import type {
+  InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult, StreamRunLogsOptions,
+  RunStatus, ResumePauseOptions, ResumePauseResponse, AnswerSteerOptions,
+  RequestAgentPauseOptions, RequestAgentPauseResponse,
+  SendAgentMessageOptions, SendAgentMessageResponse,
+  RunDetail, RunListEntry, ListRunsOptions, TimelineEvent, RunFundingResponse, EventRow, ReportEventInput,
+  ListEventsOptions, ListEventsResult, RunArtifactRow, RunLogLine, ListRunLogsOptions,
+  CancelRunResponse, ListSnapshotsOptions, SnapshotListResponse, SnapshotListEntry, RunSnapshotEntry,
+} from "./types/api-runs.js";
+import type {
+  TeamMember, Mention, CreateMentionsInput,
+  ConversationsPage, SessionsPage, ConversationDetail, ConversationThread,
+  CreateCloudSessionInput, CloudSessionCreated,
+  SessionPreview, PreviewOpened, OpenPreviewInput, SessionForked,
+  SessionChangeSet, SessionMergeReport, SessionDiscardReport,
+  SendConversationMessageInput, SendConversationMessageResult,
+  ChannelSessionRow, ChannelSessionsResponse, SessionChannelMessagePosted,
+  ConversationPresenceSnapshot, StreamConversationOptions, AgentListRow,
+} from "./types/api-conversations.js";
+import type {
+  ConversationMemberRole, ConversationMember, ArtifactScope,
+  SetScopeGrantsInput, SetTemplateScopeInput,
+} from "./types/api-scopes.js";
+import type {
+  Project, ProjectsPage, ProjectRole, ProjectMember,
+  ProjectObjectsPage, ProjectAddPreview,
+  AddProjectObjectInput, AddProjectObjectResult, RefreshProjectObjectResult,
+} from "./types/api-projects.js";
+import type {
+  RegisterResult, RegisterWorkflowInput, TemplateRow, TemplateDetail, ListTemplatesOptions,
+  SearchFactoryFilesOptions, FactoryFileSearchResult, FactoryFileWriteResult,
+  FactoryRow, CreateFactoryInput, UpdateFactoryInput,
+  ScheduleRow, CreateScheduleInput,
+  SecretOptions, SetSecretResult, SecretListEntry,
+  CreateApiKeyInput, ApiKey, ApiKeyCreated, UsageResponse,
+  DriveRepoLink, CreateDriveRepoLinkInput,
+} from "./types/api-factory.js";
+import type {
+  ComplianceSession, RequestComplianceSessionInput, ListComplianceSessionsOptions,
+  ComplianceSessionsPage, ListComplianceAccessesOptions, ComplianceAccessesPage,
+} from "./types/api-compliance.js";
+
+// The client's request/response wire types live in
+// `./types/api-{runs,conversations,scopes,factory}.ts`. They are re-exported
+// here so `client.js` stays the single import surface for the client and its
+// shapes (index.ts re-exports from here).
+export type {
+  RunState, InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult, StreamRunLogsOptions,
+  RunStatus, ResumePauseActor, ResumePauseSuccess, ResumePausePending, ResumePauseResponse,
+  ResumePauseOptions, RequestAgentPauseOptions, AnswerSteerOptions, RequestAgentPauseResponse,
+  SendAgentMessageOptions, SendAgentMessageResponse,
+  RunDetail, RunListEntry, ListRunsOptions, TimelineEvent,
+  FundingLane, RunFundingStamp, RunFundingUsageRow, RunFundingResponse,
+  EventSubjectType, EventRow, RunArtifactRow, ReportEventInput, ListEventsOptions, ListEventsResult,
+  RunLogLine, ListRunLogsOptions, CancelRunResponse,
+  ListSnapshotsOptions, SnapshotListEntry, SnapshotListResponse, RunSnapshotEntry,
+} from "./types/api-runs.js";
+export type {
+  TeamMember, Mention, CreateMentionsInput,
+  ConversationMessagePart, ConversationRow, ConversationMessageRow,
+  ConversationsPage, SessionsPage, ConversationDetail,
+  CreateCloudSessionInput, CloudSessionCreated, ConversationThread,
+  SessionPreview, PreviewOpened, OpenPreviewInput, SessionForked,
+  SessionFileChange, SessionChangeSet,
+  SessionMergeReportDetail, SessionMergeReport, SessionDiscardReport,
+  ConversationPageContext, SendConversationMessageInput, ConversationTurnState,
+  SendConversationMessageResult, ConversationPresenceSnapshot, AgentListRow, StreamConversationOptions,
+  ChannelSessionStatus, ChannelSessionRow, ChannelSessionsResponse, SessionChannelMessagePosted,
+} from "./types/api-conversations.js";
+export type {
+  ConversationMemberRole, ConversationMember,
+  DocumentCapability, TemplateCapability, ScopeGrant, ArtifactScope,
+  RunContext, SetScopeGrantsInput, SetTemplateScopeInput,
+} from "./types/api-scopes.js";
+export type {
+  Project, ProjectsPage, ProjectRole, ProjectMember,
+  ProjectObject, ProjectObjectsPage, ProjectSkippedFile, ProjectPreviewFile,
+  ProjectAddPreview, AddProjectObjectInput, AddProjectObjectResult,
+  RefreshProjectObjectResult,
+} from "./types/api-projects.js";
+export type {
+  RegisterResult, RegisteredRuntime, RuntimeSourceInput, TemplateSourceRef, RegisterWorkflowInput,
+  TemplateRow, TemplateDetail, ListTemplatesOptions,
+  FactoryFileSearchRow, FactoryFolderSearchRow, SearchFactoryFilesOptions, FactoryFileSearchResult, FactoryFileWriteResult,
+  PublicFileLinkState,
+  FactoryRow, CreateFactoryInput, UpdateFactoryInput,
+  ScheduleRow, CreateScheduleInput,
+  SecretOptions, SetSecretResult, SecretListEntry,
+  CreateApiKeyInput, ApiKey, ApiKeyCreated,
+  UsageRollupRow, UsageResponse,
+  DriveRepoLink, CreateDriveRepoLinkInput,
+} from "./types/api-factory.js";
+export type {
+  ComplianceScopeKind, ComplianceStatus, ComplianceSession, ComplianceAccess,
+  RequestComplianceSessionInput, ListComplianceSessionsOptions, ComplianceSessionsPage,
+  ListComplianceAccessesOptions, ComplianceAccessesPage,
+} from "./types/api-compliance.js";
 
 /** UUID-v4-ish — matches the server-side predicate. Used to auto-detect
  *  that `process.env.RUN_ID` was injected by the runner sandbox (rather
@@ -47,436 +142,9 @@ function templatePath(factorySlug: string, ...rest: string[]): string {
   return `/api/v1/factories/${encodeURIComponent(factorySlug)}/templates${tail}`;
 }
 
-export interface RegisterResult {
-  id: string;
-  name: string;
-  version: string;
-  runtimes?: RegisteredRuntime[];
-}
-
-export interface RegisteredRuntime {
-  id: string;
-  name: string;
-  version: string;
-}
-
-export interface RuntimeSourceInput {
-  name: string;
-  source: string;
-}
-
-/** GitHub provenance for a registered template's source file — stored as
- *  `metadata.source` on the registration. `cloud-build` stamps the built
- *  commit's sha; the dashboard's manual link path writes `sha: "manual"`. */
-export interface TemplateSourceRef {
-  owner:  string;
-  repo:   string;
-  branch: string;
-  /** Repo-relative file path, e.g. `.agentc/workflows/workflow-deploy.ts`. */
-  path:   string;
-  /** Commit sha the version was built from, or `"manual"` for hand-links. */
-  sha:    string;
-}
-
-export interface RegisterWorkflowInput {
-  name: string;
-  source: string;
-  /** Structured attestation produced by `bundleWorkflow`. The server
-   *  requires this on every registration; it proves the source was
-   *  bundled by a `defineWorkflow`-aware toolchain. The server validates
-   *  the manifest's shape and verifies `manifest.sourceHash` matches
-   *  sha256(source) — the source bytes themselves are never parsed or
-   *  executed on the server. */
-  manifest: WorkflowManifest;
-  version?: string;
-  /** Where the source file lives on GitHub — stored as `metadata.source`.
-   *  Named `sourceRef` because `source` is the bundled code itself. */
-  sourceRef?: TemplateSourceRef;
-  schedule?: string;
-  runtimes?: RuntimeSourceInput[];
-  /** Human-readable description declared via
-   *  `defineWorkflow({ description })`. Stored in template metadata and
-   *  surfaced on the dashboard template card. */
-  description?: string;
-  networkPolicy?: unknown;
-  placeholders?: Record<string, string>;
-  /** All snapshot config — `bootFrom` (where to restore at run start),
-   *  `save`, `retain`. See `WorkflowMetadata.snapshots`. */
-  snapshots?: SnapshotConfig;
-  /** Sandbox machine resources — size + provider (template defaults).
-   *  See `WorkflowMetadata.resources`. */
-  resources?: SandboxResources;
-  /** Provider-neutral execution plan detected by the CLI bundler. */
-  workflowPlan?: WorkflowPlan;
-  /** Connector requirements declared via `defineWorkflow({ connectors })`
-   *  (ADR-0007). Validated against the server's provider registry at
-   *  registration; tokens are injected at the network layer at dispatch. */
-  connectors?: ConnectorRequirements;
-  /** Connector-catalogue operation tag — see `ConnectorOperationTag`. */
-  connectorOperation?: ConnectorOperationTag;
-  /** Tier-1 invoke ACL declared via `defineWorkflow({ invokePolicy })`.
-   *  Only meaningful when the workflow also declares `connectors` — the
-   *  server gates dispatch on it before binding any grant. */
-  invokePolicy?: InvokePolicy;
-  /** Input schema extracted from the workflow's `input` zod schema. */
-  inputSchema?: IOSchema;
-  /** Output schema extracted from the workflow's `output` zod schema. */
-  outputSchema?: IOSchema;
-  /** Set by `defineSandboxEnvironment` — marks an environment build so the
-   *  server skips the /factory mount for its runs (#13). See
-   *  `WorkflowMetadata.environmentBuild`. */
-  environmentBuild?: boolean;
-  /** Factory slug. Defaults to `"default"`. */
-  factorySlug?: string;
-}
-
-export type RunState = "running" | "success" | "failed" | "abandoned" | "canceled";
-
-export interface InvokeWorkflowOptions {
-  /** Per-invocation snapshot config override. `snapshots.bootFrom`
-   *  replaces the template's boot source; `snapshots.saveLatest` and
-   *  `snapshots.retainSteps` override capture mode. Anything omitted
-   *  falls back to the template's registered default. */
-  snapshots?: SnapshotConfig;
-  /** Per-invocation network policy override. Replaces the template-level
-   *  policy for this run only — registered metadata is not mutated. */
-  networkPolicy?: SandboxNetworkPolicy;
-  /** Per-invocation placeholder override. Maps secret names referenced in
-   *  `networkPolicy` ($VAR) to the values the runner should see for env
-   *  vars after brokering. Replaces the template-level placeholders for
-   *  this run only — registered metadata is not mutated. */
-  placeholders?: Record<string, string>;
-  /** Per-invocation machine-size override of the template's `resources.size`.
-   *  `small` (default) | `medium` | `large`; omit → the template default,
-   *  else `small`. Honoured on Vercel (→ vCPUs); E2B ignores it. */
-  size?: SandboxSize;
-  /** Explicit parent run id. Pass `null` to suppress ambient RUN_ID auto-detection. */
-  parentRunId?:  string | null;
-  /** Agent loop inside the parent run that caused this invoke, when applicable. */
-  agentId?:      string | null;
-  /** Factory slug. Defaults to `"default"`. */
-  factorySlug?:  string;
-  /** Idempotency key — sent as the `Idempotency-Key` header. A repeat invoke
-   *  with the same key inside the server's dedup window returns the original
-   *  run instead of starting a new one (matches `resumePause`'s pattern). */
-  idempotencyKey?: string;
-}
-
-export interface InvokeAndWaitOptions extends InvokeWorkflowOptions {
-  timeoutMs?:      number;
-  pollIntervalMs?: number;
-}
-
-export interface InvokeResult {
-  id: string;
-}
-
-export interface ListSnapshotsOptions {
-  /** Factory slug. Defaults to `"default"`. */
-  factorySlug?: string;
-  workflow?: string;
-  limit?: number;
-  /** Cursor returned as `next_cursor` from `listSnapshotsPage`. */
-  before?: string;
-}
-
-export interface TemplateRow {
-  name: string;
-  version: string;
-  factorySlug: string;
-}
-
-export interface ListTemplatesOptions {
-  factorySlug?: string;
-}
-
-/** A human member of your team — the people an agent (or you) can @-flag. */
-export interface TeamMember {
-  /** Membership row id. */
-  id: string;
-  /** The user id — what you pass to `createMentions({ mentionedUserIds })`. */
-  userId: string;
-  role: string;
-  email: string;
-  name: string;
-  joinedAt: string;
-}
-
-/** A "you were flagged" ping, persisted server-side so it reaches the
- *  mentioned teammate in their Workbench. */
-export interface Mention {
-  id: string;
-  factoryId: string;
-  mentionedUserId: string;
-  /** Who flagged: 'user' | 'api_key' | 'run' | 'system'. */
-  actorKind: string;
-  actorId: string | null;
-  actorLabel: string | null;
-  /** Where it lives: 'doc' | 'comment' | 'plan' | 'run'. */
-  contextKind: string;
-  contextPath: string | null;
-  /** Ready-made relative dashboard URL the Workbench card links to. */
-  contextUrl: string | null;
-  text: string;
-  runId: string | null;
-  seenAt: string | null;
-  resolvedAt: string | null;
-  createdAt: string;
-}
-
-export interface CreateMentionsInput {
-  /** Team-member user ids to flag (1–20). Discover them via `listMembers()`.
-   *  Non-members are dropped server-side. */
-  mentionedUserIds: string[];
-  /** The flag message shown in the teammate's Workbench. */
-  text: string;
-  contextKind: "doc" | "comment" | "plan" | "run";
-  /** Factory-relative file path or comment thread id, when applicable. */
-  contextPath?: string;
-  /** Ready-made relative dashboard URL the Workbench card links to (e.g.
-   *  `/factories/<slug>/files/view?path=<plan>`). */
-  contextUrl?: string;
-  runId?: string;
-  factorySlug?: string;
-}
-
-export interface CreateFactoryInput {
-  slug: string;
-  name: string;
-  description?: string;
-}
-
-export interface UpdateFactoryInput {
-  name?: string;
-  description?: string;
-}
-
-export interface ScheduleRow {
-  id:           string;
-  name:         string;
-  workflowName: string;
-  cron:         string;
-  createdAt:    string;
-  updatedAt:    string;
-  nextFireAt:   string | null;
-  lastFireAt:   string | null;
-}
-
-export interface CreateScheduleInput {
-  /** Human-friendly schedule name. Unique within the factory. */
-  name:         string;
-  /** The workflow this schedule should fire. Must already be registered
-   *  in the same factory. */
-  workflow:     string;
-  /** Cron expression (UTC). */
-  cron:         string;
-  /** Factory to attach the schedule to. Defaults to `"default"`. */
-  factorySlug?: string;
-}
-
-export interface SecretOptions {
-  factorySlug?: string;
-}
-
-export interface SetSecretResult {
-  key: string;
-}
-
-export interface SecretListEntry {
-  key: string;
-  createdAt: string;
-  updatedAt: string;
-}
-
-export interface CreateApiKeyInput {
-  name?:        string;
-  scopes?:      string[];
-  expiresAt?:   string;
-  factorySlug?: string;
-}
-
-export interface StreamRunLogsOptions {
-  lastEventId?: number;
-  signal?: AbortSignal;
-}
-
-export interface RunStatus<TOutput = unknown> {
-  id: string;
-  status: RunState;
-  output?: TOutput;
-  /** The run's latest (`saveLatest`) snapshot id, populated once the run has
-   *  succeeded — the boot source to fork this run's evolved filesystem from
-   *  (pass as `snapshots.bootFrom` on a follow-up invoke). `null` while the run
-   *  is still in flight or when it captured no snapshot. Lets an orchestrator
-   *  fork a child straight off the `invokeChild` result without a separate
-   *  `listRunSnapshots` call. */
-  latestSnapshotId?: string | null;
-}
-
-/** ADR-0006 step 10 — actor record returned on a successful resume.
- *  Shape mirrors the server's `PauseResumeActor` type after the row
- *  has been stamped. Audit FKs (`userId` / `keyId` / `runId`) may be
- *  null when the referenced row was deleted between resume and the
- *  response render — the immutable `label` survives. */
-export interface ResumePauseActor {
-  kind:     "session_user" | "api_key" | "agent";
-  /** Better Auth user id when kind='session_user'. */
-  userId?:  string | null;
-  /** api_keys.id when kind='api_key'. */
-  keyId?:   string | null;
-  /** Caller-run id when kind='agent' (NOT the run being resumed). */
-  runId?:   string | null;
-  /** Agent-instance within `runId` when kind='agent'. */
-  agentId?: string | null;
-  label:    string;
-}
-
-/** Success branch of the resume HTTP response. The pause has reached
- *  a terminal state — `resolved` (workflow signal arrived), `expired`
- *  (TTL fired first), or `cancelled` (workflow terminated mid-pause).
- *  Only `resolved` carries the resume payload the user supplied. */
-export interface ResumePauseSuccess {
-  status:        "resolved" | "expired" | "cancelled";
-  pauseId:       string;
-  resolvedAt:    string | null;
-  resumePayload: unknown;
-  actor:         ResumePauseActor | null;
-}
-
-/** Pending branch — the workflow accepted the signal but the row
- *  flip didn't observe within the route's 5s wait window. The
- *  operation is in-flight; retry with the same `Idempotency-Key`
- *  and the cache collapses the duplicate to a single canonical
- *  response. */
-export interface ResumePausePending {
-  status:   "pending";
-  pauseId:  string;
-  timedOut: true;
-}
-
-export type ResumePauseResponse = ResumePauseSuccess | ResumePausePending;
-
-export interface ResumePauseOptions {
-  /** Stripe-style retry-dedup key — same syntax as the workflow-invoke
-   *  route: 1..255 chars of `[A-Za-z0-9_\-:.]`, no embedded CR/LF.
-   *  Sent as the `Idempotency-Key` request header. (The server reads the
-   *  header first, falling back to a body field for callers behind a
-   *  header-stripping proxy; this client only sends the header.) */
-  idempotencyKey?: string;
-  /** Abort the HTTP request mid-wait (e.g. from a UI cancel button).
-   *  The server's LISTEN tears down via the request's AbortSignal. */
-  signal?:         AbortSignal;
-}
-
-export interface RequestAgentPauseOptions {
-  /** Human-readable note surfaced to the agent as the pause reason. */
-  reason?:         string;
-  /** Your handle for answering this pause without the minted pauseId:
-   *  pass the same value to `resumePauseByKey`. */
-  correlationKey?: string;
-  /** Abort the HTTP request. */
-  signal?:         AbortSignal;
-}
-
-export interface AnswerSteerOptions extends ResumePauseOptions {
-  /** Who answered — surfaced to the agent as `[human steer from <actor>]`. */
-  actor?: string;
-}
-
-/** 202 envelope from a steer-pause request. The request is best-effort and
- *  fire-and-forget: it publishes a transient control message and returns
- *  immediately — the agent parks at its next iteration boundary (if it is
- *  `mode: "hitl"` and still running). Answer it via `answerSteerByKey`
- *  (pass the `correlationKey` you set here) or `answerSteer` (by pauseId). */
-export interface RequestAgentPauseResponse {
-  status:  "steer_requested";
-  runId:   string;
-  agentId: string;
-}
-
-export interface SendAgentMessageOptions {
-  /** Transcript attribution. For non-session callers (API key, orchestrator)
-   *  this names the sender; defaults to the caller's identity server-side. */
-  senderName?: string;
-  /** Abort the HTTP request. */
-  signal?:     AbortSignal;
-}
-
-/** 202 envelope from a message-to-running-agent request. The message is queued
- *  durably and delivered mid-stream as the agent's next user turn — the workflow
- *  is NOT paused. `seq` is the message's per-run ordinal. */
-export interface SendAgentMessageResponse {
-  status:  "message_enqueued";
-  runId:   string;
-  agentId: string;
-  seq:     number;
-}
-
-export interface RunDetail<TOutput = unknown> {
-  runId: string;
-  title: string;
-  metadata: Record<string, unknown>;
-  outcome: string;
-  startedAt: string;
-  endedAt: string | null;
-  durationMs: number | null;
-  failureReason: string | null;
-  input: unknown;
-  output: TOutput | null;
-  lifecycleEvents: Array<{ at: string; type: string; payload: unknown }>;
-  children?: RunDetail[];
-}
-
-export interface TimelineEvent {
-  kind: string;
-  at: string;
-  seq: number;
-  type: string;
-  payload: Record<string, unknown>;
-}
-
-export type EventSubjectType = "run" | "agent" | "workflow" | "factory";
-
-export interface EventRow {
-  id: string;
-  teamId: string;
-  subjectType: EventSubjectType | string;
-  subjectId: string;
-  runId: string | null;
-  agentId: string | null;
-  workflowId: string | null;
-  factoryId: string | null;
-  name: string;
-  body: unknown;
-  summary: string | null;
-  confidence: string | null;
-  timestamp: string;
-  attributes: Record<string, unknown>;
-  propagate: boolean;
-  idempotencyKey: string | null;
-  createdAt: string;
-}
-
-// The server emits these rows in snake_case; the client maps them to
-// camelCase at the fetch boundary so the SDK surface stays uniform
-// (`EventRow.createdAt`, `RunStatus.latestSnapshotId`, …).
-export interface RunArtifactRow {
-  path: string;
-  factorySlug: string | null;
-  sizeBytes: number | null;
-  lastWriteAt: string;
-  /** Opening text of the file (≤320 chars) — null for binary/empty. */
-  preview: string | null;
-}
-
-export interface FactoryFileWriteResult {
-  path: string;
-  contentHash: string;
-  sizeBytes: number;
-  created: boolean;
-}
-
-/** Wire shapes — what the server actually emits (snake_case). */
+/** Wire shapes — what the server actually emits (snake_case); the client
+ *  maps them to camelCase at the fetch boundary so the SDK surface stays
+ *  uniform (`RunArtifactRow.sizeBytes`, `FactoryFileWriteResult.contentHash`). */
 interface RunArtifactWire {
   path: string;
   factory_slug: string | null;
@@ -492,141 +160,6 @@ interface FactoryFileWriteWire {
   created: boolean;
 }
 
-export interface ReportEventInput {
-  name: string;
-  body: unknown;
-  summary?: string;
-  confidence?: number;
-  timestamp?: string | Date;
-  attributes?: Record<string, unknown>;
-  propagate?: boolean;
-  idempotencyKey?: string;
-}
-
-export interface ListEventsOptions {
-  factorySlug?: string;
-  limit?: number;
-  /** Case-insensitive substring match. Server uses `ILIKE %name%`, so
-   *  `"site"` matches `site.created`, `site.failed`, etc. Pass the
-   *  full event name for an effectively-exact filter (any string is a
-   *  substring of itself). */
-  name?: string;
-  /** Date-range lower bound: only include events at or after this
-   *  timestamp. Used by the dashboard's range toggle (1h / 24h / 7d
-   *  / 30d). Same semantics as `from` on the runs list endpoint. */
-  from?: string;
-  /** Timestamp cursor for "load older" pagination. Pass the
-   *  `timestamp` of the last row from the previous page; the server
-   *  returns rows strictly older than that. Distinct from `from`:
-   *  `from` filters a date range, `before` walks the page boundary.
-   *  Both can be supplied together for a paginated range-query. */
-  before?: string;
-}
-
-export interface ListEventsResult {
-  events:   EventRow[];
-  has_more: boolean;
-}
-
-/** One captured stdout or stderr line from a run's sandbox subprocess.
- *  `id` is per-run monotonically increasing — pass the highest `id`
- *  you've seen as `afterId` to paginate forward. */
-export interface RunLogLine {
-  id:     number;
-  at:     string;
-  stream: "stdout" | "stderr";
-  line:   string;
-}
-
-export interface ListRunLogsOptions {
-  /** Return only lines with `id > afterId` (forward pagination). */
-  afterId?: number;
-  /** Max lines (server clamps to [1, 1000], defaults to 200). */
-  limit?:   number;
-  /** Stream direction. `"asc"` (default) returns the oldest lines first
-   *  — use with `afterId` to paginate forward. `"desc"` returns the newest
-   *  lines first — use to fetch the last N lines of a finished run. */
-  direction?: "asc" | "desc";
-}
-
-/** Row shape returned by `GET /api-keys`. */
-export interface ApiKey {
-  object:           "api_key";
-  id:               string;
-  name:             string | null;
-  last4:            string | null;
-  scopes:           string[];
-  teamId:           string;
-  createdByUserId:  string | null;
-  /** Non-null when the key is restricted to a single factory. */
-  factoryId:        string | null;
-  createdAt:        string;
-  expiresAt:        string | null;
-  lastUsedAt:       string | null;
-  revokedAt:        string | null;
-}
-
-/** Response from `POST /api-keys`. The `key` field is the plaintext token —
- *  shown once at creation, never retrievable again. */
-export interface ApiKeyCreated extends ApiKey { key: string }
-
-/** Single rollup row from `GET /api/v1/usage`. */
-export interface UsageRollupRow {
-  eventType: string;
-  unit:      string;
-  total:     number;
-  tags:      Record<string, unknown>;
-}
-
-/** Response from `GET /api/v1/usage`. */
-export interface UsageResponse {
-  object:   "list";
-  data:     UsageRollupRow[];
-  has_more: boolean;
-  from:     string | null;
-  to:       string | null;
-}
-
-/** Response from `POST /api/v1/workflows/:id/cancel`. The endpoint is
- *  idempotent: cancelling a run that's already terminal returns its current
- *  outcome verbatim (rather than throwing or pretending it just canceled),
- *  so `status` widens to every terminal value the server might surface. */
-export interface CancelRunResponse {
-  runId:       string;
-  status:      "canceled" | "success" | "failed" | "abandoned";
-  canceledAt:  string;
-}
-
-export interface SnapshotListEntry {
-  snapshotId: string;
-  kind: "latest" | "step";
-  stepIndex: number | null;
-  runId: string;
-  workflow: string | null;
-  version: string | null;
-  createdAt: string | null;
-  /** Provider-reported on-disk size, or null when unavailable. */
-  sizeBytes: number | null;
-}
-
-export interface SnapshotListResponse {
-  object: "list";
-  data: SnapshotListEntry[];
-  has_more: boolean;
-  next_cursor: string | null;
-}
-
-export interface RunSnapshotEntry {
-  snapshotId: string;
-  /** `"latest"` = current/last pointer on the run.
-   *  `"step"` = retained per-step snapshot. */
-  kind: "latest" | "step";
-  stepIndex: number | null;
-  createdAt: string | null;
-  /** Provider-reported on-disk size, or null when unavailable. */
-  sizeBytes: number | null;
-}
-
 export interface AgentComposeClientOptions {
   /** Your team's API key — minted from the dashboard or `agentc keys create`.
    *  Required. Resolved from `process.env.AGENT_COMPOSE_API_KEY` when omitted. */
@@ -675,12 +208,50 @@ export class AgentComposeClient {
       baseURL: this.baseUrl,
       headers: { Authorization: `Bearer ${apiKey}` },
       async onResponseError({ response }) {
-        const body = response._data as { error?: string } | undefined;
-        throw new AgentComposeError(response.status, body?.error ?? response.statusText);
+        const body = response._data as { error?: string; code?: string; capability?: string } | undefined;
+        throw new AgentComposeError(response.status, body?.error ?? response.statusText, {
+          retryAfterMs: parseRetryAfterMs(response.headers.get("retry-after")),
+          ...(body?.code       ? { code:       body.code }       : {}),
+          ...(body?.capability ? { capability: body.capability } : {}),
+        });
       },
     });
   }
 
+  /** Open an authenticated SSE stream and yield its parsed frames. Uses raw
+   *  `fetch` (not ofetch) because SSE requires access to the response's
+   *  `ReadableStream`, which ofetch consumes when parsing. Auth + base URL
+   *  come from the same constructor inputs, and non-2xx responses throw the
+   *  same `AgentComposeError`. Shared by `streamRunLogs` / `streamConversation`
+   *  — per-event mapping stays at each call site. */
+  private async *openSseStream(
+    path: string,
+    opts?: { lastEventId?: number; signal?: AbortSignal },
+  ): AsyncGenerator<{ id: number; event: string; data: Record<string, unknown> }> {
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${this.apiKey}`,
+      Accept: "text/event-stream",
+    };
+    if (opts?.lastEventId && opts.lastEventId > 0) {
+      headers["Last-Event-ID"] = String(opts.lastEventId);
+    }
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      headers,
+      ...(opts?.signal ? { signal: opts.signal } : {}),
+    });
+    if (!res.ok || !res.body) {
+      let message = res.statusText;
+      try {
+        const body = await res.json() as { error?: string };
+        if (body.error) message = body.error;
+      } catch { /* non-JSON error body — fall back to statusText */ }
+      throw new AgentComposeError(res.status, message, {
+        retryAfterMs: parseRetryAfterMs(res.headers.get("retry-after")),
+      });
+    }
+    yield* parseSseStream(res.body);
+  }
+
   /** Register (or update) a workflow template inside a factory. Defaults to
    *  the team's `default` factory when `factorySlug` is omitted. */
   register(payload: RegisterWorkflowInput): Promise<RegisterResult> {
@@ -979,6 +550,23 @@ export class AgentComposeClient {
     return this.fetch(`/api/v1/workflows/${encodeURIComponent(runId)}`);
   }
 
+  /** Recent runs in one factory, newest first by default. Bounded at the
+   *  server (limit ≤ 200). `workflow` filters by the registered workflow
+   *  name (substring) — `listRuns({ workflow: "report", limit: 1 })` is
+   *  "the latest report run". */
+  async listRuns(opts: ListRunsOptions = {}): Promise<RunListEntry[]> {
+    const q = new URLSearchParams();
+    if (opts.workflow) q.set("workflow", opts.workflow);
+    if (opts.search)   q.set("search", opts.search);
+    if (opts.outcome)  q.set("outcome", opts.outcome);
+    if (opts.sort)     q.set("sort", opts.sort);
+    if (opts.limit !== undefined) q.set("limit", String(opts.limit));
+    const slug = encodeURIComponent(opts.factorySlug ?? "default");
+    const body = await this.fetch<{ workflows: RunListEntry[] }>(
+      `/api/v1/factories/${slug}/runs${q.toString() ? `?${q}` : ""}`);
+    return body.workflows;
+  }
+
   /** Ordered lifecycle timeline for one run. */
   async getRunTimeline(runId: string, opts?: { limit?: number; offset?: number }): Promise<TimelineEvent[]> {
     const q = new URLSearchParams();
@@ -990,6 +578,16 @@ export class AgentComposeClient {
     return body.events;
   }
 
+  /** One run's funding-lane surface (ADR-0048): per-step credential stamps
+   * recorded at resolution, plus the gateway-attested platform dollars —
+   * the only usage the ledger records (non-platform lanes are attribution,
+   * never metered). */
+  async getRunFunding(runId: string): Promise<RunFundingResponse> {
+    return this.fetch<RunFundingResponse>(
+      `/api/v1/workflows/${encodeURIComponent(runId)}/funding`,
+    );
+  }
+
   /** Report a durable event against a run. Events are late-binding facts
    * like quality.accepted, defect.regression, or intervention.override. */
   async reportEvent(runId: string, input: ReportEventInput): Promise<EventRow> {
@@ -1060,19 +658,415 @@ export class AgentComposeClient {
     };
   }
 
-  /** Read one file's current content (or a specific revision) as text. */
-  async getFactoryFile(
+  /** Read one file's current content (or a specific revision) as RAW BYTES —
+   *  byte-exact for any content type. This is the wire truth; `getFactoryFile`
+   *  is a UTF-8 decode over it. Binaries (images, archives) MUST come through
+   *  here: a text decode is lossy (every non-UTF-8 sequence collapses to
+   *  U+FFFD and the original bytes are unrecoverable). */
+  async getFactoryFileBytes(
     path: string,
     opts?: { factorySlug?: string; revision?: number },
-  ): Promise<string> {
+  ): Promise<Uint8Array> {
     const factorySlug = opts?.factorySlug
       ?? (typeof process !== "undefined" ? process.env?.AGENT_COMPOSE_FACTORY : undefined)
       ?? DEFAULT_FACTORY;
     const q = new URLSearchParams({ path });
     if (opts?.revision !== undefined) q.set("revision", String(opts.revision));
-    return this.fetch(
+    const buf = await this.fetch<ArrayBuffer, "arrayBuffer">(
       `/api/v1/factories/${encodeURIComponent(factorySlug)}/files/content?${q}`,
-      { responseType: "text" },
+      { responseType: "arrayBuffer" },
+    );
+    return new Uint8Array(buf);
+  }
+
+  /** Read one file's current content (or a specific revision) as text
+   *  (UTF-8). For binary files use `getFactoryFileBytes` — decoding them to
+   *  text corrupts the bytes irreversibly. */
+  async getFactoryFile(
+    path: string,
+    opts?: { factorySlug?: string; revision?: number },
+  ): Promise<string> {
+    return new TextDecoder().decode(await this.getFactoryFileBytes(path, opts));
+  }
+
+  // ── Conversations ──────────────────────────────────────────────────────────
+  // The chat surfaces (channels / solo chats / sessions) the caller can
+  // access. Key callers see what their sender scope allows; the server is the
+  // sole authority — these are thin typed wrappers.
+
+  /** List conversations the caller can access, newest-activity first.
+   *  Cursor-paginated: pass the previous page's `next_cursor`. */
+  listConversations(opts?: { cursor?: string }): Promise<ConversationsPage> {
+    const q = new URLSearchParams();
+    if (opts?.cursor) q.set("cursor", opts.cursor);
+    return this.fetch<ConversationsPage>(`/api/v1/conversations${q.toString() ? `?${q}` : ""}`);
+  }
+
+  /** List the sessions the caller can ACCESS in one factory (their own +
+   *  shared/project-reachable ones), newest first (kind='session' rows are
+   *  excluded from listConversations by design). Session or user-bound driver credential only. */
+  listSessions(factoryId: string, opts?: { cursor?: string }): Promise<SessionsPage> {
+    const q = new URLSearchParams({ factoryId });
+    if (opts?.cursor) q.set("cursor", opts.cursor);
+    return this.fetch<SessionsPage>(`/api/v1/sessions?${q}`);
+  }
+
+  /** One conversation with its latest page of messages. */
+  getConversation(id: string): Promise<ConversationDetail> {
+    return this.fetch<ConversationDetail>(`/api/v1/conversations/${encodeURIComponent(id)}`);
+  }
+
+  /** Provision a CLOUD-native session (ADR-0037 Phase 3b / ADR-0055 §9): a
+   *  persistent server-side sandbox on the factory drive that keeps working
+   *  after the caller's terminal (and laptop) closes. The session's TYPE is
+   *  fixed at creation: `chat` hosts a coding runtime driven via ACP (open →
+   *  the transcript, drive it like any conversation); `terminal`/`custom`
+   *  are raw machine surfaces with no chat pane (open → the PTY). Omitting
+   *  `type` lets the server derive it from `runtime` (the older-caller
+   *  grandfather); send it explicitly. Requires the `invoke` scope and a
+   *  user-bound credential. */
+  createCloudSession(input: CreateCloudSessionInput): Promise<CloudSessionCreated> {
+    return this.fetch<CloudSessionCreated>(`/api/v1/sessions/cloud`, {
+      method: "POST",
+      body: {
+        ...(input.type ? { type: input.type } : {}),
+        ...(input.runtime ? { runtime: input.runtime } : {}),
+        factoryId: input.factoryId,
+        ...(input.presetId ? { presetId: input.presetId } : {}),
+        ...(input.preStart ? { preStart: input.preStart } : {}),
+        ...(input.title ? { title: input.title } : {}),
+        ...(input.repoUrl ? { repoUrl: input.repoUrl } : {}),
+        ...(input.repoBranch ? { repoBranch: input.repoBranch } : {}),
+        ...(input.channelId ? { channelId: input.channelId } : {}),
+        ...(input.templateId ? { templateId: input.templateId } : {}),
+        ...(input.sandboxSize ? { sandboxSize: input.sandboxSize } : {}),
+        ...(input.networkPolicy !== undefined ? { networkPolicy: input.networkPolicy } : {}),
+        ...(input.connectorProfileId !== undefined ? { connectorProfileId: input.connectorProfileId } : {}),
+      },
+    });
+  }
+
+  /** One thread (root + replies, oldest→newest) inside a channel. */
+  getConversationThread(conversationId: string, rootId: string): Promise<ConversationThread> {
+    return this.fetch<ConversationThread>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/threads/${encodeURIComponent(rootId)}`,
+    );
+  }
+
+  // ── Channel-attached sessions (ADR-0057 — sessions VISIT channels) ────────
+  // A session is brought into a channel for as long as a piece of work
+  // lasts: attaching shares it with the channel's members (derived access,
+  // revoked on detach); the session posts back attributed as itself.
+
+  /** The sessions attached to a channel, newest attach first, each with its
+   *  durable rail status (channel read gate). 404 on non-channels. */
+  async listChannelSessions(channelId: string): Promise<ChannelSessionRow[]> {
+    const body = await this.fetch<ChannelSessionsResponse>(
+      `/api/v1/conversations/${encodeURIComponent(channelId)}/sessions`,
+    );
+    return body.sessions;
+  }
+
+  /** Attach an existing session to a channel — an explicit share act
+   *  (ADR-0052 consent): only the session's CREATOR may attach it, with
+   *  channel role ≥ write and a human credential. Idempotent (re-attach is
+   *  a no-op). Failures: 403 `human_credential_required` | `role_read_only`
+   *  | `owner_required`; 400 `not_a_session`; 409 `attach_limit_reached`. */
+  async attachChannelSession(channelId: string, sessionConversationId: string): Promise<void> {
+    await this.fetch(
+      `/api/v1/conversations/${encodeURIComponent(channelId)}/sessions`,
+      { method: "POST", body: { sessionConversationId } },
+    );
+  }
+
+  /** Detach a session from a channel — either side ends the visit (channel
+   *  role ≥ write, OR the session's creator). Forward-only: the channel's
+   *  members lose the derived access; relay rows already in the session
+   *  transcript stay; explicit shares survive. 404 when not attached. */
+  async detachChannelSession(channelId: string, sessionConversationId: string): Promise<void> {
+    await this.fetch(
+      `/api/v1/conversations/${encodeURIComponent(channelId)}/sessions/${encodeURIComponent(sessionConversationId)}`,
+      { method: "DELETE" },
+    );
+  }
+
+  /** Post one message into a channel AS the calling session (ADR-0057 Seam
+   *  4) — progress, results, questions, attributed to the session (title +
+   *  runtime mark). Session toolbelt credential ONLY (the calling session
+   *  resolves from the key server-side — 403 `session_credential_required`
+   *  otherwise); the session must be attached (409 `not_attached`). By
+   *  default the post lands in the thread of the message that last
+   *  addressed the session from that channel (the room when none);
+   *  `threadRootId` overrides it — must be a root message in the channel
+   *  (400 `invalid_thread_root`). The post never triggers any turn. */
+  postSessionChannelMessage(
+    channelId: string,
+    input: { text: string; threadRootId?: string },
+  ): Promise<SessionChannelMessagePosted> {
+    return this.fetch<SessionChannelMessagePosted>(
+      `/api/v1/conversations/${encodeURIComponent(channelId)}/session-messages`,
+      { method: "POST", body: { text: input.text, ...(input.threadRootId ? { threadRootId: input.threadRootId } : {}) } },
+    );
+  }
+
+  // ── Cloud-session developer surface (ADR-0052) ────────────────────────────
+
+  /** Open a dev preview on a cloud session: expose a port a dev server is
+   *  LISTENING on inside the session sandbox at a member-gated proxy URL, and
+   *  post an "Open preview" card to the transcript. Resumes a suspended VM
+   *  (write-tier act — read members get 403). Returns the row + the proxy URL
+   *  (never the raw sandbox host). */
+  openPreview(conversationId: string, input: OpenPreviewInput): Promise<PreviewOpened> {
+    return this.fetch<PreviewOpened>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/preview`,
+      {
+        method: "POST",
+        body: {
+          port: input.port,
+          ...(input.name ? { name: input.name } : {}),
+          ...(input.path ? { path: input.path } : {}),
+        },
+      },
+    );
+  }
+
+  /** The live dev previews on a cloud session (read-tier allowed). Rows carry
+   *  `url: null` — a URL is minted on OPEN (short-lived, member-bound). */
+  async listPreviews(conversationId: string): Promise<SessionPreview[]> {
+    const body = await this.fetch<{ previews: SessionPreview[] }>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/previews`,
+    );
+    return body.previews;
+  }
+
+  /** Take a dev preview down (write-tier). Idempotent — `closed` is false when
+   *  no active row matched. */
+  async closePreview(conversationId: string, port: number): Promise<boolean> {
+    const body = await this.fetch<{ closed: boolean }>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/preview/${port}`,
+      { method: "DELETE" },
+    );
+    return body.closed;
+  }
+
+  /** Fork a cloud session from HEAD: snapshot the VM + branch the drive + seed
+   *  a new conversation from the transcript so far, booting from both. Returns
+   *  the child conversation id to switch to. Write-tier; "Branch from here." */
+  forkSession(conversationId: string, input?: { title?: string }): Promise<SessionForked> {
+    return this.fetch<SessionForked>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/fork`,
+      { method: "POST", body: input?.title ? { title: input.title } : {} },
+    );
+  }
+
+  // ── Session branch proposals (ADR-0053) ───────────────────────────────────
+  // Every cloud session works on its own factory-drive branch; the whole
+  // branch is the unit of review, like a PR. Any member can VIEW the
+  // proposal; deciding it (merge/discard) requires role ≥ write and a human
+  // credential — the resident agent cannot self-approve.
+
+  /** The session's proposed change set: files changed on its drive branch
+   *  since it forked from `main` (read-tier — any conversation member).
+   *  `state: "unbranched"` means the session predates branching and still
+   *  writes `main` directly. The list reflects the branch's last flush and
+   *  is advisory; a merge re-verifies against fresh state. 404 = not found
+   *  or not a member (uniform). */
+  getSessionChanges(conversationId: string): Promise<SessionChangeSet> {
+    return this.fetch<SessionChangeSet>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/changes`,
+    );
+  }
+
+  /** Approve the session's proposed changes: 3-way merge its branch into
+   *  `main`, then continue the session on a fresh branch off post-merge
+   *  `main`. Write-tier + human caller. Pass `opts.branch` (the branch you
+   *  reviewed) to fail 409 `branch_changed` if it moved since.
+   *
+   *  Failures: 403 `role_read_only` (read-only member) or a plain 403 for
+   *  session toolbelt keys (agents cannot self-approve); 409 `turn_active`
+   *  (a turn is running — retry when idle) | `branch_changed`; 400
+   *  `no_branch` (session predates branching); 502 `quiesce_failed`
+   *  (nothing changed — safe to retry) | `merge_failed` (branch retained,
+   *  named in the body) | `rebranch_failed` (merge landed; retry safe). */
+  mergeSessionChanges(
+    conversationId: string,
+    opts: { branch?: string } = {},
+  ): Promise<SessionMergeReport> {
+    return this.fetch<SessionMergeReport>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/changes/merge`,
+      { method: "POST", body: opts.branch ? { branch: opts.branch } : {} },
+    );
+  }
+
+  /** Reject the session's proposed changes: abandon its branch (retained
+   *  dormant, never deleted — an admin re-merge can recover a mistaken
+   *  discard) and continue the session on a fresh branch off `main`.
+   *  Write-tier + human caller; same 4xx/5xx contract as
+   *  `mergeSessionChanges` minus the merge-step failures. */
+  discardSessionChanges(
+    conversationId: string,
+    opts: { branch?: string } = {},
+  ): Promise<SessionDiscardReport> {
+    return this.fetch<SessionDiscardReport>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/changes/discard`,
+      { method: "POST", body: opts.branch ? { branch: opts.branch } : {} },
+    );
+  }
+
+  // ── Conversation membership (ADR-0045) ────────────────────────────────────
+  // Channel rosters carry roles (`owner > write > read`). Inviting is a
+  // `write` action; removing and re-roling are `owner` (or team admin)
+  // actions. Every mutation returns the full refreshed roster.
+
+  /** The conversation's member roster with roles. Solo conversations
+   *  return an empty roster; a dm returns the pair. */
+  async getConversationMembers(conversationId: string): Promise<ConversationMember[]> {
+    const body = await this.fetch<{ members: ConversationMember[] }>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/members`,
+    );
+    return body.members;
+  }
+
+  /** Invite members to a channel (requires `write` role). Per-invitee
+   *  `role` is `'write'` (default) or `'read'` — `'owner'` is rejected
+   *  with 400. Non-team userIds are dropped server-side. */
+  async addConversationMembers(
+    conversationId: string,
+    members: Array<{ userId: string; role?: "write" | "read" }>,
+  ): Promise<ConversationMember[]> {
+    const body = await this.fetch<{ members: ConversationMember[] }>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/members`,
+      { method: "POST", body: { members } },
+    );
+    return body.members;
+  }
+
+  /** Remove a member (conversation `owner` or team admin only).
+   *  Throws 400 `last_owner` when the target is the roster's last owner. */
+  async removeConversationMember(conversationId: string, userId: string): Promise<ConversationMember[]> {
+    const body = await this.fetch<{ members: ConversationMember[] }>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/members/${encodeURIComponent(userId)}`,
+      { method: "DELETE" },
+    );
+    return body.members;
+  }
+
+  /** Change a member's role (conversation `owner` or team admin only).
+   *  Throws 400 `last_owner` when demoting the roster's last owner. */
+  async setConversationMemberRole(
+    conversationId: string,
+    userId: string,
+    role: ConversationMemberRole,
+  ): Promise<ConversationMember[]> {
+    const body = await this.fetch<{ members: ConversationMember[] }>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/members/${encodeURIComponent(userId)}`,
+      { method: "PATCH", body: { role } },
+    );
+    return body.members;
+  }
+
+  /** Send one message into a conversation. The message persists and fans
+   *  out before this resolves; the response carries the server's
+   *  authoritative turn verdict (`turnState`, ADR-0037 §4) — `queued` means
+   *  a turn is already in flight and a coalesced follow-up will answer, not
+   *  an error. Requires the `invoke` scope. */
+  sendConversationMessage(
+    conversationId: string,
+    input: SendConversationMessageInput,
+  ): Promise<SendConversationMessageResult> {
+    return this.fetch<SendConversationMessageResult>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/messages`,
+      {
+        method: "POST",
+        body: {
+          text: input.text,
+          ...(input.threadRootId ? { threadRootId: input.threadRootId } : {}),
+          ...(input.pageContext ? { pageContext: input.pageContext } : {}),
+        },
+      },
+    );
+  }
+
+  /** Pre-warm a CLOUD session's sandbox (ADR-0040 §6): resumes the
+   *  suspended VM without running a turn, so the resume latency rides the
+   *  attach/focus gap instead of the first reply. Plain no-op
+   *  (`warming: false`) for local/platform sessions; rate-limited
+   *  server-side per session. Fire-and-forget by design — never block a
+   *  surface on it. Requires the `invoke` scope. */
+  prewarmConversation(conversationId: string): Promise<{ warming: boolean; rateLimited?: boolean }> {
+    return this.fetch<{ warming: boolean; rateLimited?: boolean }>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/prewarm`,
+      { method: "POST", body: {} },
+    );
+  }
+
+  /** Stop the conversation's LIVE agent turn (ADR-0037 §5). Conversation-
+   *  scoped, not surface-scoped: any member can cancel, whichever surface
+   *  started the turn. The canceled turn closes with a terminal error part
+   *  (it is never re-run); a message sent after it stays queued and is
+   *  answered next. `canceled: false` = nothing was in flight. Requires
+   *  the `invoke` scope. */
+  cancelConversationTurn(conversationId: string): Promise<{ canceled: boolean }> {
+    return this.fetch<{ canceled: boolean }>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/cancel-turn`,
+      { method: "POST", body: {} },
+    );
+  }
+
+  /** Announce this client as ATTACHED to a conversation (ADR-0037 §6) —
+   *  beat every ~30s while a surface shows the transcript. Each beat fans
+   *  out one live-only `presence` event to every stream subscriber (the
+   *  roster assembles client-side, keyed by `clientId`) and returns a
+   *  fresh agent-liveness snapshot. Member-gated like the stream; no
+   *  scope beyond conversation access — presence is a read-side beacon. */
+  heartbeatConversationPresence(
+    conversationId: string,
+    input: { clientId: string; surface: "dashboard" | "terminal" },
+  ): Promise<ConversationPresenceSnapshot> {
+    return this.fetch<ConversationPresenceSnapshot>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/presence`,
+      { method: "POST", body: input },
+    );
+  }
+
+  /** Subscribe to a conversation's SSE stream as an async iterable of
+   *  typed events, with two conversation-specific rules the consumer must
+   *  uphold:
+   *
+   *  - advance `lastEventId` ONLY from events that carry `id` (durable
+   *    rows) — never from `part_partial` / `turn_state` / `presence`,
+   *    which are live-only and would corrupt reconnect replay;
+   *  - a conversation never "completes": the generator ends on the
+   *    server's bounded-replay batch boundary (`replay.continue` — pass
+   *    its `nextAfterSeq` back as `lastEventId` and reconnect at once) or
+   *    its 2h stream lifetime. Callers loop with their tracked id. */
+  async *streamConversation(
+    conversationId: string,
+    opts?: StreamConversationOptions,
+  ): AsyncGenerator<ConversationStreamEvent> {
+    const path = `/api/v1/conversations/${encodeURIComponent(conversationId)}/stream`;
+    for await (const ev of this.openSseStream(path, opts)) {
+      yield normalizeConversationStreamEvent(ev.event, ev.data, ev.id > 0 ? ev.id : undefined);
+    }
+  }
+
+  /** List the team's agents (platform operators + local bridge agents).
+   *  Bridge rows carry live presence (`online`) and the hosting machine's
+   *  label — what the terminal/dashboard presence dots render from. */
+  async listAgents(): Promise<AgentListRow[]> {
+    const body = await this.fetch<{ agents: AgentListRow[] }>("/api/v1/agents");
+    return body.agents;
+  }
+
+  /** Search a factory drive's live files — path substring OR full-text match
+   *  on extracted content. Cursor-paginated by path. */
+  searchFactoryFiles(query: string, opts?: SearchFactoryFilesOptions): Promise<FactoryFileSearchResult> {
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    const q = new URLSearchParams({ q: query });
+    if (opts?.limit != null) q.set("limit", String(opts.limit));
+    if (opts?.cursor) q.set("cursor", opts.cursor);
+    return this.fetch<FactoryFileSearchResult>(
+      `/api/v1/factories/${encodeURIComponent(factorySlug)}/files/search?${q}`,
     );
   }
 
@@ -1152,6 +1146,226 @@ export class AgentComposeClient {
     return body.templates;
   }
 
+  /** One template's detail (registration metadata + share scope). Falls
+   *  back to the published registry for platform templates. */
+  getTemplate(name: string, opts?: { factorySlug?: string }): Promise<TemplateDetail> {
+    return this.fetch<TemplateDetail>(templatePath(opts?.factorySlug ?? DEFAULT_FACTORY, name));
+  }
+
+  // ── Artifact sharing (ADR-0045) ────────────────────────────────────────────
+  // One scope model for templates and documents: owner + per-principal
+  // capability grants. Mutations are full-replace and owner/team-admin only
+  // (403 `capability_required` with capability "share" otherwise).
+
+  /** Full-replace a template's share grants; optionally bind/unbind its
+   *  owning conversation. Capabilities: `read|write|invoke|see_runs`. */
+  setTemplateScope(
+    name: string,
+    input: SetTemplateScopeInput,
+    opts?: { factorySlug?: string },
+  ): Promise<{ scope: ArtifactScope }> {
+    return this.fetch<{ scope: ArtifactScope }>(
+      templatePath(opts?.factorySlug ?? DEFAULT_FACTORY, name, "scope"),
+      {
+        method: "PUT",
+        body: {
+          grants: input.grants,
+          ...(input.conversationId !== undefined ? { conversationId: input.conversationId } : {}),
+        },
+      },
+    );
+  }
+
+  /** Full-replace a drive file's share grants. Capabilities: `read|write`. */
+  setFileScope(
+    path: string,
+    input: SetScopeGrantsInput,
+    opts?: { factorySlug?: string },
+  ): Promise<{ scope: ArtifactScope }> {
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    return this.fetch<{ scope: ArtifactScope }>(
+      `/api/v1/factories/${encodeURIComponent(factorySlug)}/files/scope`,
+      { method: "PUT", body: { path, grants: input.grants } },
+    );
+  }
+
+  /** Share a drive file WITH a cloud session — the session becomes a grantee
+   *  and the file appears in its fsgw mount. Fixed capabilities: the mount is
+   *  concealment-only, so the session can read AND edit the file. Requires the
+   *  `share` capability on the file (its owner or a team admin). The target
+   *  must be a CLOUD session (local sessions never mount fsgw → 400
+   *  `cloud_session_required`). No capabilities argument — semantics are fixed
+   *  "open and edit". */
+  async shareFileWithSession(
+    factorySlug: string,
+    input: { path: string; conversationId: string },
+  ): Promise<void> {
+    await this.fetch<{ ok: boolean }>(
+      `/api/v1/factories/${encodeURIComponent(factorySlug)}/files/session-grants`,
+      { method: "POST", body: { path: input.path, conversationId: input.conversationId } },
+    );
+  }
+
+  /** Revoke a file's share to a session (revocation-critical — re-conceals on
+   *  the session's live mount within push latency). Idempotent. */
+  async unshareFileWithSession(
+    factorySlug: string,
+    input: { path: string; conversationId: string },
+  ): Promise<void> {
+    await this.fetch<{ ok: boolean }>(
+      `/api/v1/factories/${encodeURIComponent(factorySlug)}/files/session-grants`,
+      { method: "DELETE", body: { path: input.path, conversationId: input.conversationId } },
+    );
+  }
+
+  // ── Projects (ADR-0045) ────────────────────────────────────────────────────
+  // A project is a member-gated group (roles owner > write > read) that holds
+  // objects (files, conversations, sessions). membership ⊆ visibility: every
+  // member sees every object. Access is DERIVED (never copied into personal
+  // scopes) and revokes the instant a member or object leaves. The server is
+  // the sole authority — these are thin typed wrappers.
+
+  /** List the projects the caller is a member of, newest-activity first.
+   *  Cursor-paginated. A creator who has left sees nothing (no implicit
+   *  creator authority) — membership is the sole gate. */
+  listProjects(opts?: { cursor?: string }): Promise<ProjectsPage> {
+    const q = new URLSearchParams();
+    if (opts?.cursor) q.set("cursor", opts.cursor);
+    return this.fetch<ProjectsPage>(`/api/v1/projects${q.toString() ? `?${q}` : ""}`);
+  }
+
+  /** Create a project. The caller is seeded as its first `owner` member. 409
+   *  on a duplicate name within the team. */
+  async createProject(name: string): Promise<Project> {
+    const body = await this.fetch<{ project: Project }>("/api/v1/projects", {
+      method: "POST",
+      body: { name },
+    });
+    return body.project;
+  }
+
+  /** One project (with the caller's role + member/object counts). 404 when
+   *  the caller is not a member. */
+  async getProject(id: string): Promise<Project> {
+    const body = await this.fetch<{ project: Project }>(
+      `/api/v1/projects/${encodeURIComponent(id)}`,
+    );
+    return body.project;
+  }
+
+  /** Rename a project (requires `write` role). */
+  async renameProject(id: string, name: string): Promise<Project> {
+    const body = await this.fetch<{ project: Project }>(
+      `/api/v1/projects/${encodeURIComponent(id)}`,
+      { method: "PATCH", body: { name } },
+    );
+    return body.project;
+  }
+
+  /** Delete a project (owner or team admin). Revokes every derived grant. */
+  async deleteProject(id: string): Promise<void> {
+    await this.fetch<{ ok: boolean }>(`/api/v1/projects/${encodeURIComponent(id)}`, {
+      method: "DELETE",
+    });
+  }
+
+  /** The project's member roster with roles (member only). */
+  async getProjectMembers(id: string): Promise<ProjectMember[]> {
+    const body = await this.fetch<{ members: ProjectMember[] }>(
+      `/api/v1/projects/${encodeURIComponent(id)}/members`,
+    );
+    return body.members;
+  }
+
+  /** Invite members (requires `write` role). Per-invitee `role` is `'write'`
+   *  (default) or `'read'` — `'owner'` is never grantable at invite. Non-team
+   *  userIds are dropped server-side; the full refreshed roster is returned. */
+  async addProjectMembers(
+    id: string,
+    members: Array<{ userId: string; role?: "write" | "read" }>,
+  ): Promise<ProjectMember[]> {
+    const body = await this.fetch<{ members: ProjectMember[] }>(
+      `/api/v1/projects/${encodeURIComponent(id)}/members`,
+      { method: "POST", body: { members } },
+    );
+    return body.members;
+  }
+
+  /** Remove a member — project owner/team admin, or self-leave. Throws 400
+   *  `last_owner` when the target is the roster's last owner. */
+  async removeProjectMember(id: string, userId: string): Promise<ProjectMember[]> {
+    const body = await this.fetch<{ members: ProjectMember[] }>(
+      `/api/v1/projects/${encodeURIComponent(id)}/members/${encodeURIComponent(userId)}`,
+      { method: "DELETE" },
+    );
+    return body.members;
+  }
+
+  /** Change a member's role (project owner or team admin). Throws 400
+   *  `last_owner` when demoting the roster's last owner. */
+  async setProjectMemberRole(
+    id: string,
+    userId: string,
+    role: ProjectRole,
+  ): Promise<ProjectMember[]> {
+    const body = await this.fetch<{ members: ProjectMember[] }>(
+      `/api/v1/projects/${encodeURIComponent(id)}/members/${encodeURIComponent(userId)}`,
+      { method: "PATCH", body: { role } },
+    );
+    return body.members;
+  }
+
+  /** List a project's objects (member only), newest first. Cursor-paginated. */
+  listProjectObjects(id: string, opts?: { cursor?: string }): Promise<ProjectObjectsPage> {
+    const q = new URLSearchParams();
+    if (opts?.cursor) q.set("cursor", opts.cursor);
+    return this.fetch<ProjectObjectsPage>(
+      `/api/v1/projects/${encodeURIComponent(id)}/objects${q.toString() ? `?${q}` : ""}`,
+    );
+  }
+
+  /** DRY-RUN preview of a session add: the files that WOULD be shared (from
+   *  the caller's owned scopes) + any owned-but-skipped entries (paths
+   *  concealed from the caller are omitted). Powers the consent dialog. Same
+   *  gates as the add, but mutates nothing. */
+  previewProjectObject(id: string, input: { conversationId: string }): Promise<ProjectAddPreview> {
+    return this.fetch<ProjectAddPreview>(
+      `/api/v1/projects/${encodeURIComponent(id)}/objects/preview`,
+      { method: "POST", body: { type: "session", conversationId: input.conversationId } },
+    );
+  }
+
+  /** Add an object to a project (requires `write` role AND authority on the
+   *  object itself). A session add also materializes the caller-owned files in
+   *  the session's context, returning them alongside the session object. */
+  addProjectObject(id: string, input: AddProjectObjectInput): Promise<AddProjectObjectResult> {
+    return this.fetch<AddProjectObjectResult>(
+      `/api/v1/projects/${encodeURIComponent(id)}/objects`,
+      { method: "POST", body: input },
+    );
+  }
+
+  /** Re-materialize a session object's file context (add-only — never removes;
+   *  picks up files scoped/created after the original add). Session objects
+   *  only; caller must be the session owner and a project writer. */
+  refreshProjectObject(id: string, objectId: string): Promise<RefreshProjectObjectResult> {
+    return this.fetch<RefreshProjectObjectResult>(
+      `/api/v1/projects/${encodeURIComponent(id)}/objects/${encodeURIComponent(objectId)}/refresh`,
+      { method: "POST", body: {} },
+    );
+  }
+
+  /** Remove an object from a project (revocation-critical). Authorized for a
+   *  project writer, the member who added it, OR — for a file object — the
+   *  file's owner even without project membership (share implies unshare).
+   *  Unauthorized → 404. */
+  async removeProjectObject(id: string, objectId: string): Promise<void> {
+    await this.fetch<{ ok: boolean }>(
+      `/api/v1/projects/${encodeURIComponent(id)}/objects/${encodeURIComponent(objectId)}`,
+      { method: "DELETE" },
+    );
+  }
+
   // ── Factories ──────────────────────────────────────────────────────────────
   // Projects within a team. Workflows + secrets belong to exactly one factory.
 
@@ -1230,13 +1444,17 @@ export class AgentComposeClient {
     });
   }
 
+  /** Both secret tiers list the same `{ secrets }` envelope — fetch + map the
+   *  wire's `secretKey` to `SecretListEntry.key`. */
+  private async listSecretEntries(path: string): Promise<SecretListEntry[]> {
+    const body = await this.fetch<{ secrets: Array<{ secretKey: string; createdAt: string; updatedAt: string }> }>(path);
+    return body.secrets.map(s => ({ key: s.secretKey, createdAt: s.createdAt, updatedAt: s.updatedAt }));
+  }
+
   /** List secret keys registered for a workflow (metadata only — values are never returned). */
-  async listSecrets(workflowName: string, opts?: SecretOptions): Promise<SecretListEntry[]> {
+  listSecrets(workflowName: string, opts?: SecretOptions): Promise<SecretListEntry[]> {
     const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
-    const body = await this.fetch<{ secrets: Array<{ secretKey: string; createdAt: string; updatedAt: string }> }>(
-      templatePath(factorySlug, workflowName, "secrets"),
-    );
-    return body.secrets.map(s => ({ key: s.secretKey, createdAt: s.createdAt, updatedAt: s.updatedAt }));
+    return this.listSecretEntries(templatePath(factorySlug, workflowName, "secrets"));
   }
 
   /** Delete a workflow secret. */
@@ -1245,6 +1463,37 @@ export class AgentComposeClient {
     return this.fetch(templatePath(factorySlug, workflowName, "secrets", key), { method: "DELETE" });
   }
 
+  // ── GitHub-linked drive directories (ADR-0030 P1) ───────────────────────────
+
+  /** List a factory's drive⇄repo links. */
+  async listRepoLinks(opts?: { factorySlug?: string }): Promise<DriveRepoLink[]> {
+    const slug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    const body = await this.fetch<{ links: DriveRepoLink[] }>(
+      `/api/v1/factories/${encodeURIComponent(slug)}/repo-links`);
+    return body.links;
+  }
+
+  /** Link a drive directory to a GitHub repo + tracked branch (`manage`
+   *  scope). Requires the drive to be graph-authoritative — 409 names the
+   *  promotion prerequisite otherwise. */
+  async createRepoLink(
+    input: CreateDriveRepoLinkInput, opts?: { factorySlug?: string },
+  ): Promise<DriveRepoLink> {
+    const slug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    const body = await this.fetch<{ link: DriveRepoLink }>(
+      `/api/v1/factories/${encodeURIComponent(slug)}/repo-links`,
+      { method: "POST", body: input });
+    return body.link;
+  }
+
+  /** Unlink (§6.3: the prefix's files and history stay on the drive). */
+  deleteRepoLink(linkId: string, opts?: { factorySlug?: string }): Promise<void> {
+    const slug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    return this.fetch(
+      `/api/v1/factories/${encodeURIComponent(slug)}/repo-links/${encodeURIComponent(linkId)}`,
+      { method: "DELETE" });
+  }
+
   // ── Factory-level secrets (ADR-0014) ────────────────────────────────────────
   // The inherited tier: a factory secret is visible to EVERY workflow in the
   // factory; a workflow secret of the same key overrides it. Values are stored
@@ -1260,12 +1509,9 @@ export class AgentComposeClient {
   }
 
   /** List factory-level secret keys (metadata only — values are never returned). */
-  async listFactorySecrets(opts?: SecretOptions): Promise<SecretListEntry[]> {
+  listFactorySecrets(opts?: SecretOptions): Promise<SecretListEntry[]> {
     const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
-    const body = await this.fetch<{ secrets: Array<{ secretKey: string; createdAt: string; updatedAt: string }> }>(
-      `/api/v1/factories/${encodeURIComponent(factorySlug)}/secrets`,
-    );
-    return body.secrets.map(s => ({ key: s.secretKey, createdAt: s.createdAt, updatedAt: s.updatedAt }));
+    return this.listSecretEntries(`/api/v1/factories/${encodeURIComponent(factorySlug)}/secrets`);
   }
 
   /** Delete a factory-level secret. */
@@ -1313,6 +1559,79 @@ export class AgentComposeClient {
     );
   }
 
+  // ── Break-glass compliance sessions (ADR-0051) ───────────────────────────────
+  // A team admin has no default access to a scoped document. To view one they
+  // don't hold a grant on, they request a READ-ONLY, owner-approved, time-boxed
+  // compliance session over a scope (a factory, or the whole team). Every verb
+  // here requires an `admin`-scoped key; approval additionally requires the
+  // caller be a team owner (or a fallback admin ≠ requester). Every access under
+  // an active session is individually audited and the doc's owner is notified.
+
+  /** Request a break-glass compliance session — returns it `pending` until a
+   *  team owner (≠ requester) approves. `scopeRef` is the factory id for
+   *  factory scope; omit it for team scope. `ttlSeconds` is the session's
+   *  lifetime once approved (15 min floor, 7 day ceiling). */
+  async requestComplianceSession(input: RequestComplianceSessionInput): Promise<ComplianceSession> {
+    const body = await this.fetch<{ session: ComplianceSession }>("/api/v1/compliance/sessions", {
+      method: "POST",
+      body: {
+        scopeKind: input.scopeKind,
+        reason: input.reason,
+        ttlSeconds: input.ttlSeconds,
+        ...(input.scopeRef != null ? { scopeRef: input.scopeRef } : {}),
+      },
+    });
+    return body.session;
+  }
+
+  /** Approve a pending compliance session → active with its TTL. The caller
+   *  must be a team owner ≠ the requester (or, when the requester is the sole
+   *  owner, any admin ≠ requester). Throws 403 on self-approval or wrong role,
+   *  409 when the session is no longer pending. */
+  async approveComplianceSession(sessionId: string): Promise<ComplianceSession> {
+    const body = await this.fetch<{ session: ComplianceSession }>(
+      `/api/v1/compliance/sessions/${encodeURIComponent(sessionId)}/approve`,
+      { method: "POST" },
+    );
+    return body.session;
+  }
+
+  /** Revoke a pending or active compliance session — revocation always
+   *  tightens, so any team owner/admin may do it. */
+  async revokeComplianceSession(sessionId: string): Promise<ComplianceSession> {
+    const body = await this.fetch<{ session: ComplianceSession }>(
+      `/api/v1/compliance/sessions/${encodeURIComponent(sessionId)}/revoke`,
+      { method: "POST" },
+    );
+    return body.session;
+  }
+
+  /** List the team's compliance sessions, newest first. Optional `status`
+   *  filter; opaque `cursor` pagination. */
+  listComplianceSessions(opts?: ListComplianceSessionsOptions): Promise<ComplianceSessionsPage> {
+    const q = new URLSearchParams();
+    if (opts?.status) q.set("status", opts.status);
+    if (opts?.limit != null) q.set("limit", String(opts.limit));
+    if (opts?.cursor) q.set("cursor", opts.cursor);
+    return this.fetch<ComplianceSessionsPage>(
+      `/api/v1/compliance/sessions${q.toString() ? `?${q}` : ""}`,
+    );
+  }
+
+  /** The documents touched under one compliance session — the individual
+   *  per-document audit trail its reasoned entry authorized. */
+  listComplianceAccesses(
+    sessionId: string,
+    opts?: ListComplianceAccessesOptions,
+  ): Promise<ComplianceAccessesPage> {
+    const q = new URLSearchParams();
+    if (opts?.limit != null) q.set("limit", String(opts.limit));
+    if (opts?.cursor) q.set("cursor", opts.cursor);
+    return this.fetch<ComplianceAccessesPage>(
+      `/api/v1/compliance/sessions/${encodeURIComponent(sessionId)}/accesses${q.toString() ? `?${q}` : ""}`,
+    );
+  }
+
   /** Stream lifecycle events for a run as an async iterable. Yields parsed
    *  `RunEvent` payloads in order; caller breaks on terminal events
    *  (`run_complete`, `run_failed`, `run_canceled`).
@@ -1320,33 +1639,13 @@ export class AgentComposeClient {
    *  `lastEventId` enables resume — pass the highest `seq` you've already
    *  processed to receive only events you missed.
    *
-   *  `event` can be used to abort the stream from the caller side.
-   *
-   *  Uses raw `fetch` (not ofetch) because SSE requires access to the
-   *  response's `ReadableStream`, which ofetch consumes when parsing. Auth
-   *  + base URL are still sourced from the same constructor inputs, and
-   *  non-2xx responses throw the same `AgentComposeError`. */
+   *  `event` can be used to abort the stream from the caller side. */
   async *streamRunLogs(
     runId: string,
     opts?: StreamRunLogsOptions,
   ): AsyncGenerator<RunEvent> {
-    const headers: Record<string, string> = { Authorization: `Bearer ${this.apiKey}` };
-    if (opts?.lastEventId && opts.lastEventId > 0) {
-      headers["Last-Event-ID"] = String(opts.lastEventId);
-    }
-    const res = await fetch(`${this.baseUrl}/api/v1/workflows/${encodeURIComponent(runId)}/stream`, {
-      headers,
-      ...(opts?.signal ? { signal: opts.signal } : {}),
-    });
-    if (!res.ok || !res.body) {
-      let message = res.statusText;
-      try {
-        const body = await res.json() as { error?: string };
-        if (body.error) message = body.error;
-      } catch { /* non-JSON error body — fall back to statusText */ }
-      throw new AgentComposeError(res.status, message);
-    }
-    for await (const ev of parseSseStream(res.body)) {
+    const path = `/api/v1/workflows/${encodeURIComponent(runId)}/stream`;
+    for await (const ev of this.openSseStream(path, opts)) {
       // The server's `data` payload already includes `event`, `runId`, `seq`,
       // `at`, and the per-event payload — so `ev.data` IS the `RunEvent`.
       // Cast directly; unknown future event names flow through untyped, and
@@ -1355,14 +1654,3 @@ export class AgentComposeClient {
     }
   }
 }
-
-/** A factory: a project-level grouping of workflows inside a team. */
-export interface FactoryRow {
-  id:          string;
-  teamId:      string;
-  slug:        string;
-  name:        string;
-  description: string | null;
-  createdAt:   string;
-  updatedAt:   string;
-}