langstage-cli 0.6.4__tar.gz → 0.6.5__tar.gz

{langstage_cli-0.6.4/langstage_cli.egg-info → langstage_cli-0.6.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langstage-cli
-Version: 0.6.4
+Version: 0.6.5
 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
@@ -19,7 +19,7 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: langgraph>=0.2.0
-Requires-Dist: langstage-core[agui]>=1.0.4
+Requires-Dist: langstage-core[agui]>=1.0.6
 Requires-Dist: click>=8.0.0
 Requires-Dist: python-dotenv
 Provides-Extra: dev
@@ -32,7 +32,7 @@ Requires-Dist: deepagents>=0.3; extra == "dev"
 Requires-Dist: ag-ui-langgraph>=0.0.41; extra == "dev"
 Requires-Dist: fastapi; extra == "dev"
 Provides-Extra: agui
-Requires-Dist: langstage-core[agui]>=1.0.4; extra == "agui"
+Requires-Dist: langstage-core[agui]>=1.0.6; extra == "agui"
 Dynamic: license-file
 
 # langstage-cli
@@ -204,9 +204,22 @@ Options:
   --demo                          Run with the built-in keyless demo agent
   --show-config                   Print the resolved configuration and exit
   -q, --quiet                     Scriptable single-shot output: only the reply
+  --verify                        Preflight the agent (one real turn); exit 0/1
   --version                       Show the version and exit
 ```
 
+### Verifying an agent (CI gate)
+
+`--verify` loads the configured agent and runs **one real turn**, exiting `0` if it
+completed cleanly and non-zero otherwise — so you can gate on it in CI before
+trusting an agent. It catches a missing key, a broken tool, or a non-runnable graph
+that a static "it imports" check would wave through (it runs the same
+`langstage-core` preflight every LangStage surface uses):
+
+```bash
+langstage-cli --verify -a my_agent.py:graph || { echo "agent broken" >&2; exit 1; }
+```
+
 ### Scriptable output
 
 A single-shot run (a `MESSAGE` argument or `-f/--file`) prints only the agent's

{langstage_cli-0.6.4 → langstage_cli-0.6.5}/README.md

@@ -167,9 +167,22 @@ Options:
   --demo                          Run with the built-in keyless demo agent
   --show-config                   Print the resolved configuration and exit
   -q, --quiet                     Scriptable single-shot output: only the reply
+  --verify                        Preflight the agent (one real turn); exit 0/1
   --version                       Show the version and exit
 ```
 
+### Verifying an agent (CI gate)
+
+`--verify` loads the configured agent and runs **one real turn**, exiting `0` if it
+completed cleanly and non-zero otherwise — so you can gate on it in CI before
+trusting an agent. It catches a missing key, a broken tool, or a non-runnable graph
+that a static "it imports" check would wave through (it runs the same
+`langstage-core` preflight every LangStage surface uses):
+
+```bash
+langstage-cli --verify -a my_agent.py:graph || { echo "agent broken" >&2; exit 1; }
+```
+
 ### Scriptable output
 
 A single-shot run (a `MESSAGE` argument or `-f/--file`) prints only the agent's

{langstage_cli-0.6.4 → langstage_cli-0.6.5}/langstage_cli/cli.py

@@ -1514,6 +1514,15 @@ def run_conversation_loop(
     "chatter, timing, and color, and emit only the agent's reply. Auto-enabled "
     "when a single-shot run is piped (stdout is not a TTY).",
 )
+@click.option(
+    "--verify",
+    "verify_agent",
+    is_flag=True,
+    default=False,
+    help="Preflight the configured agent: run ONE real turn and exit 0 if it "
+    "completed cleanly, non-zero otherwise. Catches a missing key / broken tool "
+    "/ bad graph before you rely on it (e.g. in CI).",
+)
 def main(
     message: Optional[str],
     agent_spec: Optional[str],
@@ -1527,6 +1536,7 @@ def main(
     agui: bool,
     show_config: bool,
     quiet: bool,
+    verify_agent: bool,
 ):
     """
     Run a LangGraph agent from the command line.
@@ -1561,6 +1571,7 @@ def main(
         langstage-cli -f ./prompt.md
         langstage-cli --demo "try it with no API key"
         langstage-cli --show-config
+        langstage-cli --verify -a my_agent.py   # preflight one real turn; exit 0/1
     """
     # Windows consoles default to cp1252, where the spinner (Braille frames) and
     # status glyphs (✓ ⏺ —) raise UnicodeEncodeError — the documented
@@ -1572,16 +1583,17 @@ def main(
         except (AttributeError, ValueError):  # non-reconfigurable stream
             pass
 
-    # Scriptable single-shot output (gh #53). A single-shot run (a MESSAGE arg or
-    # -f/--file) that is piped — stdout is not a TTY — auto-enables quiet so the
-    # consumer gets only the reply; --quiet forces it even in a terminal. Color is
-    # additionally stripped whenever stdout is not a TTY, matching well-behaved CLIs.
+    # Scriptable output (gh #53). A single-shot run (a MESSAGE arg or -f/--file) or
+    # a --verify preflight that is piped — stdout is not a TTY — auto-enables quiet
+    # so the consumer gets only the reply/verdict (no spinner or "Loaded" line);
+    # --quiet forces it in a terminal. Color is additionally stripped whenever stdout
+    # is not a TTY, matching well-behaved CLIs.
     try:
         _is_tty = sys.stdout.isatty()
     except (AttributeError, ValueError):
         _is_tty = False
     global _QUIET
-    _QUIET = quiet or (bool(message or prompt_file) and not _is_tty)
+    _QUIET = quiet or ((bool(message or prompt_file) or verify_agent) and not _is_tty)
     if _QUIET or not _is_tty:
         _disable_ansi()
 
@@ -1700,6 +1712,21 @@ def main(
             loading.stop()
             print(f"{GREEN}✓{RESET} {DIM}Loaded {final_spec}{RESET}")
 
+        # --verify: preflight the configured agent by running ONE real turn through
+        # the shared core primitive (langstage-core >= 1.0.6), then exit on its
+        # verdict. A green here means the agent actually completed a turn — not just
+        # that it imported — so `langstage-cli --verify -a my_agent.py` is a real CI
+        # gate. Delegates to core.verify so "healthy" means the same across surfaces.
+        if verify_agent:
+            from langstage_core.agui import verify as _core_verify
+
+            result = _core_verify(graph)
+            if result.ok:
+                print(f"{GREEN}✓{RESET} agent verified: {result.reason}")
+                sys.exit(0)
+            _status(f"{RED}✗ agent verification failed: {result.reason}{RESET}")
+            sys.exit(1)
+
         # Seed LangGraph RunnableConfig from TOML [configurable] table if present
         config_dict: Dict[str, Any] = {"configurable": {}}
         toml_configurable = config_module.get(toml_config, "configurable")

{langstage_cli-0.6.4 → langstage_cli-0.6.5/langstage_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langstage-cli
-Version: 0.6.4
+Version: 0.6.5
 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
@@ -19,7 +19,7 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: langgraph>=0.2.0
-Requires-Dist: langstage-core[agui]>=1.0.4
+Requires-Dist: langstage-core[agui]>=1.0.6
 Requires-Dist: click>=8.0.0
 Requires-Dist: python-dotenv
 Provides-Extra: dev
@@ -32,7 +32,7 @@ Requires-Dist: deepagents>=0.3; extra == "dev"
 Requires-Dist: ag-ui-langgraph>=0.0.41; extra == "dev"
 Requires-Dist: fastapi; extra == "dev"
 Provides-Extra: agui
-Requires-Dist: langstage-core[agui]>=1.0.4; extra == "agui"
+Requires-Dist: langstage-core[agui]>=1.0.6; extra == "agui"
 Dynamic: license-file
 
 # langstage-cli
@@ -204,9 +204,22 @@ Options:
   --demo                          Run with the built-in keyless demo agent
   --show-config                   Print the resolved configuration and exit
   -q, --quiet                     Scriptable single-shot output: only the reply
+  --verify                        Preflight the agent (one real turn); exit 0/1
   --version                       Show the version and exit
 ```
 
+### Verifying an agent (CI gate)
+
+`--verify` loads the configured agent and runs **one real turn**, exiting `0` if it
+completed cleanly and non-zero otherwise — so you can gate on it in CI before
+trusting an agent. It catches a missing key, a broken tool, or a non-runnable graph
+that a static "it imports" check would wave through (it runs the same
+`langstage-core` preflight every LangStage surface uses):
+
+```bash
+langstage-cli --verify -a my_agent.py:graph || { echo "agent broken" >&2; exit 1; }
+```
+
 ### Scriptable output
 
 A single-shot run (a `MESSAGE` argument or `-f/--file`) prints only the agent's

{langstage_cli-0.6.4 → langstage_cli-0.6.5}/langstage_cli.egg-info/SOURCES.txt

@@ -27,4 +27,5 @@ tests/test_spec_resolution.py
 tests/test_stream_mode.py
 tests/test_streaming_marker.py
 tests/test_turn_exit_and_render.py
-tests/test_unicode_console.py
+tests/test_unicode_console.py
+tests/test_verify_flag.py

{langstage_cli-0.6.4 → langstage_cli-0.6.5}/langstage_cli.egg-info/requires.txt

@@ -1,10 +1,10 @@
 langgraph>=0.2.0
-langstage-core[agui]>=1.0.4
+langstage-core[agui]>=1.0.6
 click>=8.0.0
 python-dotenv
 
 [agui]
-langstage-core[agui]>=1.0.4
+langstage-core[agui]>=1.0.6
 
 [dev]
 pytest>=7.0.0

{langstage_cli-0.6.4 → langstage_cli-0.6.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "langstage-cli"
-version = "0.6.4"
+version = "0.6.5"
 description = "The terminal stage for your LangGraph agent — Claude Code-style CLI for any CompiledGraph"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -29,7 +29,8 @@ dependencies = [
     # in-process AG-UI adapter — there is no built-in parser fallback — so the
     # AG-UI runtime (ag-ui-langgraph[fastapi] + uvicorn, via core's [agui] extra)
     # is a HARD dep. A bare `pip install langstage-cli` must be able to run a turn.
-    "langstage-core[agui]>=1.0.4",
+    # >=1.0.6 for the shared preflight primitive core.verify() used by --verify.
+    "langstage-core[agui]>=1.0.6",
     "click>=8.0.0",
     "python-dotenv",
 ]
@@ -53,7 +54,7 @@ dev = [
 ]
 # Redundant since AG-UI moved into base deps (core 1.0); kept as a no-op alias so
 # existing `pip install langstage-cli[agui]` scripts/READMEs still resolve.
-agui = ["langstage-core[agui]>=1.0.4"]
+agui = ["langstage-core[agui]>=1.0.6"]
 
 [project.scripts]
 langstage-cli = "langstage_cli.cli:main"

langstage_cli-0.6.5/tests/test_verify_flag.py

@@ -0,0 +1,45 @@
+"""`--verify` preflights the configured agent with a real turn (ADR 0004 adoption).
+
+It delegates to `langstage_core.agui.verify`, so a green here means the agent
+actually completed a turn — a real CI gate — not just that it imported. Exit 0 on
+success, non-zero on failure, with the diagnostic on stderr so stdout stays clean.
+"""
+
+import textwrap
+
+from click.testing import CliRunner
+
+from langstage_cli.cli import main
+
+_BROKEN_AGENT = textwrap.dedent(
+    """
+    from langgraph.graph import StateGraph, START, END, MessagesState
+
+    def boom(state):
+        raise RuntimeError("tool exploded")
+
+    b = StateGraph(MessagesState)
+    b.add_node("boom", boom)
+    b.add_edge(START, "boom")
+    b.add_edge("boom", END)
+    graph = b.compile()
+    """
+)
+
+
+def test_verify_demo_passes_exit_zero(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    r = CliRunner().invoke(main, ["--demo", "--verify"])
+    assert r.exit_code == 0, r.output
+    assert "verified" in r.output  # the pass verdict, on stdout
+    # A preflight is not a chat: no header/marker leaks.
+    assert "⏺" not in r.output and "\x1b[" not in r.output, r.output
+
+
+def test_verify_broken_agent_fails_exit_one(tmp_path, monkeypatch):
+    (tmp_path / "broken.py").write_text(_BROKEN_AGENT)
+    monkeypatch.chdir(tmp_path)
+    r = CliRunner().invoke(main, ["-a", "broken.py:graph", "--verify"])
+    assert r.exit_code == 1
+    assert r.stdout.strip() == "", r.stdout  # stdout stays clean for scripting
+    assert "verification failed" in r.stderr, r.stderr