Decode OSC 7501 program status reports #105

Merged

natsukium merged 2 commits from vt/osc7501-decoder into main 2026-10-12 14:12:24 +09:00

Conversation 0 Commits 2 Files changed 16 +1372 -2

natsukium commented 2026-10-12 12:06:28 +09:00

Owner

Copy link

First step of #67: a decode-only OSC 7501 (Program Status Protocol) decoder in felis-vt. Nothing calls it yet, so there is no behavior change and no protocol doc. The support-matrix row and the reference/explanation twins land with the daemon records, when support becomes observable.

What it does

felis_vt::program_status::parse_osc7501(body, Terminator) turns one sequence into a Query, a Report, a Clear { id }, or a Dropped(reason). It implements spec revision 0.4 (2026-10-10). The issue was written against 0.3; 0.4 only adds optional states=/kinds= to the ? reply and removes the terminfo section, so the decoder is unaffected.

• Atomic: every pair is checked before anything is built, including each occurrence of a repeated key. Otherwise an over-limit app followed by a valid one would pass.
• Bad id: a malformed or over-limit id drops the report instead of falling back to the root record.
• Invalid text: text that decodes from base64 but is not UTF-8 drops the report, as does text with a control character.
• Closed vocabulary: State and Kind are closed enums here; IPC will carry them as open strings. A new state from a later revision fails to compile until the daemon decides its lifetime.

Not in this PR

The parser dispatches an OSC on any ESC, not only on ST, so ESC ] 7501;state=done ESC [0m would look complete. The decoder takes a terminator with no "interrupted" value. A separate felis-vt parser PR will distinguish ST from an interrupting ESC before the grid wiring calls this decoder.

Tests

• Unit: one test per decoder rule, every limit at max and max+1, the spec's examples, control-character edges, and earlier-bad-duplicate drops.
• Property tests:
  • totality on arbitrary input;
  • round-trip of valid reports through any spelling (permuted pairs, padded or unpadded base64, extra whitespace), using a test-local base64 encoder;
  • pairs the spec says to ignore change nothing;
  • one poisoned occurrence anywhere drops the report;
  • invariants hold on every accepted report.
• Fuzz: new program_status target with seeds; 200,000 runs, no panics.
• cargo-mutants on the module: 94 mutants, 89 caught, 4 unviable, 1 missed. The miss showed that the key-charset check never changed the result, so the check was removed.

First step of #67: a decode-only OSC 7501 (Program Status Protocol) decoder in `felis-vt`. Nothing calls it yet, so there is no behavior change and no protocol doc. The support-matrix row and the reference/explanation twins land with the daemon records, when support becomes observable. ## What it does `felis_vt::program_status::parse_osc7501(body, Terminator)` turns one sequence into a `Query`, a `Report`, a `Clear { id }`, or a `Dropped(reason)`. It implements spec revision 0.4 (2026-10-10). The issue was written against 0.3; 0.4 only adds optional `states=`/`kinds=` to the `?` reply and removes the terminfo section, so the decoder is unaffected. - **Atomic:** every pair is checked before anything is built, including each occurrence of a repeated key. Otherwise an over-limit `app` followed by a valid one would pass. - **Bad `id`:** a malformed or over-limit `id` drops the report instead of falling back to the root record. - **Invalid text:** text that decodes from base64 but is not UTF-8 drops the report, as does text with a control character. - **Closed vocabulary:** `State` and `Kind` are closed enums here; IPC will carry them as open strings. A new state from a later revision fails to compile until the daemon decides its lifetime. ## Not in this PR The parser dispatches an OSC on *any* ESC, not only on ST, so `ESC ] 7501;state=done ESC [0m` would look complete. The decoder takes a terminator with no "interrupted" value. A separate `felis-vt` parser PR will distinguish ST from an interrupting ESC before the grid wiring calls this decoder. ## Tests - **Unit:** one test per decoder rule, every limit at max and max+1, the spec's examples, control-character edges, and earlier-bad-duplicate drops. - **Property tests:** - totality on arbitrary input; - round-trip of valid reports through any spelling (permuted pairs, padded or unpadded base64, extra whitespace), using a test-local base64 encoder; - pairs the spec says to ignore change nothing; - one poisoned occurrence anywhere drops the report; - invariants hold on every accepted report. - **Fuzz:** new `program_status` target with seeds; 200,000 runs, no panics. - **cargo-mutants** on the module: 94 mutants, 89 caught, 4 unviable, 1 missed. The miss showed that the key-charset check never changed the result, so the check was removed.

natsukium added 2 commits 2026-10-12 12:06:28 +09:00

vt: decode OSC 7501 program status reports ... 24e986f58f

Programs such as Claude Code, Codex and Terraform report through OSC
7501 whether they are idle, working, blocked on the user, done or
failed. felis has no other reliable way to tell that a TUI in a
session is waiting on the user, since a TUI never emits OSC 133 D.
This decoder is the first layer of experimental support. It turns
one sequence into a query, a report, a clear, or a drop with a reason.
Storing records and their lifetimes stays with the daemon, so the
decoder holds no state.

It implements spec revision 0.4. Every pair is checked before
anything is built, and every occurrence of a repeated key is checked,
not only the last. Otherwise an over-limit `app` followed by a valid
one would pass, while the spec discards any report that breaks a
limit. A malformed `id` drops the report instead of being skipped,
because skipping it would route the report to the root record. Text
that is valid base64 but not UTF-8 drops too. The spec only names
base64 failure and control characters, but storing replacement
characters would keep a record the program never sent.

State and kind are closed enums here although the IPC layer will
carry them as open strings. A new state from a later revision then
fails to compile until the daemon decides that state's lifetime.

The parser still dispatches an OSC on any ESC, not only on ST. The
decoder therefore takes a terminator with no "interrupted" value, and
the caller must not pass it an interrupted body.

Assisted-by: Claude Code

fuzz: cover the OSC 7501 decoder ... 718bf1331c

The decoder parses untrusted program output byte by byte under
several hard caps, so a coverage-guided target explores corners that
the proptests only sample. The first input byte picks the terminator
because the sequence-length cap depends on it.

Assisted-by: Claude Code

natsukium force-pushed vt/osc7501-decoder from 718bf1331c to 7fdeef30d1 2026-10-12 13:33:26 +09:00 Compare

natsukium merged commit 369476c9b8 into main 2026-10-12 14:12:24 +09:00

natsukium deleted branch vt/osc7501-decoder 2026-10-12 14:12:24 +09:00

natsukium referenced this pull request from a commit 2026-10-12 14:12:24 +09:00

Merge pull request 'Decode OSC 7501 program status reports' (#105) from vt/osc7501-decoder into main

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

Area/ci

CI workflows (.forgejo/workflows/)

  

Area/cli

felis-cli crate, the felis front-door binary

  

Area/client

felis-client crate, the winit GUI frontend

  

Area/client-core

felis-client-core crate, shadow screen, config, connect_or_spawn_daemon

  

Area/daemon

felis-daemon crate, session pool, IPC server

  

Area/deps

Dependency bumps

  

Area/docs

Documentation tree when no narrower area fits

  

Area/grid

felis-grid crate, cells, scrollback, image store

  

Area/manual

User-facing docs: tutorials, how-to, user-facing reference pages

  

Area/nix

Nix flake, home-manager module, package definitions

  

Area/protocol

felis-protocol crate, felis.proto, frame layout, version constants

  

Area/pty

felis-pty crate, PTY backends

  

Area/render

felis-render-wgpu crate, GPU pipeline, atlas

  

Area/shaping

felis-shaping crate, swash shaper, font fallback

  

Area/skills

Agent skills (skills/felis, .agents/skills/)

  

Area/transport

felis-transport crate, framing, socket/pipe, SSH carrier

  

Area/vt

felis-vt crate, VT parser, dispatch

  

Compat/Breaking

Breaking change that won't be backward compatible

  

Kind/Bug

Something is not working

  

Kind/Documentation

Documentation changes

  

Kind/Enhancement

Improve existing functionality

  

Kind/Feature

New functionality

  

Kind/Performance

Throughput, latency, or memory cost

  

Kind/Security

This is security issue

  

Kind/Testing

Issue or pull request related to testing

  

perf-regression-accepted

Passes the instruction-count bench gate for an intended cost; state why in a PR comment

  

Reviewed

Confirmed

Issue has been confirmed

  

Reviewed

Duplicate

This issue or pull request already exists

  

Reviewed

Invalid

Invalid issue

  

Reviewed

Won't Fix

This issue won't be fixed

  

Status

Blocked

Something is blocking this issue or pull request

  

Status

Need More Info

Feedback is required to reproduce issue or to continue work

  

Status

Upstream

Waiting on a change in an upstream project

No labels

Area/ci

Area/cli

Area/client

Area/client-core

Area/daemon

Area/deps

Area/docs

Area/grid

Area/manual

Area/nix

Area/protocol

Area/pty

Area/render

Area/shaping

Area/skills

Area/transport

Area/vt

Compat/Breaking

Kind/Bug

Kind/Documentation

Kind/Enhancement

Kind/Feature

Kind/Performance

Kind/Security

Kind/Testing

perf-regression-accepted

Reviewed

Confirmed

Reviewed

Duplicate

Reviewed

Invalid

Reviewed

Won't Fix

Status

Blocked

Status

Need More Info

Status

Upstream

Milestone

Clear milestone

No items

No milestone

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

felis-terminal/felis!105

No description provided.