Skip to content

Report program status to the terminal with OSC 7501 - #1040

Merged
wolfeidau merged 2 commits into
mainfrom
pb-3957-osc-7501-program-status
Oct 15, 2026
Merged

wolfeidau merged 2 commits into
mainfrom
pb-3957-osc-7501-program-status

Conversation

@wolfeidau

Copy link
Copy Markdown
Member

Description

OSC 7501 is a draft terminal protocol for a program to tell the terminal what it is doing: working (with progress), blocked on the user, done, or failed. Terminals and agent harnesses can show that state, such as a spinner on a background tab or a "needs you" marker, instead of guessing from output.

This adopts it in bk so we can dogfood the spec and get feedback on whether it is useful from the CLI. It starts with the shared spinner and prompt helpers and with bk build watch, the main long-running command. bk preflight, bk auth login and downloads can follow.

The sequences come from ansi.SetProgramStatus in github.com/charmbracelet/x/ansi v0.11.9, which bk already depends on, so there is no new dependency.

Reports go to stderr, so piped stdout is unaffected. They are only sent when stderr is a terminal, TERM is not dumb, and neither CI nor BUILDKITE is set. Agents run jobs in a PTY, so a terminal check alone would put these sequences in job logs. BUILDKITE_PROGRAM_STATUS=true|false overrides the detection.

Changes

  • New internal/programstatus package that tags every report with app=bk. It is process-wide because terminal records belong to the process and PromptForOne has no factory.
  • SpinWhile reports working with the spinner text.
  • Confirm reports blocked kind=permission. PromptForOne and PromptForInput report blocked kind=question. Once answered, the previous status is restored.
  • bk build watch reports working with progress from finished script jobs (retried and non-script jobs excluded), then done when the build finishes, or error if it failed or was canceled. A --timeout reports idle, since the build keeps running.

Quick commands do not leave a done record behind; terminals drop working records when the process exits. Reports are still sent with --quiet because they are not shown as output.

Testing

  • Tests have run locally (with go test ./...)
  • Code is formatted (with go fmt ./...)

I also ran the built binary in a PTY against a fake REST API, with stdout redirected to a file:

Scenario Reports on stderr Reports on stdout
Build passes working 0% → 50% → 75% → done "widgets #429 passed" 0
Build fails … → error "widgets #429 failed" 0
--timeout=1500ms working 0% → 50% → idle 0
CI=true or BUILDKITE_PROGRAM_STATUS=false 0 0
bk maintainer delete, answered n blocked kind=permission → working n/a

Not yet tried in a terminal that renders OSC 7501.

Send OSC 7501 program status reports to stderr so terminals can show
whether bk is working, waiting on the user, or finished. Spinners report
working, confirmations and prompts report blocked, and bk build watch
reports job progress then done or error when the build finishes.

Reports are only sent when stderr is a terminal outside CI, and
BUILDKITE_PROGRAM_STATUS=true|false overrides that.

Co-authored-by: Amp <amp@ampcode.com>
Amp-Thread-ID: https://ampcode.com/threads/T-e8ace642-180b-4cd2-a865-21662f7a18ca
@wolfeidau
wolfeidau marked this pull request as ready for review October 15, 2026 23:22
@wolfeidau
wolfeidau requested review from a team as code owners October 15, 2026 23:22

@mcncl mcncl left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Really keen on testing this out and seeing how we might get clearer feedback to bk callers 🚀

buildsworth-bk-app[bot]
buildsworth-bk-app Bot previously approved these changes Oct 15, 2026

@buildsworth-bk-app buildsworth-bk-app Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Want to dig deeper?

Paste this into your agent to explore the findings from this review's Buildkite build:

Download the buildsworth logs from build 41566, then answer my questions about the findings.

Install the reading-buildsworth-logs skill to run this.

About buildsworth

Model: gpt-6.1-sol with xhigh thinking.

How to request a review: Comment @buildsworth-bk review on the PR, or request buildsworth-bk as a reviewer.

Risk labels (how buildsworth classifies risk) — buildsworth classifies risk itself from the diff. Unless repository policy already allows L2 approval, grant it by mentioning @buildsworth-bk (see approval ceiling and L2 approval grant):

  • L1 — Low risk (dep bumps, docs/copy, lockfiles, small presentational fixes). buildsworth may approve by default.
  • L2 — Standard risk (new UI, additive API fields, refactors). Approved only when repository policy or a verified grant allows it; otherwise comment-only.
  • L3 — High risk (auth, migrations, payments, secrets, perf-critical pipeline paths). Human approval required unless repository policy explicitly allows L3 approval; per-PR grants cannot allow it.

Comment thread cmd/build/watch.go Resolved
Distinguish the watch's own timeout from repeated poll request timeouts by
checking the command context instead of the error, which wraps
context.DeadlineExceeded in both cases. Report idle or error when build
resolution fails too, not only when polling stops.

Drop broken jobs from the finished count: watchJobs removes them first.

Co-authored-by: Amp <amp@ampcode.com>
Amp-Thread-ID: https://ampcode.com/threads/T-e8ace642-180b-4cd2-a865-21662f7a18ca
@buildsworth-bk-app
buildsworth-bk-app Bot dismissed their stale review October 15, 2026 23:43

Superseded by a newer Buildsworth review.

@buildsworth-bk-app buildsworth-bk-app Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

The earlier polling-timeout feedback is addressed; no new findings.

Want to dig deeper?

Paste this into your agent to explore the findings from this review's Buildkite build:

Download the buildsworth logs from build 41572, then answer my questions about the findings.

Install the reading-buildsworth-logs skill to run this.

@wolfeidau
wolfeidau merged commit 4590fb1 into main Oct 15, 2026
2 checks passed
@wolfeidau
wolfeidau deleted the pb-3957-osc-7501-program-status branch October 15, 2026 23:44
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.

2 participants