@agent-compose/sdk 0.8.3 → 0.8.5

package/src/sandbox/providers/e2b.ts

@@ -5,7 +5,7 @@
  * registry entry.
  */
 
-import { Sandbox } from "e2b";
+import { Sandbox, Template } from "e2b";
 import type { CommandHandle } from "e2b";
 import type { Sandbox as Desktop } from "@e2b/desktop";
 import pRetry from "p-retry";
@@ -13,7 +13,7 @@ import type {
   SandboxProvider, SandboxCommandRunOptions, SandboxBackgroundProcess, SandboxPtyHandle,
 } from "../../types/sandbox.js";
 import { toE2bNetwork } from "../network-policy.js";
-import { DEFAULT_SANDBOX_SIZE, e2bBaseTemplate, isE2bSupportedSize } from "../sizes.js";
+import { DEFAULT_SANDBOX_SIZE, e2bAgentEnvTemplate, isE2bSupportedSize } from "../sizes.js";
 import { AGENT_COMPOSE_TAG } from "../provider-def.js";
 import type { OwnedSandbox, SandboxProviderDef } from "../provider-def.js";
 
@@ -104,6 +104,9 @@ export function e2bMaxSandboxMs(): number {
   return Number(process.env.E2B_MAX_SANDBOX_MS) || 60 * 60 * 1000;
 }
 
+/** Once-per-process latch for the extendLifetime clamp warning below. */
+let e2bExtendClampWarned = false;
+
 /** Wrap an E2B `CommandHandle` as a provider-agnostic background process.
  *  `wait()` is normalised NOT to throw on a non-zero exit (mirroring the
  *  `commands.run` contract in `makeSandboxProvider`) so callers branch on
@@ -245,7 +248,20 @@ function makeE2bSandboxProvider(sb: Sandbox): SandboxProvider {
     // the create timeout — an over-cap push would 400 and leave the OLD
     // (possibly short) deadline standing.
     async extendLifetime(ms) {
-      await sb.setTimeout(Math.min(ms, e2bMaxSandboxMs()));
+      const maxMs = e2bMaxSandboxMs();
+      if (ms > maxMs && !e2bExtendClampWarned) {
+        // Once per process, not per extension: every far-horizon push clamps
+        // identically, and the fact worth surfacing is the CONFIGURATION —
+        // the server believes it bought `ms` of kill-clock slack but the
+        // plan cap silently shortens it, so the "orphan backstop" can reap
+        // a machine the platform still considers covered.
+        e2bExtendClampWarned = true;
+        console.warn(
+          `[sandbox] e2b lifetime extension clamped: requested ${ms}ms exceeds the plan cap ${maxMs}ms — ` +
+          `the kill-clock backstop fires at the cap, not the requested horizon. Raise E2B_MAX_SANDBOX_MS on plans that allow more.`,
+        );
+      }
+      await sb.setTimeout(Math.min(ms, maxMs));
     },
     // Push a freshly-resolved egress policy onto the live sandbox via E2B's
     // native `updateNetwork` — the E2B analogue of Vercel's `update({
@@ -281,18 +297,24 @@ export const e2bProviderDef: SandboxProviderDef = {
   // E2B has no create-time resource knob (specs are baked into the
   // template/snapshot), so honouring `size` on E2B = picking a PRE-SIZED
   // template, not passing the field through. We resolve the boot template
-  // from `size` below (`e2bBaseTemplate(size)`) when the caller gave no
+  // from `size` below (`e2bAgentEnvTemplate(size)`) when the caller gave no
   // explicit template/bootFrom; the field itself is never forwarded to E2B.
   create: async ({ template, timeoutMs, networkPolicy, size, ...rest }) => {
     // `template` is an E2B template id/alias, a snapshot id (a valid create
     // source that persists beyond its origin sandbox — bootFrom parity), or
-    // absent. When absent we pick the SIZE-MATCHED platform base alias
-    // (`agent-compose-base-<size>`) so `resources.size` gives the same
-    // machine spec on E2B as on Vercel — the cross-provider parity this whole
-    // change exists for. Only when no size is resolvable at all do we fall
-    // back to E2B_DEFAULT_TEMPLATE if set (a prebuilt base — e.g. one with the claude CLI
-    // + chromium baked in and more RAM than the stock 482MB base), the
-    // per-deployment analogue of Vercel's node24; else E2B's stock base.
+    // absent. When absent we pick the SIZE-MATCHED platform agent-env alias
+    // (`agent-env-<size>`) — the SAME image every cloud session boots
+    // (server/src/sandbox/persistent.ts resolves the identical
+    // `e2bAgentEnvTemplate(size)`), so a template-less workflow run gets the
+    // full session toolchain (claude runtime, dev toolbelt, agentc, fsgw
+    // client) instead of a thinner image. One seam, both lanes: the
+    // session/run divergence that caused fleet-wide `exit 127`s (missing
+    // harness CLIs, fixed by on-demand install in v0.10.73) is structurally
+    // gone — there is no separate run-lane template to drift. The per-size
+    // aliasing also keeps `resources.size` giving the same machine spec on
+    // E2B as on Vercel (cross-provider parity). Only when no size is
+    // resolvable at all do we fall back to E2B_DEFAULT_TEMPLATE if set (the
+    // per-deployment analogue of Vercel's node24); else E2B's stock base.
     // Self-provisioning runtimes (claude/codex/amp via bootFrom:"reuse") install
     // their CLI on the base and cache it in the captured snapshot, so a
     // template-less first run boots, installs, snapshots. Clamp the lifetime to
@@ -317,28 +339,41 @@ export const e2bProviderDef: SandboxProviderDef = {
     const sandboxOpts = {
       ...rest,
       timeoutMs: Math.min(timeoutMs, maxMs),
+      // Lifetime-deadline expiry PAUSES instead of killing, and the next
+      // incoming connection auto-resumes (recycle forensics 2026-08-23:
+      // uncontrolled kill-clock loss was the dominant machine-end cause
+      // ~60:1 — under this policy a missed extension becomes a resumable
+      // park our redial paths revive). CREATE-time policy, persistent for
+      // the sandbox's life — connect() takes no lifecycle. NOTE: this is
+      // e2b's `lifecycle` contract, NOT the deprecated `autoPause` flag
+      // (which the create body would silently drop).
+      lifecycle: { onTimeout: "pause" as const, autoResume: true },
       ...(networkPolicy ? { network: toE2bNetwork(networkPolicy) } : {}),
     };
     // Boot template resolution, in priority order:
     //   1. explicit `template`/bootFrom (a pinned snapshot or alias),
-    //   2. else the SIZE-MATCHED base alias `agent-compose-base-<size>`
-    //      (`size` resolved to DEFAULT_SANDBOX_SIZE when unset) — this is the
-    //      cross-provider parity path,
+    //   2. else the SIZE-MATCHED agent-env alias `agent-env-<size>` — the
+    //      session-identical image (`size` resolved to DEFAULT_SANDBOX_SIZE
+    //      when unset). NEVER the legacy `agent-compose-base-<size>` — that
+    //      family remains a valid EXPLICIT bootFrom target only,
     //   3. else E2B_DEFAULT_TEMPLATE as an ultimate per-deployment fallback,
     //   4. else E2B's stock base.
-    // `32vcpu-64gb` has no base-<size> template (Pro caps ~8 vCPU); the
+    // `32vcpu-64gb` has no per-size template (Pro caps ~8 vCPU); the
     // register + invoke guards reject it before a run reaches here, so we
-    // never synthesize a non-existent `agent-compose-base-32vcpu-64gb` alias.
+    // never synthesize a non-existent `agent-env-32vcpu-64gb` alias.
     const resolvedSize = size ?? DEFAULT_SANDBOX_SIZE;
     const tmpl =
       template ??
-      (isE2bSupportedSize(resolvedSize) ? e2bBaseTemplate(resolvedSize) : undefined) ??
+      (isE2bSupportedSize(resolvedSize) ? e2bAgentEnvTemplate(resolvedSize) : undefined) ??
       process.env.E2B_DEFAULT_TEMPLATE;
     return makeE2bSandboxProvider(
       await (tmpl ? Sandbox.create(tmpl, sandboxOpts) : Sandbox.create(sandboxOpts)),
     );
   },
   reconnect: async (sandboxId) => makeE2bSandboxProvider(
+    // The pause-on-timeout policy is create-time and persistent — connect
+    // takes no lifecycle options (the old per-connect autoPause flag is
+    // deprecated API-side).
     await Sandbox.connect(sandboxId, { apiKey: process.env.E2B_API_KEY ?? "", timeoutMs: 60 * 60 * 1000 }),
   ),
   killAll: async () => {
@@ -355,4 +390,41 @@ export const e2bProviderDef: SandboxProviderDef = {
     // E2B snapshots are team-scoped; delete by id. Best-effort like Vercel's.
     await Sandbox.deleteSnapshot(snapshotId, { apiKey: env.E2B_API_KEY });
   },
+  snapshotExists: async (snapshotId, env) => {
+    // Existence probe for a CREATE SOURCE (the `snapshotResolves` contract:
+    // `true` = resolves, `false` = the provider definitively says it does not
+    // exist, anything indeterminate PROPAGATES — never reported as missing).
+    //
+    // e2b 2.30.5 has no GET-snapshot-by-id, so this composes the two
+    // documented lookups, cheapest first:
+    //   1. `Template.exists` — ONE round-trip to the template-existence
+    //      endpoint (`GET /templates/aliases/{alias}`), with DOCUMENTED
+    //      not-found semantics: 404 → false, 403 → exists but owned by
+    //      another team → true (the SDK's own mapping). Snapshots are
+    //      templates provider-side, and this probe also resolves the
+    //      `agent-env-*` template ALIASES that E2B-pinned default templates
+    //      register as their bootFrom — boot-time platform validation
+    //      (validatePlatformSnapshots) probes those through this same seam,
+    //      so a snapshots-only lookup would falsely alert "unresolvable" on
+    //      every alias.
+    //   2. A paged scan of the team's snapshot list (`Sandbox.listSnapshots`)
+    //      — authoritative for `createSnapshot` artifacts whatever their id
+    //      shape, reached only when the template probe answered not-found.
+    //      Bounded by the team's snapshot count (session rings are GC'd to a
+    //      fixed retain depth), and this is rare-path code: machine-loss
+    //      recovery and boot validation, never a hot loop.
+    // `false` therefore means BOTH documented lookups answered not-found.
+    // (`Sandbox.listSnapshots({ sandboxId })` — source-filtered — was
+    // rejected as the primary: callers hold only the snapshot id, and a
+    // filtered miss would still need the full scan before "absent" is
+    // honest.) Transport/auth faults from either call throw — indeterminate.
+    const opts = { apiKey: env.E2B_API_KEY };
+    if (await Template.exists(snapshotId, opts)) return true;
+    const paginator = Sandbox.listSnapshots(opts);
+    while (paginator.hasNext) {
+      const items = await pRetry(() => paginator.nextItems(), { retries: 3, minTimeout: 500, factor: 2 });
+      if (items.some((s) => s.snapshotId === snapshotId || s.names.includes(snapshotId))) return true;
+    }
+    return false;
+  },
 };

package/src/sandbox/registry.ts

@@ -6,7 +6,7 @@
  * at creation time.
  */
 
-import { SandboxNotFoundError, RateLimitError } from "e2b";
+import { SandboxNotFoundError, RateLimitError, NotFoundError } from "e2b";
 import pRetry from "p-retry";
 import type { FailedAttemptError } from "p-retry";
 import type { SandboxProvider } from "../types/sandbox.js";
@@ -45,6 +45,24 @@ function isTransientSandboxError(error: unknown): boolean {
     .test(message);
 }
 
+/** Did a CREATE fail because its create SOURCE (template alias / snapshot id)
+ *  does not resolve on the provider — vs any other create fault? The server's
+ *  recovery-boot fall-through keys on this: a ring snapshot licensed on an
+ *  INDETERMINATE existence probe that turns out to be gone must fall through
+ *  the ring toward the base image, while every other create fault (quota,
+ *  auth, 5xx, network) must propagate — falling through on those would trade
+ *  a still-recoverable machine state for a base boot. E2B maps the create-
+ *  time 404 ("template not found") to its typed `NotFoundError`; the message
+ *  match is the fallback for untyped transports (Vercel). Lives in the SDK
+ *  because the server holds its OWN `e2b` module instance — an `instanceof`
+ *  against the class from the wrong copy is always false. */
+export function isSandboxSourceNotFoundError(error: unknown): boolean {
+  if (error instanceof NotFoundError) return true;
+  const message = error instanceof Error ? error.message : String(error ?? "");
+  return /(?:template|snapshot)[^\n]{0,80}not[\s_-]?found|not[\s_-]?found[^\n]{0,80}(?:template|snapshot)/i
+    .test(message);
+}
+
 /** The ONE place the sandbox retry policy lives. Provisioning, reconnecting, and
  *  snapshotting all race with the sandbox being paused/reclaimed; this runs the call
  *  through p-retry's generic backoff, retrying ONLY the transient race (and failing

package/src/sandbox/sizes.ts

@@ -148,15 +148,21 @@ export function sandboxSizeLabel(size: SandboxSize): string {
 /** Stable E2B template ALIAS for the platform base at a given size
  *  (`agent-compose-base-<size>`). Aliases — not snapshot ids — so the refs are
  *  multi-account-clean: the same string resolves in any E2B account that built
- *  the templates. Built by `infra/e2b-template/build.ts`; the E2B provider
- *  boots this when a run on E2B declares no explicit `bootFrom`/template. */
+ *  the templates. Built by `infra/e2b-template/build.ts`. An EXPLICIT
+ *  `bootFrom`/template target only — nothing boots it by default: template-less
+ *  E2B creates resolve `e2bAgentEnvTemplate` (the session-identical image)
+ *  instead, so the run and session lanes can never diverge on baked tooling. */
 export function e2bBaseTemplate(size: SandboxSize): string {
   return `agent-compose-base-${size}`;
 }
 
-/** Stable E2B template ALIAS for the agent runtime (base + claude binary) at a
- *  given size (`agent-env-<size>`). The agent default templates boot from this
- *  via `bootFrom: { snapshotId: e2bAgentEnvTemplate(size) }`. Multi-account-clean
+/** Stable E2B template ALIAS for the agent runtime (base + claude binary +
+ *  dev toolbelt + session desktop) at a given size (`agent-env-<size>`).
+ *  THE default E2B boot image, both lanes: every cloud SESSION boots it
+ *  (server/src/sandbox/persistent.ts), and every template-less E2B workflow
+ *  RUN boots it too (the e2b provider's size-matched default). The agent
+ *  default templates boot from this via
+ *  `bootFrom: { snapshotId: e2bAgentEnvTemplate(size) }`. Multi-account-clean
  *  for the same reason as `e2bBaseTemplate`. */
 export function e2bAgentEnvTemplate(size: SandboxSize): string {
   return `agent-env-${size}`;

package/src/sandbox.ts

@@ -54,7 +54,7 @@ export type { SandboxCreateOpts, OwnedSandbox } from "./sandbox/provider-def.js"
 export { parseSseExecStream } from "./sandbox/exec-stream.js";
 export type { ParseSseExecStreamOptions } from "./sandbox/exec-stream.js";
 
-export { makeSandboxProvider } from "./sandbox/providers/e2b.js";
+export { makeSandboxProvider, e2bMaxSandboxMs } from "./sandbox/providers/e2b.js";
 export { makeDesktopSandboxProvider } from "./sandbox/providers/desktop.js";
 export { VERCEL_MAX_TAGS, buildVercelTags } from "./sandbox/providers/vercel.js";
 export { makeLocalSandboxProvider } from "./sandbox/providers/local.js";
@@ -65,6 +65,7 @@ export {
   reconnectSandbox,
   deleteSandboxSnapshot,
   snapshotResolves,
+  isSandboxSourceNotFoundError,
   getSandboxQuotas,
   listOwnedSandboxes,
   killSandboxById,

package/src/types/api-conversations.ts

@@ -430,6 +430,49 @@ export interface BackgroundWorkHeld {
   leaseUntil: string;
 }
 
+/** One background CHILD declared beside the busy lease (task #63): a
+ *  detached process, by pid, with its durable journal/log file — what lets
+ *  the platform VERIFY the work (`/proc/<pid>` + journal mtime) and
+ *  reattach it after a park instead of losing it. */
+export interface BackgroundWorkChildDecl {
+  pid: number;
+  /** Absolute guest-side path to the child's own durable output/journal
+   *  file — its mtime is the progress evidence. */
+  journalPath?: string;
+  label?: string;
+}
+
+/** Outcome of requesting one machine size up
+ *  (`POST /conversations/:id/machine/request-upsize` — task #110, the
+ *  auto-resize policy's agent door). The platform arbitrates: within the
+ *  team's daily cap the upsize is auto-granted (and lands immediately when
+ *  no turn/background work holds the machine); past it a human approval
+ *  card is posted. Wire shape mirrors
+ *  server/src/sandbox/session-auto-resize.ts `UpsizeRequestOutcome`. */
+export interface MachineUpsizeOutcome {
+  /** "executed" (landed now), "granted" (lands when the work settles),
+   *  "pending_approval" (a card awaits the owner). Refusals arrive as HTTP
+   *  errors carrying `code`. */
+  outcome: "executed" | "granted" | "pending_approval";
+  /** The size the grant/card names (e.g. "4vcpu-8gb"). */
+  size: string;
+  approvalId: string;
+  /** One human-readable line the CLI can print verbatim. */
+  message: string;
+}
+
+/** The session's background-work status
+ *  (`GET /conversations/:id/background-work`). */
+export interface BackgroundWorkStatus {
+  /** ISO deadline of the live lease, or null (no lease held). */
+  leaseUntil: string | null;
+  /** The declared children (each with its server-stamped `declaredAt`). */
+  children: Array<BackgroundWorkChildDecl & { declaredAt: string }>;
+  /** Non-null when a mid-work park froze declared children and the session
+   *  still owes its conversation a status report (ISO park instant). */
+  frozenAt: string | null;
+}
+
 // ── 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. Wire shapes mirror
@@ -511,11 +554,9 @@ export interface SessionChangeSet {
    *  (hard cap 2; a manual re-review resets it). */
   reviewAutoFollowup?: boolean;
   reviewAutoRounds?: number;
-  /** The OPT-IN main-advance auto-rebase reflex (additive — absent on
-   *  older servers; default OFF): armed ⇒ when main moves and a preflight
-   *  proves the fold clean, the platform rebases this session's branch
-   *  from main headlessly. Toggled via `setSessionAutoRebase`. */
-  autoRebaseFromMain?: boolean;
+  /** The session's selectable cap on automatic follow-up rounds (additive
+   *  — absent on older servers; default 2, range 1..5). */
+  reviewAutoRoundsMax?: number;
   /** STRUCTURED review suggestions beside the notes (additive — absent on
    *  older servers): individually actionable {id, path, title, rationale,
    *  patch} entries the review session wrote back, status-stamped
@@ -793,14 +834,6 @@ export interface SessionRebaseReport {
   foldSkipped?: boolean;
 }
 
-/** Result of `POST /conversations/:id/changes/autorebase` — the opt-in
- *  main-advance auto-rebase reflex's new state. */
-export interface SessionAutoRebaseState {
-  object: "session_autorebase";
-  conversationId: string;
-  autoRebaseFromMain: boolean;
-}
-
 /** The sender's page stamp (HUD bar sends) — persisted server-side, never
  *  echoed back on the wire. Mirrors the server's `PageContext` schema. */
 export interface ConversationPageContext {
@@ -1004,3 +1037,22 @@ export interface StreamConversationOptions {
   lastEventId?: number;
   signal?: AbortSignal;
 }
+
+/** Shared chat creation includes its own Ivy unless explicitly disabled. */
+export interface CreateChatInput {
+  title?: string;
+  visibility: "shared";
+  access?: "public" | "private";
+  memberIds?: string[];
+  includeIvy?: boolean;
+}
+export interface ChannelIvyState {
+  projects: Array<{ id: string; name: string }>;
+  agent: AgentListRow | null;
+  enabled: boolean; agentId: string | null; canManage: boolean; nextReviewAt: string | null;
+  work: Array<{ id: string; title: string; status: string; evidence: string; nextAction: string; waitingOn: string | null; reviewAt: string | null }>;
+}
+export interface ProjectIvyConnection {
+  id: string; teamId: string; projectId: string; provider: "github"; installationId: string;
+  accountLogin: string; repositories: string[]; allowWrites: boolean; configuredBy: string | null; updatedAt: string;
+}

package/src/types/api-factory.ts

@@ -107,9 +107,15 @@ export interface RegisterWorkflowInput {
 export interface TemplateRow {
   name: string;
   version: string;
-  factorySlug: string;
+  /** Owning factory's slug. `null` on platform-published rows — a published
+   *  default belongs to no single factory and is invokable via any slug. */
+  factorySlug: string | null;
   /** Share scope (ADR-0045) — `null` = unscoped/grandfathered team tier. */
   scope: ArtifactScope | null;
+  /** `factory` = registered in a factory of the caller's team; `published` =
+   *  platform default (team-wide read+invoke in EVERY factory, never write;
+   *  fork it to edit under a new name). Optional: older servers omit it. */
+  origin?: "factory" | "published";
 }
 
 /** Template detail (`GET /factories/:slug/templates/:name`) — the typed
@@ -132,6 +138,17 @@ export interface ListTemplatesOptions {
   factorySlug?: string;
 }
 
+/** One team connector grant, as `GET /api/v1/connectors` returns it (wire
+ *  shape verbatim — snake_case). The typed subset the SDK pins; additional
+ *  fields flow through untyped. */
+export interface ConnectorGrantSummary {
+  id: string;
+  provider: string;
+  external_account_label: string | null;
+  status: "active" | "revoked" | "reauth_required";
+  connected_by_user_id: string;
+}
+
 // ── Factory-file search (wire shape mirrors routes/factory-files.ts) ────────
 
 /** Public "anyone with the link" state — the additive `public` field on file
@@ -381,6 +398,27 @@ export interface SessionSecretRequestCreated {
   requestId: string;
   url: string;
   expiresAt: string;
+  /** True = a standing auto-approve set already filled the request at the
+   *  mint — nothing is pending; source the session env now. */
+  autoApproved?: boolean;
+}
+
+/** What KIND of credential a vault request asks for (advisory): the vault
+ *  page leads with the user's MATCHING standing entries. */
+export type VaultRequestKind =
+  | "login" | "password" | "api_key" | "payment_card" | "env_file" | "note" | "other";
+
+/** One STANDING vault entry usable for a session (the catalog read,
+ *  2026-08-31) — labels, kinds, and field NAMES only; values are write-only
+ *  and never on this wire. */
+export interface VaultCatalogEntry {
+  label: string;
+  kind: string;
+  fieldKeys: string[];
+  via: "owner" | "member" | "project";
+  ownerName: string | null;
+  projectName: string | null;
+  lastUsedAt: string | null;
 }
 
 /** A vault link's polled status. */
@@ -389,6 +427,26 @@ export interface SessionSecretRequestStatus {
   status: "pending" | "fulfilled" | "cancelled" | "expired";
   keys: string[];
   expiresAt: string;
+  /** Cancellation attribution (task #111) — present on cancelled rows:
+   *  who ended the ask ('human' = denied; 'agent' = withdrawn) and why. */
+  cancelledVia?: "human" | "agent";
+  cancelReason?: string | null;
+  /** The denying human's display name (best-effort; 'human' via only). */
+  deniedByName?: string | null;
+  /** Newest USER message in the session SINCE the mint (pending rows only)
+   *  — the chat-interrupt probe: the human may be answering in chat while
+   *  the agent blocks on --wait. */
+  userMessageAt?: string;
+}
+
+/** One OPEN vault request, as the list endpoint returns it — receipts
+ *  only (keys + reason + clocks), never values. */
+export interface SessionSecretRequestSummary {
+  requestId: string;
+  keys: string[];
+  reason: string | null;
+  expiresAt: string;
+  createdAt: string;
 }
 
 export interface CreateApiKeyInput {
@@ -515,6 +573,23 @@ export interface DriveRepoLink {
  *  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. */
+/** POST /factories/:slug/repo-links/native — a repo whose origin IS the
+ *  platform git plane (no GitHub side). `name` is ONE segment of GitHub's
+ *  repo alphabet; `dirPrefix` defaults to `repos/<name>`. */
+export interface CreateNativeRepoInput {
+  name: string;
+  dirPrefix?: string;
+}
+
+export interface CreateNativeRepoResult {
+  link: DriveRepoLink;
+  /** Stock-git clone/push URL on the platform origin (credentials are
+   *  minted per operation by `agentc repos git-credential --link`). */
+  repoUrl: string;
+  /** The CLI one-liner: `agentc repos clone <id> --via origin`. */
+  cloneCommand: string;
+}
+
 export interface CreateDriveRepoLinkInput {
   dirPrefix:     string;
   repoFullName:  string;
@@ -524,3 +599,48 @@ export interface CreateDriveRepoLinkInput {
   /** Two-way sync ("push-out") — defaults to TRUE for new links. */
   pushOut?:      boolean;
 }
+
+/** A retained merge conflict. Resolution edits a live session branch;
+ * publication still goes through its normal merge and approval gates. */
+/** A project-scoped secret's METADATA (scoped-secrets spec §4.1) — names
+ * only; values are write-only. Reaches SESSIONS linked into the project whose
+ * owner is a live member; workflow runs never receive project secrets. */
+export interface ProjectSecretMeta {
+  id: string;
+  projectId: string;
+  secretKey: string;
+  createdBy: string | null;
+  delivery: "injected" | "brokered";
+  brokerHost: string | null;
+  brokerHeaderName: string | null;
+  brokerHeaderScheme: string | null;
+  createdAt: string | null;
+  updatedAt: string | null;
+}
+
+export interface ProjectSecretList {
+  secrets: ProjectSecretMeta[];
+  tier: "project";
+  audience: "sessions";
+}
+
+export interface FactoryFileConflict {
+  id: string;
+  path: string;
+  conversationId: string | null;
+  runId: string | null;
+  runLabel: string | null;
+  reason: "same_region" | "binary" | "delete_vs_edit";
+  oursHash: string | null;
+  theirsHash: string | null;
+  baseHash: string | null;
+  status: string;
+  createdAt: string;
+  resolvesTo: "branch" | "main";
+}
+export interface FactoryFileConflictList {
+  object: "list";
+  data: FactoryFileConflict[];
+  has_more: boolean;
+  next_cursor: string | null;
+}

package/src/types/conversation-stream.ts

@@ -130,6 +130,15 @@ export interface ConversationTurnStateEvent {
   pendingCount: number;
   at: number;
   partial: true;
+  /** When the open turn started (ms) — carried by the connect-time
+   *  snapshot frame only; absent on live transition frames. */
+  startedAt?: number | null;
+  /** The session holds a live background-work lease (snapshot frames
+   *  only). */
+  leaseHeld?: boolean;
+  /** The open turn is blocked on a HUMAN ask — an open vault/secret
+   *  request or approval (snapshot frames only). */
+  blockedOnAsk?: "secrets" | "approval" | null;
 }
 
 /** One attached surface (a dashboard tab, an `agentc session` TUI process)
@@ -185,6 +194,19 @@ export interface ConversationSessionStatusEvent {
   at: number;
 }
 
+/** Live-only tool-run pulse (2026-08-29): the running turn's guest session
+ *  PROVED progress (CPU/output counters advanced between heartbeat pulse
+ *  samples) while the stream was otherwise silent — a long foreground tool
+ *  (`bun install`) is working. Emitted at the executor's evidence-tick
+ *  cadence, only on proof; carries no output content. Same contract as
+ *  `turn_state`: never persisted, never advances `Last-Event-ID`. */
+export interface ConversationToolPulseEvent {
+  event: "tool_pulse";
+  conversationId: string;
+  advancing: true;
+  at: number;
+}
+
 export type ConversationStreamEvent =
   | ConversationPartEvent
   | ConversationPartPartialEvent
@@ -195,7 +217,8 @@ export type ConversationStreamEvent =
   | ConversationReplayContinueEvent
   | ConversationTurnStateEvent
   | ConversationPresenceEvent
-  | ConversationSessionStatusEvent;
+  | ConversationSessionStatusEvent
+  | ConversationToolPulseEvent;
 
 /**
  * Fold one parsed SSE frame into a `ConversationStreamEvent`.