@agent-compose/sdk 0.8.1 → 0.8.3

package/src/types/api-factory.ts

@@ -192,6 +192,48 @@ export interface FactoryFileSearchResult {
   folders_truncated?: boolean;
 }
 
+// ── Factory-file listing (`GET /files` — live index or browse-at-head) ─────
+
+/** One file row of `GET /factories/:slug/files` — the flat recursive
+ *  listing. Same row shape live and at a pinned head; rows arrive
+ *  camelCase on the wire (mirrors `FactoryFileSearchRow`). */
+export interface FactoryFileListRow {
+  id: string;
+  path: string;
+  sizeBytes: number;
+  contentType: string | null;
+  contentHash: string;
+  deletedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface ListFactoryFilesOptions {
+  factorySlug?: string;
+  /** Only paths under this prefix. */
+  prefix?: string;
+  /** Path cursor from a prior page's `nextCursor`. */
+  cursor?: string;
+  limit?: number;
+  /** List AS OF a drive branch (e.g. a session's `session-<uuid>`). */
+  branch?: string;
+  /** Browse-at-head: a retained 64-hex commit of the MAIN drive (or, with
+   *  `branch`, a pin of that graph branch). The server answers 410
+   *  `at_unavailable` for a garbage-collected/unknown head. */
+  at?: string;
+}
+
+/** One page of `GET /factories/:slug/files`. */
+export interface FactoryFileListPage {
+  data: FactoryFileListRow[];
+  hasMore: boolean;
+  /** Pass as `cursor` to fetch the next page; null on the last page. */
+  nextCursor: string | null;
+  /** The pinned head this page was read at — non-null exactly when the
+   *  request carried `at`. `committedAt` is RFC3339 or null (unknown). */
+  at: { head: string; committedAt: string | null } | null;
+}
+
 export interface FactoryFileWriteResult {
   path: string;
   contentHash: string;
@@ -237,6 +279,28 @@ export interface FactoryRow {
   updatedAt:   string;
 }
 
+/** GET /factories/:slug/perf-summary — team-level sandbox perf aggregates
+ *  over a window (session_perf_rollups). Aggregate-only by design: sessions
+ *  are member-gated, so no conversation ids appear here; per-session detail
+ *  is the member-gated perf-history surface. */
+export interface FactoryPerfSummary {
+  /** The aggregated window, ISO 8601. */
+  from: string;
+  to: string;
+  /** Distinct sessions with any rollup bucket in the window. */
+  sessions: number;
+  /** Rollup buckets (15-min) in the window. */
+  buckets: number;
+  /** Guest samples folded into those buckets. */
+  samples: number;
+  cpu_busy_p95_max: number | null;
+  mem_used_p95_max: number | null;
+  disk_used_p95_max: number | null;
+  load1_max: number | null;
+  /** Total seconds any session sat ≥90% on a resource, summed. */
+  saturated_seconds: number;
+}
+
 export interface CreateFactoryInput {
   slug: string;
   name: string;
@@ -285,6 +349,48 @@ export interface SecretListEntry {
   updatedAt: string;
 }
 
+/** One SESSION secret on the wire (metadata only — values are write-only).
+ *  `kind` 'value' = a session-own secret; 'factory' = an attachment by name
+ *  to the session factory's secret tier. `ownerUserId` is the user who set
+ *  it — only the owner or a team admin may replace/remove it. */
+export interface SessionSecretEntry {
+  secretKey: string;
+  kind: "value" | "factory";
+  ownerUserId: string;
+  /** Delivery mode (vault v2): 'injected' = the session env file;
+   *  'brokered' = an egress-ruleset header — the value never enters the
+   *  sandbox (call the host WITHOUT auth headers; the platform adds them). */
+  delivery: "injected" | "brokered";
+  /** Brokered entries: the API host the header rides on. */
+  brokerHost: string | null;
+  /** Non-null = an ephemeral use-and-scrub copy, and when its TTL lapses. */
+  ephemeralExpiresAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** One entry of a session-secret set: a literal value, or a factory
+ *  attachment by name (`source: "factory"`). */
+export type SessionSecretInput =
+  | { key: string; value: string }
+  | { key: string; source: "factory" };
+
+/** A freshly minted vault link (session secret request). `url` is the
+ *  single-use page a session writer opens to provide the named values. */
+export interface SessionSecretRequestCreated {
+  requestId: string;
+  url: string;
+  expiresAt: string;
+}
+
+/** A vault link's polled status. */
+export interface SessionSecretRequestStatus {
+  requestId: string;
+  status: "pending" | "fulfilled" | "cancelled" | "expired";
+  keys: string[];
+  expiresAt: string;
+}
+
 export interface CreateApiKeyInput {
   name?:        string;
   scopes?:      string[];
@@ -313,6 +419,27 @@ export interface ApiKey {
  *  shown once at creation, never retrievable again. */
 export interface ApiKeyCreated extends ApiKey { key: string }
 
+/** Options for `GET /api-keys` — the list is bounded and keyset-paginated
+ *  (every run step / session boot mints a key row, so "all keys ever" is
+ *  unbounded by construction). */
+export interface ListApiKeysOptions {
+  /** Page size, 1–200 (server default 100). */
+  limit?:  number;
+  /** `active` = unrevoked + unexpired only; `all` (default) includes
+   *  revoked/expired history. */
+  status?: "active" | "all";
+  /** Opaque cursor from a previous page's `nextCursor`. */
+  cursor?: string;
+}
+
+/** One page of `GET /api-keys`. */
+export interface ApiKeyPage {
+  data:       ApiKey[];
+  hasMore:    boolean;
+  /** Pass as `cursor` to fetch the next page; null on the last page. */
+  nextCursor: string | null;
+}
+
 /** Single rollup row from `GET /api/v1/usage`. */
 export interface UsageRollupRow {
   eventType: string;
@@ -333,7 +460,10 @@ export interface UsageResponse {
 // ── GitHub-linked drive directories (ADR-0030 P1) ───────────────────────────
 
 /** One drive-directory ⇄ GitHub-repo link (`/factories/:slug/repo-links`).
- *  The webhook secret ref is operator plumbing and never on the wire. */
+ *  Multi-branch model: ONE link row per (repo, branch); sibling branches
+ *  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;
@@ -343,26 +473,54 @@ export interface DriveRepoLink {
   provider:      string;
   /** "org/repo". */
   repoFullName:  string;
-  /** The GitHub branch drive `main` syncs with. */
+  /** The GitHub branch this link's placement syncs with. */
   trackedBranch: string;
   connectorGrantId: string | null;
   /** v1 links are always 'write' (the round trip is the feature). */
   access:        "read" | "write";
+  /** 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. */
+  pushOutEnabled: boolean;
+  /** Follow-all mode (stamped identically on every sibling link of one
+   *  repo): pushes to NEW branches auto-link them; GitHub branch deletes
+   *  auto-unlink. False = explicit selection. */
+  followAllBranches: boolean;
+  /** Branches follow-all could NOT link (with the reason) — stamped on
+   *  the repo's PRIMARY link row only; empty everywhere else. */
+  autoLinkSkips: Array<{ branch: string; reason: string; at: string }>;
   lastSyncedGitSha:    string | null;
   lastSyncedAcgCommit: string | null;
-  syncState:     "idle" | "syncing" | "diverged" | "reauth_required";
-  visibility:    "team" | "restricted";
+  syncState:     "idle" | "syncing" | "pushing" | "error" | "conflict" | "diverged" | "reauth_required";
+  /** Human-readable detail when syncState is 'error' or 'conflict'. */
+  syncError:     string | null;
   createdBy:     string | null;
   lastSyncedAt:  string | null;
   createdAt:     string;
 }
 
 /** Input for `POST /factories/:slug/repo-links`. Requires the drive to be
- *  graph-authoritative (ADR-0058 Phase 4 promoted) — 409 otherwise. */
+ *  graph-authoritative (ADR-0058 Phase 4 promoted) — 409 otherwise.
+ *  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`:
+ *  index 0 is the PRIMARY and keeps the plain placement; every additional
+ *  branch lands at the sibling `dirPrefix@<sanitized-branch>` placement. */
 export interface CreateDriveRepoLinkInput {
   dirPrefix:     string;
   repoFullName:  string;
-  trackedBranch: string;
+  trackedBranches?: string[];
+  followAllBranches?: boolean;
   connectorGrantId: string;
-  visibility?:   "team" | "restricted";
+  /** Two-way sync ("push-out") — defaults to TRUE for new links. */
+  pushOut?:      boolean;
 }

package/src/types/api-runs.ts

@@ -281,6 +281,29 @@ export interface RunFundingResponse {
   };
 }
 
+/** One step's attested platform token totals — `GET
+ *  /workflows/:id/step-usage`. Derived server-side from the spend ledger
+ *  by step time window (steps run serially, so every gateway call falls in
+ *  exactly one). Steps with no ledger rows are absent from the list. */
+export interface RunStepUsage {
+  stepIndex: number;
+  costUsd: number;
+  promptTokens: number;
+  completionTokens: number;
+  cacheReadTokens: number;
+  cacheCreationTokens: number;
+  calls: number;
+}
+
+/** `GET /workflows/:id/step-usage`. Empty `steps` is an honest answer: a
+ *  legacy run with no ledger rows, or a run funded outside the platform
+ *  lane (that money is never metered — ADR-0048). */
+export interface RunStepUsageResponse {
+  object: "run.step_usage";
+  runId: string;
+  steps: RunStepUsage[];
+}
+
 /** One row from the factory runs list (`GET /factories/:slug/runs`) — the
  *  summary shape, a strict subset of what the route returns. */
 export interface RunListEntry {
@@ -303,7 +326,8 @@ export interface ListRunsOptions {
   factorySlug?: string;
   /** Substring match on the registered workflow name (`metadata._workflow`). */
   workflow?: string;
-  /** Substring match across title / task title / branch / run id. */
+  /** Substring match across title / task title / branch — or an exact run
+   *  id (full UUID). */
   search?: string;
   outcome?: string;
   sort?: "newest" | "oldest" | "fastest" | "slowest";

package/src/types/protocol.ts

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

package/src/types/runtime.ts

@@ -15,6 +15,34 @@ export interface McpServerConfig {
   env?: Record<string, string>;
 }
 
+/**
+ * Exit-event push (the completion DOORBELL, v0.10.43). When set, the durable
+ * detached transport's in-guest wrapper fires ONE best-effort HTTP POST
+ * announcing `{ turnId, exitCode }` immediately AFTER the exit sentinel is
+ * durably written — so the server can verify-and-harvest at event latency
+ * instead of the watchdog's poll cadence.
+ *
+ * THE PUSH IS A DOORBELL, NEVER A VERDICT: the durable file stays the only
+ * truth; the push's arrival triggers verification against it, its absence
+ * means nothing (the poll ladder is the unchanged backstop), and a lost /
+ * duplicate / spoofed push must be harmless. Accordingly the wrapper never
+ * blocks sentinel-writing on the push (sentinel first, push after; failures
+ * are invisible to the runner lifecycle).
+ *
+ * Auth: `tokenEnv` NAMES a guest env var (e.g. the cloud session's
+ * `AGENT_COMPOSE_API_KEY`) — the wrapper reads it at push time, so the
+ * credential never appears in the generated script text or any log.
+ */
+export interface TurnExitNotify {
+  /** Absolute URL of the server's turn-exit-event endpoint. */
+  url: string;
+  /** The bridge turn id this runner executes (rides the POST body). */
+  turnId: string;
+  /** Guest env var holding the bearer credential. A name that is not a
+   *  plain env identifier disables the push (never risks shell injection). */
+  tokenEnv: string;
+}
+
 /** Options passed to a runtime when creating a ModelExecutionContract. */
 export interface RuntimeOptions {
   allowedTools?: string[];
@@ -47,8 +75,35 @@ export interface RuntimeOptions {
   pause?: BoundaryPauseFn;
   /** Optional JSON schema for runtimes with native structured-output support. */
   outputFormat?: { type: "json_schema"; schema: Record<string, unknown> };
+  /** Exit-event doorbell config (cloud sessions) — see `TurnExitNotify`.
+   *  Absent ⇒ no push; the durable transport behaves exactly as before. */
+  turnExitNotify?: TurnExitNotify;
+  /** $HOME-relative path of a shell env file the CLI process sources at
+   *  launch (cloud sessions: the platform-managed session-secrets file,
+   *  `SESSION_ENV_FILE_RELPATH`). Sourced fresh at EVERY turn launch, so a
+   *  rewrite between turns lands on the next turn without a VM recycle.
+   *  Absent ⇒ nothing is sourced (local/BYOM runs never read a user's own
+   *  dotfiles by surprise). Must be a plain relative path — no quotes, no
+   *  `..`; the runtime validates and drops anything else. */
+  sessionEnvFile?: string;
+  /** ABSOLUTE guest path of a per-turn model-credential shell fragment
+   *  (cloud subscription sessions: the server ships the TURN ACTOR's own
+   *  subscription credential there before dispatching the turn). Sourced at
+   *  launch AFTER `sessionEnvFile`, so the turn's credential always wins —
+   *  each turn runs on its actor's plan, never a baked or session-wide one.
+   *  Absent ⇒ nothing extra is sourced. Must be a plain absolute path — no
+   *  quotes, no `..`; the runtime validates and drops anything else. */
+  credEnvFile?: string;
 }
 
+/** Three-valued liveness verdict for a runtime's CURRENT turn, read from
+ *  DURABLE guest state (heartbeat file, stdout file, exit sentinel, pid) over
+ *  a fresh short exec — never from the health of any long-lived stream.
+ *  `probe-failed` (exec timeout, transport fault, unparseable output) is
+ *  NEVER evidence of death: the caller tracks it separately and only many
+ *  consecutive failures escalate to a sandbox-unreachable verdict. */
+export type RunnerLivenessVerdict = "alive" | "dead" | "probe-failed";
+
 /** Runtime-normalized result of running pre-tool processors. */
 export type ToolCallGateResult =
   | { kind: "allow"; call: ToolCall }
@@ -110,6 +165,73 @@ export interface ModelExecutionContract {
    * `captureCheckpoint` is omitted, this is never called.
    */
   restoreCheckpoint?(blob: unknown): void;
+  /**
+   * Durable liveness probe for the CURRENT turn (2026-08-15 incident, turn
+   * 18dc5261: a silently wedged tail stream blinded the executor's
+   * process-grep probe to a turn that had FINISHED into its durable file —
+   * ten minutes of "no evidence" over a completed answer). Runtimes that run
+   * the detached durable transport implement this by reading the guest's
+   * durable trio — heartbeat file, stdout size, exit sentinel, pid — over a
+   * fresh short exec. The executor's evidence ticker prefers this over its
+   * generic process-grep probe.
+   *
+   * Contract: resolves fast (the implementation carries its own explicit
+   * exec timeout) and never throws — faults map to "probe-failed". Null
+   * means NO durable probe exists right now (boot phase before the runner
+   * launched, a transport without durable files): the caller keeps whatever
+   * fallback probe it already had; null is never a verdict.
+   */
+  probeTurnLiveness?(): Promise<RunnerLivenessVerdict | null>;
+  /**
+   * DOORBELL, NEVER A VERDICT (exit-event push, v0.10.43): wake the current
+   * turn's durable watchdog NOW so it runs its normal verification pass —
+   * durable probe, then harvest-on-sentinel / honest no-sentinel death —
+   * immediately instead of at the next poll interval. Carries NO information
+   * of its own: a nudge for a live turn verifies alive and is a no-op; a
+   * spurious / duplicate / stale nudge is harmless; the poll ladder is the
+   * unchanged backstop when no nudge arrives. Never throws; a nudge while no
+   * watchdog is armed is remembered for the next arm (or dropped at turn
+   * start — a new turn owes nothing to the previous turn's doorbell).
+   */
+  nudgeTurnProbe?(): void;
+  /**
+   * RESUME HANDOFF, NEVER A KILL (redispatch-carries-session, 2026-08-15
+   * forensics): mark the CURRENT turn's in-guest runner as handed off — the
+   * caller intends a successor turn to RESUME the same guest session, so
+   * abort/early-exit must unwind the transport WITHOUT reaping the detached
+   * process tree or deleting its durable files (heartbeat included — the
+   * park path's busy signal keeps reading it). Without this, "stop
+   * consuming" and "kill the guest tree" are fused on the abort seam, and a
+   * supersede-then-resume would destroy the very session it resumes.
+   * One-way for the runner instance; a runtime without a detachable guest
+   * (single-exec transports, ACP) simply omits the method — its abort
+   * semantics are unchanged and the caller falls back to kill semantics.
+   */
+  detachGuest?(): void;
+  /**
+   * Deliver ONE user message INTO the currently running turn (the cloud
+   * analogue of `inboxStream` for runtimes whose agent loop lives in a
+   * detached in-guest CLI). The message rides a durable per-turn inbox
+   * file; the guest-side feeder forwards it to the CLI's stdin, where a
+   * steering-capable harness folds it into the live turn at the next safe
+   * boundary. Four-valued and honest:
+   *   - "delivered"   — the guest feeder forwarded the message to the CLI's
+   *     stdin BEFORE the turn's terminal result: the running turn saw it.
+   *     Only this verdict may advance any answered watermark.
+   *   - "pending"     — the append landed in the durable inbox but the ack
+   *     window exhausted before the feeder forwarded it (guest exit 5: the
+   *     CLI is not draining stdin mid-step — a long single tool call — or
+   *     the guest is crawling). NOT seen yet; leave it owed. The line stays
+   *     appended, so the CLI may still read it when the current step
+   *     finishes — callers may narrate that bound but must never advance a
+   *     watermark on it.
+   *   - "closed"      — the turn ended (guest exit 4 / exec fault) before
+   *     the message was consumed: it was NOT seen; leave it owed.
+   *   - "unsupported" — no live stream-input turn exists right now (boot
+   *     phase, a spec/transport without stream input, ACP path).
+   * Calls are serialized per turn; never throws.
+   */
+  injectUserMessage?(text: string): Promise<"delivered" | "pending" | "closed" | "unsupported">;
   sendMessage(opts: {
     prompt: string;
     sessionId?: string;

package/src/types/workflow-metadata.ts

@@ -154,11 +154,12 @@ export interface InvokePolicy {
  *  today; kept as its own object so finer controls (disk, gpu, …) can be
  *  added later without reshaping `WorkflowMetadata`. */
 export interface SandboxResources {
-  /** Machine hardware SKU — one of the `SandboxSize` vCPU strings
-   *  (`2vcpu-4gb` | `4vcpu-8gb` | `8vcpu-16gb` | `32vcpu-64gb`). Maps to
-   *  provider specs at create time (Vercel: 2 / 4 / 8 / 32 vCPU, 2048 MB RAM
-   *  per vCPU). Omit → the smallest SKU. E2B sizing is template-defined and
-   *  ignores this. */
+  /** Machine hardware SKU. The vocabulary is `SANDBOX_SIZES` in
+   *  `sandbox/sizes.ts` — the single source; do not restate it here or
+   *  anywhere else. Maps to provider specs at create time: Vercel takes the
+   *  vCPU count and allocates RAM at 2048 MB/vCPU; E2B has no create-time
+   *  cpu/mem knob at all, so the size selects a PRE-BUILT per-size template
+   *  (`E2B_TEMPLATE_SIZES`). Omit → `DEFAULT_SANDBOX_SIZE`. */
   size?: SandboxSize;
   /** Sandbox provider this workflow's runs execute on — `"vercel"` or
    *  `"e2b"`. Optional and additive: omit and the run resolves to the