◌
Your local agent, in the browser.
diff --git a/crates/tui/src/runtime_web/styles.css b/crates/tui/src/runtime_web/styles.css
index 047d21b3dd..0f37512145 100644
--- a/crates/tui/src/runtime_web/styles.css
+++ b/crates/tui/src/runtime_web/styles.css
@@ -34,6 +34,7 @@ body {
width: 100%;
min-width: 280px;
height: 100%;
+ height: var(--vv-height, 100dvh);
margin: 0;
overflow: hidden;
background: var(--ink-0);
@@ -1009,6 +1010,24 @@ noscript {
}
}
+@media (pointer: coarse) {
+ .icon-button,
+ .quiet-button,
+ .primary-button,
+ .send-button,
+ .new-thread,
+ .thread-row,
+ .answer-option,
+ .rail-open,
+ .rail-close {
+ min-height: 44px;
+ }
+
+ .answer-option {
+ padding: 12px 14px;
+ }
+}
+
@media (prefers-reduced-motion: reduce) {
*,
*::before,
diff --git a/crates/tui/src/tools/subagent/mod.rs b/crates/tui/src/tools/subagent/mod.rs
index 34c59a6537..0b79b07569 100644
--- a/crates/tui/src/tools/subagent/mod.rs
+++ b/crates/tui/src/tools/subagent/mod.rs
@@ -1574,6 +1574,9 @@ pub(crate) struct SubAgentSpawnOptions {
/// Checkpoint resume: preserve the interrupted child's runtime posture
/// instead of rebuilding it from the caller's role.
pub preserve_runtime_profile: Option
,
+ /// When true, the child is independently durable across parent-turn
+ /// cancellation. Default false binds the child to the initiating turn.
+ pub detached: bool,
}
#[derive(Debug, Clone)]
@@ -1808,6 +1811,10 @@ struct SpawnRequest {
/// → verify). The source must be settled (not running), in the same
/// workspace, and reachable by the spawning agent.
resume_from: Option,
+ /// When true, the child uses an independent cancellation token and survives
+ /// parent-turn cancellation. Default false: the child is owned by the
+ /// initiating turn and is cancelled+joined before `TurnComplete`.
+ detached: bool,
}
/// Declared child write authority for a (deliberate) spawn.
@@ -2747,6 +2754,9 @@ pub struct SubAgent {
work_lifecycle: Option,
input_tx: Option>,
task_handle: Option>,
+ /// Independently durable across parent-turn cancellation when true.
+ /// Default direct spawns are turn-owned (`false`).
+ detached: bool,
}
impl SubAgent {
@@ -2792,6 +2802,7 @@ impl SubAgent {
work_lifecycle: None,
input_tx: Some(input_tx),
task_handle: None,
+ detached: false,
}
}
@@ -3906,6 +3917,9 @@ impl SubAgentManager {
work_lifecycle: None,
input_tx: None,
task_handle: None,
+ // Restored records have no live task; treat as detached so a
+ // later turn-end join cannot mistake them for turn-owned work.
+ detached: true,
};
self.agents.insert(persisted.id, agent);
}
@@ -4738,6 +4752,45 @@ impl SubAgentManager {
self.get_result(&agent_id)
}
+ /// Cancel every turn-owned (non-detached) running child and await its task
+ /// handle. Detached children keep their own tokens and are left alone.
+ ///
+ /// The engine calls this before emitting `TurnComplete` so foreground
+ /// children cannot outlive the turn that owns them.
+ pub async fn cancel_and_join_turn_owned_agents(&mut self) {
+ let turn_owned: Vec = self
+ .agents
+ .iter()
+ .filter(|(_, agent)| {
+ !agent.detached
+ && agent.status == SubAgentStatus::Running
+ && !agent.completion_claimed
+ })
+ .map(|(id, _)| id.clone())
+ .collect();
+
+ let mut join_handles = Vec::new();
+ for agent_id in turn_owned {
+ let Some(agent) = self.agents.get_mut(&agent_id) else {
+ continue;
+ };
+ if let Some(handle) = agent.task_handle.take() {
+ handle.abort();
+ join_handles.push(handle);
+ }
+ let mut terminal = agent.snapshot();
+ terminal.status = SubAgentStatus::Cancelled;
+ terminal.result = Some("Cancelled because the owning parent turn ended.".to_string());
+ terminal.needs_input = None;
+ // Handle already taken above; abort_task=false avoids a second take.
+ let _ = self.finish_terminal_result(&agent_id, terminal, false, true);
+ }
+
+ for handle in join_handles {
+ let _ = handle.await;
+ }
+ }
+
/// Queue parent mail without waking the child (`agents/message`).
pub fn queue_parent_message(
&mut self,
@@ -5035,8 +5088,8 @@ impl SubAgentManager {
child_route,
)
};
- // Resume runs at child depth with a detached cancellation token, the
- // same seam a fresh spawn uses; fail closed on the depth ceiling.
+ // Resume runs at child depth with a detached cancellation token so the
+ // continuation survives the parent turn that requested the resume.
// Checked on the parent runtime before derivation, matching the
// fresh-spawn order (would_exceed_depth at the spawn seam).
if runtime.would_exceed_depth() {
@@ -5065,6 +5118,7 @@ impl SubAgentManager {
.unwrap_or(false),
claim_pre_namespaced: claim.is_some(),
preserve_runtime_profile: preserved_profile,
+ detached: true,
..Default::default()
};
let resumed = self.spawn_background_with_assignment_options(
@@ -5525,6 +5579,7 @@ impl SubAgentManager {
agent.session_name = name.to_string();
}
agent.fork_context = options.fork_context;
+ agent.detached = options.detached;
let agent_id = agent.id.clone();
let started_at = agent.started_at;
let tool_profile = match tools.clone() {
@@ -7083,11 +7138,44 @@ enum AgentToolAction {
}
fn parse_agent_tool_action(input: &Value) -> Result {
+ parse_agent_tool_action_with_policy(input, AgentActionPolicy::RequireAction)
+}
+
+/// Stored/programmatic legacy parsing: a missing `action` still means Start.
+/// Live model-facing calls must use [`parse_agent_tool_action`].
+#[cfg(test)]
+fn parse_agent_tool_action_legacy(input: &Value) -> Result {
+ parse_agent_tool_action_with_policy(input, AgentActionPolicy::LegacyMissingMeansStart)
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum AgentActionPolicy {
+ RequireAction,
+ LegacyMissingMeansStart,
+}
+
+fn parse_agent_tool_action_with_policy(
+ input: &Value,
+ policy: AgentActionPolicy,
+) -> Result {
let Some(action) = optional_input_str(input, &["action", "op"])? else {
- return Ok(AgentToolAction::Start);
+ return match policy {
+ AgentActionPolicy::RequireAction => Err(ToolError::invalid_input(
+ "agent requires action. Use start, status, peek, message, followup, interrupt, wait, or cancel."
+ .to_string(),
+ )),
+ AgentActionPolicy::LegacyMissingMeansStart => Ok(AgentToolAction::Start),
+ };
};
match action.trim().to_ascii_lowercase().as_str() {
- "" | "start" | "spawn" | "run" => Ok(AgentToolAction::Start),
+ "" if matches!(policy, AgentActionPolicy::LegacyMissingMeansStart) => {
+ Ok(AgentToolAction::Start)
+ }
+ "" => Err(ToolError::invalid_input(
+ "agent requires action. Use start, status, peek, message, followup, interrupt, wait, or cancel."
+ .to_string(),
+ )),
+ "start" | "spawn" | "run" => Ok(AgentToolAction::Start),
"status" | "list" | "inspect" => Ok(AgentToolAction::Status),
"peek" | "progress" => Ok(AgentToolAction::Peek),
"message" | "queue_message" => Ok(AgentToolAction::Message),
@@ -7205,7 +7293,11 @@ impl ToolSpec for AgentTool {
"action": {
"type": "string",
"enum": ["start", "status", "peek", "message", "followup", "interrupt", "wait", "cancel"],
- "description": "start (default) launches a background worker and returns immediately. status/peek inspect. message queues a note without waking a running child. followup delivers queued notes and wakes a running child for its next user-provenance model turn. interrupt stops the current turn while preserving the child checkpoint. wait only observes; see until. cancel permanently cancels a running child."
+ "description": "Required. start launches a worker owned by this turn and returns immediately (cancelled+joined when the turn ends). Pass detached=true for independently durable background work. status/peek inspect. message queues a note without waking a running child. followup delivers queued notes and wakes a running child for its next user-provenance model turn. interrupt stops the current turn while preserving the child checkpoint. wait only observes; see until. cancel permanently cancels a running child."
+ },
+ "detached": {
+ "type": "boolean",
+ "description": "For action=start only. Default false: the child is owned by the initiating turn. Set true to keep the child running after the parent turn cancels or completes."
},
"until": {
"type": "string",
@@ -7397,7 +7489,7 @@ impl ToolSpec for AgentTool {
]
}
},
- "required": []
+ "required": ["action"]
})
}
@@ -8086,7 +8178,14 @@ async fn spawn_subagent_from_input(
)));
}
- let mut child_runtime = runtime.background_runtime();
+ // Default direct spawns are turn-owned (`child_runtime`). Explicit
+ // `detached=true` keeps an independent cancel token so the child survives
+ // parent-turn cancellation.
+ let mut child_runtime = if spawn_request.detached {
+ runtime.background_runtime()
+ } else {
+ runtime.child_runtime()
+ };
let provider_binding = child_provider_binding(&runtime, profile_member.as_ref())?;
child_runtime.client = provider_binding.client;
child_runtime.api_config = provider_binding.api_config;
@@ -8340,6 +8439,7 @@ async fn spawn_subagent_from_input(
resume_from_agent_id: resume_from_agent_id.clone(),
claim_pre_namespaced: false,
preserve_runtime_profile: None,
+ detached: spawn_request.detached,
},
);
let result = match result {
@@ -8518,6 +8618,8 @@ pub(crate) async fn spawn_workflow_task(
let mut input = json!({
"prompt": request.description,
"worktree": request.worktree,
+ // Workflow-backed children are independently durable orchestration.
+ "detached": true,
});
if let Some(value) = request.cwd {
input["cwd"] = json!(value);
@@ -10092,8 +10194,8 @@ async fn run_subagent(
for _step in 0..max_steps {
// Cooperative cancellation: bail if this session's token was cancelled
- // while we were between steps. Top-level model-visible sub-agents use
- // a detached token so parent turn cancellation does not stop them.
+ // while we were between steps. Default turn-owned children share the
+ // parent turn token; explicit detached=true children keep their own.
if runtime.cancel_token.is_cancelled() {
record_agent_progress(
runtime,
@@ -11342,6 +11444,7 @@ fn parse_spawn_request(input: &Value) -> Result {
.map(str::trim)
.filter(|s| !s.is_empty())
.map(str::to_string);
+ let detached = parse_optional_bool(input, &["detached"])?.unwrap_or(false);
let prompt_only_general = agent_type == FleetRole::Worker
&& !agent_type_explicit
&& profile.is_none()
@@ -11380,6 +11483,7 @@ fn parse_spawn_request(input: &Value) -> Result {
exact_files,
coordination_contracts,
resume_from,
+ detached,
};
// A roster profile may resolve the parse-time General placeholder to a
// read-only scout/reviewer or to a write-capable manager/builder. Defer
diff --git a/crates/tui/src/tools/subagent/tests.rs b/crates/tui/src/tools/subagent/tests.rs
index 6d63749081..b1f1526fdd 100644
--- a/crates/tui/src/tools/subagent/tests.rs
+++ b/crates/tui/src/tools/subagent/tests.rs
@@ -15579,6 +15579,59 @@ async fn agent_peek_unchanged_within_window_returns_compact_nudge() {
);
}
+#[test]
+fn agent_action_requires_action_for_model_facing_calls() {
+ let err = parse_agent_tool_action(&json!({"prompt": "look around"}))
+ .expect_err("missing action must fail for live model calls");
+ assert!(
+ err.to_string().contains("requires action"),
+ "error should name the missing action: {err}"
+ );
+}
+
+#[test]
+fn agent_action_legacy_missing_means_start() {
+ assert_eq!(
+ parse_agent_tool_action_legacy(&json!({"prompt": "look around"}))
+ .expect("legacy parse accepts missing action"),
+ AgentToolAction::Start,
+ );
+}
+
+#[test]
+fn parse_spawn_request_defaults_to_turn_owned_unless_detached() {
+ let owned = parse_spawn_request(&json!({
+ "prompt": "inspect the module",
+ "type": "scout"
+ }))
+ .expect("spawn should parse");
+ assert!(!owned.detached, "default direct spawns are turn-owned");
+
+ let detached = parse_spawn_request(&json!({
+ "prompt": "inspect the module",
+ "type": "scout",
+ "detached": true
+ }))
+ .expect("detached spawn should parse");
+ assert!(detached.detached);
+}
+
+#[test]
+fn turn_owned_children_cancel_with_parent_while_detached_survive() {
+ let parent = stub_runtime();
+ let owned = parent.child_runtime();
+ let detached = parent.background_runtime();
+ parent.cancel_token.cancel();
+ assert!(
+ owned.cancel_token.is_cancelled(),
+ "turn-owned children share the parent cancel token"
+ );
+ assert!(
+ !detached.cancel_token.is_cancelled(),
+ "explicit detached children keep an independent token"
+ );
+}
+
#[test]
fn agent_action_parses_wait_aliases() {
for alias in ["wait", "join", "await", "block"] {
diff --git a/crates/tui/tests/runtime_web_client.test.mjs b/crates/tui/tests/runtime_web_client.test.mjs
index 0d2c8137c0..6b88409470 100644
--- a/crates/tui/tests/runtime_web_client.test.mjs
+++ b/crates/tui/tests/runtime_web_client.test.mjs
@@ -6,16 +6,24 @@ import {
STREAM_EVENT_NAMES,
applyRuntimeEvent,
applySnapshot,
+ captureTranscriptChrome,
+ collectUserInputAnswers,
+ compactFailureSummary,
createThreadState,
eventStreamUrl,
formatRuntimeProvenance,
+ looksLikeMcpOrToolFailure,
modeLabel,
+ refusalMessage,
renderRuntimeProvenance,
+ resolveUserInputTarget,
restoreDraft,
+ restoreTranscriptChrome,
runtimeEventContinuity,
saveDraft,
setSafeText,
snapshotThenSubscribe,
+ threadTarget,
} from "../src/runtime_web/app.mjs";
function snapshot(threadId = "thread-a", latestSeq = 7) {
@@ -585,3 +593,136 @@ test("renders hostile Runtime text only through the textContent sink", async ()
assert.equal(source.includes("local" + "Storage"), false);
assert.equal(source.includes("session" + "Storage"), false);
});
+
+test("SSE gap flag clears only after snapshot and resubscription both succeed", async () => {
+ const state = createThreadState("thread-a");
+ applySnapshot(state, snapshot("thread-a", 7));
+ let streamGap = true;
+ let subscribeCalls = 0;
+
+ const recovered = await snapshotThenSubscribe({
+ state,
+ threadId: "thread-a",
+ loadSnapshot: async () => snapshot("thread-a", 15),
+ subscribe: () => {
+ subscribeCalls += 1;
+ },
+ });
+ assert.equal(recovered, true);
+ assert.equal(subscribeCalls, 1);
+ // Mirrors recoverProjection: clear only after both steps succeed.
+ if (recovered) streamGap = false;
+ assert.equal(streamGap, false);
+
+ streamGap = true;
+ const failed = await snapshotThenSubscribe({
+ state,
+ threadId: "thread-a",
+ loadSnapshot: async () => ({ thread: { id: "other" }, latest_seq: 1 }),
+ subscribe: () => {
+ subscribeCalls += 1;
+ },
+ });
+ assert.equal(failed, false);
+ assert.equal(subscribeCalls, 1);
+ if (failed) streamGap = false;
+ assert.equal(streamGap, true);
+});
+
+test("stream re-render restores open disclosures without losing chrome", () => {
+ const openDetails = [{ getAttribute: () => "item-reason" }];
+ const restored = { open: false };
+ const stubRoot = {
+ querySelectorAll: (sel) => (sel.includes("details") ? openDetails : []),
+ querySelector: () => restored,
+ ownerDocument: { activeElement: null },
+ contains: () => false,
+ };
+ const chrome = captureTranscriptChrome(stubRoot);
+ assert.deepEqual(chrome.openIds, ["item-reason"]);
+ restoreTranscriptChrome(stubRoot, chrome);
+ assert.equal(restored.open, true);
+});
+
+test("transcript is not a polite live region; streaming bodies mute announcements", async () => {
+ const html = await readFile(new URL("../src/runtime_web/index.html", import.meta.url), "utf8");
+ assert.match(html, /id="status-banner"[^>]*aria-live="polite"/);
+ assert.doesNotMatch(
+ html,
+ /id="transcript"[^>]*aria-live="/,
+ );
+ const source = await readFile(new URL("../src/runtime_web/app.mjs", import.meta.url), "utf8");
+ assert.match(source, /aria-live", "off"/);
+ assert.match(source, /data-live-body/);
+});
+
+test("user-input Other is always offered with exact single-select cardinality and thread binding", () => {
+ const checked = { checked: true };
+ const unchecked = { checked: false };
+ const other = { value: "custom" };
+ const ok = collectUserInputAnswers([
+ {
+ question: { id: "q1", multi_select: false, header: "Pick" },
+ controls: [{ input: unchecked, label: "A", value: "A" }],
+ other,
+ },
+ ]);
+ assert.equal(ok.ok, true);
+ assert.deepEqual(ok.answers, [{ id: "q1", label: "Other", value: "custom" }]);
+
+ const tooMany = collectUserInputAnswers([
+ {
+ question: { id: "q1", multi_select: false, header: "Pick" },
+ controls: [{ input: checked, label: "A", value: "A" }],
+ other,
+ },
+ ]);
+ assert.equal(tooMany.ok, false);
+ assert.match(tooMany.reason, /exactly one/);
+
+ const state = createThreadState("thread-a");
+ applySnapshot(state, {
+ ...snapshot(),
+ pending_user_inputs: [{ id: "input-1", turn_id: "turn-1", request: { questions: [] } }],
+ });
+ const bound = resolveUserInputTarget("input-1", threadTarget("thread-a"), state);
+ assert.equal(bound.ok, true);
+ assert.equal(bound.threadId, "thread-a");
+ const stale = resolveUserInputTarget("input-1", threadTarget("thread-b"), state);
+ assert.equal(stale.ok, false);
+ assert.equal(refusalMessage(stale.reason), "That thread is no longer the selected one — nothing was sent.");
+});
+
+test("long MCP failures stay compact until expanded", () => {
+ const detail = `MCP server error\n${"x".repeat(400)}\ntraceback: boom`;
+ assert.equal(looksLikeMcpOrToolFailure("tool failed", detail), true);
+ const summary = compactFailureSummary("tool failed", detail, 40);
+ assert.ok(summary.length <= 41);
+ assert.match(summary, /…$/);
+});
+
+test("mobile drawer uses modal semantics with Escape, inert, and coarse targets", async () => {
+ const [source, styles] = await Promise.all([
+ readFile(new URL("../src/runtime_web/app.mjs", import.meta.url), "utf8"),
+ readFile(new URL("../src/runtime_web/styles.css", import.meta.url), "utf8"),
+ ]);
+ assert.match(source, /aria-modal/);
+ assert.match(source, /session\.inert/);
+ assert.match(source, /Escape/);
+ assert.match(source, /visualViewport/);
+ assert.match(styles, /@media \(pointer: coarse\)/);
+ assert.match(styles, /min-height:\s*44px/);
+ assert.match(styles, /--vv-height/);
+});
+
+test("gap recovery clears streamGap only on successful snapshotThenSubscribe", async () => {
+ const source = await readFile(new URL("../src/runtime_web/app.mjs", import.meta.url), "utf8");
+ assert.match(source, /app\.streamGap = true/);
+ // Success path inside recoverProjection must clear the flag after subscribe.
+ assert.match(
+ source,
+ /if \(!subscribed\) return;\s*\/\/ Gap state clears only after both[\s\S]*?app\.streamGap = false/m,
+ );
+ // Failure path must not clear the flag.
+ assert.match(source, /Leave streamGap true/);
+});
diff --git a/docs/SUBAGENTS.md b/docs/SUBAGENTS.md
index 95bd3efa8e..0f0b15fa45 100644
--- a/docs/SUBAGENTS.md
+++ b/docs/SUBAGENTS.md
@@ -35,8 +35,9 @@ filtered out of a child's catalog only when the depth budget is spent —
grandchildren. The removed `agent_open`/`agent_eval`/`agent_close` lifecycle
tools are gone from every registry, parent and child alike.
-`agent` launches detached background work: cancelling the parent turn stops the
-parent wait path, but it does not kill already-opened child runs.
+`agent` launches turn-owned work by default: cancelling the parent turn cancels
+and joins foreground children before `TurnComplete`. Pass `detached=true` for
+independently durable background children that survive the parent turn.
This doc covers the role taxonomy and current compatibility controls. The active
orchestration surface is `agent`; see the sub-agent guidance in
diff --git a/docs/WEB.md b/docs/WEB.md
index 3b5a3f6338..d9206058e3 100644
--- a/docs/WEB.md
+++ b/docs/WEB.md
@@ -38,7 +38,7 @@ weaken the configured approval and sandbox policies.
## Authentication boundary
-The browser-launch URL contains a random, short-lived, one-time bootstrap
+The browser-launch URL contains a random, ten-minute, one-time bootstrap
capability. It never contains the Runtime bearer token. A loopback request
exchanges the capability for an `HttpOnly`, `SameSite=Strict`, process-local
session cookie and immediately invalidates the capability.
@@ -68,9 +68,10 @@ before operating either one, especially before selecting a non-loopback bind.
## Troubleshooting
- If port `7878` is occupied, pass an unused `--port` value.
-- If the browser cannot be opened, the command exits with an error rather than
- printing or leaving a reusable bootstrap capability behind. Check the
- operating system's default-browser setup, then start `codewhale web` again.
+- If the browser cannot be opened, the Runtime keeps serving and prints a
+ single-use bootstrap URL (valid for ten minutes) for manual recovery. Open
+ that URL in any local browser; do not share it. Check the operating system's
+ default-browser setup if you want auto-open next time.
- If the page loads but a provider is unavailable, inspect `codewhale doctor`
and `/provider`; the web command does not configure or move provider
credentials.