@agent-compose/sdk 0.8.1 → 0.8.3

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

@@ -180,6 +180,46 @@ export interface FactoryFileSearchResult {
     /** True when more directories matched than the server's folder bound. */
     folders_truncated?: boolean;
 }
+/** One file row of `GET /factories/:slug/files` — the flat recursive
+ *  listing. Same row shape live and at a pinned head; rows arrive
+ *  camelCase on the wire (mirrors `FactoryFileSearchRow`). */
+export interface FactoryFileListRow {
+    id: string;
+    path: string;
+    sizeBytes: number;
+    contentType: string | null;
+    contentHash: string;
+    deletedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ListFactoryFilesOptions {
+    factorySlug?: string;
+    /** Only paths under this prefix. */
+    prefix?: string;
+    /** Path cursor from a prior page's `nextCursor`. */
+    cursor?: string;
+    limit?: number;
+    /** List AS OF a drive branch (e.g. a session's `session-<uuid>`). */
+    branch?: string;
+    /** Browse-at-head: a retained 64-hex commit of the MAIN drive (or, with
+     *  `branch`, a pin of that graph branch). The server answers 410
+     *  `at_unavailable` for a garbage-collected/unknown head. */
+    at?: string;
+}
+/** One page of `GET /factories/:slug/files`. */
+export interface FactoryFileListPage {
+    data: FactoryFileListRow[];
+    hasMore: boolean;
+    /** Pass as `cursor` to fetch the next page; null on the last page. */
+    nextCursor: string | null;
+    /** The pinned head this page was read at — non-null exactly when the
+     *  request carried `at`. `committedAt` is RFC3339 or null (unknown). */
+    at: {
+        head: string;
+        committedAt: string | null;
+    } | null;
+}
 export interface FactoryFileWriteResult {
     path: string;
     contentHash: string;
@@ -216,6 +256,27 @@ export interface FactoryRow {
     createdAt: string;
     updatedAt: string;
 }
+/** GET /factories/:slug/perf-summary — team-level sandbox perf aggregates
+ *  over a window (session_perf_rollups). Aggregate-only by design: sessions
+ *  are member-gated, so no conversation ids appear here; per-session detail
+ *  is the member-gated perf-history surface. */
+export interface FactoryPerfSummary {
+    /** The aggregated window, ISO 8601. */
+    from: string;
+    to: string;
+    /** Distinct sessions with any rollup bucket in the window. */
+    sessions: number;
+    /** Rollup buckets (15-min) in the window. */
+    buckets: number;
+    /** Guest samples folded into those buckets. */
+    samples: number;
+    cpu_busy_p95_max: number | null;
+    mem_used_p95_max: number | null;
+    disk_used_p95_max: number | null;
+    load1_max: number | null;
+    /** Total seconds any session sat ≥90% on a resource, summed. */
+    saturated_seconds: number;
+}
 export interface CreateFactoryInput {
     slug: string;
     name: string;
@@ -257,6 +318,48 @@ export interface SecretListEntry {
     createdAt: string;
     updatedAt: string;
 }
+/** One SESSION secret on the wire (metadata only — values are write-only).
+ *  `kind` 'value' = a session-own secret; 'factory' = an attachment by name
+ *  to the session factory's secret tier. `ownerUserId` is the user who set
+ *  it — only the owner or a team admin may replace/remove it. */
+export interface SessionSecretEntry {
+    secretKey: string;
+    kind: "value" | "factory";
+    ownerUserId: string;
+    /** Delivery mode (vault v2): 'injected' = the session env file;
+     *  'brokered' = an egress-ruleset header — the value never enters the
+     *  sandbox (call the host WITHOUT auth headers; the platform adds them). */
+    delivery: "injected" | "brokered";
+    /** Brokered entries: the API host the header rides on. */
+    brokerHost: string | null;
+    /** Non-null = an ephemeral use-and-scrub copy, and when its TTL lapses. */
+    ephemeralExpiresAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** One entry of a session-secret set: a literal value, or a factory
+ *  attachment by name (`source: "factory"`). */
+export type SessionSecretInput = {
+    key: string;
+    value: string;
+} | {
+    key: string;
+    source: "factory";
+};
+/** A freshly minted vault link (session secret request). `url` is the
+ *  single-use page a session writer opens to provide the named values. */
+export interface SessionSecretRequestCreated {
+    requestId: string;
+    url: string;
+    expiresAt: string;
+}
+/** A vault link's polled status. */
+export interface SessionSecretRequestStatus {
+    requestId: string;
+    status: "pending" | "fulfilled" | "cancelled" | "expired";
+    keys: string[];
+    expiresAt: string;
+}
 export interface CreateApiKeyInput {
     name?: string;
     scopes?: string[];
@@ -284,6 +387,25 @@ export interface ApiKey {
 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;
@@ -300,7 +422,10 @@ export interface UsageResponse {
     to: string | null;
 }
 /** 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;
@@ -310,25 +435,57 @@ 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/dist/types/api-runs.d.ts

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

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

package/dist/types/runtime.d.ts

@@ -12,6 +12,33 @@ export interface McpServerConfig {
     args?: string[];
     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,7 +74,33 @@ export interface RuntimeOptions {
         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";
@@ -114,6 +167,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/dist/types/workflow-metadata.d.ts

@@ -146,11 +146,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/sdk",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Client library for agent-compose — define agents, runtimes, and workflows, and invoke them against an agent-compose server.",
   "license": "MIT",
   "repository": {