osc

Documentation

Overview

CompletionScanner detects OSC 133 prompt-mark sequences (shell integration) in PTY output. When a shell with prompt-mark integration (zsh's osc133 precmd/preexec hooks, fish's fish_mark_prompt) emits the "command done" marker, this scanner fires — the daemon uses it to emit a cmdDone event for push notifications + agent-state transitions.

OSC 133 sequences (the "FinalTerm" shell integration spec):

ESC ] 133 ; A <term>  — prompt start (shell showing a fresh prompt)
ESC ] 133 ; B <term>  — command start (user pressed Enter)
ESC ] 133 ; C <term>  — output start (command output begins)
ESC ] 133 ; D [; exitcode] <term>  — command done (command finished)

This scanner watches ONLY for `133;D` (the command-done marker). The A/B/C markers are less useful for the daemon (it doesn't track prompt state) and would add noise. The D marker carries an optional exit code — extracted and returned so callers can surface success/failure.

Thread-safety: same as TitleScanner — NOT goroutine-safe; called exclusively from the session's readLoop (single goroutine).

Package osc contains byte-scanners for OSC (Operating System Command) sequences in PTY output. The daemon scans raw PTY bytes (NOT a full VT — it stays VT-free per the plan's hard constraint) for two OSC categories:

• Title capture (this file): OSC 0 / OSC 2 sequences set the terminal title. Shells emit these on every prompt (e.g., zsh's `precmd` hook sets title to "user@host:cwd"). Capturing them gives the daemon the tab's current title for auto-naming without running a full VT.

• OSC 133 prompt markers (completion.go, Step 4): shell integration sequences that mark prompt/command/output boundaries. Used for cmdDone detection (the "command finished" signal for push notifications).

Both scanners are stateless per-call with a carryover buffer for sequences split across PTY reads — the same discipline as the C1 querystubber.

Index

• type CompletionResult
• type CompletionScanner
  • func (c *CompletionScanner) Scan(chunk []byte) CompletionResult
• type TitleScanner
  • func (t *TitleScanner) Scan(chunk []byte) string

Types

type CompletionResult

type CompletionResult struct {
	Done     bool // true iff a 133;D marker was found in this chunk
	ExitCode *int // nil if the marker carried no exit code; &code if present
}

CompletionResult describes a detected command-done event.

type CompletionScanner

type CompletionScanner struct {
	// contains filtered or unexported fields
}

CompletionScanner extracts OSC 133;D command-done markers from PTY output. Uses the same carryover-buffer discipline as TitleScanner for sequences split across PTY reads.

func (*CompletionScanner) Scan

func (c *CompletionScanner) Scan(chunk []byte) CompletionResult

Scan feeds a chunk of PTY output bytes and returns whether a command-done (OSC 133;D) marker was present. If multiple markers appear in one chunk (rapid shell cycling), the LAST one's exit code is returned — the caller cares about the most recent completion, not intermediate ones.

type TitleScanner

type TitleScanner struct {
	// contains filtered or unexported fields
}

TitleScanner extracts the terminal title from OSC 0 / OSC 2 sequences.

Wire format:

ESC ] 0 ; <title> BEL     (OSC 0 — set icon name + window title)
ESC ] 2 ; <title> BEL     (OSC 2 — set window title)
ESC ] 0 ; <title> ESC \   (ST-terminated variant)
ESC ] 2 ; <title> ESC \

Shells emit these on prompt redraw. zsh's default precmd sets `ESC]0;%n@%m: %1~` — the title reflects user@host + current directory. Capturing it lets the daemon name tabs after their working directory without a VT.

The scanner is NOT a full OSC parser: it recognizes ONLY the 0 and 2 parameter codes (the two that carry titles). Other OSC sequences (color queries, hyperlink markers, etc.) are skipped by scanning for the terminator (BEL or ST) and discarding.

Thread-safety: Scan is NOT goroutine-safe — it's called exclusively from the session's readLoop (single goroutine), matching the querystubber's discipline. The caller serializes calls.

func (*TitleScanner) Scan

func (t *TitleScanner) Scan(chunk []byte) string

Scan feeds a chunk of PTY output bytes and returns any complete title extracted. Returns "" when no complete title sequence is present (either no OSC title in this chunk, or one is split across chunks and the remainder hasn't arrived yet). Multiple titles in one chunk are possible (shells re-set the title every prompt); only the LAST is returned, since that's the current title. Earlier ones are intermediate states.