@agent-compose/sdk 0.8.2 → 0.8.4

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;