langgraph-stream-parser 0.2.1__tar.gz → 0.3.0__tar.gz

{langgraph_stream_parser-0.2.1 → langgraph_stream_parser-0.3.0}/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## [0.3.0] - 2026-06-10
+
+The host family is renamed to **LangStage** ("every stage for your LangGraph agent"); this package keeps its name as the shared core.
+
+### Added
+- **`LANGSTAGE_*` is the canonical config vocabulary**: `LANGSTAGE_AGENT_SPEC` etc. env vars, project `langstage.toml`, global `~/.langstage/config.toml`, and `LANGSTAGE_CONFIG_HOME`. The legacy names (`DEEPAGENT_*`, `deepagents.toml`, `~/.deepagents/config.toml`, `DEEPAGENTS_CONFIG_HOME`) still resolve everywhere as deprecated fallbacks — canonical wins when both are set; legacy env use emits a once-per-var `DeprecationWarning`. Moving the global config out of `~/.deepagents/` also exits the schema collision with LangChain's dcode, which owns that directory.
+- Host subclasses may declare either spelling in their `_ENV` maps; both names resolve (`_env_pair` derivation), so downstream hosts need no immediate change.
+
+### Changed
+- `HostConfig.title` default: `"Deep Agent"` → `"LangStage"`.
+- `describe()` shows both vocabularies per field (`env: LANGSTAGE_X (legacy DEEPAGENT_X)`).
+- README family table updated to the LangStage package names.
+
+## [0.2.2] - 2026-06-10
+
+### Added
+- `demo.create_stub_agent()` / `langgraph_stream_parser.demo.stub:graph` — the keyless, deterministic echo agent behind every surface's `--demo` mode. Lazy imports; base install stays dependency-free.
+
+## [0.2.1] - 2026-06-08
+
+### Added
+- `GenericToolExtractor` + `default_extractor` fallback for unknown tools (#16).
+- Tag-driven Release workflow (#17).
+
+## [0.2.0] - 2026-06-02
+
+Repositions langgraph-stream-parser as the **shared runtime substrate** for the deep-agent host family (`cowork-dash`, `deepagent-lab`, `deepagent-code`, `deepagent-vscode`).
+
+### Added
+- **`host/` submodule** — shared host conventions:
+  - `load_agent_spec("path.py:var" | "module:var")` — strict agent-spec loader (the `:object` suffix is required).
+  - `HostConfig` — layered config resolver: `defaults < deepagents.toml < DEEPAGENT_* env < overrides`, with per-field source tracking. Subclass and extend the `_ENV` / `_TOML` maps (merged across the MRO) to add host-specific keys. `DEEPAGENT_AGENT_SPEC` is the canonical agent-spec env var.
+  - `load_toml_config()` — loads + deep-merges global `~/.deepagents/config.toml` (override dir via `DEEPAGENTS_CONFIG_HOME`) and the nearest project `deepagents.toml`.
+  - `Workspace` — workspace-root wrapper with traversal-safe `subpath()`.
+  - `python -m langgraph_stream_parser.host` (and `HostConfig.describe()`) — prints each resolved value, its source, and the env var / TOML key that sets it.
+- **`adapters.SessionAdapter`** — session-scoped streaming for web hosts: per-session event queue, cancellation, side-channel `push_event()`, and persistent SSE that survives client reconnects.
+- **`demo.create_default_agent()`** — shared filesystem-backed default agent factory (behind the `[demo]` extra; lazy-imports `deepagents`).
+- **Four built-in extractors** for the agentskills.io / Hermes pattern, wired into the default set so every host gets them through `compat`: `SkillManageExtractor` (`skill_manage`), `SkillViewExtractor` (`skill_view`), `CompressionExtractor` (`__compression__`), `MemoryExtractor` (`memory`).
+- `event_to_dict(event, *, max_result_len=...)` — lets hosts drop bespoke serializer shims.
+
+### Fixed
+- `skip_tools` previously suppressed a tool's **extractor** as well as its lifecycle events, silently dropping `todo_list` / `reflection`. Extractors now run for skipped tools; only the lifecycle (start/end) events are suppressed.
+
 ## [0.1.9] - 2026-05-19
 
 Compatibility refresh for **langgraph 1.2**, **langchain-core 1.4**, and **deepagents 0.6**.

{langgraph_stream_parser-0.2.1 → langgraph_stream_parser-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langgraph-stream-parser
-Version: 0.2.1
+Version: 0.3.0
 Summary: Universal parser for LangGraph streaming outputs
 Project-URL: Homepage, https://github.com/dkedar7/langgraph-stream-parser
 Project-URL: Documentation, https://github.com/dkedar7/langgraph-stream-parser#readme
@@ -49,6 +49,27 @@ Description-Content-Type: text/markdown
 
 Universal parser for LangGraph streaming outputs. Normalizes complex, variable output shapes from `graph.stream()` and `graph.astream()` into consistent, typed event objects.
 
+## Every stage for your LangGraph agent
+
+`langgraph-stream-parser` is the shared core of the **[LangStage](https://github.com/dkedar7/langstage) family**: write your agent once — any LangGraph `CompiledGraph` — and run it on every stage with the same spec string (`module:attr` or `path/to/file.py:attr`), the same `langstage.toml` config file, and the same `LANGSTAGE_*` environment variables. (The pre-rename `deepagents.toml` / `DEEPAGENT_*` vocabulary still resolves as a deprecated fallback.)
+
+| Stage | Package | Try it |
+|---|---|---|
+| Web app | [langstage](https://github.com/dkedar7/langstage) | `langstage run --agent my_agent.py:graph` |
+| JupyterLab | [langstage-jupyter](https://github.com/dkedar7/langstage-jupyter) | `pip install langstage-jupyter`, then the chat sidebar in `jupyter lab` |
+| Terminal | [langstage-cli](https://github.com/dkedar7/langstage-cli) | `langstage-cli -a my_agent.py:graph` |
+| VS Code | [langstage-vscode](https://github.com/dkedar7/langstage-vscode) | chat participant + stdio sidecar |
+| Reference agent | [langstage-hermes](https://github.com/dkedar7/langstage-hermes) | `LANGSTAGE_AGENT_SPEC=langstage_hermes.agent:graph` on any stage |
+| Shared core | langgraph-stream-parser | **you are here** |
+
+No agent yet? Every stage has a keyless demo mode backed by this package's stub agent — no API key required:
+
+```bash
+export LANGSTAGE_AGENT_SPEC=langgraph_stream_parser.demo.stub:graph  # or each CLI's --demo flag
+```
+
+And the resolved configuration (each value, its source, and the env var / `langstage.toml` key that sets it) is printable everywhere: `python -m langgraph_stream_parser.host`, or each CLI's `--show-config`.
+
 ## Installation
 
 ```bash

{langgraph_stream_parser-0.2.1 → langgraph_stream_parser-0.3.0}/README.md

@@ -6,6 +6,27 @@
 
 Universal parser for LangGraph streaming outputs. Normalizes complex, variable output shapes from `graph.stream()` and `graph.astream()` into consistent, typed event objects.
 
+## Every stage for your LangGraph agent
+
+`langgraph-stream-parser` is the shared core of the **[LangStage](https://github.com/dkedar7/langstage) family**: write your agent once — any LangGraph `CompiledGraph` — and run it on every stage with the same spec string (`module:attr` or `path/to/file.py:attr`), the same `langstage.toml` config file, and the same `LANGSTAGE_*` environment variables. (The pre-rename `deepagents.toml` / `DEEPAGENT_*` vocabulary still resolves as a deprecated fallback.)
+
+| Stage | Package | Try it |
+|---|---|---|
+| Web app | [langstage](https://github.com/dkedar7/langstage) | `langstage run --agent my_agent.py:graph` |
+| JupyterLab | [langstage-jupyter](https://github.com/dkedar7/langstage-jupyter) | `pip install langstage-jupyter`, then the chat sidebar in `jupyter lab` |
+| Terminal | [langstage-cli](https://github.com/dkedar7/langstage-cli) | `langstage-cli -a my_agent.py:graph` |
+| VS Code | [langstage-vscode](https://github.com/dkedar7/langstage-vscode) | chat participant + stdio sidecar |
+| Reference agent | [langstage-hermes](https://github.com/dkedar7/langstage-hermes) | `LANGSTAGE_AGENT_SPEC=langstage_hermes.agent:graph` on any stage |
+| Shared core | langgraph-stream-parser | **you are here** |
+
+No agent yet? Every stage has a keyless demo mode backed by this package's stub agent — no API key required:
+
+```bash
+export LANGSTAGE_AGENT_SPEC=langgraph_stream_parser.demo.stub:graph  # or each CLI's --demo flag
+```
+
+And the resolved configuration (each value, its source, and the env var / `langstage.toml` key that sets it) is printable everywhere: `python -m langgraph_stream_parser.host`, or each CLI's `--show-config`.
+
 ## Installation
 
 ```bash

{langgraph_stream_parser-0.2.1 → langgraph_stream_parser-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "langgraph-stream-parser"
-version = "0.2.1"
+version = "0.3.0"
 description = "Universal parser for LangGraph streaming outputs"
 readme = "README.md"
 license = {text = "MIT"}

{langgraph_stream_parser-0.2.1 → langgraph_stream_parser-0.3.0}/src/langgraph_stream_parser/demo/__init__.py

@@ -9,7 +9,13 @@ everything.
 Requires the optional ``deepagents`` dependency:
 
     pip install langgraph-stream-parser[demo]
+
+This package also ships the keyless **stub agent** behind every surface's
+``--demo`` mode (:func:`create_stub_agent` / spec
+``langgraph_stream_parser.demo.stub:graph``) — that one needs no extra and no
+API key.
 """
 from .agent import create_default_agent
+from .stub import create_stub_agent
 
-__all__ = ["create_default_agent"]
+__all__ = ["create_default_agent", "create_stub_agent"]

langgraph_stream_parser-0.3.0/src/langgraph_stream_parser/demo/stub.py

@@ -0,0 +1,139 @@
+"""A keyless, deterministic stub agent — the engine behind every ``--demo`` mode.
+
+Every LangStage surface (langstage, langstage-cli, langstage-jupyter,
+langstage-vscode) offers a demo mode so a new user can see the surface working
+before configuring a real agent or any API key. This module is the single
+shared implementation: a real compiled LangGraph graph with a checkpointer,
+streaming token-by-token through the exact same parser path as a production
+agent — but the "model" is a local echo, so it needs no network and no keys.
+
+Point any surface at it with the standard spec string::
+
+    LANGSTAGE_AGENT_SPEC=langgraph_stream_parser.demo.stub:graph
+
+or build a customized one in code::
+
+    from langgraph_stream_parser.demo import create_stub_agent
+    agent = create_stub_agent(name="My Demo")
+
+``langgraph`` and ``langchain-core`` are imported lazily — importing this
+module stays dependency-free; only building the agent requires them (every
+host surface already depends on both).
+"""
+from __future__ import annotations
+
+from typing import Any
+
+DEFAULT_REPLY_PREFIX = "(demo agent) You said: "
+DEFAULT_NAME = "Demo Agent"
+
+_GRAPH_CACHE: Any = None
+
+
+def create_stub_agent(
+    *,
+    name: str = DEFAULT_NAME,
+    reply_prefix: str = DEFAULT_REPLY_PREFIX,
+    checkpointer: Any = None,
+):
+    """Build the echo stub agent.
+
+    Args:
+        name: Display name surfaced in host UIs.
+        reply_prefix: Prepended to the echoed user message in every reply.
+        checkpointer: LangGraph checkpointer. Defaults to an in-memory saver
+            so multi-turn threads work out of the box.
+
+    Returns:
+        A compiled LangGraph graph that replies to each user message with
+        ``reply_prefix + <last human message>``, streamed token-by-token.
+
+    Raises:
+        RuntimeError: If ``langgraph`` / ``langchain-core`` are not installed.
+    """
+    try:
+        from langchain_core.callbacks import CallbackManagerForLLMRun
+        from langchain_core.language_models import BaseChatModel
+        from langchain_core.messages import AIMessage, AIMessageChunk, BaseMessage
+        from langchain_core.outputs import ChatGeneration, ChatGenerationChunk, ChatResult
+        from langgraph.checkpoint.memory import MemorySaver
+        from langgraph.graph import END, START, MessagesState, StateGraph
+    except ImportError as e:  # pragma: no cover — exercised only without the deps
+        raise RuntimeError(
+            "The stub agent needs langgraph + langchain-core "
+            "(every deep-agent surface already installs them): "
+            f"{e}"
+        ) from e
+
+    from typing import Iterator, List, Optional
+
+    def _last_human(messages: List[BaseMessage]) -> str:
+        for message in reversed(messages):
+            if getattr(message, "type", None) == "human":
+                content = message.content
+                return content if isinstance(content, str) else str(content)
+        return ""
+
+    class EchoChatModel(BaseChatModel):
+        """A no-API chat model that echoes the user's last message.
+
+        Implements ``_stream`` so that under LangGraph's ``messages`` stream
+        mode the reply is emitted token-by-token, matching how a real chat
+        model behaves through the parser.
+        """
+
+        @property
+        def _llm_type(self) -> str:
+            return "echo-stub"
+
+        def _generate(
+            self,
+            messages: List[BaseMessage],
+            stop: Optional[List[str]] = None,
+            run_manager: Optional[CallbackManagerForLLMRun] = None,
+            **kwargs: Any,
+        ) -> ChatResult:
+            text = reply_prefix + _last_human(messages)
+            return ChatResult(generations=[ChatGeneration(message=AIMessage(content=text))])
+
+        def _stream(
+            self,
+            messages: List[BaseMessage],
+            stop: Optional[List[str]] = None,
+            run_manager: Optional[CallbackManagerForLLMRun] = None,
+            **kwargs: Any,
+        ) -> Iterator[ChatGenerationChunk]:
+            text = reply_prefix + _last_human(messages)
+            tokens = text.split(" ")
+            for i, token in enumerate(tokens):
+                piece = token if i == len(tokens) - 1 else token + " "
+                chunk = ChatGenerationChunk(message=AIMessageChunk(content=piece))
+                if run_manager is not None:
+                    run_manager.on_llm_new_token(piece, chunk=chunk)
+                yield chunk
+
+    model = EchoChatModel()
+
+    def _respond(state: MessagesState) -> dict:
+        return {"messages": [model.invoke(state["messages"])]}
+
+    builder = StateGraph(MessagesState)
+    builder.add_node("respond", _respond)
+    builder.add_edge(START, "respond")
+    builder.add_edge("respond", END)
+
+    graph = builder.compile(checkpointer=checkpointer or MemorySaver())
+    graph.name = name
+    return graph
+
+
+def __getattr__(attr: str) -> Any:
+    # ``graph`` is built lazily on first access so plain imports of this module
+    # never require langgraph — but ``load_agent_spec("...demo.stub:graph")``
+    # gets a ready compiled agent.
+    if attr == "graph":
+        global _GRAPH_CACHE
+        if _GRAPH_CACHE is None:
+            _GRAPH_CACHE = create_stub_agent()
+        return _GRAPH_CACHE
+    raise AttributeError(f"module {__name__!r} has no attribute {attr!r}")

langgraph_stream_parser-0.3.0/src/langgraph_stream_parser/host/__init__.py

@@ -0,0 +1,17 @@
+"""Host conventions shared across the LangStage surfaces.
+
+Agent-spec loading, the shared ``LANGSTAGE_*`` config schema (legacy
+``DEEPAGENT_*`` still resolves), and a workspace wrapper — the plumbing every
+host (``langstage``, ``langstage-jupyter``, ``langstage-cli``,
+``langstage-vscode``) needs but used to reimplement.
+"""
+from .config import HostConfig, load_toml_config
+from .loader import load_agent_spec
+from .workspace import Workspace
+
+__all__ = [
+    "load_agent_spec",
+    "HostConfig",
+    "load_toml_config",
+    "Workspace",
+]

langgraph_stream_parser-0.3.0/src/langgraph_stream_parser/host/__main__.py

@@ -0,0 +1,18 @@
+"""``python -m langgraph_stream_parser.host`` — print the resolved shared config.
+
+Shows each ``LANGSTAGE_*`` value (legacy ``DEEPAGENT_*`` names still resolve),
+where it resolved from (default / TOML / env / override), and the env var +
+``langstage.toml`` key that set it — so you never have to remember the
+variable names. Hosts can ship their own subclass printer for host-specific
+keys; this covers the shared core.
+"""
+from .config import HostConfig
+
+
+def main() -> int:
+    print(HostConfig.resolve().describe())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{langgraph_stream_parser-0.2.1 → langgraph_stream_parser-0.3.0}/src/langgraph_stream_parser/host/config.py

@@ -1,21 +1,30 @@
-"""Shared ``DEEPAGENT_*`` configuration for hosts.
+"""Shared ``LANGSTAGE_*`` configuration for hosts.
 
 ``HostConfig`` holds the keys every host has in common (agent spec, workspace
 root, bind/title basics) and resolves them from one layered chain:
 
-    defaults  <  deepagents.toml  <  DEEPAGENT_* env vars  <  explicit overrides
+    defaults  <  langstage.toml  <  LANGSTAGE_* env vars  <  explicit overrides
 
 Host-specific keys (theme, auth, model, Jupyter token, ...) belong in each
 host's own subclass — drift *below* the shared core is fine — but every host
 gets the same resolution order, the same TOML files, and the same env-var
 names, so there's one place to look.
 
+Legacy vocabulary (the pre-LangStage names) still works everywhere as a
+deprecated fallback: ``DEEPAGENT_*`` env vars, project ``deepagents.toml``,
+global ``~/.deepagents/config.toml``, and ``DEEPAGENTS_CONFIG_HOME``. The
+canonical names win when both are set; using only the legacy env names emits
+a once-per-var ``DeprecationWarning``. Moving the global config out of
+``~/.deepagents/`` also exits the schema collision with LangChain's dcode,
+which owns that directory now.
+
 Discoverability: ``HostConfig.resolve().describe()`` (or
 ``python -m langgraph_stream_parser.host``) prints each value, where it came
 from, and the env var / TOML key that sets it — so you never have to remember
-whether it's ``DEEPAGENT_SPEC`` or ``DEEPAGENT_AGENT_SPEC`` (it's the latter).
+the variable names.
 """
 import os
+import warnings
 from dataclasses import MISSING, dataclass, fields, replace
 from pathlib import Path
 from typing import Any, Callable, ClassVar
@@ -28,8 +37,40 @@ except ModuleNotFoundError:  # pragma: no cover - 3.10 path
     except ModuleNotFoundError:
         _tomllib = None  # type: ignore
 
-GLOBAL_TOML = Path.home() / ".deepagents" / "config.toml"
-PROJECT_TOML = "deepagents.toml"
+GLOBAL_TOML = Path.home() / ".langstage" / "config.toml"
+PROJECT_TOML = "langstage.toml"
+# Pre-rename locations, still honoured as fallbacks.
+LEGACY_GLOBAL_TOML = Path.home() / ".deepagents" / "config.toml"
+LEGACY_PROJECT_TOML = "deepagents.toml"
+
+_CANONICAL_ENV_PREFIX = "LANGSTAGE"
+_LEGACY_ENV_PREFIX = "DEEPAGENT"
+
+_warned_legacy_env: set[str] = set()
+
+
+def _env_pair(declared: str) -> tuple[str, str]:
+    """Return ``(canonical, legacy)`` env-var names for a declared name.
+
+    Hosts may declare either spelling in their ``_ENV`` maps during the
+    rename transition; both resolve, canonical wins.
+    """
+    if declared.startswith(_CANONICAL_ENV_PREFIX):
+        return declared, _LEGACY_ENV_PREFIX + declared[len(_CANONICAL_ENV_PREFIX):]
+    if declared.startswith(_LEGACY_ENV_PREFIX):
+        return _CANONICAL_ENV_PREFIX + declared[len(_LEGACY_ENV_PREFIX):], declared
+    return declared, declared
+
+
+def _warn_legacy_env(legacy: str, canonical: str) -> None:
+    if legacy in _warned_legacy_env:
+        return
+    _warned_legacy_env.add(legacy)
+    warnings.warn(
+        f"{legacy} is deprecated; use {canonical}.",
+        DeprecationWarning,
+        stacklevel=4,
+    )
 
 
 def _env_bool(value: str | None, default: bool = False) -> bool:
@@ -43,17 +84,27 @@ def _env_bool(value: str | None, default: bool = False) -> bool:
 
 
 def _global_toml_path() -> Path:
-    override = os.getenv("DEEPAGENTS_CONFIG_HOME")
-    return (Path(override).expanduser() / "config.toml") if override else GLOBAL_TOML
+    override = os.getenv("LANGSTAGE_CONFIG_HOME") or os.getenv("DEEPAGENTS_CONFIG_HOME")
+    if override:
+        return Path(override).expanduser() / "config.toml"
+    # New home wins when present; otherwise fall back to the legacy location
+    # (which load_toml_config skips anyway if the file doesn't exist).
+    return GLOBAL_TOML if GLOBAL_TOML.is_file() else LEGACY_GLOBAL_TOML
 
 
 def _find_project_toml(start: Path | None = None) -> Path | None:
-    """Walk up from ``start`` (or cwd) looking for ``deepagents.toml``."""
+    """Walk up from ``start`` (or cwd) looking for ``langstage.toml``.
+
+    Checks ``langstage.toml`` then legacy ``deepagents.toml`` in each
+    directory, so the nearest file wins and the new name wins within a
+    directory.
+    """
     here = (start or Path.cwd()).resolve()
     for directory in (here, *here.parents):
-        candidate = directory / PROJECT_TOML
-        if candidate.is_file():
-            return candidate
+        for fname in (PROJECT_TOML, LEGACY_PROJECT_TOML):
+            candidate = directory / fname
+            if candidate.is_file():
+                return candidate
     return None
 
 
@@ -75,11 +126,13 @@ def _read_toml(path: Path) -> dict:
 
 
 def load_toml_config(start: Path | None = None) -> tuple[dict, list[Path]]:
-    """Load + deep-merge the global and project ``deepagents.toml`` files.
+    """Load + deep-merge the global and project ``langstage.toml`` files.
 
-    Global is ``~/.deepagents/config.toml`` (override the dir with
-    ``DEEPAGENTS_CONFIG_HOME``); project is the nearest ``deepagents.toml`` at
-    or above ``start``/cwd. Project wins on conflicts. Returns
+    Global is ``~/.langstage/config.toml`` (override the dir with
+    ``LANGSTAGE_CONFIG_HOME``; legacy ``~/.deepagents/config.toml`` and
+    ``DEEPAGENTS_CONFIG_HOME`` still work as fallbacks); project is the
+    nearest ``langstage.toml`` — or legacy ``deepagents.toml`` — at or above
+    ``start``/cwd. Project wins on conflicts. Returns
     ``(merged_config, sources_used)``; ``({}, [])`` if no TOML reader is
     available (Python 3.10 without ``tomli``).
     """
@@ -120,28 +173,30 @@ class HostConfig:
         @dataclass
         class WebConfig(HostConfig):
             theme: str = "auto"
-            _ENV = {"theme": ("DEEPAGENT_THEME", str)}
+            _ENV = {"theme": ("LANGSTAGE_THEME", str)}
             _TOML = {"theme": "ui.theme"}
 
     ``resolve()`` merges the maps across the MRO, so the subclass inherits all
     of ``HostConfig``'s keys and adds its own.
     """
 
-    agent_spec: str | None = None     # DEEPAGENT_AGENT_SPEC ("path.py:var")
-    workspace_root: Path = Path(".")  # DEEPAGENT_WORKSPACE_ROOT
-    host: str = "localhost"           # DEEPAGENT_HOST
-    port: int = 8050                  # DEEPAGENT_PORT
-    debug: bool = False               # DEEPAGENT_DEBUG
-    title: str = "Deep Agent"         # DEEPAGENT_TITLE
+    agent_spec: str | None = None     # LANGSTAGE_AGENT_SPEC ("path.py:var")
+    workspace_root: Path = Path(".")  # LANGSTAGE_WORKSPACE_ROOT
+    host: str = "localhost"           # LANGSTAGE_HOST
+    port: int = 8050                  # LANGSTAGE_PORT
+    debug: bool = False               # LANGSTAGE_DEBUG
+    title: str = "LangStage"          # LANGSTAGE_TITLE
 
-    # field -> (DEEPAGENT_* env var, caster). DEEPAGENT_AGENT_SPEC is canonical.
+    # field -> (env var, caster). Canonical names are LANGSTAGE_*; the
+    # matching DEEPAGENT_* legacy names resolve as deprecated fallbacks
+    # (see _env_pair).
     _ENV: ClassVar[dict[str, tuple[str, Callable[[str], Any]]]] = {
-        "agent_spec": ("DEEPAGENT_AGENT_SPEC", str),
-        "workspace_root": ("DEEPAGENT_WORKSPACE_ROOT", Path),
-        "host": ("DEEPAGENT_HOST", str),
-        "port": ("DEEPAGENT_PORT", int),
-        "debug": ("DEEPAGENT_DEBUG", _env_bool),
-        "title": ("DEEPAGENT_TITLE", str),
+        "agent_spec": ("LANGSTAGE_AGENT_SPEC", str),
+        "workspace_root": ("LANGSTAGE_WORKSPACE_ROOT", Path),
+        "host": ("LANGSTAGE_HOST", str),
+        "port": ("LANGSTAGE_PORT", int),
+        "debug": ("LANGSTAGE_DEBUG", _env_bool),
+        "title": ("LANGSTAGE_TITLE", str),
     }
     # field -> dotted key in deepagents.toml
     _TOML: ClassVar[dict[str, str]] = {
@@ -226,10 +281,17 @@ class HostConfig:
 
             if name in env_map:
                 var, caster = env_map[name]
-                ev = env.get(var)
+                canonical, legacy = _env_pair(var)
+                ev = env.get(canonical)
+                used = canonical
+                if ev is None or ev == "":
+                    ev = env.get(legacy)
+                    used = legacy
+                    if ev not in (None, "") and legacy != canonical:
+                        _warn_legacy_env(legacy, canonical)
                 if ev is not None and ev != "":
                     val = caster(ev)
-                    src = f"env:{var}"
+                    src = f"env:{used}"
 
             if name in overrides:
                 val = overrides[name]
@@ -270,7 +332,11 @@ class HostConfig:
             origin = src.get(f.name, "default")
             hints = []
             if f.name in env_map:
-                hints.append(f"env: {env_map[f.name][0]}")
+                canonical, legacy = _env_pair(env_map[f.name][0])
+                env_hint = f"env: {canonical}"
+                if legacy != canonical:
+                    env_hint += f" (legacy {legacy})"
+                hints.append(env_hint)
             if f.name in toml_map:
                 hints.append(f"toml: {toml_map[f.name]}")
             hint = f"   ({', '.join(hints)})" if hints else ""
@@ -280,7 +346,7 @@ class HostConfig:
         if toml_paths:
             lines.append("  TOML read from: " + ", ".join(str(p) for p in toml_paths))
         else:
-            lines.append("  TOML: no deepagents.toml found")
+            lines.append("  TOML: no langstage.toml (or legacy deepagents.toml) found")
         return "\n".join(lines)
 
 

langgraph_stream_parser-0.3.0/tests/test_demo_stub.py

@@ -0,0 +1,65 @@
+"""Tests for the keyless stub agent behind every surface's --demo mode.
+
+Unlike the default agent (which needs deepagents + an API key), the stub only
+needs langgraph + langchain-core — both in the dev extras — so these tests
+exercise it end to end through the parser.
+"""
+from langgraph_stream_parser import StreamParser, load_agent_spec, prepare_agent_input
+from langgraph_stream_parser.demo import create_stub_agent
+from langgraph_stream_parser.events import CompleteEvent, ContentEvent
+
+STREAM_MODE = ["updates", "messages"]
+
+
+def _run_turn(graph, message: str, thread_id: str = "t1"):
+    parser = StreamParser(stream_mode=STREAM_MODE)
+    stream = graph.stream(
+        prepare_agent_input(message=message),
+        config={"configurable": {"thread_id": thread_id}},
+        stream_mode=STREAM_MODE,
+    )
+    return list(parser.parse(stream))
+
+
+def _content(events) -> str:
+    return "".join(e.content for e in events if isinstance(e, ContentEvent))
+
+
+def test_streams_echo_through_the_parser():
+    graph = create_stub_agent()
+    events = _run_turn(graph, "hello demo")
+
+    assert "(demo agent) You said: hello demo" in _content(events)
+    assert isinstance(events[-1], CompleteEvent)
+
+
+def test_streams_token_by_token():
+    graph = create_stub_agent()
+    events = _run_turn(graph, "one two three four")
+    content_events = [e for e in events if isinstance(e, ContentEvent)]
+    # The echo splits on spaces — a multi-word message must arrive in pieces.
+    assert len(content_events) > 1
+
+
+def test_multi_turn_thread_persists():
+    graph = create_stub_agent()
+    _run_turn(graph, "first", thread_id="conv")
+    state = graph.get_state({"configurable": {"thread_id": "conv"}})
+    _run_turn(graph, "second", thread_id="conv")
+    state2 = graph.get_state({"configurable": {"thread_id": "conv"}})
+    assert len(state2.values["messages"]) > len(state.values["messages"])
+
+
+def test_custom_name_and_prefix():
+    graph = create_stub_agent(name="My Demo", reply_prefix="echo: ")
+    assert graph.name == "My Demo"
+    events = _run_turn(graph, "hi")
+    assert "echo: hi" in _content(events)
+
+
+def test_loadable_via_standard_spec_string():
+    graph = load_agent_spec("langgraph_stream_parser.demo.stub:graph")
+    events = _run_turn(graph, "spec works", thread_id="spec")
+    assert "spec works" in _content(events)
+    # The module-level graph is cached — same object on a second load.
+    assert load_agent_spec("langgraph_stream_parser.demo.stub:graph") is graph

{langgraph_stream_parser-0.2.1 → langgraph_stream_parser-0.3.0}/tests/test_host.py

@@ -67,7 +67,7 @@ class TestHostConfig:
         assert cfg.host == "localhost"
         assert cfg.port == 8050
         assert cfg.debug is False
-        assert cfg.title == "Deep Agent"
+        assert cfg.title == "LangStage"
 
     def test_from_env(self, monkeypatch):
         monkeypatch.setenv("DEEPAGENT_AGENT_SPEC", "agent.py:graph")

{langgraph_stream_parser-0.2.1 → langgraph_stream_parser-0.3.0}/tests/test_host_config.py

@@ -111,6 +111,85 @@ class TestSubclass:
         assert "DEEPAGENT_THEME" in cfg.describe()
 
 
+class TestLangstageVocabulary:
+    """Canonical LANGSTAGE_* / langstage.toml with deprecated legacy fallbacks."""
+
+    def test_canonical_env_resolves(self, isolated_global, tmp_path):
+        cfg = HostConfig.resolve(
+            env={"LANGSTAGE_AGENT_SPEC": "a.py:g", "LANGSTAGE_PORT": "9100"},
+            toml_start=tmp_path,
+        )
+        assert cfg.agent_spec == "a.py:g"
+        assert cfg.port == 9100
+        assert cfg.sources["agent_spec"] == "env:LANGSTAGE_AGENT_SPEC"
+
+    def test_canonical_beats_legacy(self, isolated_global, tmp_path):
+        cfg = HostConfig.resolve(
+            env={"LANGSTAGE_PORT": "1111", "DEEPAGENT_PORT": "2222"},
+            toml_start=tmp_path,
+        )
+        assert cfg.port == 1111
+        assert cfg.sources["port"] == "env:LANGSTAGE_PORT"
+
+    def test_legacy_env_warns_once(self, isolated_global, tmp_path):
+        import langgraph_stream_parser.host.config as config_mod
+
+        config_mod._warned_legacy_env.discard("DEEPAGENT_TITLE")
+        with pytest.warns(DeprecationWarning, match="LANGSTAGE_TITLE"):
+            HostConfig.resolve(env={"DEEPAGENT_TITLE": "Old"}, toml_start=tmp_path)
+
+    def test_langstage_toml_preferred_in_same_dir(self, isolated_global, tmp_path):
+        (tmp_path / "deepagents.toml").write_text("[server]\nport = 1000\n")
+        (tmp_path / "langstage.toml").write_text("[server]\nport = 2000\n")
+        cfg = HostConfig.resolve(env={}, toml_start=tmp_path)
+        assert cfg.port == 2000
+
+    def test_legacy_toml_still_read(self, isolated_global, tmp_path):
+        (tmp_path / "deepagents.toml").write_text("[server]\nport = 1234\n")
+        cfg = HostConfig.resolve(env={}, toml_start=tmp_path)
+        assert cfg.port == 1234
+
+    def test_nearest_toml_wins_across_dirs(self, isolated_global, tmp_path):
+        # langstage.toml in the parent must NOT beat deepagents.toml in cwd.
+        (tmp_path / "langstage.toml").write_text("[server]\nport = 1000\n")
+        sub = tmp_path / "sub"
+        sub.mkdir()
+        (sub / "deepagents.toml").write_text("[server]\nport = 2000\n")
+        cfg = HostConfig.resolve(env={}, toml_start=sub)
+        assert cfg.port == 2000
+
+    def test_langstage_config_home_override(self, tmp_path, monkeypatch):
+        gdir = tmp_path / "newhome"
+        gdir.mkdir()
+        (gdir / "config.toml").write_text("[server]\nport = 4321\n")
+        monkeypatch.delenv("DEEPAGENTS_CONFIG_HOME", raising=False)
+        monkeypatch.setenv("LANGSTAGE_CONFIG_HOME", str(gdir))
+        cfg = HostConfig.resolve(env={}, toml_start=tmp_path)
+        assert cfg.port == 4321
+
+    def test_describe_shows_both_vocabularies(self, isolated_global, tmp_path):
+        text = HostConfig.resolve(env={}, toml_start=tmp_path).describe()
+        assert "LANGSTAGE_AGENT_SPEC" in text
+        assert "legacy DEEPAGENT_AGENT_SPEC" in text
+
+    def test_subclass_legacy_declaration_resolves_canonical_name(
+        self, isolated_global, tmp_path
+    ):
+        """A host still declaring DEEPAGENT_* in its _ENV map picks up the
+        LANGSTAGE_* var without any subclass change."""
+        from dataclasses import dataclass
+        from typing import ClassVar
+
+        @dataclass
+        class OldHost(HostConfig):
+            theme: str = "auto"
+            _ENV: ClassVar[dict] = {"theme": ("DEEPAGENT_THEME", str)}
+
+        cfg = OldHost.resolve(env={"LANGSTAGE_THEME": "dark"}, toml_start=tmp_path)
+        assert cfg.theme == "dark"
+        assert cfg.sources["theme"] == "env:LANGSTAGE_THEME"
+
+
 class TestFromEnvBackCompat:
     def test_from_env_skips_toml(self, isolated_global, tmp_path, monkeypatch):
         _toml(tmp_path, "[server]\nport = 1234\n")

langgraph_stream_parser-0.2.1/src/langgraph_stream_parser/host/__init__.py

@@ -1,16 +0,0 @@
-"""Host conventions shared across deep-agent surfaces.
-
-Agent-spec loading, the shared ``DEEPAGENT_*`` config schema, and a workspace
-wrapper — the plumbing every host (``cowork-dash``, ``deepagent-lab``,
-``deepagent-code``, ``deepagent-vscode``) needs but used to reimplement.
-"""
-from .config import HostConfig, load_toml_config
-from .loader import load_agent_spec
-from .workspace import Workspace
-
-__all__ = [
-    "load_agent_spec",
-    "HostConfig",
-    "load_toml_config",
-    "Workspace",
-]

langgraph_stream_parser-0.2.1/src/langgraph_stream_parser/host/__main__.py

@@ -1,17 +0,0 @@
-"""``python -m langgraph_stream_parser.host`` — print the resolved shared config.
-
-Shows each ``DEEPAGENT_*`` value, where it resolved from (default / TOML / env /
-override), and the env var + ``deepagents.toml`` key that set it — so you never
-have to remember the variable names. Hosts can ship their own subclass printer
-for host-specific keys; this covers the shared core.
-"""
-from .config import HostConfig
-
-
-def main() -> int:
-    print(HostConfig.resolve().describe())
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())