feat(cli): session stream and start --stream

The operator's side of the four verbs: `hhstream session stream
enable|disable|list|status`, and `start --stream [--stream-phrase]
[--stream-fps]` for the one-call case.

`stream enable` prints the URL on **stdout and nothing else**, with the detail
on stderr, so `url=$(hhstream session stream enable ID)` works -- the same shape
`start` already has for the session id. `start --stream` prints the id and then
the URL, two lines, because a caller who asked for both should not have to run
a second verb for the second one.

The phrase is a credential, and the two renderers disagree on purpose:

* `render_streams` (`stream list`) does **not** show it. A listing is what ends
  up in a shared terminal, a paste or a screenshot, so what it shows is enough
  to recognise and manage a stream -- session, output, rate, viewers, `LIVE` --
  and not enough to watch one. It also prints the daemon's reachability, because
  "two records and no daemon" is a different situation from "two records and two
  captures" and the rows alone cannot say which.
* `render_stream` (`stream status ID`) does show the URL. That question was
  asked about one session by name, which is what somebody about to watch it
  does, and making them reach for `--json` for the thing the verb is for would
  be the worse trade.

When the daemon is not publishing, `status` says so and prints no URL -- the
phrase is kept, so re-enabling restores the same one.

`start --stream` that starts the session but cannot open the stream exits 0 and
says `WARNING: the session is running but its stream was not enabled: …` on
stderr. Loudly, because the exit code is the session's and a caller who asked
for a stream must not read a 0 as one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
This commit is contained in:
HermenixandClaude Opus 5 committed 2026-10-11 22:48:00 +00:00
1 parent 7d8ca6191b
commit 850f9caa1d
2 files changed
+333

No files matched your search

+252
View File
@@ -38,6 +38,9 @@ The verb tree, beyond the original eight:
session keyboard type ID TEXT one argument, raw UTF-8, no escapes
session keyboard key ID NAME tap: down then up
session keyboard down/up ID NAME
session stream enable ID publish ID's screen behind a spoken phrase
session stream disable ID stop publishing, and forget the phrase
session stream list/status what is being published, and who is watching
The pointer *and keyboard* verbs share one precondition — the pointer lease —
and the lease id lives in :mod:`hhstream_session.lease` between invocations,
@@ -187,6 +190,27 @@ def _build_namespace(parser: argparse.ArgumentParser) -> None:
help="deduplication token: retrying a start with the same id returns the "
"original reply instead of launching a second application",
)
start.add_argument(
"--stream",
action="store_true",
help="also enable a live stream for this session and print its URL. "
"Needs the session's container output, which this creates — which is "
"why it is a flag here rather than a second command you have to "
"sequence yourself.",
)
start.add_argument(
"--stream-phrase",
metavar="PHRASE",
help="use this phrase instead of a minted one (four words and a "
"five-character tail). It is the stream's only credential, so it is "
"held to exactly that shape.",
)
start.add_argument(
"--stream-fps",
type=int,
metavar="N",
help="frames per second for the stream (default: the broker's)",
)
start.add_argument(
"--no-container",
action="store_true",
@@ -303,6 +327,9 @@ def _build_namespace(parser: argparse.ArgumentParser) -> None:
# ---- keyboard ----------------------------------------------------
_build_keyboard(verbs, common)
# ---- stream ------------------------------------------------------
_build_stream(verbs, common)
#: Button names the driver knows (``hhstream_pointer.buttons.CODES``), mirrored
#: here rather than imported: this module's whole integration promise is that it
@@ -627,6 +654,136 @@ def _build_keyboard(verbs: Any, common: argparse.ArgumentParser) -> None:
sub.add_argument("name", help="XKB keysym name, e.g. Control_L, Shift_L")
#: Printed under `stream --help` and under `enable`. The two facts an operator
#: gets wrong about this group, and they pull in opposite directions: the
#: phrase is a password, and *watching* is the one thing besides `touch` that
#: keeps a session alive.
STREAM_NOTE = (
"CREDENTIAL: the phrase in the URL is the stream's only protection — no "
"TLS, no second factor. Anyone who can reach the port and guess four "
"words can watch. It is never written to the audit log, and it is not "
"echoed by 'list' unless you ask for --json.\n\n"
"ACTIVITY: 'stream enable|disable|list|status' do NOT reset the idle "
"clock, like every pointer and keyboard verb. But A CONNECTED VIEWER "
"DOES: about once a minute the broker stamps 'touch' on any session "
"somebody is watching, so a session you are watching on a phone is not "
"reaped at three hours. An enabled stream with nobody watching captures "
"nothing and keeps nothing alive."
)
def _build_stream(verbs: Any, common: argparse.ArgumentParser) -> None:
"""``session stream <verb>`` — a live view of one session, behind a phrase.
A nested namespace for the reason ``pointer`` is one: these four verbs
share a precondition nothing else here has. It is the session's **container
output** — a stream never falls back to the main output, because that one
carries every other session.
"""
namespace = verbs.add_parser(
"stream",
parents=[common],
help="publish one session's screen on the LAN, behind a spoken phrase",
description=(
"A live view of one session, in a browser, at a URL whose path is "
"four words and a five-character tail. Off by default and per "
"session: a session does not stream because it exists, it streams "
"because it was switched on.\n\n"
"What is published is the session's own container output, never "
"the main one — that output carries every other session, and "
"putting it behind one session's phrase is the mistake this "
"refuses to make (exit 10 with no container).\n\n"
"The transport is MJPEG over HTTP: a browser <img> is the whole "
"client. Capture runs only while somebody is connected."
),
epilog=f"{STREAM_NOTE}\n\n{ACTIVITY_NOTE}",
formatter_class=argparse.RawDescriptionHelpFormatter,
)
streams = namespace.add_subparsers(dest="stream_verb", metavar="VERB")
namespace.set_defaults(
func=_cmd_stream_list, hhstream_session_handler=_cmd_stream_list, json=False
)
def add_stream_verb(name: str, handler, **kwargs: Any):
sub = streams.add_parser(name, parents=[common], **kwargs)
sub.set_defaults(func=handler, hhstream_session_handler=handler)
sub.add_argument("--json", action="store_true", help="emit the protocol object on stdout")
return sub
enable = add_stream_verb(
"enable",
_cmd_stream_enable,
help="switch a session's stream on and print its URL",
description=(
"Mint a phrase, open a capture, and print the URL on stdout — so "
"$(hhstream session stream enable ID) is the URL and nothing "
"else. The phrase is kept in the session's record, so it survives "
"a broker restart and a re-enable: somebody you read it out to "
"keeps the URL you gave them.\n\n"
"Re-enabling an enabled session prints the same URL. A --phrase "
"that differs from the stored one is exit 8 rather than a silent "
"rotation, because rotating under a caller holding the old URL is "
"the one outcome neither answer can be mistaken for. 'disable' "
"then 'enable' rotates it."
),
epilog=f"{STREAM_NOTE}\n\n{ACTIVITY_NOTE}",
formatter_class=argparse.RawDescriptionHelpFormatter,
)
enable.add_argument("id", help="session id")
enable.add_argument(
"--phrase",
metavar="PHRASE",
help="use this phrase instead of a minted one. Held to exactly the "
"generated shape (four words of 3+ letters, then a five-character "
"tail): it is a password, and a looser check would accept 'a-b-c'.",
)
enable.add_argument(
"--fps",
type=int,
metavar="N",
help="frames per second (default: the broker's; the daemon caps it)",
)
disable = add_stream_verb(
"disable",
_cmd_stream_disable,
help="switch a session's stream off and forget its phrase",
description=(
"Close the capture, drop the route, and clear the record. The "
"phrase is gone: a later 'enable' mints a new one, which is how a "
"phrase is rotated.\n\n"
"Disabling a stream the daemon has already forgotten is not an "
"error — that is the ordinary case after the daemon restarts, and "
"the record has to be cleared either way. 'detached' says which "
"happened."
),
)
disable.add_argument("id", help="session id")
add_stream_verb(
"list",
_cmd_stream_list,
help="every session with a stream (does NOT count as activity)",
description=(
"Every session a stream was enabled on, with its output, rate and "
"connected viewer count. The phrase is shown only under --json: "
"this listing is the kind of thing that ends up in a terminal "
"somebody is sharing, and the phrase is the credential.\n\n"
"'available' is whether the stream daemon could be asked at all, "
"so 'no streams' is distinguishable from 'no daemon' without "
"parsing an error."
),
)
status = add_stream_verb(
"status",
_cmd_stream_status,
help="one session's stream (does NOT count as activity)",
)
status.add_argument("id", nargs="?", help="session id; omit for all of them")
def _button_help() -> str:
return f"one of: {', '.join(BUTTONS)} (default: left)"
@@ -749,6 +906,9 @@ def _cmd_start(args: argparse.Namespace) -> int:
home=args.home,
ephemeral_home=args.ephemeral_home or None,
request_id=args.request_id,
stream=args.stream or None,
stream_phrase=args.stream_phrase,
stream_fps=args.stream_fps,
)
if not reply.get("ok"):
# A failed start may still have created a session (it exited at once, or
@@ -778,6 +938,27 @@ def _cmd_start(args: argparse.Namespace) -> int:
"(the only mark of activity; list/status/logs/gc do not count)",
file=sys.stderr,
)
if args.stream:
stream = session.get("stream") or {}
error = session.get("stream_error")
if stream.get("url"):
# stdout, beside the id: the URL is the other thing a caller asked
# for, and `$(... --stream)` giving the id and the URL on two lines
# is more useful than making them run a second verb for it.
print(stream["url"])
print(
f"watching it counts as activity; stop it with: hhstream "
f"session stream disable {session_id}",
file=sys.stderr,
)
else:
# The session started. Saying so loudly, because the exit code is
# 0 and a caller who asked for a stream must not read that as one.
print(
f"WARNING: the session is running but its stream was not "
f"enabled: {error or 'the broker reported no stream'}",
file=sys.stderr,
)
return int(ExitCode.OK)
@@ -1312,6 +1493,77 @@ def _cmd_keyboard_hold(args: argparse.Namespace) -> int:
return _finish_gesture(args, reply, render, args.id)
# --------------------------------------------------------------------------
# the live stream
# --------------------------------------------------------------------------
@_guard
def _cmd_stream_enable(args: argparse.Namespace) -> int:
reply = _request(
args, "stream.enable", id=args.id, phrase=args.phrase, fps=args.fps
)
if not reply.get("ok"):
return _finish(args, reply, lambda r: "")
if args.json:
fmt.dump_json(reply)
return int(ExitCode.OK)
stream = reply.get("stream") or {}
# stdout is the URL and nothing else, the same shape `start` and `pointer
# acquire` already have: one token a caller passes on, detail on stderr.
print(stream.get("url") or "")
print(
f"{reply.get('id')}: streaming output {stream.get('output')} "
f"at {stream.get('fps')} fps",
file=sys.stderr,
)
print(
"the phrase in that URL is its only protection, and watching it counts "
"as activity; stop it with: hhstream session stream disable "
f"{reply.get('id')}",
file=sys.stderr,
)
if not stream.get("attached"):
# `enable` cannot normally get here -- it had to attach to succeed --
# but a reply without it means the daemon answered and then went away,
# and a printed URL that serves nothing is worse than a warning.
print(
"WARNING: the broker recorded this stream but the daemon did not "
"confirm it is attached; the URL may not answer",
file=sys.stderr,
)
return int(ExitCode.OK)
@_guard
def _cmd_stream_disable(args: argparse.Namespace) -> int:
reply = _request(args, "stream.disable", id=args.id)
def render(r: dict[str, Any]) -> str:
detached = r.get("detached")
return (
f"{r.get('id')}: stream disabled and its phrase forgotten"
+ ("" if detached else "; the daemon had already dropped it")
)
return _finish(args, reply, render)
@_guard
def _cmd_stream_list(args: argparse.Namespace) -> int:
reply = _request(args, "stream.list")
return _finish(args, reply, fmt.render_streams)
@_guard
def _cmd_stream_status(args: argparse.Namespace) -> int:
session_id = getattr(args, "id", None)
reply = _request(args, "stream.status", id=session_id)
if session_id is None:
return _finish(args, reply, fmt.render_streams)
return _finish(args, reply, fmt.render_stream)
# --------------------------------------------------------------------------
# standalone use
# --------------------------------------------------------------------------
+81
View File
@@ -120,6 +120,87 @@ def render_list(
)
def render_streams(reply: dict[str, Any]) -> str:
"""``session stream list``: what is published, and who is watching.
**The phrase is not in this table**, and that is the whole shape of it. A
listing is the kind of thing that ends up in a shared terminal, a paste or
a screenshot, and the phrase is the stream's only credential — so what is
shown is enough to recognise and manage a stream (the session, the output,
the rate, the viewers) and not enough to watch one. ``--json`` carries the
phrase and the URL, because a caller that asked for the object asked for
the credential too.
``available`` is printed even when there are streams: "two records and no
daemon" is a different situation from "two records and two captures", and
the difference is invisible from the rows alone.
"""
rows = []
for row in reply.get("streams") or []:
rows.append(
[
_cell(row.get("id")),
_cell(row.get("app")),
_cell(row.get("output")),
_cell(row.get("fps")),
"yes" if row.get("attached") else "NO",
_cell(row.get("viewers")),
]
)
lines = [
render_table(rows, ["ID", "APP", "OUTPUT", "FPS", "LIVE", "VIEWERS"])
if rows
else "no session has a stream enabled"
]
available = reply.get("available")
lines.append(
"daemon: "
+ (
"answering"
if available
else "NOT REACHABLE — the records below are what was asked for, "
"not what is running"
)
)
if rows:
lines.append(
"the URL (with its phrase) is in --json, or in `stream status <id>`"
)
return "\n".join(lines)
def render_stream(reply: dict[str, Any]) -> str:
"""``session stream status ID``: one session's stream, URL included.
The URL *is* here, unlike in the listing: this was asked about one session
by name, which is what somebody about to watch it does, and making them
reach for ``--json`` to get the thing the verb is for would be a worse
trade than the one the listing makes.
"""
stream = reply.get("stream")
if not stream:
return f"{_cell(reply.get('id'))}: no stream enabled"
lines = [
f"{_cell(reply.get('id'))}: output {_cell(stream.get('output'))} "
f"at {_cell(stream.get('fps'))} fps",
]
if stream.get("attached"):
lines.append(f" url {_cell(stream.get('url'))}")
lines.append(f" viewers {_cell(stream.get('viewers'))}")
else:
# No URL, deliberately: the record's phrase is still there, but a URL
# that no longer serves anything is worse than none. See
# `SessionManager._stream_public`.
lines.append(
" url — (the daemon is not publishing this; the phrase is "
"kept, so re-enabling restores the same URL)"
)
lines.append(f" enabled {_cell(stream.get('enabled_at'))}")
return "\n".join(lines)
def render_containers(reply: dict[str, Any]) -> str:
"""``session container`` with no id: every container, and every orphan.