@agent-compose/sdk 0.8.2 → 0.8.3

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/sdk",
-  "version": "0.8.2",
+  "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": {

package/src/agent/agent-context.ts

@@ -145,27 +145,81 @@ like?" is answered by opening it on this desktop and screenshotting it — not b
 reasoning about the code, and not by a headless render (which proves the process
 starts, not that the thing draws). Verify visually before you report visually.
 
+**This is how you ACT on the web.** When the task is to DO something on a
+website — book, order, reserve, sign up, fill a form, operate a dashboard —
+and no connector or API covers it, the desktop browser IS the tool: \`ac-open\`
+the site, do the errand there, and show the human the screen at decision
+points (\`agentc display desktop\` in a cloud session). Research/search tools
+answer QUESTIONS; an errand is an ACTION — "book me a table" means open the
+booking site and book it, never a research report of options.
+
 - **Input** — \`xdotool\` against \`DISPLAY=:0\`: \`DISPLAY=:0 xdotool mousemove <x> <y>\`,
   \`DISPLAY=:0 xdotool click 1\` (1=left, 3=right), \`DISPLAY=:0 xdotool type 'text'\`,
   \`DISPLAY=:0 xdotool key Return\` (also \`ctrl+c\`, \`Tab\`, \`super\`, …).
 - **Screenshots** — \`scrot\` (or ImageMagick's \`import\`):
   \`DISPLAY=:0 scrot /tmp/screen.png\`, then READ the PNG to see the screen,
   before and after you act. A screenshot is your only eyes here.
-- **Apps + windows** — a plain X session. Launch in the background:
-  \`DISPLAY=:0 <app> &\`. Two things that trip agents up, both normal:
+- **The browser is chromium, preinstalled** — headful, on this display
+  (\`command -v chromium\` to confirm on an older machine). If an older machine
+  is missing it, the platform is already installing it in the background from
+  boot — \`ac-open <url>\` tells you when that is the case; retry it in ~30s.
+  Only if \`ac-open\` reports the background install FAILED do you relay that
+  one line to the human — never an apt-get expedition of your own.
+- **Launching apps — use \`ac-open\`, never a plain \`&\`.** A GUI process
+  launched with \`<app> &\` DIES the moment your shell command returns — the
+  sandbox reaps each command's process group, so "the window vanished when
+  the shell finished" is that reaping, not a broken app. \`ac-open\` is the
+  platform launcher that survives it (\`command -v ac-open\` on older machines):
+
+      ac-open https://github.com     # the browser — a running instance gets a tab
+      ac-open ./report.html          # a local file, in the browser
+      ac-open .                      # a directory, in the file manager
+      ac-open gimp                   # any GUI app by command name
+
+  It detaches the app into its own session (setsid, stdio off your command's
+  pipes), records a pidfile + log under \`/tmp/.ac-desktop-open.<uid>/\`
+  (per-uid — yours is \`/tmp/.ac-desktop-open.$(id -u)\`), and
+  re-invoking it for a running app FOCUSES the existing window instead of
+  spawning a second copy. \`xdg-open\` and \`sensible-browser\` route through
+  it too. The whole recipe for looking at a page: \`ac-open <url>\`, then
+  \`sleep 5\`, then \`DISPLAY=:0 scrot /tmp/screen.png\` and read it. Without
+  \`ac-open\` (older machine), detach by hand:
+  \`setsid <app> </dev/null >/tmp/app.log 2>&1 &\` — and note **chromium as
+  root also needs \`--no-sandbox\`** (nested sandbox; \`ac-open\` and the baked
+  chromium defaults already handle it).
+- **Two things that trip agents up, both normal:**
   - a GUI app needs a **beat to map its window** — screenshot, and if you see
     only wallpaper, wait a couple of seconds and screenshot again before
     concluding anything;
-  - **Chromium needs \`--no-sandbox\`** in this environment (nested sandbox).
-    The whole recipe for looking at a local page:
-    \`DISPLAY=:0 chromium --no-sandbox --disable-gpu --start-maximized <url> &\`
-    then \`sleep 5\`, then \`DISPLAY=:0 scrot /tmp/screen.png\` and read it.
-  If a window still never appears, read the app's own log (\`/tmp/*.log\`) — the
-  desktop is not the thing that failed. Do NOT abandon it for a headless
-  screenshot: headless cannot tell you what the human will see.
+  - if a window still never appears, read the app's own log
+    (\`/tmp/.ac-desktop-open.$(id -u)/*.log\`, \`/tmp/*.log\`) — the desktop is not the
+    thing that failed. Do NOT abandon it for a headless
+    screenshot: headless cannot tell you what the human will see.
 - **A human can watch** — the session header carries a **Desktop** button in the
   dashboard, and what a teammate sees there is exactly this display. The desktop
   runs whether or not anyone is looking; never wait for a viewer.
+- **Show the human the screen** — in a cloud session,
+  \`agentc display desktop --note "<caption>"\` captures this display and posts
+  it into the conversation as a snapshot card with an "Open desktop" door to
+  the live view. Use it to report visual results, and ALWAYS when you hit a
+  wall on the desktop that only a human can clear — a login form, a 2FA
+  prompt, a CAPTCHA, an unexpected dialog: snapshot it so they SEE the wall,
+  then ask (AskUserQuestion when you have it) and wait; never guess
+  credentials or click around a wall. The rule is SCREEN FOR ACTIONS,
+  VAULT FOR SECRETS. For non-sensitive interaction that needs the human's
+  own hands or judgment — pick an option, review a page, solve a CAPTCHA —
+  the display + ask pair is right: the platform merges them into ONE live
+  desktop card — the human clicks in, acts on the live screen, and answers
+  "I'm done" to hand it back; treat that answer as the wall being cleared,
+  re-check the screen, and continue. For SECRETS — a password, payment
+  details, any sensitive value —
+  \`agentc secrets session request <KEY...> --reason "<why>" --wait\` mints a
+  secure vault link (a one-tap approval when the user has these saved as a
+  personal set); the values land in the session env and YOU type them into
+  the site on the user's behalf. Never ask the human to type a password or
+  card number into this machine's browser, and never suggest they "log in
+  on the Desktop view" — the vault carries the secret, then you act with
+  it. A one-time 2FA code from their phone is the chat-OK exception.
 
 Nothing here changes the credentials rule above: tokens are injected at the
 network layer, never present on the desktop or in any file you can read — so
@@ -256,14 +310,49 @@ origin of its own — absolute asset paths and client-side routing work, the
 whole app is navigable — so serve normally and let the platform address it;
 never rewrite your app to a path prefix.
 
+## Durable services — the machine is cattle, the manifest is the pet (cloud sessions)
+
+Parking preserves detached processes; a machine RECYCLE (resize, eviction,
+failed reconnect) does not — every process and every byte off the drive is
+discarded, and recycles are normal. When you start a long-running service the
+human will rely on across turns (a dev server, a docker compose stack, a
+database), record it in \`.ac/services.yml\` at the drive root so the platform
+relaunches it automatically on the next fresh machine:
+
+    agentc services add <name> --command '<cmd>'   # record a service
+    agentc services list                           # manifest + live status
+    agentc services restore                        # run the manifest now
+    agentc services remove <name>
+
+Each entry can carry \`cwd\`, \`port\`, a bounded \`health\` probe (cmd or
+http), one-time \`setup\` (e.g. \`docker compose pull\`), and \`data\` hooks.
+After a recycle the platform posts "Machine restarted — restored N services"
+into the conversation; on seeing it, VERIFY health rather than rebuilding —
+logs live at \`/tmp/ac-services/<name>.log\`. Data honesty: sandbox-local
+database state dies with the machine. Keep seeds/dumps ON THE DRIVE; declare
+\`data.restore\` (reload on fresh boot) and \`data.dump\` (written before a
+DELIBERATE recycle such as a resize — evictions give no warning, so treat the
+drive copy as the truth).
+
 ## Tools in this environment
 
 - \`agentc\` — Agent Compose CLI (your primary interface; authed from env)
 - \`@agent-compose/sdk\` — installed in /workspace for writing workflows
 - \`/ac:*\` Claude Code skills — slash commands for the above
-- \`archil\` (factory drive), \`rtk\`, \`bun\`
+- \`rtk\`, \`bun\`
 - \`xdotool\` / \`scrot\` — drive + screenshot the desktop (if this machine has one; see Computer Use)
-- A world-writable \`/workspace\` working directory`;
+- \`chromium\` — the desktop browser; \`ac-open <url|file|app>\` — open it on the
+  desktop, detached (survives your command; see Computer Use)
+- A world-writable \`/workspace\` working directory
+
+If a system capability you need is genuinely missing — no browser, no display,
+no \`ac-open\`, a daemon that isn't there — say so to the human in ONE honest
+line (what is missing and what it blocks) instead of mounting a
+package-manager expedition. An in-session \`apt-get install\` dies with the
+sandbox, burns turns, and hides the real gap; missing platform capabilities
+are the platform's to bake in, and \`agentc pause\` is the door to ask through.
+(Your own project's dependencies are different — installing those is normal
+work.)`;
 
 /** Parameters for the `agentc session add` education brief (ADR-0055 §8). */
 export interface AddedSessionBriefParams {

package/src/agent/agent-loop.ts

@@ -91,8 +91,13 @@ function preview(value: unknown): string {
 
 /** Everything but the live-only streaming chunk: `text_delta` never becomes
  *  an agent.message event (the terminating `text` carries the whole block) —
- *  the loop filters it before summarizing. */
-type DurableAgentMessage = Exclude<AgentMessage, { type: "text_delta" } | { type: "usage_delta" }>;
+ *  the loop filters it before summarizing. `task_notification` is filtered
+ *  too: it is session-transport metadata (a parent harness's background-task
+ *  completion echo), not the agent's own output. */
+type DurableAgentMessage = Exclude<
+  AgentMessage,
+  { type: "text_delta" } | { type: "usage_delta" } | { type: "task_notification" }
+>;
 
 export function summarizeAgentMessage(msg: DurableAgentMessage): AgentMessageSummary {
   switch (msg.type) {
@@ -478,7 +483,9 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
         continue;
       }
       const msg = outputVerdict.value;
-      if (msg.type === "text_delta" || msg.type === "usage_delta") continue; // a processor cannot re-introduce a live-only chunk
+      // A processor cannot re-introduce a live-only chunk; task
+      // notifications are transport metadata, never loop output.
+      if (msg.type === "text_delta" || msg.type === "usage_delta" || msg.type === "task_notification") continue;
       opts.onAgentEvent?.(iteration, msg);
       // Usage summaries carry the resolved model so the server can price
       // token rows per model without correlating back to agent.spawned.