Skip to content

Surface background tasks and Workflow tool calls in the harness and dashboard - #378

Merged
based64god merged 8 commits into
mainfrom
bandolier/backgrounded-tasks-subag-wa4hik
Jul 18, 2026
Merged

based64god merged 8 commits into
mainfrom
bandolier/backgrounded-tasks-subag-wa4hik

Conversation

@based64god

Copy link
Copy Markdown
Owner

Adds a live "running in the background" indicator and a distinct Workflow glyph to the session UI, backed by a new harness-to-dashboard frame for in-flight background subagent tasks.

Suggested review order

  1. agent-harness/cmd/harness/acp_agent.go, providers_claude.go, internal/acp/types.go (+ tests) — add ToolKindWorkflow and workflowSummary, so a Workflow tool call renders as "Workflow: " instead of a generic dumped-script row.
  2. agent-harness/cmd/harness/acp_agent.go, providers_claude.go (+ tests) — change onBackgroundTasks to carry task ids instead of a bare count, and emit them to the client as a new _bandolier/background_tasks session/update frame.
  3. web/src/lib/acp/timeline.ts (+ tests) — teach applyFrames to fold the new frame into a backgroundTasks set (authoritative, empty on drain, undefined when absent from a batch) and add collectBackgroundTasks to pair task ids with subagent spawn labels.
  4. web/src/app/dashboard/_components/background-tasks-panel.tsx, use-acp-session.ts, interactive-sessions.tsx, conversation.tsx — new BackgroundTasksPanel (pinned amber indicator + popout), the hook exposing backgroundTasks, and a workflow glyph in the conversation view.
  5. web/src/app/dev/background-tasks/page.tsx, web/src/app/dev/conversation/page.tsx, web/e2e/background-tasks.spec.ts, web/e2e/run.ts — dev harness fixtures and an e2e spec covering count, labels, prune-on-drain, and popout contents.
  6. providers_claude.go's workflowMetaNameRe (two follow-up commits) — harden the meta.name regex so it can't be fooled by keys merely ending in "name" or by name: text embedded in an earlier string value.
  7. background-tasks-panel.tsx — gate the indicator on running so a session that ends abnormally (pod killed/expired/OOM) without emitting a drain frame doesn't show a phantom "N tasks running" forever on replay; also fix the label fallback to omit empty titles.

Changes

  • Harness: onBackgroundTasks now carries the live set of task ids (not just a count) and forwards it to the client as a new _bandolier/background_tasks frame whenever it changes, including on drain.
  • Harness: Workflow tool calls get a new ToolKindWorkflow kind and are summarized as "Workflow: ", resolved from the name arg or an inline script's meta.name.
  • Harness: the meta.name extraction regex is anchored to a property position (preceded by { or ,) to avoid matching name-suffixed keys or name: text inside string values.
  • Web: applyFrames/collectBackgroundTasks fold the new frame into a backgroundTasks set and pair each id with a correlated subagent spawn's label.
  • Web: new BackgroundTasksPanel component shows a pinned "N tasks running in the background" indicator with a popout listing, mirroring SubagentPanel; it prunes on drain and is suppressed when the session isn't running.
  • Web: useAcpSession exposes backgroundTasks, and the conversation view gets a distinct glyph for the workflow tool kind.
  • Web: adds a /dev/background-tasks harness page, extends /dev/conversation with a Workflow example, and adds an e2e spec plus route registration.

@vercel

vercel Bot commented Jul 18, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
bandolier Building Building Preview, Comment Jul 18, 2026 4:38pm

Request Review

@bandolier-dev bandolier-dev Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Summary

Adds a live "running in the background" indicator plus a distinct Workflow glyph, backed by a new _bandolier/background_tasks session/update frame. The change is well-scoped, thoroughly tested (Go unit tests for the frame + workflow summary, vitest for applyFrames/collectBackgroundTasks, and a Playwright e2e), and carefully documented.

I verified:

  • The claudeEventSink.onBackgroundTasks(taskIDs []string) signature change is propagated to every implementor (claudeDriver, claudeLogSink, and the test sinks) — no stragglers.
  • PR-relevant tests pass: go test -run 'Workflow|BackgroundTasks|...' (5 tests) and vitest run timeline.test.ts (66 tests). The lone failing Go test, TestOneShotRunLifecycle, fails on an unrelated environment issue (review-submit 401 / git commit), not this diff.
  • Web wiring is correct: useAcpSession returns backgroundTasks, InteractiveRow passes session.backgroundTasks/running through, and the Modal prop names (titleAccessory, panelClassName) match the component API.

What I liked

  • The TaskIDs slice is always non-nil (make([]string, 0, …)), so a drain serializes as [] rather than null, and the web side defends with ?? [] regardless — belt and suspenders.
  • The running gate on BackgroundTasksPanel is the right fix for the phantom-indicator-on-replay problem: unlike SubagentPanel (which derives in-flight state from item status and self-heals), the background set comes from an authoritative frame that can go stale if a pod dies before draining. Good that this is called out in a comment and covered by the panel-not-running e2e case.
  • undefined (no frame this batch) vs [] (real drain) is handled consistently across applyFrames, the hook, and the tests.

Minor, non-blocking

  • workflowMetaNameRe anchoring to [{,] genuinely closes the filename:/the name:-in-a-string cases the tests cover, but a comma inside an earlier string value (e.g. a description containing , name: 'x') can still false-match. This is acknowledged as best-effort and only affects a display label, so it's fine as-is — noted inline in case it's cheap to tighten later.

Nothing here blocks. Nice, complete change.

// description that happens to contain the text "name:") or a key that merely ends
// in "name" (filename:, nickname:). Best-effort: the first such match is meta.name,
// which the meta literal (required to be first in the script) supplies.
var workflowMetaNameRe = regexp.MustCompile(`[{,]\s*name\s*:\s*['"]([^'"]+)['"]`)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The [{,] anchor correctly rejects filename: and a name: preceded by ordinary text inside a string (both covered by tests). One residual gap the tests don't exercise: a comma inside an earlier string value followed by name: — e.g. a description like 'a, name: "x"' — would still false-match and return x. Since this only affects the display label (never behavior) and the comment already flags it as best-effort, this is fine to leave; just noting the boundary.

// session does, and an abnormally-ended session (pod killed / expired / OOM)
// never emits a drain frame — so its last non-empty set would otherwise linger in
// the durable log and show phantom "running" work on every replay. Gate on this.
running: boolean;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gating on running is the right call here — the background-task set is authoritative-but-stale (an abnormally-ended pod never emits a drain), unlike SubagentPanel which self-heals off item status. Good that the panel-not-running e2e case locks this in.

@github-actions
github-actions Bot force-pushed the bandolier/backgrounded-tasks-subag-wa4hik branch 2 times, most recently from a8de7c5 to 01328ff Compare July 18, 2026 16:35
@based64god
based64god enabled auto-merge July 18, 2026 16:37
@based64god
based64god disabled auto-merge July 18, 2026 16:38
The Workflow tool (Claude's multi-agent orchestration) previously fell
through toolKind's default to "other" and toolSummary's default, so it
reached the dashboard as a generic row titled "Workflow: {json}" with the
whole inline script dumped into the title.

Map it to a new ToolKindWorkflow ACP extension (a sibling of the existing
ToolKindSubagent extension) and summarise it by the workflow's name — the
`name` arg for a saved workflow, or the meta.name of an inline script —
so the client can give it its own glyph and a clean "Workflow: <name>"
title. The agents a workflow spawns still nest beneath it via
parentToolCallId, exactly as an ordinary subagent's calls do.

Signed-off-by: based64god <6633471+based64god@users.noreply.github.com>
background_tasks_changed events were consumed only for turn-timing (the
count decided whether a result was a mid-turn yield or the turn's end) and
never reached the client. A backgrounded subagent therefore had no live
representation: its spawn's own tool call completes the instant it hands
back a task handle, so the ordinary tool-call stream can't show that the
task is still running.

Emit the live set as a new _bandolier/background_tasks session/update frame
(a Bandolier ACP extension, ignored by any client that doesn't know it)
whenever the set changes, including the empty drain. The sink now carries
the task ids rather than a bare count; the turn-timing logic keys off the
set's size exactly as before. No contract-version bump: the frame is purely
additive and both directions degrade gracefully (an old client ignores it;
an old harness simply never sends it).

Signed-off-by: based64god <6633471+based64god@users.noreply.github.com>
applyFrames now recognises the harness's _bandolier/background_tasks
update and returns the live set as `backgroundTasks` — an authoritative
list the latest frame replaces, empty on drain, undefined when no frame
was in the batch (so the caller keeps its previous value), mirroring how
`commands` is handled. It's not a timeline item: it drives a live
indicator, while each background task's actual work still streams into the
tool tree under its spawn.

collectBackgroundTasks turns that set into view models, pairing each task
id with its subagent spawn's label when the two share an id and the spawn
is in the fetched window.

Signed-off-by: based64god <6633471+based64god@users.noreply.github.com>
Adds the pieces that surface the two new harness signals next to the
existing subagent card:

- BackgroundTasksPanel: a pinned amber indicator, mirroring SubagentPanel,
  driven by the session's live backgroundTasks set. It shows how many tasks
  are running in the background (with a spawn label when correlatable) and
  prunes itself once the set drains. It complements SubagentPanel — that
  card tracks synchronous subagents the agent is blocked on, this one the
  tasks it has backgrounded, whose spawn calls complete immediately.
- useAcpSession now tracks and exposes backgroundTasks, folding each batch's
  set from applyFrames (keeping the previous set when a batch carries none).
- A distinct glyph for the workflow tool kind, so a Workflow reads as
  orchestration rather than a generic tool row.

Signed-off-by: based64god <6633471+based64god@users.noreply.github.com>
Adds a /dev/background-tasks harness (mirroring /dev/subagent-panel) that
mounts BackgroundTasksPanel over a few fixture sets — a correlatable label
plus generic fallbacks, a single task, and a drained set that prunes to
nothing — and an e2e spec asserting the count, singular/plural, label
preview, prune, and popout contents. Registers the route with the e2e
runner's readiness gate.

Extends /dev/conversation with a Workflow tool call and nested agents so
the workflow glyph and its nesting render in a real browser.

Signed-off-by: based64god <6633471+based64god@users.noreply.github.com>
Anchor the meta.name regex with a word boundary so a key that merely ends
in "name" (filename:, nickname:) inside an inline workflow script can't be
mistaken for the workflow's name.

Signed-off-by: based64god <6633471+based64god@users.noreply.github.com>
An adversarial review found the meta.name regex could match a name:"…"
that appears inside an earlier string value (e.g. a description that
contains the text "name:"), mislabelling the workflow. Require the key to
sit at a property position — preceded by { or , — which excludes both
name-suffixed keys (filename:) and name: text embedded in string values,
while still picking meta.name as the first real property.

Signed-off-by: based64god <6633471+based64god@users.noreply.github.com>
An adversarial review found a phantom-indicator bug: if a background task
is in flight when a session ends abnormally (pod killed / expired / OOM),
Claude never emits the draining background_tasks_changed, so the last
non-empty set stays in the durable frame log and every replay of the dead
session shows "N tasks running in the background" forever.

A background task only runs while the session does, so gate the panel on
`running`: a non-running session shows no indicator regardless of its last
logged set. Also harden the label fallback — collectBackgroundTasks now
omits empty titles so the panel's `?? "Background task N"` reliably applies
— and correct the useMemo comment (it recomputes when taskIds/items change,
which is what saves work on the row's scroll/focus re-renders).

Signed-off-by: based64god <6633471+based64god@users.noreply.github.com>
@github-actions
github-actions Bot force-pushed the bandolier/backgrounded-tasks-subag-wa4hik branch from 01328ff to bccd5ba Compare July 18, 2026 16:38
@based64god
based64god enabled auto-merge July 18, 2026 16:39
@based64god
based64god merged commit 6949de4 into main Jul 18, 2026
14 of 15 checks passed
@based64god
based64god deleted the bandolier/backgrounded-tasks-subag-wa4hik branch July 18, 2026 16:41

This branch had an error being deployed

1 failed deployment
production — bccd5ba1 Deployed Jul 18, 2026 by based64god via delete-branch #280
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant