langstage-cli 0.5.7__tar.gz → 0.5.9__tar.gz

{langstage_cli-0.5.7/langstage_cli.egg-info → langstage_cli-0.5.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langstage-cli
-Version: 0.5.7
+Version: 0.5.9
 Summary: The terminal stage for your LangGraph agent — Claude Code-style CLI for any CompiledGraph
 Author-email: Kedar Dabhadkar <kdabhadk@gmail.com>
 License-Expression: MIT
@@ -175,7 +175,7 @@ root = "."
 [ui]
 verbose = true
 async_mode = false
-stream_mode = "updates"
+stream_mode = "auto"   # auto | updates | messages
 
 [configurable]
 # seeds LangGraph RunnableConfig.configurable
@@ -196,8 +196,8 @@ Options:
   -f, --file PATH                 Read message from a file (any extension)
   --interactive/--no-interactive  Handle interrupts (default: interactive)
   --async-mode/--sync-mode        Async streaming (default: sync)
-  --stream-mode [updates|messages]
-                                  Stream mode (default: updates)
+  --stream-mode [auto|updates|messages]
+                                  Stream mode (default: auto)
   -v, --verbose                   Verbose output
   --demo                          Run with the built-in keyless demo agent
   --show-config                   Print the resolved configuration and exit

{langstage_cli-0.5.7 → langstage_cli-0.5.9}/README.md

@@ -140,7 +140,7 @@ root = "."
 [ui]
 verbose = true
 async_mode = false
-stream_mode = "updates"
+stream_mode = "auto"   # auto | updates | messages
 
 [configurable]
 # seeds LangGraph RunnableConfig.configurable
@@ -161,8 +161,8 @@ Options:
   -f, --file PATH                 Read message from a file (any extension)
   --interactive/--no-interactive  Handle interrupts (default: interactive)
   --async-mode/--sync-mode        Async streaming (default: sync)
-  --stream-mode [updates|messages]
-                                  Stream mode (default: updates)
+  --stream-mode [auto|updates|messages]
+                                  Stream mode (default: auto)
   -v, --verbose                   Verbose output
   --demo                          Run with the built-in keyless demo agent
   --show-config                   Print the resolved configuration and exit

{langstage_cli-0.5.7 → langstage_cli-0.5.9}/langstage_cli/cli.py

@@ -736,6 +736,20 @@ def handle_interrupt_input(num_actions: int = 1) -> List[Dict[str, Any]]:
         sys.exit(0)
 
 
+def _resolve_stream_mode(stream_mode: str):
+    """Map the user-facing stream mode to what LangGraph actually streams.
+
+    'auto' = dual-channel ``["updates", "messages"]``: the parser renders LLM
+    tokens live when the agent streams them, and falls back to the finished
+    message content otherwise — so a node that returns a complete (non-token-
+    streamed) ``AIMessage`` still renders instead of an empty turn. (Bare
+    'messages' only carries LLM token streams, which is exactly why it was a
+    silent-blank trap — gh #-dogfood.) 'updates'/'messages' pass through as the
+    explicit single-mode power-user choices.
+    """
+    return ["updates", "messages"] if stream_mode == "auto" else stream_mode
+
+
 async def run_single_turn_async(
     graph,
     message: str,
@@ -746,6 +760,7 @@ async def run_single_turn_async(
 ) -> float:
     """Run a single turn of an async LangGraph graph. Returns total duration in seconds."""
     input_data = prepare_agent_input(message=message)
+    lg_stream_mode = _resolve_stream_mode(stream_mode)
     start_time = time.time()
 
     while True:
@@ -757,7 +772,7 @@ async def run_single_turn_async(
 
         try:
             async for chunk in astream_graph_updates(
-                graph, input_data, config=config, stream_mode=stream_mode
+                graph, input_data, config=config, stream_mode=lg_stream_mode
             ):
                 # Stop spinner on first chunk
                 if first_chunk:
@@ -796,6 +811,7 @@ def run_single_turn_sync(
 ) -> float:
     """Run a single turn of a sync LangGraph graph. Returns total duration in seconds."""
     input_data = prepare_agent_input(message=message)
+    lg_stream_mode = _resolve_stream_mode(stream_mode)
     start_time = time.time()
 
     while True:
@@ -807,7 +823,7 @@ def run_single_turn_sync(
 
         try:
             for chunk in stream_graph_updates(
-                graph, input_data, config=config, stream_mode=stream_mode
+                graph, input_data, config=config, stream_mode=lg_stream_mode
             ):
                 # Stop spinner on first chunk
                 if first_chunk:
@@ -847,7 +863,10 @@ def print_help():
     for cmd in sorted(commands, key=lambda c: c.name):
         aliases_str = ""
         if cmd.aliases:
-            aliases_str = f", {CYAN}/{RESET}, {CYAN}/".join([""] + cmd.aliases)[4:]
+            # Each alias as its own cyan "/x" token. The old
+            # `…join([""] + aliases)[4:]` sliced into the leading ANSI escape,
+            # leaking a literal "36m" and bleeding color (gh #-dogfood).
+            aliases_str = "".join(f", {CYAN}/{alias}{RESET}" for alias in cmd.aliases)
         print(f"  {CYAN}/{cmd.name}{RESET}{aliases_str}")
         print(f"    {DIM}{cmd.description}{RESET}")
 
@@ -1342,8 +1361,10 @@ def run_conversation_loop(
 )
 @click.option(
     "--stream-mode",
-    type=click.Choice(["updates", "messages"]),
-    help="Stream mode: 'updates' (default) or 'messages' (token-level).",
+    type=click.Choice(["auto", "updates", "messages"]),
+    help="Stream mode: 'auto' (default; token streaming when the agent emits "
+    "tokens, full-message fallback otherwise), 'updates' (whole-message), or "
+    "'messages' (token-level only — a finished AIMessage renders nothing here).",
 )
 @click.option(
     "--verbose",
@@ -1395,7 +1416,7 @@ def main(
     \b
     - LANGSTAGE_AGENT_SPEC: Agent location (same formats as above).
     - LANGSTAGE_WORKSPACE_ROOT: Working directory for the agent
-    - LANGSTAGE_STREAM_MODE: Stream mode for LangGraph (updates or messages)
+    - LANGSTAGE_STREAM_MODE: Stream mode for LangGraph (auto, updates, or messages)
 
     Reads ~/.langstage/config.toml (global) and langstage.toml (project,
     walks up from cwd). Precedence: CLI args > env vars > project TOML >
@@ -1488,10 +1509,10 @@ def main(
         # The CLI's render path only supports 'updates' / 'messages'. Reject anything
         # else (e.g. LANGSTAGE_STREAM_MODE=values, which bypasses the flag's Choice)
         # with a clean error instead of a fatal crash deep in the stream worker.
-        if final_stream_mode not in ("updates", "messages"):
+        if final_stream_mode not in ("auto", "updates", "messages"):
             print(
                 f"{RED}⏺ Error: unsupported stream mode {final_stream_mode!r} "
-                f"(use 'updates' or 'messages'){RESET}"
+                f"(use 'auto', 'updates', or 'messages'){RESET}"
             )
             sys.exit(2)
         use_async = cfg.async_mode

{langstage_cli-0.5.7 → langstage_cli-0.5.9}/langstage_cli/config.py

@@ -86,7 +86,7 @@ class CodeConfig(HostConfig):
     resolver); the even-older ``DEEPAGENT_SPEC`` alias is reconciled below.
     """
 
-    stream_mode: str = "updates"
+    stream_mode: str = "auto"
     graph_name: str = "graph"
     verbose: bool = False
     async_mode: bool = False

{langstage_cli-0.5.7 → langstage_cli-0.5.9/langstage_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langstage-cli
-Version: 0.5.7
+Version: 0.5.9
 Summary: The terminal stage for your LangGraph agent — Claude Code-style CLI for any CompiledGraph
 Author-email: Kedar Dabhadkar <kdabhadk@gmail.com>
 License-Expression: MIT
@@ -175,7 +175,7 @@ root = "."
 [ui]
 verbose = true
 async_mode = false
-stream_mode = "updates"
+stream_mode = "auto"   # auto | updates | messages
 
 [configurable]
 # seeds LangGraph RunnableConfig.configurable
@@ -196,8 +196,8 @@ Options:
   -f, --file PATH                 Read message from a file (any extension)
   --interactive/--no-interactive  Handle interrupts (default: interactive)
   --async-mode/--sync-mode        Async streaming (default: sync)
-  --stream-mode [updates|messages]
-                                  Stream mode (default: updates)
+  --stream-mode [auto|updates|messages]
+                                  Stream mode (default: auto)
   -v, --verbose                   Verbose output
   --demo                          Run with the built-in keyless demo agent
   --show-config                   Print the resolved configuration and exit

{langstage_cli-0.5.7 → langstage_cli-0.5.9}/langstage_cli.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ tests/test_cli.py
 tests/test_cli_help.py
 tests/test_codeconfig.py
 tests/test_config.py
+tests/test_help_render.py
 tests/test_rename_shim.py
 tests/test_show_config.py
 tests/test_stream_mode.py

{langstage_cli-0.5.7 → langstage_cli-0.5.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "langstage-cli"
-version = "0.5.7"
+version = "0.5.9"
 description = "The terminal stage for your LangGraph agent — Claude Code-style CLI for any CompiledGraph"
 readme = "README.md"
 requires-python = ">=3.11"

{langstage_cli-0.5.7 → langstage_cli-0.5.9}/tests/test_codeconfig.py

@@ -21,7 +21,7 @@ def _toml(d: Path, body: str) -> None:
 
 def test_defaults(isolated, tmp_path):
     cfg = CodeConfig.resolve(env={}, toml_start=tmp_path)
-    assert cfg.stream_mode == "updates"
+    assert cfg.stream_mode == "auto"
     assert cfg.graph_name == "graph"
     assert cfg.verbose is False
     assert cfg.async_mode is False

langstage_cli-0.5.9/tests/test_help_render.py

@@ -0,0 +1,35 @@
+"""`/help` must not leak ANSI fragments (gh #-dogfood).
+
+The Commands block built alias strings with `…join([""] + aliases)[4:]`, whose
+slice cut into the leading `\x1b[36m` escape — leaking a literal "36m" and bleeding
+color. Each alias is now its own cyan token.
+"""
+
+import io
+import re
+from contextlib import redirect_stdout
+
+from langstage_cli.cli import print_help
+
+_ANSI = re.compile(r"\x1b\[[0-9;]*m")
+
+
+def _rendered_help() -> str:
+    buf = io.StringIO()
+    with redirect_stdout(buf):
+        print_help()
+    return buf.getvalue()
+
+
+def test_help_has_no_leaked_ansi_fragment():
+    plain = _ANSI.sub("", _rendered_help())
+    # No bare color-code residue once real escapes are stripped.
+    assert "36m" not in plain
+    assert "[0m" not in plain and "[36" not in plain
+
+
+def test_help_renders_aliases_cleanly():
+    plain = _ANSI.sub("", _rendered_help())
+    # A multi-alias command renders as comma-separated /tokens.
+    assert "/quit" in plain
+    assert re.search(r"/quit(, /\w+)+", plain), plain

langstage_cli-0.5.9/tests/test_stream_mode.py

@@ -0,0 +1,88 @@
+"""--stream-mode validation + the 'auto' default (gh #-dogfood).
+
+`values` was advertised but unsupported by the CLI's render path; passing it
+crashed with a fatal interpreter-shutdown error (a ValueError surfaced while the
+spinner daemon thread held stdout). Now: the flag is a Choice {auto,updates,
+messages}, and the resolved value (incl. LANGSTAGE_STREAM_MODE, which bypasses
+the flag) is validated up front with a clean error.
+
+Separately, single 'messages' mode only carries LLM *token* streams, so a node
+that returns a finished (non-token-streamed) AIMessage rendered an empty turn.
+The default is now 'auto' (dual updates+messages) so that agent shape — the one
+the README's own "Creating Your Own Agent" example produces — still renders.
+"""
+
+import textwrap
+
+from click.testing import CliRunner
+
+from langstage_cli.cli import main
+
+# A graph whose node returns a *finished* AIMessage (no token streaming) — the
+# shape that was a silent blank turn under bare 'messages'.
+FINISHED_AIMESSAGE_AGENT = textwrap.dedent(
+    """
+    from langchain_core.messages import AIMessage
+    from langgraph.graph import START, END, StateGraph, MessagesState
+
+    def _respond(state):
+        return {"messages": [AIMessage(content="FINISHED_MARKER_42")]}
+
+    builder = StateGraph(MessagesState)
+    builder.add_node("respond", _respond)
+    builder.add_edge(START, "respond")
+    builder.add_edge("respond", END)
+    graph = builder.compile()
+    """
+)
+
+
+def test_default_auto_renders_finished_aimessage(tmp_path, monkeypatch):
+    """Regression: the default mode must render a finished AIMessage's content."""
+    (tmp_path / "fin_agent.py").write_text(FINISHED_AIMESSAGE_AGENT)
+    monkeypatch.chdir(tmp_path)
+    r = CliRunner().invoke(main, ["-a", "fin_agent.py:graph", "--no-interactive", "ping"])
+    assert r.exit_code == 0, r.output
+    assert "FINISHED_MARKER_42" in r.output
+
+
+def test_messages_mode_alone_is_token_only(tmp_path, monkeypatch):
+    """Documents why 'auto' is the default: bare 'messages' carries only LLM
+    token streams, so a finished AIMessage yields no content there."""
+    (tmp_path / "fin_agent.py").write_text(FINISHED_AIMESSAGE_AGENT)
+    monkeypatch.chdir(tmp_path)
+    r = CliRunner().invoke(
+        main, ["-a", "fin_agent.py:graph", "--no-interactive", "--stream-mode", "messages", "ping"]
+    )
+    assert r.exit_code == 0, r.output
+    assert "FINISHED_MARKER_42" not in r.output
+
+
+def test_default_stream_mode_is_auto():
+    r = CliRunner().invoke(main, ["--show-config"])
+    assert r.exit_code == 0, r.output
+    assert "auto" in r.output
+
+
+def test_stream_mode_values_flag_rejected_cleanly():
+    r = CliRunner().invoke(main, ["--demo", "--no-interactive", "--stream-mode", "values", "hi"])
+    assert r.exit_code != 0
+    assert "values" in r.output
+    assert "Fatal" not in r.output  # no interpreter-shutdown crash
+
+
+def test_stream_mode_messages_flag_accepted():
+    # A valid mode must still be accepted by the Choice (parses, doesn't error on the flag).
+    r = CliRunner().invoke(main, ["--stream-mode", "messages", "--show-config"])
+    assert r.exit_code == 0, r.output
+    assert "messages" in r.output
+
+
+def test_stream_mode_values_via_env_rejected():
+    r = CliRunner().invoke(
+        main,
+        ["--demo", "--no-interactive", "hi"],
+        env={"LANGSTAGE_STREAM_MODE": "values"},
+    )
+    assert r.exit_code == 2, r.output
+    assert "unsupported stream mode" in r.output.lower()

langstage_cli-0.5.7/tests/test_stream_mode.py

@@ -1,36 +0,0 @@
-"""--stream-mode validation (gh #-dogfood).
-
-`values` was advertised but unsupported by the CLI's render path; passing it
-crashed with a fatal interpreter-shutdown error (a ValueError surfaced while the
-spinner daemon thread held stdout). Now: the flag is a Choice {updates,messages},
-and the resolved value (incl. LANGSTAGE_STREAM_MODE, which bypasses the flag) is
-validated up front with a clean error.
-"""
-
-from click.testing import CliRunner
-
-from langstage_cli.cli import main
-
-
-def test_stream_mode_values_flag_rejected_cleanly():
-    r = CliRunner().invoke(main, ["--demo", "--no-interactive", "--stream-mode", "values", "hi"])
-    assert r.exit_code != 0
-    assert "values" in r.output
-    assert "Fatal" not in r.output  # no interpreter-shutdown crash
-
-
-def test_stream_mode_messages_flag_accepted():
-    # A valid mode must still be accepted by the Choice (parses, doesn't error on the flag).
-    r = CliRunner().invoke(main, ["--stream-mode", "messages", "--show-config"])
-    assert r.exit_code == 0, r.output
-    assert "messages" in r.output
-
-
-def test_stream_mode_values_via_env_rejected():
-    r = CliRunner().invoke(
-        main,
-        ["--demo", "--no-interactive", "hi"],
-        env={"LANGSTAGE_STREAM_MODE": "values"},
-    )
-    assert r.exit_code == 2, r.output
-    assert "unsupported stream mode" in r.output.lower()