Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

feat(cli): concise help and one-step Session titles (#2980)

Call White6f2bf0bb3b62
diff --git a/core/prompts/session-title.md b/core/prompts/session-title.md
index 54f8dc946..dbc274d19 100644
--- a/core/prompts/session-title.md
+++ b/core/prompts/session-title.md
@@ -1,8 +1,5 @@
## Session Title
-Once this Web conversation's topic is clear, silently set one concise, human-scannable Session title without waiting for the user. First inspect:
-`vibe session get`
+Once this Web conversation's topic is clear, silently set one concise, human-scannable Session title without waiting for the user:
+`vibe session update --title "<short title>" --if-untitled`
-If `metadata.title_source` is `user` or `agent`, leave the title unchanged. Otherwise set it once:
-`vibe session update --title "<short title>"`
-
-Do not mention the update unless asked. After setting it, do not rename it again.
+It keeps a title the user or an Agent already set. Do not mention the update unless asked. After setting it, do not rename it again.
diff --git a/docs/CLI.md b/docs/CLI.md
index 47a87ace5..c46fe1615 100644
--- a/docs/CLI.md
+++ b/docs/CLI.md
@@ -511,6 +511,7 @@ vibe session list --page 2 --limit 50 # request page 2 with 50 rows (at most 1
vibe session get # inside an Avibe Agent shell, the caller Session
vibe session get --session-id sesk8m4q2p7x # full detail for another Session
vibe session update --title 'Release review' # inside an Avibe Agent shell
+vibe session update --title 'Release review' --if-untitled # keep a title a user or Agent set
vibe session update --session-id sesk8m4q2p7x --title '' # clear the title
vibe session update --session-id sesk8m4q2p7x --hidden # background-only; --visible promotes it
vibe session queue list --session-id sesk8m4q2p7x # queued messages in FIFO order
@@ -519,7 +520,11 @@ vibe session send-now --session-id sesk8m4q2p7x # promote the exact
```
Every command except `list` acts on one Session: `--session-id`, or the caller
-Session inside an Avibe Agent shell (see [Grammar](#grammar)). `--type` accepts
+Session inside an Avibe Agent shell (see [Grammar](#grammar)). With `--if-untitled`,
+`update --title` writes only when no user or Agent has titled the Session; an
+automatic title still counts as untitled. The check and the write are one
+transaction, so a concurrent rename is never overwritten, and `updated: false`
+reports that the existing title was kept. `--type` accepts
a platform id: `avibe` (Web/Workbench), `slack`, `discord`, `telegram`, `lark`,
`wechat`. For richer filtering — by agent, time range, message content, or
cross-table joins — use `vibe data query`.
diff --git a/docs/CLI_ZH.md b/docs/CLI_ZH.md
index 674a3a759..110787330 100644
--- a/docs/CLI_ZH.md
+++ b/docs/CLI_ZH.md
@@ -403,6 +403,7 @@ vibe session list --page 2 --limit 50 # 第 2 页,每页 50 条(最多 100
vibe session get # 在 Avibe Agent shell 内查看调用方 Session
vibe session get --session-id sesk8m4q2p7x # 其他会话的完整明细
vibe session update --title 'Release review' # 在 Avibe Agent shell 内
+vibe session update --title 'Release review' --if-untitled # 保留用户或 Agent 已设置的标题
vibe session update --session-id sesk8m4q2p7x --title '' # 清空标题
vibe session update --session-id sesk8m4q2p7x --hidden # 只在后台;--visible 恢复显示
vibe session queue list --session-id sesk8m4q2p7x # 按 FIFO 顺序列出排队消息
@@ -411,7 +412,9 @@ vibe session send-now --session-id sesk8m4q2p7x # 提升精确的
```
除 `list` 外,每个命令都作用于一个 Session:`--session-id`,或在 Avibe Agent shell
-内默认的调用方 Session(见 [语法](#语法))。`--type` 取平台 id:`avibe`(Web/Workbench)、`slack`、`discord`、`telegram`、`lark`、`wechat`。需要更高级的筛选——按 Agent、时间段、消息内容或跨表联查——请使用 `vibe data query`。
+内默认的调用方 Session(见 [语法](#语法))。加上 `--if-untitled` 时,`update --title`
+只在用户或 Agent 尚未设置标题时写入,自动生成的标题仍视为未命名;检查与写入在同一个事务内,
+不会覆盖同时发生的重命名,`updated: false` 表示保留了原标题。`--type` 取平台 id:`avibe`(Web/Workbench)、`slack`、`discord`、`telegram`、`lark`、`wechat`。需要更高级的筛选——按 Agent、时间段、消息内容或跨表联查——请使用 `vibe data query`。
### `vibe runs`
diff --git a/tests/test_cli_task_command.py b/tests/test_cli_task_command.py
index 50ee12f8c..5345fd8cb 100644
--- a/tests/test_cli_task_command.py
+++ b/tests/test_cli_task_command.py
@@ -3,7 +3,6 @@ from __future__ import annotations
import io
import json
import os
-import shlex
import sqlite3
import sys
from contextlib import redirect_stderr
@@ -338,7 +337,7 @@ def test_supported_task_platforms_always_includes_avibe() -> None:
assert "avibe" in cli._supported_task_platforms()
-def test_task_help_describes_session_id_guidance(capsys) -> None:
+def test_task_help_examples_use_the_caller_session_default(capsys) -> None:
parser = cli.build_parser()
with pytest.raises(SystemExit) as exc:
@@ -346,29 +345,27 @@ def test_task_help_describes_session_id_guidance(capsys) -> None:
assert exc.value.code == 0
captured = capsys.readouterr()
- assert "Create, inspect, and control scheduled Agent messages for Avibe." in captured.out
- assert "vibe task add --session-id sesk8m4q2p7x --cron '0 * * * *' --message" in captured.out
assert "{add,update,list,show,pause,resume,run,remove}" in captured.out
+ assert "vibe task add --cron '0 * * * *' --message 'Share the hourly summary.'" in captured.out
+ assert "--session-id" not in captured.out
assert "rm (remove)" not in captured.out
assert "\n ls" not in captured.out
-def test_task_add_help_includes_examples_and_threadless_guidance(capsys) -> None:
+def test_task_add_help_states_task_kinds_and_cron_weekday_names(capsys) -> None:
parser = cli.build_parser()
with pytest.raises(SystemExit) as exc:
parser.parse_args(["task", "add", "--help"])
assert exc.value.code == 0
- captured = capsys.readouterr()
- assert "If this is your first time using this command, read this whole help entry before creating a task." in captured.out
- assert "`--session-id` chooses which Agent Session Avibe will continue using when the task runs." in captured.out
- assert "tasks continue this conversation by default" in captured.out
- assert "--post-to" not in captured.out
- assert "--same-scope" in captured.out
- assert "--scope-id" in captured.out
- assert "--deliver-key" not in captured.out
- assert "Write cron weekdays as names (mon, tue, ... sun)." in captured.out
+ text = " ".join(capsys.readouterr().out.split())
+ assert "A message task stores --message and sends it to the target Session on each run." in text
+ assert "A command task (--shell, or a command after '--') runs with no Agent turn." in text
+ assert "with --on-failure agent starts one Agent turn" in text
+ assert "Only that form takes Session, scope, or Agent flags." in text
+ assert "Write cron weekdays as names (mon ... sun): numbers are rejected" in text
+ assert "vibe task add --cron '0 9 * * mon-fri' --message" in text
def test_task_list_help_mentions_completed_one_shots_hidden_by_default(capsys) -> None:
@@ -386,64 +383,36 @@ def test_task_list_help_mentions_completed_one_shots_hidden_by_default(capsys) -
assert "--all" not in captured.out
-def test_task_update_help_includes_partial_update_guidance(capsys) -> None:
+def test_task_update_help_states_partial_update_and_kind_rules(capsys) -> None:
parser = cli.build_parser()
with pytest.raises(SystemExit) as exc:
parser.parse_args(["task", "update", "--help"])
assert exc.value.code == 0
- captured = capsys.readouterr()
- assert "keeping its task ID" in captured.out
- assert "--reset-delivery" in captured.out
- assert "Unspecified fields keep their existing values." in captured.out
- assert "Write cron weekdays as names (mon, tue, ... sun)." in captured.out
+ text = " ".join(capsys.readouterr().out.split())
+ assert "Unspecified fields keep their values." in text
+ assert "A message task cannot become a command task, or the reverse, and --on-failure cannot change" in text
+ assert "Write cron weekdays as names (mon ... sun); numbers are rejected." in text
-def test_agent_run_help_includes_fork_session_guidance(capsys) -> None:
+def test_agent_run_help_states_session_callback_and_fork_rules(capsys) -> None:
parser = cli.build_parser()
with pytest.raises(SystemExit) as exc:
parser.parse_args(["agent", "run", "--help"])
assert exc.value.code == 0
- captured = capsys.readouterr()
- assert "--fork-session FORK_SESSION" in captured.out
- assert "--fork-self" in captured.out
- assert "--sync" in captured.out
- assert "--send-now" not in captured.out
- assert "--create-session" not in captured.out
- assert "--async" not in captured.out
- assert "--same-scope" in captured.out
- assert "--scope-id" in captured.out
- assert "--visible" in captured.out
- assert "--deliver-key" not in captured.out
- assert "Avibe Agent shell examples:" in captured.out
- assert "Normal terminal examples:" in captured.out
- assert "--fork-self forks this current Session." in captured.out
- assert "Forks keep the same backend, scope, and cwd as the source Session." in captured.out
- assert "vibe agent run --fork-self --message" in captured.out
- assert "vibe agent run --session-id sesk8m4q2p7x --message" in captured.out
- assert "vibe session queue list --session-id sesk8m4q2p7x" in captured.out
- assert "vibe session queue remove msg_queued123 --session-id sesk8m4q2p7x" in captured.out
- assert "vibe session send-now --session-id sesk8m4q2p7x" in captured.out
- assert "Agent runs are async by default. From an Avibe Agent shell, they return their final result to this conversation by default." in captured.out
- assert "vibe agent run --agent release-reviewer --message 'Review the latest deployment result.'" in captured.out
- assert (
- "vibe agent run --agent release-reviewer --visible --message 'Review this project in a visible sibling Session.'"
- in captured.out
- )
- assert (
- "vibe agent run --agent release-reviewer --no-callback --message 'Review the latest deployment result.'"
- not in captured.out
- )
- assert "vibe agent run --agent release-reviewer --same-scope --no-callback --message" not in captured.out
- assert "From a normal terminal, pass --callback-session-id or --no-callback for async runs." in captured.out
- assert "Review the latest CI result and print it here." in captured.out
- assert "Review the latest CI result and report back." in captured.out
- assert "--callback-session-id sescaller456 --message 'Review the latest CI result and report back.'" in captured.out
- assert "--no-callback --message 'Review the latest CI result and report back.'" not in captured.out
- assert "Do not combine fork flags with --session-id." in captured.out
+ text = " ".join(capsys.readouterr().out.split())
+ assert "Runs are async: the final result returns to the caller Session." in text
+ assert "Elsewhere, pass --callback-session-id, --no-callback, or --sync." in text
+ assert "--session-id ID Join this Session's running turn, or start one if idle" in text
+ assert "--queue With --session-id: wait for the running turn" in text
+ assert "Fork this Session's context, backend, scope, and cwd" in text
+ assert "Agent for a new Session (a fork: same backend only)" in text
+ assert "--model, --reasoning-effort, --visible, --same-scope, --scope-id, and --close-after apply only to a new or forked Session." in text
+ for jargon in ("P1", "P3", "native Turn", "steer"):
+ assert jargon not in text
def test_agent_run_visible_sugar_sets_foreground_visibility() -> None:
@@ -462,7 +431,7 @@ def test_task_add_parse_error_is_structured_json(capsys) -> None:
payload = json.loads(capsys.readouterr().err)
assert payload["code"] == "invalid_arguments"
assert payload["help_command"] == "vibe task add --help"
- assert "--session-id SESSION_ID" in payload["usage"]
+ assert "--session-id ID" in payload["usage"]
def test_task_remove_parse_error_keeps_structured_guidance(capsys) -> None:
@@ -4714,26 +4683,6 @@ def test_task_payload_renders_message_kind_for_message_tasks(tmp_path: Path) ->
assert {"command_preview", "last_exit_code"}.isdisjoint(brief)
-# --- documented examples --------------------------------------------------
-
-
-def test_documented_task_command_examples_stay_parseable() -> None:
- """Injected help text is a live caller: every example must survive the parser."""
-
- parser = cli.build_parser()
- text = cli._task_add_examples_text() + "\n" + cli._task_update_examples_text()
- examples = [
- line.strip()
- for line in text.splitlines()
- if line.strip().startswith(("vibe task add ", "vibe task update "))
- ]
- command_examples = [line for line in examples if "--shell" in line or "--timeout" in line]
- assert len(examples) >= 4
- assert len(command_examples) >= 3
-
- for example in examples:
- parser.parse_args(shlex.split(example)[1:])
-
def test_task_resume_rejects_orphaned_owner_without_execution_target(
monkeypatch, tmp_path: Path
) -> None:
diff --git a/tests/test_cli_watch_command.py b/tests/test_cli_watch_command.py
index 408b8be0d..92775dbff 100644
--- a/tests/test_cli_watch_command.py
+++ b/tests/test_cli_watch_command.py
@@ -80,7 +80,7 @@ def _add_test_watch(
)
-def test_watch_help_describes_session_id_guidance(capsys) -> None:
+def test_watch_help_examples_use_the_caller_session_default(capsys) -> None:
parser = cli.build_parser()
with pytest.raises(SystemExit) as exc:
@@ -88,40 +88,9 @@ def test_watch_help_describes_session_id_guidance(capsys) -> None:
assert exc.value.code == 0
captured = capsys.readouterr()
- assert "managed background watchers" in captured.out
- assert "vibe watch add --session-id sesk8m4q2p7x --name 'Wait for export' --message" in captured.out
assert "{add,update,list,show,pause,resume,remove}" in captured.out
-
-
-def test_watch_add_help_mentions_shell_and_lifetime_timeout(capsys) -> None:
- parser = cli.build_parser()
-
- with pytest.raises(SystemExit) as exc:
- parser.parse_args(["watch", "add", "--help"])
-
- assert exc.value.code == 0
- captured = capsys.readouterr()
- normalized_help = " ".join(captured.out.split())
- assert "Pass either --shell '<command>' or a command after '--'." in captured.out
- assert "--lifetime-timeout" in captured.out
- assert "vibe watch add --session-id sesk8m4q2p7x --message 'The export finished. Inspect it and continue.'" in captured.out
- assert "watches follow up in this conversation by default" in captured.out
- assert "Use --message or --message-file for follow-up instructions." in captured.out
- assert "--prefix" not in captured.out
- assert "--session-key" not in captured.out
- assert "Terminal failures also send a follow-up and disable the watch." in captured.out
- assert "an allowed `--retry-exit-code` keeps waiting" in captured.out
- assert "A once Watch stops after its first event" in captured.out
- assert "five-second safety delay" in captured.out
- assert "automatically pause the Watch" in captured.out
- assert "a once Watch ends and a forever Watch re-arms" in captured.out
- assert "A once waiter that is still waiting must use a retry exit code" in captured.out
- assert "If this is your first time using this command, read this whole help entry before creating a watch." in captured.out
- assert "Use 0 for no per-cycle timeout" in normalized_help
- assert "--same-scope" in captured.out
- assert "--scope-id" in captured.out
- assert "--post-to" not in captured.out
- assert "--deliver-key" not in captured.out
+ assert "vibe watch add --name 'Wait for export' --message" in captured.out
+ assert "--session-id" not in captured.out
def test_watch_update_preserves_archived_agent_reference(tmp_path: Path, capsys) -> None:
@@ -2116,14 +2085,23 @@ def test_watch_add_refuses_the_reserved_session_with_no_side_effects(
)
-def test_watch_add_help_states_the_no_event_marker_contract() -> None:
+def test_watch_add_help_states_the_waiter_contract(capsys) -> None:
"""The help is a live caller of the waiter contract, not a description of it.
A custom waiter written from this text is what the supervisor then judges, so
guidance that named the exit code but not the marker sent people straight into
a watch that reports a failure and disables itself.
"""
- text = cli._watch_add_examples_text()
-
- assert str(watches.NO_EVENT_EXIT_CODE) in text
- assert watches.NO_EVENT_MARKER in text
+ with pytest.raises(SystemExit):
+ cli.build_parser().parse_args(["watch", "add", "--help"])
+ text = capsys.readouterr().out
+
+ assert "0 one new event" in text
+ assert f"{watches.DEFAULT_RETRY_EXIT_CODE} still waiting (any --retry-exit-code)" in text
+ assert f"{watches.NO_EVENT_EXIT_CODE} plus the stderr line '{watches.NO_EVENT_MARKER}'" in text
+ assert f"A bare {watches.NO_EVENT_EXIT_CODE} is a failure" in text
+ assert "failure (124 = timed out)" in text
+ assert "A once Watch stops at its first event or quiet cycle; --forever re-arms after each." in text
+ assert "rapid repeats pause the Watch" in text
+ first_example = next(line for line in text.splitlines() if line.strip().startswith("vibe watch add"))
+ assert "--session-id" not in first_example
diff --git a/tests/test_prompt_render_export.py b/tests/test_prompt_render_export.py
index 0af222b7d..780dc5be8 100644
--- a/tests/test_prompt_render_export.py
+++ b/tests/test_prompt_render_export.py
@@ -68,6 +68,15 @@ _FOLLOW_THROUGH_PRINCIPLE = (
"across turns as well as within one. When repeatedly blocked, rethink the approach instead of "
"retrying it. Stop only to wait on a stated condition or at an explained blocker."
)
+_PREVIOUS_SESSION_TITLE_STEPS = (
+ "without waiting for the user. First inspect:\n`vibe session get`\n\n"
+ "If `metadata.title_source` is `user` or `agent`, leave the title unchanged. Otherwise set it once:\n"
+ '`vibe session update --title "<short title>"`\n\nDo not mention'
+)
+_SESSION_TITLE_STEPS = (
+ 'without waiting for the user:\n`vibe session update --title "<short title>" --if-untitled`\n\n'
+ "It keeps a title the user or an Agent already set. Do not mention"
+)
_CODEX_SKILL_REUSE_GUIDANCE = (
"Choose skills by task relevance, but load a skill only if it has not already been read "
"in this conversation; reuse already-loaded instructions across turns, callbacks, "
@@ -553,7 +562,9 @@ def test_approved_guidance_changes_preserve_all_other_injection_bytes(monkeypatc
assert text.count(_FOLLOW_THROUGH_PRINCIPLE) == 1
assert text.count(_NEW_SESSION_MODEL_GUIDANCE) == 1
assert text.count(_HARNESS_SOURCE_GUIDANCE) == 1
+ assert text.count(_SESSION_TITLE_STEPS) == 1
text = text.replace(_HARNESS_SOURCE_GUIDANCE, "")
+ text = text.replace(_SESSION_TITLE_STEPS, _PREVIOUS_SESSION_TITLE_STEPS)
text = text.replace(_NEW_SESSION_MODEL_GUIDANCE, _PREVIOUS_FORK_OVERRIDE_GUIDANCE)
text = text.replace(_HISTORY_AS_MEMORY_GUIDANCE, _PREVIOUS_HISTORY_GUIDANCE)
text = text.replace(_FOLLOW_THROUGH_PRINCIPLE, _PREVIOUS_FOLLOW_THROUGH_PRINCIPLE)
@@ -565,6 +576,7 @@ def test_approved_guidance_changes_preserve_all_other_injection_bytes(monkeypatc
# verification principle and conversation-history guidance and Follow-through
# principle, and the Harness rule that a run's --model applies
# only to forks (now: to any new Session a run creates), and without the
- # Harness line that says what a `[Harness: ...]` input is.
+ # Harness line that says what a `[Harness: ...]` input is, and restoring the
+ # two-call Session Title steps that `--if-untitled` replaced.
# Every other byte/order stays pinned, including all Claude/OpenCode output.
assert digest == "262c7cbabbbb0bfefa4a69511d805d28f76a3559bd511184006242f831b4836e"
diff --git a/tests/test_session_cli.py b/tests/test_session_cli.py
index 2f6415489..592472ad8 100644
--- a/tests/test_session_cli.py
+++ b/tests/test_session_cli.py
@@ -659,6 +659,83 @@ def test_update_empty_title_clears(monkeypatch, tmp_path, capsys):
assert payload["session"]["title"] is None
+ ("title_source", "updated"),
+ [
+ (None, True),
+ ("backend", True),
+ ("derived_first_prompt", True),
+ ("user", False),
+ ("agent", False),
+ ],
+)
+def test_update_if_untitled_keeps_only_a_deliberate_title(monkeypatch, tmp_path, capsys, title_source, updated):
+ """The Session Title prompt's one call: an automatic title counts as untitled."""
+ engine = _setup(monkeypatch, tmp_path)
+ _seed(engine, "sesaaa", title="Old", title_source=title_source)
+
+ code, payload = _run(
+ cli.cmd_session_update,
+ ["session", "update", "--session-id", "sesaaa", "--title", "New name", "--if-untitled"],
+ capsys,
+ )
+
+ assert code == 0
+ assert payload["updated"] is updated
+ assert payload["session"]["title"] == ("New name" if updated else "Old")
+ assert payload["session"]["metadata"].get("title_source") == ("agent" if updated else title_source)
+
+
+def test_update_if_untitled_never_overwrites_a_concurrent_user_rename(monkeypatch, tmp_path, capsys):
+ """A rename committed while the call waits wins, because the check holds the write lock."""
+ import threading
+ import time
+
+ engine = _setup(monkeypatch, tmp_path)
+ _seed(engine, "sesaaa", title="Auto", title_source="backend")
+ args = cli.build_parser().parse_args(
+ ["session", "update", "--session-id", "sesaaa", "--title", "Agent name", "--if-untitled"]
+ )
+ result = {}
+ with engine.connect() as web:
+ web.exec_driver_sql("BEGIN IMMEDIATE")
+ web.execute(
+ agent_sessions.update()
+ .where(agent_sessions.c.id == "sesaaa")
+ .values(title="User name", metadata_json=json.dumps({"title_source": "user"}))
+ )
+ worker = threading.Thread(target=lambda: result.update(code=cli.cmd_session_update(args)))
+ worker.start()
+ time.sleep(0.5) # let the CLI reach the lock before the rename commits
+ web.commit()
+ worker.join(timeout=10)
+
+ assert result["code"] == 0
+ assert json.loads(capsys.readouterr().out)["updated"] is False
+ with engine.connect() as conn:
+ assert conn.execute(
+ agent_sessions.select().where(agent_sessions.c.id == "sesaaa")
+ ).mappings().one()["title"] == "User name"
+
+
+ "extra",
+ [[], ["--title", "x", "--hidden"], ["--title", "x", "--scope-id", "none"]],
+)
+def test_update_if_untitled_applies_only_to_title(monkeypatch, tmp_path, capsys, extra):
+ engine = _setup(monkeypatch, tmp_path)
+ _seed(engine, "sesaaa", title="Old")
+
+ code, payload = _run(
+ cli.cmd_session_update,
+ ["session", "update", "--session-id", "sesaaa", "--if-untitled", *extra],
+ capsys,
+ )
+
+ assert code == 1
+ assert payload["code"] == "invalid_arguments"
+
+
def test_update_help_teaches_visibility_sugar(capsys):
parser = cli.build_parser()
@@ -836,13 +913,11 @@ def test_web_title_prompt_defaults_to_current_session():
out = _injection_for("sesweb")
title_prompt = out[out.index("## Session Title") :]
assert "## Session Title" in out
- assert "`vibe session get`" in out
- assert '`vibe session update --title "<short title>"`' in out
- assert "vibe session get sesweb" not in out
- assert 'vibe session update sesweb --title "<short title>"' not in out
- assert "metadata.title_source" in out
- assert "`user` or `agent`" in out
- assert "leave the title unchanged" in out
+ # One call: the CLI keeps a deliberate title, so no `vibe session get` first.
+ assert '`vibe session update --title "<short title>" --if-untitled`' in title_prompt
+ assert "vibe session get" not in title_prompt
+ assert "sesweb" not in title_prompt
+ assert "keeps a title the user or an Agent already set" in out
assert "silently set one concise, human-scannable Session title" in out
assert "without waiting for the user" in out
assert "do not rename it again" in out
diff --git a/tests/test_show_pages.py b/tests/test_show_pages.py
index 0dd1f957d..5682cb151 100644
--- a/tests/test_show_pages.py
+++ b/tests/test_show_pages.py
@@ -114,8 +114,7 @@ def test_show_without_subcommand_prints_help(capsys):
assert "Manage the one visual Show Page attached to an Agent Session." in captured.out
assert "usage: vibe show [-h]" in captured.out
assert "{list,path,status,update,mark,reply,marks,unmark,event,annotate} ..." in " ".join(captured.out.split())
- assert "vibe show list" in captured.out
- assert "vibe show path --session-id sesk8m4q2p7x" in captured.out
+ assert " vibe show path\n" in captured.out
assert "Accept: text/markdown" in captured.out
diff --git a/tests/test_vibe_cli.py b/tests/test_vibe_cli.py
index ab6e531fd..aff4335ae 100644
--- a/tests/test_vibe_cli.py
+++ b/tests/test_vibe_cli.py
@@ -76,25 +76,26 @@ def _write_alembic_revision(db_path: Path, revision: str) -> None:
conn.execute("insert into alembic_version values (?)", (revision,))
+def _parser_leaves(parser, path=()):
+ import argparse
+
+ yield path, parser
+ for action in parser._actions:
+ if isinstance(action, argparse._SubParsersAction):
+ for name, child in action.choices.items():
+ yield from _parser_leaves(child, (*path, name))
+
+
def test_cli_text_is_english_whatever_the_ui_language(monkeypatch, tmp_path, capsys):
"""Agents read CLI help and errors; they stay English when the Web UI is set to Chinese."""
- import argparse
-
config_path = tmp_path / "config.json"
config_path.write_text(json.dumps({"language": "zh"}), encoding="utf-8")
monkeypatch.setattr(cli.paths, "get_config_path", lambda: config_path)
monkeypatch.setattr(cli.V2Config, "load", lambda *_args, **_kwargs: SimpleNamespace(language="zh"))
han = re.compile(r"[\u4e00-\u9fff]")
- def leaves(parser, path=()):
- yield path, parser
- for action in parser._actions:
- if isinstance(action, argparse._SubParsersAction):
- for name, child in action.choices.items():
- yield from leaves(child, (*path, name))
-
- for path, parser in leaves(cli.build_parser()):
+ for path, parser in _parser_leaves(cli.build_parser()):
help_text = parser.format_help()
assert not han.search(help_text), f"vibe {' '.join(path)} --help is not English"
@@ -103,6 +104,24 @@ def test_cli_text_is_english_whatever_the_ui_language(monkeypatch, tmp_path, cap
assert not han.search(capsys.readouterr().err)
+def test_every_help_fits_its_budget_and_its_examples_parse(monkeypatch):
+ """Agents read --help before a first call, pay for every byte, and copy its examples."""
+
+ monkeypatch.setenv("COLUMNS", "80") # what a non-TTY Agent shell renders
+ for path, parser in _parser_leaves(cli.build_parser()):
+ command = " ".join(("vibe", *path))
+ size = len(parser.format_help().encode())
+ assert size <= 2560, f"{command} --help is {size} bytes; keep it within 2.5 KiB"
+ for line in (parser.epilog or "").splitlines():
+ example = line.strip()
+ if not example.startswith("vibe "):
+ continue
+ try:
+ cli.build_parser().parse_args(shlex.split(example, comments=True)[1:])
+ except SystemExit as exc:
+ raise AssertionError(f"{command} --help teaches an unparseable example: {example!r}") from exc
+
+
def test_top_level_help_lists_only_public_commands(capsys):
parser = cli.build_parser()
diff --git a/vibe/cli.py b/vibe/cli.py
index abb7e3096..28d29d660 100644
--- a/vibe/cli.py
+++ b/vibe/cli.py
@@ -61,6 +61,7 @@ from core.vibe_agents import AgentAlwaysEnabledError, AgentArchivedEditError, Ag
from core.watches import (
DEFAULT_RETRY_EXIT_CODE,
NO_EVENT_EXIT_CODE,
+ NO_EVENT_MARKER,
WATCH_RECOVERY_ENTRY_TIMEOUT_SECONDS,
WATCH_RECONCILE_INTERVAL_SECONDS,
JobWatchUpdateRefused,
@@ -1159,10 +1160,9 @@ def _task_examples_text() -> str:
return dedent(
"""\
Examples:
- vibe task add --session-id sesk8m4q2p7x --cron '0 * * * *' --message 'Share the hourly summary.'
+ vibe task add --cron '0 * * * *' --message 'Share the hourly summary.'
vibe task update 12ab34cd56ef --cron '*/30 * * * *' --name 'Half-hour summary'
vibe task run 12ab34cd56ef
- vibe task add --create-session --scope-id slack::channel::C123 --cron '*/5 * * * *' --message 'Tell a new joke each time.'
vibe task add --create-session --scope-id slack::channel::C123 --at '2026-03-31T09:00:00+08:00' --message-file briefing.md
"""
)
@@ -1171,36 +1171,17 @@ def _task_examples_text() -> str:
def _task_add_examples_text() -> str:
return dedent(
"""\
- Session target:
- Use --session-id with the target Agent Session ID, for example sesk8m4q2p7x.
- Inside an Avibe Agent shell, tasks continue this conversation by default.
-
- Guidance:
- If this is your first time using this command, read this whole help entry before creating a task.
- `--session-id` chooses which Agent Session Avibe will continue using when the task runs.
- Use --create-session with --scope-id <scopes.id> to create a reusable Session in a specific existing scope.
- Use --create-session with --same-scope only from an Avibe Agent shell, where the caller Session scope is available.
- Use --cwd only for Sessions created by this task; existing target Sessions keep their own cwd.
- `--message` and `--message-file` provide the stored user message that will be sent each time the task runs.
- Use --cron for recurring jobs and --at for one-shot jobs.
- Write cron weekdays as names (mon, tue, ... sun). Numeric weekdays are rejected because Avibe's scheduler reads 0 as Monday while crontab(5) reads 0 as Sunday.
- --timezone controls how --cron and naive --at timestamps are interpreted.
-
- Command tasks:
- A command task runs a subprocess on schedule with NO Agent turn, so it needs no Session, Agent, or message.
- Use --shell for a shell command string, or pass the executable and its args after '--'.
- Failure handling is silent-success by default: a successful run stays quiet, and a failed run records a failure notice.
- Add --on-failure agent with --message to spend an Agent turn triaging a failed run instead.
- --timeout bounds one run; use 0 for no timeout.
- --cwd is where the command runs; without it, a Session-bound command follows that Session's directory
- and every other command records the directory you ran this from.
+ A message task stores --message and sends it to the target Session on each run.
+ A command task (--shell, or a command after '--') runs with no Agent turn. A success is
+ silent; a failure records a notice, or with --on-failure agent starts one Agent turn
+ with the failure and --message. Only that form takes Session, scope, or Agent flags.
+ Write cron weekdays as names (mon ... sun): numbers are rejected, because Avibe reads
+ 0 as Monday and crontab(5) reads it as Sunday.
Examples:
- vibe task add --session-id sesk8m4q2p7x --cron '0 * * * *' --message 'Share the hourly summary.'
- vibe task add --create-session --scope-id slack::channel::C123 --cron '*/5 * * * *' --message 'Tell a new joke each time.'
- vibe task add --create-session --scope-id slack::channel::C123 --cron '0 9 * * *' --message 'Post a visible daily summary in this scope.'
- vibe task add --name nightly-sync --cron '0 3 * * *' --shell './scripts/sync.sh'
- vibe task add --cron '0 3 * * *' --shell './scripts/sync.sh' --on-failure agent --message 'The nightly sync failed. Diagnose it.'
+ vibe task add --cron '0 9 * * mon-fri' --message 'Share the morning summary.'
+ vibe task add --at '2026-03-31T09:00:00+08:00' --create-session --scope-id slack::channel::C123 --message-file briefing.md
+ vibe task add --cron '0 3 * * *' --shell './scripts/sync.sh' --on-failure agent --message 'The sync failed. Diagnose it.'
"""
)
@@ -1208,26 +1189,14 @@ def _task_add_examples_text() -> str:
def _task_update_examples_text() -> str:
return dedent(
"""\
- You may update any subset of the stored task fields while keeping the same task ID.
-
- Common updates:
- vibe task update 12ab34cd56ef --name 'Morning summary'
- vibe task update 12ab34cd56ef --cron '*/30 * * * *'
- vibe task update 12ab34cd56ef --message 'Send a shorter summary.'
- vibe task update 12ab34cd56ef --session-id sesk8m4q2p7x
- vibe task update 12ab34cd56ef --create-session --scope-id slack::channel::C123
- vibe task update 12ab34cd56ef --reset-delivery
- vibe task update 12ab34cd56ef --shell './scripts/sync.sh --verbose'
- vibe task update 12ab34cd56ef --timeout 900
-
- Guidance:
- Unspecified fields keep their existing values.
- A command task and a message task are different kinds: remove and recreate the task to move between them, or to change --on-failure.
- Use --reset-delivery to return to following the session target directly.
- Use --same-scope or --scope-id when this task should create new Sessions in a specific scope.
- When changing schedule fields, pass either --cron or --at.
- Write cron weekdays as names (mon, tue, ... sun). Numeric weekdays are rejected because Avibe's scheduler reads 0 as Monday while crontab(5) reads 0 as Sunday.
- Use --clear-name if you want the task to stop storing a custom name.
+ Unspecified fields keep their values. A message task cannot become a command task, or
+ the reverse, and --on-failure cannot change: remove the task and add a new one.
+ Write cron weekdays as names (mon ... sun); numbers are rejected.
+
+ Examples:
+ vibe task update 12ab34cd56ef --cron '0 9 * * mon-fri'
+ vibe task update 12ab34cd56ef --name 'Morning summary' --message 'Send a shorter summary.'
+ vibe task update 12ab34cd56ef --shell './scripts/sync.sh --verbose' --timeout 900
"""
)
@@ -1236,9 +1205,8 @@ def _watch_examples_text() -> str:
return dedent(
"""\
Examples:
- vibe watch add --session-id sesk8m4q2p7x --name 'Wait for export' --message 'The export finished. Inspect it and continue.' --shell 'python3 scripts/wait_for_export.py'
+ vibe watch add --name 'Wait for export' --message 'The export finished. Inspect it and continue.' --shell 'python3 scripts/wait_for_export.py'
vibe watch add --create-session --scope-id slack::channel::C123 --message 'The CI job finished. Inspect the result.' -- python3 scripts/wait_for_ci.py --build 42
- vibe watch add --session-id sesk8m4q2p7x --forever --retry-exit-code 75 --retry-delay 60 --message 'The log pattern appeared. Continue from the result below.' --shell 'bash scripts/wait_for_log_pattern.sh'
vibe watch list
vibe watch show 12ab34cd56ef
vibe watch pause 12ab34cd56ef
@@ -1924,59 +1892,20 @@ def _remote_pair_examples_text() -> str:
def _show_examples_text() -> str:
- markdown_help = "Public Show Page links automatically return agent-readable Markdown to Agents and command-line clients. For an authorized private read, request the URL with Accept: text/markdown."
return dedent(
"""\
- A Show Page is one session-scoped visual page that Avibe serves through the Web UI / Avibe Cloud tunnel.
- One Agent Session has exactly one Show Page.
-
- Agent-readable representation:
- __MARKDOWN_HELP__
-
- Commands:
- list List existing Show Pages across sessions.
- path Create or resolve the local workspace.
- status Inspect local path, visibility, active URL, and share state.
- update Switch visibility, set a custom public link, rotate share links, or take the page offline.
- mark Add an assistant mark event to the session.
- reply Reply to a dispatched page annotation at its original anchor.
- marks List active assistant marks.
- unmark Resolve active assistant marks by id or target.
- event Record a generic annotation-layer event.
- annotate Control the page's annotation overlay.
-
- Visibility:
- private Authenticated Web UI URL under /show/<session-id>/.
- public Short unauthenticated share URL under /p/<share-id>/.
- offline URL access is revoked; local files remain.
+ Each Agent Session has one Show Page, served through the Web UI or the Avibe Cloud tunnel.
+ Visibility: private is the signed-in /show/<session-id>/ URL; public is an unauthenticated
+ /p/<share-id>/ URL; offline revokes URL access and keeps the local files.
+ Public Show Page links automatically return agent-readable Markdown to Agents and
+ command-line clients. For an authorized private read, send Accept: text/markdown.
Examples:
- vibe show list
- vibe show list --global --visibility public
- vibe show path --session-id sesk8m4q2p7x
- vibe show status --session-id sesk8m4q2p7x
- vibe show update --session-id sesk8m4q2p7x --visibility public
- vibe show update --session-id sesk8m4q2p7x --visibility offline
- vibe show mark mark-default-summary --session-id sesk8m4q2p7x --message "Review this summary."
- vibe show reply show_evt_1a2b3c4d --message "The source changed in W30."
- vibe show marks
- vibe show unmark mark_1 mark-default-summary
- vibe show event --session-id sesk8m4q2p7x --event-json @./show-event.json
- vibe show annotate --session-id sesk8m4q2p7x --on --mode screenshot
-
- More:
- vibe show list --help
- vibe show path --help
- vibe show status --help
- vibe show update --help
- vibe show mark --help
- vibe show reply --help
- vibe show marks --help
- vibe show unmark --help
- vibe show event --help
- vibe show annotate --help
+ vibe show path
+ vibe show update --visibility public
+ vibe show annotate --on --mode screenshot
"""
- ).replace("__MARKDOWN_HELP__", markdown_help)
+ )
def _show_path_examples_text() -> str:
@@ -2080,35 +2009,19 @@ def _print_json(payload: dict) -> None:
def _watch_add_examples_text() -> str:
return dedent(
- """\
- Session target:
- Use --session-id with the target Agent Session ID, for example sesk8m4q2p7x.
- Inside an Avibe Agent shell, watches follow up in this conversation by default.
-
- Guidance:
- If this is your first time using this command, read this whole help entry before creating a watch.
- Use a watch when a script should wait in the background and send a follow-up when it detects an event or reaches a terminal failure.
- `--session-id` chooses which Agent Session Avibe will continue using for follow-up messages from the watch.
- Use --create-session with --scope-id <scopes.id> to create a reusable Session in a specific existing scope.
- Use --create-session with --same-scope only from an Avibe Agent shell, where the caller Session scope is available.
- Use --message or --message-file for follow-up instructions.
- Terminal failures also send a follow-up and disable the watch.
- In either mode, an allowed `--retry-exit-code` keeps waiting. A once Watch stops after its first event.
- A forever Watch waits for each event's Agent Run to finish before re-arming, then applies a five-second safety delay.
- Exit 0 must mean one new reportable event, not a condition that merely remains true. Repeated rapid successes automatically pause the Watch and send the Agent a repair message.
- Waiter exit codes: 0 detected an event and sends the follow-up; 124 timed out and is terminal unless explicitly allowed for retry;
- 64 PLUS the line 'avibe-watch: no-event' on stderr means the cycle ran and found nothing worth reporting,
- so a once Watch ends and a forever Watch re-arms WITHOUT an Agent turn. A once waiter that is still waiting must use a retry exit code.
- Any other non-zero is a failure.
- The marker is required: 64 alone is also sysexits EX_USAGE, so a bare 64 stays a failure and stops the watch.
- Use it in waiters whose normal outcome is uninteresting, such as green CI.
- Pass either --shell '<command>' or a command after '--'.
- --timeout applies to each cycle. --lifetime-timeout applies to the whole Watch lifetime across retries and re-arms.
+ f"""\
+ Waiter exit codes:
+ 0 one new event: start the follow-up Run
+ {DEFAULT_RETRY_EXIT_CODE} still waiting (any --retry-exit-code): rerun after --retry-delay
+ {NO_EVENT_EXIT_CODE} plus the stderr line '{NO_EVENT_MARKER}': quiet cycle, no Agent turn
+ other failure (124 = timed out): a follow-up Run, then the Watch stops
+ A once Watch stops at its first event or quiet cycle; --forever re-arms after each.
+ Exit 0 only for a new event: rapid repeats pause the Watch. A bare {NO_EVENT_EXIT_CODE} is a failure.
Examples:
- vibe watch add --session-id sesk8m4q2p7x --message 'The export finished. Inspect it and continue.' --shell 'python3 scripts/wait_for_export.py'
- vibe watch add --create-session --scope-id slack::channel::C123 --message 'The export finished.' -- bash -lc 'sleep 120; echo done'
- vibe watch add --session-id sesk8m4q2p7x --forever --timeout 600 --lifetime-timeout 86400 --retry-exit-code 75 --retry-delay 30 --message 'PR #153 changed. Inspect it and continue.' -- uv run --no-project scripts/wait_pr.py --repo avibe-bot/avibe --pr 153
+ vibe watch add --name export --message 'The export finished. Check it.' -- python3 wait_export.py
+ vibe watch add --forever --timeout 0 --message 'The deploy changed.' --shell './wait_deploy.sh'
+ vibe watch add --create-session --scope-id slack::channel::C123 --message 'Build done.' -- make build
"""
)
@@ -2116,50 +2029,15 @@ def _watch_add_examples_text() -> str:
def _agent_run_examples_text() -> str:
return dedent(
"""\
- Session target:
- Use --session-id to continue an existing Agent Session.
- The default is P1: steer an active native Turn, start when idle, or fall back to the durable P3 queue.
- Add --queue to persist this Run as P3 behind the active Turn.
- To promote the exact existing P3 queue head without a new message, use: vibe session send-now --session-id <session-id>
- Inspect queued work with: vibe session queue list --session-id <session-id>
- Remove one exact queued row with: vibe session queue remove <message-id> --session-id <session-id>
- Omit --session-id/--fork-self/--fork-session to create a background Session for --agent.
- Inside an Agent shell it inherits the caller scope and invocation cwd; outside one it is standalone with its own Show workspace.
- Use --same-scope to explicitly place a new Session in the caller/source Session's scope.
- Use --scope-id <scopes.id> to place a new Session in a specific existing scope.
- New and forked delegated Sessions are background by default; pass --visible to make them user-facing and enable outward delivery.
- --cwd only applies to new Sessions; existing Sessions keep their own cwd.
-
- Callback:
- Agent runs are async by default. From an Avibe Agent shell, they return their final result to this conversation by default.
- From a normal terminal, pass --callback-session-id or --no-callback for async runs.
- Pass --no-callback only when you intentionally want no automatic follow-up.
- Pass --callback-session-id only when the final result should return somewhere else.
- Pass --sync when the CLI should wait for the run result in the terminal.
-
- Forking:
- --fork-self forks this current Session.
- --fork-session <session-id> creates a new Avibe Agent Session and asks the native backend to fork the source native session on the first turn.
- Forks keep the same backend, scope, and cwd as the source Session. Passing --agent is allowed only when that Agent uses the same backend.
- --agent, --model, and --reasoning-effort may override the forked Session's Agent/model/effort.
- Do not combine fork flags with --session-id.
-
- Avibe Agent shell examples:
- vibe agent run --agent release-reviewer --message 'Review the latest deployment result.'
- vibe agent run --agent release-reviewer --visible --message 'Review this project in a visible sibling Session.'
- vibe agent run --session-id sesk8m4q2p7x --message 'Apply this correction in the current turn.'
- vibe session queue list --session-id sesk8m4q2p7x
- vibe session queue remove msg_queued123 --session-id sesk8m4q2p7x
- vibe session send-now --session-id sesk8m4q2p7x
-
- Normal terminal examples:
- vibe agent run --sync --agent release-reviewer --message 'Review the latest CI result and print it here.'
- vibe agent run --agent release-reviewer --callback-session-id sescaller456 --message 'Review the latest CI result and report back.'
- vibe agent run --agent release-reviewer --no-callback --message 'Run a background experiment; I will inspect the run later.'
-
- Fork examples:
- vibe agent run --fork-self --message 'Explore this alternate fix from the current context.'
- vibe agent run --fork-session sesk8m4q2p7x --agent reviewer --model gpt-5.4 --reasoning-effort high --message 'Review the forked context.'
+ Inside an Agent shell a new Session takes the caller's scope and current directory.
+ Elsewhere, pass --callback-session-id, --no-callback, or --sync.
+ --model, --reasoning-effort, --visible, --same-scope, --scope-id, and --close-after
+ apply only to a new or forked Session.
+
+ Examples:
+ vibe agent run --agent reviewer --message 'Review the latest deployment result.'
+ vibe agent run --session-id sesk8m4q2p7x --queue --message 'After this turn, also update the docs.'
+ vibe agent run --fork-self --message 'Explore the alternate fix from this context.'
"""
)
@@ -7859,8 +7737,22 @@ def cmd_session_queue_remove(args):
def cmd_session_update(args):
from core.services import sessions as sessions_service
+ from storage.agent_session_rows import reserve_write_lock
+ from storage.workbench_sessions_service import DELIBERATE_TITLE_SOURCES
try:
+ if_untitled = bool(getattr(args, "if_untitled", False))
+ if if_untitled and (
+ getattr(args, "title", None) is None
+ or getattr(args, "visibility", None) is not None
+ or getattr(args, "scope_id", None) is not None
+ ):
+ raise TaskCliError(
+ "--if-untitled applies only to --title",
+ code="invalid_arguments",
+ hint="Pass --title with --if-untitled, and change visibility or scope in a separate call.",
+ help_command="vibe session update --help",
+ )
updates = {}
if getattr(args, "title", None) is not None:
updates["title"] = args.title
@@ -7891,10 +7783,19 @@ def cmd_session_update(args):
)
engine = _open_session_engine()
with engine.begin() as conn:
+ # Hold the write lock from before the read, so a rename committed by the
+ # Web UI cannot land between the --if-untitled check and this write.
+ reserve_write_lock(conn)
# Validate first so an archived/missing id is a clean not-found rather
# than silently writing a title onto a soft-deleted row.
previous_session = sessions_service.get_active_session(conn, session_id)
- payload = sessions_service.update_session(conn, session_id, **updates)
+ title_source = (previous_session.get("metadata") or {}).get("title_source")
+ updated = not (if_untitled and title_source in DELIBERATE_TITLE_SOURCES)
+ payload = (
+ sessions_service.update_session(conn, session_id, **updates)
+ if updated
+ else previous_session
+ )
except LookupError:
_print_task_error(
TaskCliError(
@@ -7910,14 +7811,15 @@ def cmd_session_update(args):
return 1
# The DB write is committed above; ping a running UI so the rename shows live
# (best-effort — never affects this command's result).
- _post_session_activity_to_live_ui(
- session_id,
- previous_scope_id=previous_session.get("scope_id"),
- previous_visibility=previous_session.get("visibility"),
- )
+ if updated:
+ _post_session_activity_to_live_ui(
+ session_id,
+ previous_scope_id=previous_session.get("scope_id"),
+ previous_visibility=previous_session.get("visibility"),
+ )
_print_cli_payload(
"agent_session",
- updated=True,
+ updated=updated,
session=_session_row(payload, brief=False),
)
return 0
@@ -17295,59 +17197,49 @@ def build_parser():
agent_run_parser = agent_subparsers.add_parser(
"run",
help="Run an Avibe Agent",
- description="Run an Avibe Agent turn. Runs are async by default; use --sync to wait for the result.",
+ description=(
+ "Run an Agent turn in a new background Session (--agent), an existing Session "
+ "(--session-id), or a fork. Runs are async: the final result returns to the caller Session."
+ ),
epilog=_agent_run_examples_text(),
formatter_class=argparse.RawDescriptionHelpFormatter,
error_help_command="vibe agent run --help",
)
- agent_run_parser.add_argument("--agent", help="Avibe Agent name")
- agent_run_parser.add_argument("--session-id", help="Existing Agent Session ID to continue")
+ agent_run_parser.add_argument("--agent", metavar="NAME", help="Agent for a new Session (a fork: same backend only)")
agent_run_parser.add_argument(
- "--queue",
- action="store_true",
- help="Queue this Run behind the active Turn instead of steering it",
+ "--session-id", metavar="ID", help="Join this Session's running turn, or start one if idle"
)
- agent_run_parser.add_argument("--fork-session", help="Existing Agent Session ID to fork into a new Session")
- agent_run_parser.add_argument("--fork-self", action="store_true", help="Fork this current Agent Session")
- agent_run_parser.add_argument("--same-scope", action="store_true", help="Place a new or forked Session in the caller/source Session scope")
- agent_run_parser.add_argument("--scope-id", help="Existing scopes.id that should own the new or forked Session")
+ agent_run_parser.add_argument("--queue", action="store_true", help="With --session-id: wait for the running turn")
+ agent_run_parser.add_argument("--fork-session", metavar="ID", help="Fork this Session's context, backend, scope, and cwd")
+ agent_run_parser.add_argument("--fork-self", action="store_true", help="Fork the caller Session")
+ agent_run_parser.add_argument("--same-scope", action="store_true", help="Place the new Session in the caller's scope")
+ agent_run_parser.add_argument("--scope-id", metavar="ID", help="Place the new Session in this scopes.id")
agent_run_parser.add_argument(
"--visible",
dest="visibility",
action="store_const",
const="foreground",
- help="Make the new or forked Session user-facing from the start (default: background)",
- )
- agent_run_parser.add_argument(
- "--model", help="Model for the new Session this run creates (a blank new Session or a fork); kept on that Session for its later turns. Not valid with --session-id. See `vibe agent models <agent>`."
- )
- agent_run_parser.add_argument(
- "--reasoning-effort", help="Reasoning effort for the new Session this run creates; kept on that Session. Not valid with --session-id."
+ help="Make the new Session user-facing",
)
- agent_run_parser.add_argument(
- "--cwd",
- help=(
- "Working directory for the NEW session. Caller-delegated sessions default to the invocation "
- "directory; explicit scoped sessions use the scope workdir; standalone sessions use their Show workspace. Invalid with --session-id "
- "(an existing session keeps its own working directory)."
- ),
- )
- agent_run_parser.add_argument("--callback-session-id", help="Caller Session ID to receive the completed async run result")
+ agent_run_parser.add_argument("--model", help="Model the new Session keeps; see 'vibe agent models <agent>'")
+ agent_run_parser.add_argument("--reasoning-effort", metavar="EFFORT", help="Reasoning effort the new Session keeps")
+ agent_run_parser.add_argument("--cwd", metavar="DIR", help="Working directory for a new, unforked Session")
+ agent_run_parser.add_argument("--callback-session-id", metavar="ID", help="Send the result to this Session instead")
agent_run_parser.add_argument(
"--no-callback",
action="store_true",
- help="For async runs, intentionally skip automatic callback delivery and inspect the run later.",
+ help="Send the result nowhere; read it with 'vibe runs show'",
)
agent_run_parser.add_argument(
"--close-after",
action="store_true",
- help="Close the newly-created Agent runtime after the run settles while keeping its Session and transcript.",
+ help="Release the new Session's runtime when the run ends",
)
- agent_run_parser.add_argument("--sync", dest="sync_run", action="store_true", help="Wait for the run result before exiting")
- agent_run_parser.add_argument("--wait-timeout", type=float, help="Maximum seconds the CLI waits for a synchronous run result")
+ agent_run_parser.add_argument("--sync", dest="sync_run", action="store_true", help="Wait and print the finished run")
+ agent_run_parser.add_argument("--wait-timeout", metavar="SEC", type=float, help="With --sync: maximum seconds to wait")
agent_message_group = agent_run_parser.add_mutually_exclusive_group(required=True)
- agent_message_group.add_argument("--message")
- agent_message_group.add_argument("--message-file")
+ agent_message_group.add_argument("--message", metavar="TEXT", help="Message for the Agent")
+ agent_message_group.add_argument("--message-file", metavar="PATH", help="Read the message from a UTF-8 file")
_add_json_noop(agent_run_parser)
runs_parser = subparsers.add_parser(
@@ -17524,6 +17416,11 @@ def build_parser():
session_update_parser.add_argument(
"--title", help="New title. Pass an empty string to clear it (reverts to id-based display)."
)
+ session_update_parser.add_argument(
+ "--if-untitled",
+ action="store_true",
+ help="Set --title only if no user or Agent has titled the Session; else keep it (updated: false).",
+ )
session_visibility_group = session_update_parser.add_mutually_exclusive_group()
session_visibility_group.add_argument(
"--visible",
@@ -18151,120 +18048,88 @@ def build_parser():
task_add_parser = task_subparsers.add_parser(
"add",
help="Create a scheduled task",
- description="Create a recurring or one-shot scheduled Agent message.",
+ description="Schedule an Agent message (message task) or a command with no Agent turn (command task).",
epilog=_task_add_examples_text(),
formatter_class=argparse.RawDescriptionHelpFormatter,
error_help_command="vibe task add --help",
- error_hint="Use --session-id together with exactly one schedule flag and one message input flag. Use --same-scope or --scope-id when the task creates a new Session.",
- )
- task_add_parser.add_argument(
- "--name",
- help="Optional human-friendly task name",
- )
- task_add_parser.add_argument(
- "--session-id",
- help="Agent Session ID to continue when the task runs.",
- )
- task_add_parser.add_argument("--create-session", action="store_true", help="Create one reusable Avibe Session ID for this task")
- task_add_parser.add_argument("--create-session-per-run", action="store_true", help="Create a new Avibe Session ID each time this task runs")
- task_add_parser.add_argument("--same-scope", action="store_true", help="Place a created Session in the caller Session scope")
- task_add_parser.add_argument("--scope-id", help="Existing scopes.id that should own created Sessions")
- task_add_parser.add_argument("--agent", help="Avibe Agent name to use when the task runs")
- task_add_parser.add_argument(
- "--cwd",
- help=(
- "Working directory for Sessions created by this task, and for a command task, "
- "the directory its command runs in. Defaults to the caller's current directory."
- ),
- )
+ error_hint="Pass --cron or --at, plus --message, --shell, or a command after '--'.",
+ )
+ task_add_parser.add_argument("--name", help="Display name")
+ task_add_parser.add_argument("--session-id", metavar="ID", help="Run in this Session instead of the caller")
+ task_add_parser.add_argument("--create-session", action="store_true", help="Run in one new reusable Session")
+ task_add_parser.add_argument("--create-session-per-run", action="store_true", help="Create a new Session for each run")
+ task_add_parser.add_argument("--same-scope", action="store_true", help="Place a created Session in the caller's scope")
+ task_add_parser.add_argument("--scope-id", metavar="ID", help="Place a created Session in this scopes.id")
+ task_add_parser.add_argument("--agent", metavar="NAME", help="Agent that runs the message")
+ task_add_parser.add_argument("--cwd", metavar="DIR", help="Created Session's directory; also where a command runs")
schedule_group = task_add_parser.add_mutually_exclusive_group(required=True)
- schedule_group.add_argument(
- "--cron", help="Recurring schedule in 5-field crontab format; write weekdays as names (mon ... sun)"
- )
- schedule_group.add_argument("--at", help="One-shot timestamp in ISO 8601 format")
+ schedule_group.add_argument("--cron", metavar="EXPR", help="Recurring 5-field cron schedule")
+ schedule_group.add_argument("--at", metavar="TIME", help="One-shot ISO 8601 time")
# Not ``required=True`` any more: a command task carries no message at all, so the
# "message or command" choice is enforced in ``cmd_task_add`` where both inputs are
# visible (``missing_task_action``).
prompt_group = task_add_parser.add_mutually_exclusive_group()
- prompt_group.add_argument("--message", help="Stored user message to send each time the task runs")
- prompt_group.add_argument("--message-file", help="Read stored user message from a UTF-8 text file")
- task_add_parser.add_argument("--timezone", help="IANA timezone name used for --cron and naive --at values")
- task_add_parser.add_argument(
- "--shell",
- help="Shell command to run on schedule. Use this or pass a command after '--'.",
- )
+ prompt_group.add_argument("--message", metavar="TEXT", help="Message sent on each run")
+ prompt_group.add_argument("--message-file", metavar="PATH", help="Read the message from a UTF-8 file")
+ task_add_parser.add_argument("--timezone", metavar="TZ", help="IANA timezone for --cron and a naive --at")
+ task_add_parser.add_argument("--shell", metavar="CMD", help="Command task: one shell command string")
task_add_parser.add_argument(
"--on-failure",
choices=["none", "agent"],
default=None,
- help="What a failed command run does: 'none' records the failure, 'agent' starts an Agent turn to triage it. Default: none",
+ help="Command task failure: record a notice, or start an Agent turn",
)
task_add_parser.add_argument(
"--timeout",
+ metavar="SEC",
type=float,
- help="Per-run timeout in seconds for command tasks. Use 0 for no timeout. Default: 21600.",
+ help="Command task per-run timeout; 0 = none. Default: 21600",
)
task_add_parser.add_argument(
"command_argv",
nargs=argparse.REMAINDER,
- help="-- followed by the command to run on schedule",
+ help="Or the command task's command after '--'",
)
_add_json_noop(task_add_parser)
task_update_parser = task_subparsers.add_parser(
"update",
help="Update a scheduled task",
- description="Update one stored scheduled task while keeping its task ID.",
+ description="Update one scheduled task in place; unspecified fields keep their values.",
epilog=_task_update_examples_text(),
formatter_class=argparse.RawDescriptionHelpFormatter,
error_help_command="vibe task update --help",
error_hint="Pass the task ID plus at least one field to change. Unspecified fields keep their existing values.",
)
task_update_parser.add_argument("task_id", help="Task ID from 'vibe task list'")
- task_update_parser.add_argument("--name", help="New human-friendly task name")
- task_update_parser.add_argument(
- "--clear-name",
- action="store_true",
- help="Remove the stored custom task name",
- )
- task_update_parser.add_argument("--session-id", help="Replace the stored Agent Session ID")
- task_update_parser.add_argument("--create-session", action="store_true", help="Replace the task with one reusable newly-created Avibe Session ID")
- task_update_parser.add_argument("--create-session-per-run", action="store_true", help="Create a new Avibe Session ID each time this task runs")
- task_update_parser.add_argument("--same-scope", action="store_true", help="Place created Sessions in the caller Session scope")
- task_update_parser.add_argument("--scope-id", help="Existing scopes.id that should own created Sessions")
- task_update_parser.add_argument("--agent", help="Replace the Avibe Agent used by this task")
- task_update_parser.add_argument("--clear-agent", action="store_true", help="Clear the stored Avibe Agent override")
- task_update_parser.add_argument(
- "--cwd",
- help="Set working directory for Sessions created by this task, or for a command task, where its command runs",
- )
+ task_update_parser.add_argument("--name", help="Set the display name")
+ task_update_parser.add_argument("--clear-name", action="store_true", help="Clear the display name")
+ task_update_parser.add_argument("--session-id", metavar="ID", help="Run in this Session")
+ task_update_parser.add_argument("--create-session", action="store_true", help="Run in one new reusable Session")
+ task_update_parser.add_argument("--create-session-per-run", action="store_true", help="Create a new Session for each run")
+ task_update_parser.add_argument("--same-scope", action="store_true", help="Place created Sessions in the caller's scope")
+ task_update_parser.add_argument("--scope-id", metavar="ID", help="Place created Sessions in this scopes.id")
+ task_update_parser.add_argument("--agent", metavar="NAME", help="Set the Agent")
+ task_update_parser.add_argument("--clear-agent", action="store_true", help="Clear the Agent override")
+ task_update_parser.add_argument("--cwd", metavar="DIR", help="Directory for created Sessions, or the command's")
task_update_parser.add_argument(
"--reset-delivery",
action="store_true",
- help="Clear any stored delivery override so delivery follows the session target directly",
- )
- task_update_parser.add_argument(
- "--cron", help="Replace the schedule with a recurring 5-field crontab; write weekdays as names (mon ... sun)"
- )
- task_update_parser.add_argument("--at", help="Replace the schedule with a one-shot ISO 8601 timestamp")
- task_update_parser.add_argument("--message", help="Replace the stored user message text")
- task_update_parser.add_argument("--message-file", help="Replace the stored user message from a UTF-8 text file")
- task_update_parser.add_argument("--timezone", help="Replace the stored IANA timezone name")
- task_update_parser.add_argument(
- "--shell",
- help="Replace the shell command a command task runs. Use this or pass a command after '--'.",
- )
+ help="Clear the delivery override; deliver to the Session",
+ )
+ task_update_parser.add_argument("--cron", metavar="EXPR", help="Switch to this recurring cron schedule")
+ task_update_parser.add_argument("--at", metavar="TIME", help="Switch to this one-shot ISO 8601 time")
+ task_update_parser.add_argument("--message", metavar="TEXT", help="Replace the message")
+ task_update_parser.add_argument("--message-file", metavar="PATH", help="Read the message from a UTF-8 file")
+ task_update_parser.add_argument("--timezone", metavar="TZ", help="Set the IANA timezone")
+ task_update_parser.add_argument("--shell", metavar="CMD", help="Replace the command; or pass one after '--'")
task_update_parser.add_argument(
"--on-failure",
choices=["none", "agent"],
default=None,
help=argparse.SUPPRESS,
)
- task_update_parser.add_argument(
- "--timeout",
- type=float,
- help="Replace the per-run timeout in seconds for a command task. Use 0 for no timeout.",
- )
+ task_update_parser.add_argument("--timeout", metavar="SEC", type=float, help="Command per-run timeout; 0 = none")
# No positional landing slot here: the trailing ``-- <command ...>`` tail is lifted
# out of argv before argparse runs, exactly as for 'vibe watch update'.
task_update_parser.set_defaults(command_argv=None)
@@ -18371,119 +18236,115 @@ def build_parser():
watch_add_parser = watch_subparsers.add_parser(
"add",
help="Create a managed background watch",
- description="Create a managed background watch that runs a waiter command and sends a follow-up on success or terminal failure.",
+ description=(
+ "Run a waiter in the background; on an event or a failure, start a follow-up Agent Run "
+ "in the caller Session."
+ ),
epilog=_watch_add_examples_text(),
formatter_class=argparse.RawDescriptionHelpFormatter,
error_help_command="vibe watch add --help",
- error_hint="Use --session-id and either --shell or a command after '--'. Retry exit codes keep either mode waiting; add --forever only when distinct successful events should re-arm the Watch.",
- )
- watch_add_parser.add_argument("--name", help="Optional human-friendly watch name")
- watch_add_parser.add_argument(
- "--session-id",
- help="Agent Session ID to continue for follow-up messages from this watch.",
- )
- watch_add_parser.add_argument("--create-session", action="store_true", help="Create one reusable Avibe Session ID for this watch")
- watch_add_parser.add_argument("--create-session-per-run", action="store_true", help="Create a new Avibe Session ID each time this watch triggers")
- watch_add_parser.add_argument("--same-scope", action="store_true", help="Place a created Session in the caller Session scope")
- watch_add_parser.add_argument("--scope-id", help="Existing scopes.id that should own created Sessions")
- watch_add_parser.add_argument("--agent", help="Avibe Agent name to use for follow-up messages")
+ error_hint="Pass the waiter as --shell '<command>' or as a command after '--'.",
+ )
+ watch_add_parser.add_argument("--name", help="Display name")
+ watch_add_parser.add_argument("--session-id", metavar="ID", help="Follow up in this Session instead of the caller")
+ watch_add_parser.add_argument("--create-session", action="store_true", help="Follow up in one new reusable Session")
+ watch_add_parser.add_argument("--create-session-per-run", action="store_true", help="Create a new Session for each follow-up")
+ watch_add_parser.add_argument("--same-scope", action="store_true", help="Place a created Session in the caller's scope")
+ watch_add_parser.add_argument("--scope-id", metavar="ID", help="Place a created Session in this scopes.id")
+ watch_add_parser.add_argument("--agent", metavar="NAME", help="Agent for the follow-up Run")
watch_message_group = watch_add_parser.add_mutually_exclusive_group()
- watch_message_group.add_argument("--message", help="Follow-up user message template sent with waiter output")
- watch_message_group.add_argument("--message-file", help="Read follow-up user message from a UTF-8 text file")
- watch_add_parser.add_argument("--cwd", help="Working directory for the waiter process")
+ watch_message_group.add_argument("--message", metavar="TEXT", help="Follow-up instructions; waiter stdout is appended")
+ watch_message_group.add_argument("--message-file", metavar="PATH", help="Read the message from a UTF-8 file")
+ watch_add_parser.add_argument("--cwd", metavar="DIR", help="Waiter working directory")
watch_add_parser.add_argument(
"--timeout",
+ metavar="SEC",
type=float,
default=21600,
- help="Per-cycle timeout in seconds. Use 0 for no per-cycle timeout. Default: 21600",
- )
- watch_add_parser.add_argument(
- "--forever",
- action="store_true",
- help="Monitor distinct events continuously. After each event's Agent Run settles, the Watch re-arms; terminal failures still stop it unless their exit code is retryable.",
+ help="Per-cycle timeout; 0 = none. Default: 21600",
)
+ watch_add_parser.add_argument("--forever", action="store_true", help="Re-arm after each event instead of stopping")
watch_add_parser.add_argument(
"--lifetime-timeout",
+ metavar="SEC",
type=float,
default=0,
- help="Overall Watch lifetime timeout in seconds across retries and re-arms. Use 0 for no lifetime limit.",
+ help="Total lifetime; 0 = none (default)",
)
watch_add_parser.add_argument(
"--retry-exit-code",
+ metavar="N",
dest="retry_exit_code",
action="append",
type=int,
default=None,
- help=f"Cycle exit code that should keep waiting. Repeat to add more. Default: {DEFAULT_RETRY_EXIT_CODE}",
+ help=f"Still-waiting exit code; repeatable. Default: {DEFAULT_RETRY_EXIT_CODE}",
)
watch_add_parser.add_argument(
"--retry-delay",
+ metavar="SEC",
type=float,
default=30,
- help="Delay in seconds before retrying an allowed cycle result. Default: 30",
- )
- watch_add_parser.add_argument(
- "--shell",
- help="Shell command to run as the waiter. Use this or pass a command after '--'.",
+ help="Seconds before a still-waiting rerun. Default: 30",
)
+ watch_add_parser.add_argument("--shell", metavar="CMD", help="Waiter as one shell command string")
watch_add_parser.add_argument(
"waiter_command",
nargs=argparse.REMAINDER,
- help="Waiter command to run after '--'. Example: vibe watch add ... -- python3 script.py --flag value",
+ help="Or the waiter command after '--'",
)
_add_json_noop(watch_add_parser)
watch_update_parser = watch_subparsers.add_parser(
"update",
help="Update one background watch",
- description="Update stored watch metadata, target, delivery, command, or runtime options.",
- epilog="Find watch IDs with: vibe watch list",
+ description="Update a watch's target, message, waiter, or timing. Unspecified fields keep their values.",
+ epilog="Exit codes and modes: vibe watch add --help",
formatter_class=argparse.RawDescriptionHelpFormatter,
error_help_command="vibe watch update --help",
error_hint="Pass at least one field to update, such as --name, --shell, --timeout, --session-id, or --scope-id.",
)
watch_update_parser.add_argument("watch_id", help="Watch ID from 'vibe watch list'")
- watch_update_parser.add_argument("--name", help="Set a human-friendly watch name")
- watch_update_parser.add_argument("--clear-name", action="store_true", help="Clear the stored watch name")
- watch_update_parser.add_argument(
- "--session-id",
- help="Agent Session ID to continue for follow-up messages from this watch.",
- )
- watch_update_parser.add_argument("--create-session", action="store_true", help="Replace the watch with one reusable newly-created Avibe Session ID")
- watch_update_parser.add_argument("--create-session-per-run", action="store_true", help="Create a new Avibe Session ID each time this watch triggers")
- watch_update_parser.add_argument("--same-scope", action="store_true", help="Place created Sessions in the caller Session scope")
- watch_update_parser.add_argument("--scope-id", help="Existing scopes.id that should own created Sessions")
- watch_update_parser.add_argument("--agent", help="Replace the Avibe Agent used for follow-up messages")
- watch_update_parser.add_argument("--clear-agent", action="store_true", help="Clear the stored Avibe Agent override")
+ watch_update_parser.add_argument("--name", help="Set the display name")
+ watch_update_parser.add_argument("--clear-name", action="store_true", help="Clear the display name")
+ watch_update_parser.add_argument("--session-id", metavar="ID", help="Follow up in this Session")
+ watch_update_parser.add_argument("--create-session", action="store_true", help="Follow up in one new reusable Session")
+ watch_update_parser.add_argument("--create-session-per-run", action="store_true", help="Create a new Session for each follow-up")
+ watch_update_parser.add_argument("--same-scope", action="store_true", help="Place created Sessions in the caller's scope")
+ watch_update_parser.add_argument("--scope-id", metavar="ID", help="Place created Sessions in this scopes.id")
+ watch_update_parser.add_argument("--agent", metavar="NAME", help="Set the follow-up Agent")
+ watch_update_parser.add_argument("--clear-agent", action="store_true", help="Clear the Agent override")
watch_update_parser.add_argument(
"--reset-delivery",
action="store_true",
- help="Clear any stored delivery override and deliver back to the continued session target.",
+ help="Clear the delivery override; deliver to the Session",
)
watch_update_message_group = watch_update_parser.add_mutually_exclusive_group()
- watch_update_message_group.add_argument("--message", help="Replace the follow-up user message template")
- watch_update_message_group.add_argument("--message-file", help="Read replacement follow-up user message from a UTF-8 text file")
- watch_update_parser.add_argument("--cwd", help="Set working directory for the waiter process")
- watch_update_parser.add_argument("--clear-cwd", action="store_true", help="Clear the stored waiter working directory")
- watch_update_parser.add_argument("--timeout", type=float, help="Set per-cycle timeout in seconds")
+ watch_update_message_group.add_argument("--message", metavar="TEXT", help="Replace the follow-up instructions")
+ watch_update_message_group.add_argument("--message-file", metavar="PATH", help="Read the message from a UTF-8 file")
+ watch_update_parser.add_argument("--cwd", metavar="DIR", help="Set the waiter working directory")
+ watch_update_parser.add_argument("--clear-cwd", action="store_true", help="Clear the waiter working directory")
+ watch_update_parser.add_argument("--timeout", metavar="SEC", type=float, help="Per-cycle timeout; 0 = none")
watch_update_mode_group = watch_update_parser.add_mutually_exclusive_group()
- watch_update_mode_group.add_argument("--forever", action="store_true", help="Switch this watch to forever mode")
- watch_update_mode_group.add_argument("--once", action="store_true", help="Switch this watch to one-shot mode")
+ watch_update_mode_group.add_argument("--forever", action="store_true", help="Re-arm after each event")
+ watch_update_mode_group.add_argument("--once", action="store_true", help="Stop after the first event")
watch_update_parser.add_argument(
"--lifetime-timeout",
+ metavar="SEC",
type=float,
- help="Set the overall Watch lifetime timeout across retries and re-arms. Use 0 for no lifetime limit.",
+ help="Total lifetime; 0 = none",
)
watch_update_parser.add_argument(
"--retry-exit-code",
+ metavar="N",
dest="retry_exit_code",
action="append",
type=int,
default=None,
- help="Replace exit codes that keep this Watch waiting. Repeat to add more.",
+ help="Replace the still-waiting exit codes; repeatable",
)
- watch_update_parser.add_argument("--retry-delay", type=float, help="Set retry delay in seconds")
- watch_update_parser.add_argument("--shell", help="Replace waiter with a shell command")
+ watch_update_parser.add_argument("--retry-delay", metavar="SEC", type=float, help="Seconds before a still-waiting rerun")
+ watch_update_parser.add_argument("--shell", metavar="CMD", help="Replace the waiter; or pass a command after '--'")
watch_update_parser.set_defaults(waiter_command=None)
_add_json_noop(watch_update_parser)